vLLM en un servidor GPU: API compatible con OpenAI para tu propia LLM

Qué configuramos y por qué

vLLM es un servidor de inferencia para modelos de lenguaje grandes. Carga el modelo en la memoria de la GPU, recibe solicitudes HTTP y devuelve texto generado. La principal característica práctica de vLLM es la compatibilidad con la API de OpenAI. Una aplicación que puede trabajar con el SDK de OpenAI normalmente puede cambiarse a un servidor propio sustituyendo base_url y la clave API.

En este escenario, el servidor GPU funciona como un endpoint privado para una o varias LLM. Por ejemplo, puedes utilizar Qwen3-8B para un chatbot interno, Llama 3.1 8B para resumir documentos, DeepSeek-R1-Distill para razonamiento o un modelo de embeddings para buscar en una base de conocimientos. vLLM en sí no es un chat web: es una capa de API. La interfaz para empleados o clientes se conecta por separado.

Qué obtendrás al final

• Un servidor Ubuntu 24.04 LTS con el controlador NVIDIA, Docker y NVIDIA Container Toolkit instalados.
• El contenedor vllm/vllm-openai, que utiliza la GPU mediante Docker.
• El modelo Qwen/Qwen3-8B, descargado automáticamente en la caché local de Hugging Face.
• API compatible con OpenAI: https://llm.example.com/v1/chat/completions.
• Autorización mediante un token Bearer, verificado por vLLM.
• Certificado TLS de Let’s Encrypt, gestionado automáticamente por Caddy.
• Un esquema claro para actualizar, realizar copias de seguridad y diagnosticar errores de GPU.

Por qué vLLM y no una ejecución habitual de Transformers

Ejecutar un modelo mediante la biblioteca Python Transformers es práctico para experimentar, pero poco adecuado para una API permanente. Con varias solicitudes simultáneas, una aplicación Python suele quedar inactiva o procesar solicitudes secuencialmente. vLLM utiliza procesamiento por lotes continuo de solicitudes: la GPU genera tokens para diferentes usuarios en un mismo ciclo de cálculo.

Además, vLLM gestiona de forma más eficiente la caché KV, la memoria donde el modelo almacena el contexto de la conversación. En chats con historiales largos, la caché KV suele convertirse en una limitación antes que los propios pesos del modelo. PagedAttention divide esta caché en bloques y reduce la fragmentación de VRAM.

Self-hosted o API gestionada

La opción self-hosted se justifica si los datos no pueden enviarse a una API externa, la carga es predecible, se requiere un modelo open-weight específico o se necesita control total sobre límites, registro y versiones. Si el tráfico es escaso e impredecible, una API gestionada suele ser más económica: la GPU no debe permanecer inactiva las 24 horas.

Importante: no todos los modelos de Hugging Face tienen licencia para uso comercial. Antes de integrarlo en un producto, revisa la licencia del modelo, los requisitos de atribución y las condiciones de acceso a repositorios gated.

Qué configuración de VPS se necesita para esta tarea

Para vLLM, lo más importante no es el número de núcleos de CPU, sino la capacidad y el tipo de memoria de la GPU. La VRAM debe alojar simultáneamente los pesos del modelo, la caché KV del contexto, los tensores temporales y un margen para la fragmentación. La memoria RAM del servidor se utiliza para cargar los archivos del modelo, Docker, la caché y el sistema operativo.

Estimación de memoria para el modelo

Una fórmula aproximada para los pesos: el número de parámetros multiplicado por el tamaño de un parámetro. Un modelo de 8 mil millones de parámetros en FP16 ocupa alrededor de 16 GB solo para los pesos. En formato AWQ o GPTQ de 4 bits ocupa aproximadamente 5–7 GB, pero el valor exacto depende de la arquitectura, la configuración de quantization y la versión del motor.

Para esta guía, es óptimo un servidor con una GPU de 24 GB de VRAM, 8 vCPU, 32–64 GB de RAM, 200 GB de NVMe y una red de al menos 1 Gbit/s. Esta configuración ofrece margen para Qwen3-8B, Llama 3.1 8B y modelos comparables. Como una de las opciones neutrales, puedes elegir un VPS con las características indicadas, si la descripción garantiza explícitamente una GPU NVIDIA dedicada, la cantidad de VRAM y acceso a ella desde la máquina virtual.

