Docker vLLM: Ejecute un servidor de inferencia acelerado por 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. La ruta más rápida: instale la Herramienta de contenedores de NVIDIA en el host y luego ejecute la imagen con --gpus all y un identificador de modelo de Hugging Face. Una vez descargado 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 o posterior — Docker Desktop en Windows y macOS funciona mediante el backend WSL2.
• GPU de NVIDIA con un controlador que admita CUDA 12.x. Ejecute nvidia-smi para confirmarlo; la «versión de CUDA» mostrada es la máxima que admite su controlador.
• Herramienta de contenedores de NVIDIA — el puente que permite a Docker detectar la GPU. Consulte la siguiente sección.
• Suficiente VRAM para su modelo objetivo. Utilice la Calculadora de VRAM herramienta de cálculo de memoria de vLLM

Instalación de la Herramienta de contenedores de NVIDIA

Omita esta sección si docker run --gpus all nvidia/cuda:12.0-base nvidia-smi ya funciona en su equipo.

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: Reemplace la URL del repositorio deb por su equivalente rpm en la documentación de NVIDIA y use dnf en lugar de apt-get.

Windows (WSL2): Instale el controlador NVIDIA para Windows en el sistema anfitrión; no es necesario instalar por separado el kit de herramientas para contenedores dentro de WSL2. Docker Desktop gestiona automáticamente la transmisión directa (passthrough).

macOS: Las GPUs de NVIDIA no son compatibles con macOS. vLLM no se ejecuta en Apple Silicon mediante Docker con aceleración GPU. Para inferencia local en hardware Apple, considere una compilación exclusiva para CPU o un entorno de ejecución alternativo.

Comando mínimo de ejecución

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

Para descargar un modelo restringido (Llama 3, Mistral, etc.), también pase -e HUGGING_FACE_HUB_TOKEN=hf_yourtoken. Guarde el token en un archivo .env y páselo mediante --env-file .env en lugar de incluirlo directamente en el historial de su shell.

Montaje de la caché de Hugging Face

vLLM descarga los pesos del modelo en /root/.cache/huggingface dentro del contenedor. Sin un montaje de volumen, cada ejecución de docker run vuelve a descargar íntegramente el modelo —habitualmente entre 5 y 80 GB—. La línea de montaje es:

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

Si sus modelos se encuentran en una ubicación distinta de la predeterminada, establezca -e HF_HOME=/su/ruta y monte esa ruta en su lugar. Para entornos sin conexión a Internet (air-gapped), descargue primero el modelo con huggingface-cli download y luego pase --model /ruta/en/el/contenedor junto con un volumen montado que contenga el directorio de pesos del modelo.

Parámetros clave del servidor vLLM

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

¿No está seguro de si su GPU dispone de suficiente VRAM para un modelo determinado? La Guía de requisitos de VRAM lista modelos comunes Calculadora de VRAM le permite ingresar la cuantización y el tamaño de lote. Para tomar decisiones sobre la adquisición de hardware, consulte la guía de recomendaciones de GPU.

Exposición y prueba del punto final compatible con OpenAI

Una vez que el contenedor muestre INFO: Application startup complete, la API estará disponible.

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

# Completado 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}'

# Completado 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, LangChain, LlamaIndex — funciona configurando openai base_url="http://localhost:8000/v1" y proporcionando cualquier cadena no vacía como api_key. api_key.

Ejemplo de Docker Compose

Para despliegues persistentes, un archivo Compose resulta más fácil de administrar que un comando largo de 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.

Errores comunes y soluciones

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, aunque el rendimiento será varios órdenes de magnitud más lento y no resulta práctico para servicios. Para inferencia local exclusivamente en CPU, alternativas más adecuadas son llama.cpp u Ollama; consulte la 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.