vLLM Docker: Ejecuta un Servidor de Inferencia con GPU en Minutos

vLLM publica una imagen oficial de Docker, vllm/vllm-openai, que incluye un servidor de inferencia compatible con OpenAI listo para usar. El camino más rápido: instala el NVIDIA Container Toolkit en el host, luego ejecuta la imagen con --gpus all y un ID de modelo de Hugging Face. Una vez que se descargue el modelo, el servidor estará activo en el puerto 8000 y aceptará las mismas solicitudes que la API de OpenAI.

Requisitos previos

• Docker Engine 20.10+ — Docker Desktop en Windows y macOS funciona a través del backend WSL2.
• GPU de NVIDIA con un driver que admita CUDA 12.x. Ejecuta nvidia-smi para confirmar; la «CUDA Version» mostrada es la máxima que tu driver admite.
• Herramienta de contenedores de NVIDIA — el puente que permite a Docker ver la GPU. Consulta la siguiente sección.
• Suficiente VRAM para tu modelo objetivo. Usa Calculadora de VRAM para verificar antes de comprometerte con una descarga de modelo.

Instalación del NVIDIA Container Toolkit

Salta esta sección si docker run --gpus all nvidia/cuda:12.0-base nvidia-smi ya funciona en tu máquina.

Linux (Ubuntu/Debian):

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-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

RHEL/CentOS: Reemplaza la deb URL del repositorio con el equivalente rpm de la documentación de NVIDIA y usa dnf en lugar de apt-get.

Windows (WSL2): Instala el driver NVIDIA para Windows en el host — no se necesita una instalación separada del toolkit del contenedor dentro de WSL2. Docker Desktop maneja el paso automáticamente.

macOS: Las GPU NVIDIA no son compatibles en macOS. vLLM no se ejecuta en Apple Silicon a través de Docker con aceleración de GPU. Para inferencia local en hardware Apple, considera una compilación solo CPU o un runtime diferente.

El Comando de Ejecución Mínimo

docker run --runtime nvidia --gpus all 
  --ipc=host 
  -v ~/.cache/huggingface:/root/.cache/huggingface 
  -p 8000:8000 
  vllm/vllm-openai:latest 
  --model meta-llama/Meta-Llama-3-8B-Instruct

Marcar	Por qué es importante
--runtime nvidia	Enruta las llamadas de GPU a través del runtime del contenedor NVIDIA.
--gpus all	Expone todas las GPU del host. Usar "device=0,1" para apuntar a GPU específicas.
--ipc=host	Comparte el espacio de nombres IPC del host. Requerido para memoria compartida de PyTorch; omitirlo causa un Bus error o un fallo de memoria compartida.
-v ~/.cache/huggingface:…	Monta la caché HF del host para que los pesos persistan después de reiniciar el contenedor.
-p 8000:8000	Expone el servidor compatible con OpenAI en el host.
--model	Cualquier ID de modelo de Hugging Face o una ruta local montada en el contenedor.

Para extraer un modelo restringido (Llama 3, Mistral, etc.), también pasa -e HUGGING_FACE_HUB_TOKEN=hf_yourtoken. Guarda el token en un .env archivo y pásalo con --env-file .env en lugar de incluirlo directamente en tu historial de shell.

Montaje de la Caché de Hugging Face

vLLM descarga los pesos del modelo a /root/.cache/huggingface dentro del contenedor. Sin un montaje de volumen, cada docker run descarga el modelo completo de nuevo — a menudo 5–80 GB. La línea de montaje es:

-v ~/.cache/huggingface:/root/.cache/huggingface

Si tus modelos están en una ubicación no predeterminada, establece -e HF_HOME=/your/path y monta esa ruta en su lugar. Para entornos aislados, descarga el modelo con huggingface-cli download primero, luego pasa --model /path/in/container junto con un montaje de volumen del directorio de pesos.

Banderas Clave del Servidor vLLM

Estas banderas se pasan después del nombre de la imagen — son argumentos para el proceso del servidor vLLM, no para Docker.

Marcar	Predeterminado	Cuándo cambiarla
--tensor-parallel-size N	1	Establécelo al número de GPUs para servicio multi-GPU. Las cabezas de atención del modelo deben ser divisibles por N. Combina con --gpus "device=0,1,..." listando exactamente N dispositivos.
--gpu-memory-utilization 0.X	0.90	Reduce a 0.75–0.80 si ves errores OOM o compartes la GPU con otros procesos.
--max-model-len N	Configuración del modelo	Limita el tamaño de la caché KV. Útil cuando el contexto predeterminado de un modelo (p. ej. 128 k) agotaría VRAM. Prueba --max-model-len 8192 como una primera reducción.
--dtype auto	automático	Anula con bfloat16 o float16 si la detección automática elige una precisión inesperada.
--quantization awq / gptq	none	Habilita variantes de modelos pre-cuantificados. Reduce aproximadamente a la mitad VRAM con algún costo de calidad.
--port	8000	Cambia si 8000 ya está ocupado en el host.

¿No estás seguro de si tu GPU tiene suficiente VRAM para un modelo dado? La guía de requisitos de VRAM lista modelos comunes, y la Calculadora de VRAM te permite ingresar la cuantificación y el tamaño del lote. Para decisiones de compra de hardware, consulta la guía de recomendaciones de GPU.