Por qué no puedes guiarte solo por el nombre de la GPU

Verifica la cantidad de VRAM, no solo el modelo del acelerador. Por ejemplo, las GPU de centro de datos pueden comercializarse en configuraciones con distinta memoria. Confirma que la GPU está dedicada íntegramente a ti y no se comparte entre clientes sin una cuota garantizada. Asegúrate también de que el proveedor permita Docker y proporcione el controlador NVIDIA o un GPU passthrough compatible.

Cuándo se necesita un servidor dedicado en lugar de un GPU VPS

Un servidor dedicado es necesario para varias GPU, modelos de 70B parámetros o más, una carga constante alta, requisitos estrictos de aislamiento o la necesidad de control total sobre la topología PCIe. También es útil si deseas ejecutar modelos independientes en varias GPU o atender a decenas de usuarios simultáneos.

Un GPU VPS es una opción racional para una sola GPU y carga moderada: es más fácil de iniciar, más barato al principio y más sencillo de escalar cambiando la configuración. Para un único modelo de 8B, un servidor dedicado suele ser excesivo.

Elección de ubicación

La ubicación afecta a la latencia de la API. Si los usuarios y la aplicación están en Europa, un servidor en un centro de datos europeo normalmente ofrecerá una latencia de red de 10–60 ms en lugar de cientos de milisegundos. Para las LLM, este no es el único factor: generar cada token también requiere tiempo. Sin embargo, un servidor remoto empeora notablemente la sensación de respuesta en un chat con streaming.

Si la API procesa datos personales, ten en cuenta los requisitos de jurisdicción y almacenamiento de datos. No envíes registros de solicitudes a regiones donde su almacenamiento contradiga tus contratos o las normas de tratamiento de datos.

Preparación del servidor

A continuación se utiliza Ubuntu 24.04 LTS. En el momento de preparar esta guía, es una elección base práctica para cargas de trabajo con GPU: el sistema cuenta con soporte de larga duración y es compatible con los controladores NVIDIA actuales, Docker Engine 29 y NVIDIA Container Toolkit. Realice la configuración inicial con un usuario con permisos de sudo, no como root.

Cree un usuario y configure una clave SSH

Conéctese al servidor mediante el método inicial proporcionado por el servicio de hosting. En su equipo, cree una clave si aún no la tiene y añada después la parte pública al servidor. No cierre la sesión SSH actual hasta comprobar el inicio de sesión con el nuevo usuario.

# En el servidor: creamos un administrador independiente y lo añadimos a sudo
sudo adduser deploy
sudo usermod -aG sudo deploy

# En el equipo local: copiamos la clave pública SSH al servidor
ssh-copy-id deploy@SERVER_IP

Compruebe el inicio de sesión en una nueva ventana de terminal:

# En el equipo local: comprobamos el inicio de sesión mediante clave
ssh deploy@SERVER_IP

Actualice el sistema e instale herramientas básicas

# Actualizamos los paquetes de Ubuntu e instalamos utilidades de diagnóstico
sudo apt update && sudo apt full-upgrade -y
sudo apt install -y ca-certificates curl gnupg git jq htop tmux \
  fail2ban ufw unzip ncdu

Después de actualizar el kernel o el controlador NVIDIA, reinicie el servidor. En los nodos con GPU, el reinicio es especialmente importante: el controlador cargado debe corresponder a las bibliotecas instaladas.

# Reiniciamos el servidor si se actualizó el kernel o el controlador
sudo reboot

Cierre los puertos de red innecesarios

vLLM escucha de forma predeterminada el puerto HTTP 8000. No lo publique directamente en Internet: una clave de API no sustituye el perímetro de red y HTTP sin cifrar transmite las solicitudes y el token en texto plano. Desde el exterior solo estarán disponibles SSH, HTTP para emitir el certificado y HTTPS.

# Permitimos SSH, HTTP y HTTPS; bloqueamos todas las demás conexiones entrantes
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Configure Fail2ban y desactive el inicio de sesión con contraseña

Fail2ban bloquea las fuentes con una serie de intentos fallidos de inicio de sesión SSH. Después de comprobar la clave SSH, desactive la autenticación mediante contraseña. Si pierde la clave privada y no tiene acceso a la consola mediante el panel del servidor, la recuperación requerirá la intervención del proveedor.

# Activamos la protección SSH y creamos una configuración local de Fail2ban
sudo systemctl enable --now fail2ban
sudo tee /etc/fail2ban/jail.d/sshd.local > /dev/null <<'EOF'
[sshd]
enabled = true
maxretry = 5
findtime = 10m
bantime = 1h
EOF
sudo systemctl restart fail2ban
sudo fail2ban-client status sshd

# Desactivamos las contraseñas SSH y el inicio de sesión root solo después de comprobar la clave
sudo tee /etc/ssh/sshd_config.d/99-hardening.conf > /dev/null <<'EOF'
PasswordAuthentication no
KbdInteractiveAuthentication no
PermitRootLogin no
PubkeyAuthentication yes
EOF
sudo sshd -t && sudo systemctl reload ssh

Compruebe también las reglas de firewall en el panel del propio servidor, si existen. El firewall externo debe coincidir con UFW: permita los puertos 22, 80 y 443, y no abra el 8000.

Instalación de software — paso a paso

Antes de instalar el contenedor, asegúrese de que la GPU sea visible para el sistema operativo. Muchos VPS con GPU incluyen un controlador NVIDIA ya instalado. Si el comando nvidia-smi no funciona, instale primero el controlador recomendado desde el repositorio de Ubuntu o consulte la documentación de la imagen del servidor.

Compruebe el controlador NVIDIA

# Mostramos el modelo de GPU, la versión del controlador y la VRAM disponible
nvidia-smi

Debería ver una tabla con la GPU y la versión del controlador. Para las imágenes modernas de vLLM con CUDA 12, normalmente se requiere un controlador NVIDIA de la serie 535 o posterior; en la práctica, se prefieren las ramas 550, 570 o posteriores compatibles con su sistema operativo. No instale CUDA Toolkit en el host salvo que sea necesario: el contenedor vLLM ya incluye las bibliotecas CUDA de espacio de usuario necesarias.

Instale Docker Engine

Instale Docker desde el repositorio oficial de Docker, no el paquete antiguo docker.io del repositorio base de Ubuntu. Así obtendrá Docker Engine 29.x actualizado y el plugin Docker Compose.

# Añadimos la clave GPG oficial y el repositorio de Docker para Ubuntu
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

# Permitimos que el usuario deploy ejecute Docker sin sudo y comprobamos la versión
sudo usermod -aG docker deploy
newgrp docker
docker version
docker compose version

Instale NVIDIA Container Toolkit

NVIDIA Container Toolkit transfiere la GPU del host al contenedor Docker. El repositorio y la clave siguientes se utilizan para los paquetes actuales del toolkit. Tras la instalación se reinicia el daemon de Docker, por lo que los contenedores que ya estén en ejecución se detendrán brevemente.

# Conectamos el repositorio oficial de NVIDIA Container Toolkit
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt update
sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Compruebe la GPU dentro del contenedor

# Ejecutamos el contenedor CUDA oficial y comprobamos que la GPU se transfiere a Docker
docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi

Si la salida dentro del contenedor muestra su GPU, la infraestructura básica está lista. El error could not select device driver "" with capabilities: [[gpu]] normalmente significa que el toolkit no está instalado o que Docker no se reinició.

Prepare el directorio de la aplicación

Separe los datos de la aplicación de los datos del contenedor. El directorio del proyecto contendrá el archivo Compose, Caddyfile, variables de entorno y scripts. La caché de Hugging Face se almacena en un volume independiente para no descargar decenas de gigabytes del modelo después de recrear el contenedor.