Exposición y Prueba del Punto Final Compatible con OpenAI

Una vez que el contenedor imprime INFO: Application startup complete, la API está en vivo.

# Listar modelos cargados
curl http://localhost:8000/v1/models

# Finalización de texto
curl http://localhost:8000/v1/completions 
  -H "Content-Type: application/json" 
  -d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "prompt": "La capital de Francia es", "max_tokens": 20}'

# Finalización de chat
curl http://localhost:8000/v1/chat/completions 
  -H "Content-Type: application/json" 
  -d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "messages": [{"role": "user", "content": "Hola"}]}'

Cualquier cliente compatible con OpenAI — el SDK de Python openai , LangChain, LlamaIndex — funciona configurando base_url="http://localhost:8000/v1" y proporcionando cualquier cadena no vacía como api_key.

Ejemplo de Docker Compose

Para despliegues persistentes, un archivo Compose es más fácil de gestionar que un docker run docker run:

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    ports:
      - "8000:8000"
    ipc: host
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    command: >
      --model meta-llama/Meta-Llama-3-8B-Instruct
      --gpu-memory-utilization 0.90
      --max-model-len 8192

Comience con docker compose up -d. El bloque deploy.resources equivale en Compose v3 a la opción --gpus all.

Fallos Comunes y Soluciones

Error	Causa	Corregir
Bus error o /dev/shm demasiado pequeño	El tamaño predeterminado de Docker para /dev/shm es de 64 MB, lo cual es insuficiente para PyTorch.	Agregue --ipc=host --ipc=host --shm-size=8g si no puede compartir el espacio de nombres IPC del host.
Error de CUDA: ninguna imagen de kernel disponible	La versión de CUDA compilada en la imagen vLLM supera la versión compatible con su controlador.	Ejecutar nvidia-smi Ejecute nvidia-smi).
torch.cuda.OutOfMemoryError	Los pesos del modelo más la caché KV superan la VRAM disponible.	Pruebe --max-model-len 4096 primero. Luego reduzca --gpu-memory-utilization a 0,80. Si sigue apareciendo el error OOM, utilice una variante cuantizada o una GPU más grande.
permiso denegado en el directorio de caché	El contenedor se ejecuta como root; el directorio del host pertenece a otro usuario.	Ejecutar chmod -R a+rw ~/.cache/huggingface en el host o use un volumen nombrado de Docker en lugar de un montaje vinculado (bind mount).
El contenedor inicia pero curl devuelve «connection refused»	El modelo aún se está cargando o -p 8000:8000 falta.	Espere la línea de registro Application startup complete . Verifique que la asignación de puertos esté presente en su comando de ejecución.

Preguntas Frecuentes

¿Qué etiqueta de imagen Docker de vLLM debo usar?

vllm/vllm-openai:latest se actualiza con la versión más reciente y es adecuada para experimentación. Para entornos de producción, fije la imagen a una etiqueta de versión específica (por ejemplo, v0.6.0) para garantizar la reproducibilidad de las compilaciones. Cada etiqueta de versión publicada en Docker Hub indica la versión de CUDA contra la que se compiló, la cual debe ser menor o igual a la versión compatible con su controlador.

¿Puedo ejecutar vLLM en Docker sin GPU?

La imagen estándar requiere una GPU NVIDIA. Es posible realizar inferencia únicamente en CPU compilando vLLM desde el código fuente con VLLM_TARGET_DEVICE=cpu, but throughput is orders of magnitude slower and not practical for serving. For CPU-only local inference, llama.cpp or Ollama are more suitable alternatives — see the Guía de Ollama para compararlas.

¿Cómo ejecuto un modelo restringido que requiere un token de Hugging Face?

Pase el token como variable de entorno: -e HUGGING_FACE_HUB_TOKEN=hf_yourtoken. Guárdelo en un archivo .env y haga referencia a él mediante --env-file .env para evitar que se registre en el historial de la shell. El servidor lo utiliza durante la descarga inicial del modelo; no es necesario una vez que los pesos se hayan almacenado localmente en caché.

¿Qué hace el parámetro –tensor-parallel-size y cuándo lo necesito?

La paralelización por tensores divide las matrices de pesos del modelo entre varias GPUs, permitiendo ejecutar modelos demasiado grandes para una sola tarjeta. Establézcalo al número de GPUs que desea utilizar (2 o 4 son valores comunes). Dicho número debe coincidir con la cantidad de GPUs especificada en --gpus, y el número de cabezas de atención del modelo debe ser divisible por ese valor.

¿Es rentable ejecutar vLLM en Docker comparado con una API gestionada?

Depende completamente del volumen de solicitudes. El alojamiento propio implica altos costos fijos (instancia GPU o hardware), pero un costo marginal casi nulo por solicitud. Las APIs gestionadas no tienen costos fijos, pero cobran por token. Utilice la calculadora de autohospedaje frente a API para determinar su punto de equilibrio antes de comprometerse con la infraestructura.

¿Cómo sirvo varios modelos simultáneamente?

Ejecute un contenedor por modelo, cada uno asignado a un puerto distinto del host (por ejemplo, 8000, 8001). Actualmente vLLM no admite servir múltiples modelos desde un único proceso. Coloque un proxy inverso como nginx o Caddy delante de los contenedores para enrutar las solicitudes según el nombre del modelo al puerto correspondiente.