# Creamos la estructura del proyecto vLLM y los directorios para datos persistentes
sudo mkdir -p /opt/vllm/{caddy,data/hf-cache,backups,scripts}
sudo chown -R deploy:deploy /opt/vllm
cd /opt/vllm

Obtenga un token de Hugging Face si es necesario

Para Qwen3-8B público normalmente no se necesita un token. Sin embargo, será necesario para modelos gated, por ejemplo, algunas variantes de Llama. Cree un access token con el permiso mínimo Read en su cuenta de Hugging Face y guárdelo únicamente en .env. No incluya dicho token en Git, una imagen Docker ni el archivo Compose.

Configuración

El ejemplo utiliza vLLM OpenAI server y el modelo Qwen/Qwen3-8B. La imagen está fijada a la etiqueta específica v0.10.2 para que una actualización no cambie el comportamiento de forma inadvertida. Antes de un nuevo despliegue, compruebe la etiqueta estable actual en el registro oficial de vLLM y pruébela en un entorno independiente; no use latest en producción.

Cree el archivo de variables de entorno

Genere una clave API aleatoria y larga. Las aplicaciones de usuario la enviarán en el encabezado Authorization: Bearer .... El valor de VLLM_MAX_MODEL_LEN limita el contexto: 8192 tokens es una configuración inicial segura para GPU con 24 GB de VRAM.

# Генерируем секреты и создаём .env с правами только для владельца
cd /opt/vllm
umask 077
cat > .env <<EOF
DOMAIN=llm.example.com
VLLM_API_KEY=$(openssl rand -hex 32)
HF_TOKEN=
MODEL_NAME=Qwen/Qwen3-8B
SERVED_MODEL_NAME=qwen3-8b
VLLM_MAX_MODEL_LEN=8192
GPU_MEMORY_UTILIZATION=0.88
EOF
chmod 600 .env

# Просматриваем ключ только локально; не копируйте его в публичные чаты и репозитории
grep VLLM_API_KEY .env

Sustituya llm.example.com por su dominio. Antes de iniciar Caddy, cree un registro DNS de tipo A que apunte a la dirección IPv4 pública del servidor. Si utiliza IPv6, añada un registro AAAA y asegúrese de que el puerto 443 sea accesible mediante IPv6.

Cree la configuración de Docker Compose

El puerto 8000 está vinculado a 127.0.0.1, por lo que no se puede abrir directamente desde Internet. Caddy y vLLM están en la misma red Docker. La variable HF_TOKEN se pasa al contenedor solo si la especificó en .env.

services:
  vllm:
    image: vllm/vllm-openai:v0.10.2
    container_name: vllm-api
    restart: unless-stopped
    env_file:
      - .env
    environment:
      HF_HOME: /root/.cache/huggingface
      HUGGING_FACE_HUB_TOKEN: ${HF_TOKEN}
      TOKENIZERS_PARALLELISM: "false"
    volumes:
      - ./data/hf-cache:/root/.cache/huggingface
    ports:
      - "127.0.0.1:8000:8000"
    ipc: host
    gpus: all
    command:
      - --model
      - ${MODEL_NAME}
      - --served-model-name
      - ${SERVED_MODEL_NAME}
      - --host
      - 0.0.0.0
      - --port
      - "8000"
      - --api-key
      - ${VLLM_API_KEY}
      - --max-model-len
      - ${VLLM_MAX_MODEL_LEN}
      - --gpu-memory-utilization
      - ${GPU_MEMORY_UTILIZATION}
      - --enable-prefix-caching
    healthcheck:
      test: ["CMD-SHELL", "python3 -c \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=5)\""]
      interval: 30s
      timeout: 10s
      retries: 10
      start_period: 180s

  caddy:
    image: caddy:2.10-alpine
    container_name: vllm-caddy
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./data/caddy-data:/data
      - ./data/caddy-config:/config
    depends_on:
      vllm:
        condition: service_started

Guarde este archivo como /opt/vllm/compose.yml. El parámetro --gpu-memory-utilization 0.88 no reserva toda la VRAM, dejando margen para CUDA y los procesos del sistema. Si el modelo no cabe, primero reduzca el contexto, luego disminuya este valor a 0.80–0.85 o elija un modelo cuantizado.

Configure Caddy y HTTPS

Caddy solicitará y renovará automáticamente el certificado TLS si el dominio ya apunta al servidor y los puertos 80 y 443 están abiertos. A continuación, solo se configuran como proxy la API y el endpoint de health. No active registros detallados de solicitudes HTTP sin necesidad: los prompts de los usuarios podrían aparecer en los registros.

{
    email [email protected]
}

{$DOMAIN} {
    encode zstd gzip

    @api {
        path /v1/ /health
    }

    handle @api {
        reverse_proxy vllm:8000 {
            flush_interval -1
        }
    }

    respond "Not found" 404
}

# Скачиваем образы и запускаем Caddy с сервером модели в фоне
cd /opt/vllm
docker compose -f compose.yml pull
docker compose -f compose.yml up -d

# Смотрим прогресс скачивания модели и загрузки движка vLLM
docker compose -f compose.yml logs -f vllm

# Проверяем readiness напрямую с сервера, не раскрывая API наружу
curl -s http://127.0.0.1:8000/health && echo

# Получаем перечень моделей через публичный HTTPS endpoint
source /opt/vllm/.env
curl -s https://$DOMAIN/v1/models \
  -H "Authorization: Bearer $VLLM_API_KEY" | jq

# Отправляем тестовый запрос к OpenAI-совместимому API
source /opt/vllm/.env
curl -s https://$DOMAIN/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VLLM_API_KEY" \
  -d '{
    "model": "qwen3-8b",
    "messages": [
      {"role": "system", "content": "Отвечай кратко и технически."},
      {"role": "user", "content": "Что такое KV-кеш в LLM?"}
    ],
    "temperature": 0.2,
    "max_tokens": 180
  }' | jq '.choices[0].message.content'

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://llm.example.com/v1",
    api_key=os.environ["VLLM_API_KEY"],
)

response = client.chat.completions.create(
    model="qwen3-8b",
    messages=[{"role": "user", "content": "Составь план резервного копирования."}],
    temperature=0.3,
)

print(response.choices[0].message.content)

Copias de seguridad y mantenimiento

El peso del modelo se puede descargar de nuevo, por lo que no es el principal objeto de copia de seguridad. Son críticos los archivos .env, compose.yml, Caddyfile, los datos TLS de Caddy y los scripts de mantenimiento. Si añade RAG, bases de datos de búsqueda vectorial, archivos de usuario o adaptadores LoRA propios, deberá incluirlos en un plan de copias de seguridad independiente.

Qué conservar

Datos	Se debe hacer copia de seguridad	Motivo
.env	Sí, con cifrado	Contiene la clave API y la configuración del modelo
compose.yml, Caddyfile	Sí	Recuperación rápida de la infraestructura
Datos de Caddy	Sí	Certificados TLS y estado de ACME
HF cache	Opcional	Ahorra tiempo de descarga, pero se restaura fácilmente
Registros de solicitudes	Normalmente no	Pueden contener prompts sensibles
Base de datos vectorial y documentos RAG	Obligatorio	Son datos empresariales únicos

Copia de seguridad con restic

Restic cifra los archivos antes de enviarlos a un almacenamiento compatible con S3, a un servidor independiente mediante SFTP o a un backend en la nube compatible. A continuación se muestra una opción con S3. No guarde la contraseña del repositorio en el mismo repositorio público de Git donde se encuentra el código de infraestructura.

# Устанавливаем restic и создаём каталог для секретов резервного копирования
sudo apt install -y restic
sudo install -d -m 700 /root/.config/restic

# Создаём файл окружения; замените значения своими S3-реквизитами
sudo tee /root/.config/restic/vllm.env > /dev/null <<'EOF'
export RESTIC_REPOSITORY="s3:https://s3.example.net/vllm-backups"
export RESTIC_PASSWORD="CHANGE_THIS_TO_A_LONG_UNIQUE_SECRET"
export AWS_ACCESS_KEY_ID="CHANGE_ME"
export AWS_SECRET_ACCESS_KEY="CHANGE_ME"
EOF
sudo chmod 600 /root/.config/restic/vllm.env

# Инициализируем зашифрованный репозиторий один раз
sudo bash -c 'source /root/.config/restic/vllm.env && restic init'

# Создаём ежедневный скрипт: конфиги и сертификаты сохраняются, кеш модели исключается
sudo tee /opt/vllm/scripts/backup.sh > /dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

source /root/.config/restic/vllm.env

restic backup /opt/vllm \
  --exclude /opt/vllm/data/hf-cache \
  --exclude /opt/vllm/backups \
  --tag vllm-config

restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune
restic check
EOF
sudo chmod 700 /opt/vllm/scripts/backup.sh

# Выполняем первый бэкап вручную и убеждаемся, что он завершается без ошибок
sudo /opt/vllm/scripts/backup.sh

# Запускаем бэкап ежедневно в 03:20 и сохраняем технический журнал в syslog
sudo crontab -e

# Добавьте следующую строку в открывшийся файл:
20 3    /opt/vllm/scripts/backup.sh >> /var/log/vllm-backup.log 2>&1

Compruebe no solo el estado exitoso de la copia de seguridad, sino también la restauración. Una vez por trimestre, despliegue las configuraciones en una máquina de prueba o ejecute restic restore latest --target /tmp/vllm-restore sin sobrescribir los datos de producción.

Actualizaciones sin sorpresas

Para un servidor con una sola GPU, es más seguro usar una ventana de mantenimiento: detenga la API, actualice la imagen, iníciela y ejecute una solicitud de prueba. Una rolling update tiene sentido con dos o más réplicas detrás de un balanceador, cuando se pueden retirar los servidores del tráfico uno a uno.

# Перед обновлением фиксируем текущий статус и делаем бэкап
cd /opt/vllm
docker compose -f compose.yml ps
sudo /opt/vllm/scripts/backup.sh

# После изменения тега образа в compose.yml перезапускаем только сервисы проекта
docker compose -f compose.yml pull
docker compose -f compose.yml up -d
docker compose -f compose.yml logs --tail=100 vllm

No actualice simultáneamente Ubuntu, el controlador NVIDIA, Docker, las imágenes base de CUDA y vLLM antes de un lanzamiento importante. Cambie una capa cada vez, fije la versión, compruebe nvidia-smi y luego realice una prueba de humo de la API.

Solución de problemas + FAQ

¿Por qué el contenedor vLLM no detecta la GPU?

Si los registros muestran un mensaje sobre un dispositivo CUDA no disponible, primero ejecute nvidia-smi en el host. Si no funciona, el problema está en el controlador o en el GPU passthrough. Si la GPU es visible en el host pero no en Docker, compruebe el comando docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi. Reinstale NVIDIA Container Toolkit, ejecute sudo nvidia-ctk runtime configure --runtime=docker y reinicie Docker.

Error CUDA out of memory al cargar el modelo: ¿qué hacer?

El error CUDA out of memory significa que no hay suficiente VRAM para los pesos, la caché KV o los búferes de servicio. Primero reduzca VLLM_MAX_MODEL_LEN, por ejemplo de 8192 a 4096, y baje GPU_MEMORY_UTILIZATION a 0.80. Luego utilice un modelo más pequeño o cuantizado AWQ/GPTQ compatible con vLLM. Consulte nvidia-smi: es posible que la memoria esté ocupada por otro contenedor o un proceso bloqueado.

La API devuelve 401 Unauthorized, aunque la clave parece correcta

Compruebe que el encabezado se envía en el formato Authorization: Bearer SU_CLAVE, sin comillas ni espacios adicionales. Luego compare la clave con el contenido de /opt/vllm/.env. Después de modificar .env es necesario reiniciar: docker compose -f compose.yml up -d --force-recreate vllm. No utilice una variable con un valor vacío de otra sesión de shell; ejecute source /opt/vllm/.env antes de curl.

¿Por qué Caddy no emite un certificado HTTPS?

Con mayor frecuencia, el registro DNS del dominio todavía no apunta a la IP del servidor o el puerto 80 está bloqueado por el firewall en la nube. Compruebe dig +short llm.example.com, luego sudo ufw status y las reglas de red en el panel del servidor. Consulte docker logs vllm-caddy: allí estará la causa del error ACME. Para la validación HTTP-01, el dominio debe ser accesible externamente por el puerto 80, incluso si la API principal funciona solo mediante HTTPS.

El modelo responde demasiado lento. ¿Qué comprobar?

Divida la latencia entre el tiempo hasta el primer token y la velocidad de generación. Compruebe la utilización de la GPU y la VRAM mediante watch -n 1 nvidia-smi, los registros de vLLM y la carga de la CPU. Un contexto demasiado largo, una alta concurrencia y los modelos de razonamiento aumentan la latencia. Reduzca max_tokens, limite el contexto y active el modo de streaming stream: true en el cliente. Si la GPU está inactiva, asegúrese de que las solicitudes realmente llegan a vLLM y no están bloqueadas por el proxy o la aplicación.

¿Qué configuración de VPS es mínimamente adecuada?

Para una API educativa o personal con un modelo de 7B–8B en 4-bit, la opción mínima razonable es una GPU NVIDIA con 16 GB de VRAM, 4–8 vCPU, 32 GB de RAM y 100 GB de NVMe. Sin embargo, es más cómodo comenzar con 24 GB de VRAM: esto deja margen para el contexto y varias solicitudes simultáneas. Para pesos FP16 de un modelo 8B, 16 GB normalmente no son suficientes, ya que la memoria no se necesita solo para los propios pesos.

¿Qué elegir: VPS o dedicated para esta tarea?

Para una sola GPU, modelos de hasta 8B–14B y una API interna, elija un VPS con GPU si la plataforma garantiza acceso al acelerador y permite ejecutar Docker. Se necesita un dedicated para varias GPU, 48–80 GB de VRAM, modelos 32B–70B, alta carga constante y requisitos estrictos de aislamiento. Comience con un VPS, mida los tokens reales por segundo, la concurrencia máxima y la VRAM, y después migre a hardware dedicado cuando exista una necesidad confirmada.

¿Se puede exponer la API directamente en el puerto 8000?

Técnicamente es posible, pero para producción es una mala práctica. HTTP directo no cifra el token Bearer ni el contenido de los prompts, y es más fácil dejar el puerto expuesto accidentalmente sin restricciones. Mantenga 127.0.0.1:8000:8000 en Compose y publique externamente solo Caddy en el puerto 443. Si la API es solo para usted, es aún más seguro no abrir el 443 en absoluto y conectarse mediante WireGuard o un túnel SSH.

¿Cómo cambiar el modelo sin reconfigurar todo el servidor?

Modifique MODEL_NAME y, si es necesario, SERVED_MODEL_NAME en .env, luego reinicie el contenedor con el comando docker compose -f compose.yml up -d --force-recreate vllm. Tenga en cuenta los requisitos del nuevo modelo respecto a VRAM, chat template, licencia y token de Hugging Face. Puede conservar la caché antigua: no interfiere con el funcionamiento, pero ocupa espacio en disco. Antes de sustituir el modelo, guarde la configuración actual y pruebe la nueva opción en una ventana de mantenimiento independiente.

Conclusiones y próximos pasos

Ahora dispone de su propia API compatible con OpenAI basada en vLLM: el modelo funciona en una GPU dedicada, la API está protegida por token y TLS, y la configuración es reproducible mediante Docker Compose. Esta arquitectura es adecuada para asistentes internos, sistemas RAG, automatización del desarrollo y aplicaciones privadas de IA.

1. Mida la carga real: tokens por segundo, tiempo hasta el primer token, VRAM y número de solicitudes simultáneas.
2. Agregue un API gateway con claves separadas, rate limit y métricas si varias equipos o clientes utilizan el servicio.
3. Para buscar en documentos, conecte un modelo de embedding y una base de datos vectorial; para aumentar la carga, implemente varias réplicas de vLLM detrás de un balanceador.