vLLM Docker: arquitectura, rendimiento y guía de despliegue en la nube

vLLM Docker: arquitectura, rendimiento y guía de despliegue en la nube

Docker es la forma más directa de poner vLLM detrás de un endpoint compatible con OpenAI en GPU que usted controla. Sin embargo, un buen despliegue de vLLM Docker no consiste solo en un comando docker run: necesita un runtime de GPU compatible, un plan con límites definidos de memoria y concurrencia, autenticación en el perímetro y un método reproducible para probar el rendimiento antes de que llegue el tráfico.

Esta guía explica la arquitectura, un primer despliegue seguro, los parámetros que realmente modifican la capacidad y el camino desde una sola GPU hasta una flota de GPU en la nube.

Use vLLM Docker cuando necesite controlar los pesos del modelo, la ubicación del despliegue, la configuración del runtime o una carga de trabajo estable autoalojada. Si el coste operativo supera el valor de ese control, una API de modelos gestionada o una puerta de enlace unificada suele ser una mejor opción.

Qué le ofrece vLLM Docker

vLLM publica una imagen oficial de Docker, vllm/vllm-openai, que inicia un servidor compatible con OpenAI. Esto convierte a vLLM Docker en un puente útil entre un repositorio de modelos y las aplicaciones que ya utilizan el formato de cliente de OpenAI: la disponibilidad del listado de modelos, las completaciones de chat, las completaciones, los embeddings y otros endpoints compatibles relacionados depende del modelo y de la versión del servidor que despliegue. La documentación de Docker de vLLM incluye la imagen actual y ejemplos de configuración del runtime.

La implicación práctica es sencilla: su aplicación no debería necesitar un cliente a medida para el servidor de modelos solo porque traslade una carga de trabajo a su propia GPU. No obstante, sí necesita un nombre de modelo explícito, una clave API, un tiempo de espera y un comportamiento de reintento que se ajusten a su objetivo de disponibilidad.

Cómo funciona la arquitectura de vLLM Docker

A grandes rasgos, vLLM Docker tiene cinco capas:

1. Su cliente envía una solicitud autenticada a un endpoint compatible con OpenAI.
2. El servidor de API valida y tokeniza la solicitud y, a continuación, la entrega al motor de vLLM.
3. El planificador agrupa en lotes las tareas compatibles y las distribuye a uno o más procesos de trabajo de GPU.
4. Los procesos de trabajo de GPU mantienen los pesos del modelo y la caché de clave-valor (KV) mientras generan tokens.
5. La respuesta se transmite de vuelta al cliente a través del servidor de API.

La idea central para el rendimiento es PagedAttention. En lugar de reservar una gran región contigua de caché KV para la longitud máxima posible de una solicitud, vLLM gestiona el estado KV en bloques. Esto facilita distribuir las cargas de trabajo de longitud variable en la memoria disponible y permite que las solicitudes completadas liberen bloques para tareas posteriores. El artículo original sobre PagedAttention describe el planificador, los procesos de trabajo de GPU, la correspondencia entre bloques KV lógicos y físicos, y el equilibrio entre la utilización de la caché y el procesamiento por lotes.

Esta arquitectura tiene una consecuencia operativa importante: la VRAM no es solo el «tamaño del modelo». Se comparte entre los pesos del modelo, la sobrecarga del runtime, las activaciones y una caché KV cuya demanda crece con la longitud del contexto y las solicitudes simultáneas. Considere el contexto, la concurrencia y la utilización de memoria como una sola decisión, no como tres tareas de ajuste independientes.

Antes de ejecutar vLLM Docker en una GPU en la nube

Comience con cuatro comprobaciones:

1. Elija una etiqueta de imagen probada. Fije una etiqueta de versión de vLLM en producción en lugar de seguir a ciegas latest. Lea la documentación correspondiente a esa etiqueta antes de depender de un indicador o de un valor predeterminado.
2. Use un modelo que tenga permiso para descargar y servir. Algunos repositorios requieren un token de Hugging Face o la aceptación de una licencia del modelo. Fije la revisión del modelo después de validarla.
3. Compruebe el acceso a la GPU fuera del contenedor del modelo. Instale el controlador NVIDIA en el host y NVIDIA Container Toolkit y, a continuación, valide un contenedor con acceso a la GPU mediante nvidia-smi. La guía de instalación de NVIDIA explica los requisitos previos del host y la configuración del runtime.
4. Mantenga el puerto privado al principio. Vincúlelo a la interfaz de bucle local para una prueba de concepto en un solo host, o mantenga el servicio en una subred privada detrás de TLS, autenticación y un proxy inverso o balanceador de carga. No considere el servidor de modelos sin protección como un perímetro de seguridad expuesto a Internet.

Use el comando de ejemplo de NVIDIA antes de depurar vLLM:

docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

Si ese comando no detecta la GPU esperada, deténgase ahí. Un registro del servidor de modelos no solucionará la falta de un controlador, un runtime de contenedores sin configurar o una GPU que nunca se asignó a la máquina virtual en la nube.

Ejecutar un servidor vLLM Docker con una sola GPU

Lo siguiente es un punto de partida deliberadamente pequeño. Refleja el patrón de imagen oficial, pero añade una clave de API y vincula el puerto publicado a la interfaz de bucle local. Sustituya los marcadores de posición por un modelo y una etiqueta de imagen que haya probado.

export HF_TOKEN="your_hugging_face_token"
export VLLM_API_KEY="replace-with-a-long-random-secret"
export VLLM_IMAGE="vllm/vllm-openai:<tested-version>"
export MODEL="Qwen/Qwen3-0.6B"

docker run -d \
  --name vllm-api \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --dtype auto \
  --api-key "$VLLM_API_KEY"

La configuración de memoria compartida y el montaje de caché de Hugging Face siguen el ejemplo oficial de vLLM Docker. El montaje de caché evita descargar de nuevo los mismos pesos del modelo cuando se recrea el contenedor. La clave de API es un control de aplicación, no un sustituto del aislamiento de red, TLS, límites de velocidad ni un gestor de secretos.

Verifique que el servidor esté sirviendo el modelo esperado antes de conectar una aplicación:

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/models \
  -H "Authorization: Bearer $VLLM_API_KEY"

Después, envíe una solicitud pequeña con el mismo identificador de modelo que devuelve /v1/models:

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $VLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [{"role": "user", "content": "Reply with the word ready."}],
    "max_tokens": 16
  }'

Si su modelo no incluye una plantilla de chat utilizable, las solicitudes de finalización de chat pueden fallar incluso cuando el contenedor se haya iniciado. vLLM documenta cómo proporcionar --chat-template para modelos cuya configuración de tokenizador no incluye una; pruebe esto antes de desplegar una aplicación. Consulte la guía sobre plantillas de chat.

Defina el rango de rendimiento antes de cambiar las opciones

No existe un comando vLLM Docker universalmente correcto. La configuración adecuada depende de la arquitectura del modelo, el tipo y la memoria de la GPU, la distribución de longitudes de entrada/salida, la concurrencia y el objetivo de latencia. Establezca una línea de base con una carga de trabajo representativa y, después, cambie una variable a la vez.

Capture al menos estas mediciones:

• Tasa de éxito/error de solicitudes y eventos de reinicio/OOM.
• Tiempo hasta el primer token (TTFT) y tiempo por token de salida (TPOT), segmentados por longitud del prompt.
• Latencia de extremo a extremo en p50 y p95/p99 con la concurrencia esperada.
• Tokens de entrada, tokens de salida, tiempo en cola, solicitudes activas y uso de memoria de GPU.
• Rendimiento solo junto con el objetivo de latencia y calidad que cumplió.

Las opciones de vLLM Docker que modifican sustancialmente la capacidad

Los valores predeterminados y el comportamiento exactos de las opciones dependen de la versión. La referencia actual de argumentos del motor de vLLM define los controles del planificador, la caché, el paralelismo y la cola; su referencia de configuración de caché explica las opciones de utilización de memoria y caché de prefijos.

Un orden práctico de ajuste

1. Establezca un valor realista para --max-model-len a partir de los límites de la aplicación.
2. Comience de forma conservadora con la utilización de memoria y deje margen para la sobrecarga del controlador/entorno de ejecución.
3. Realice pruebas de carga de --max-num-seqs y --max-num-batched-tokens con longitudes reales de prompts y completados.
4. Añada paralelismo de tensores solo cuando una GPU no pueda alojar el modelo o cumplir el objetivo para este.
5. Añada réplicas detrás de un equilibrador de carga cuando las necesidades de disponibilidad o tráfico agregado requieran dominios de fallo independientes.

Esta secuencia evita un error común: añadir GPU o aumentar la concurrencia antes de saber si la carga de trabajo está realmente limitada por el contexto, la cola, la memoria o el cómputo.

Escale vLLM Docker en varias GPU

Para un modelo que necesita varias GPU, vLLM admite el servicio con paralelismo de tensores y de canalización. En un host, exponga las GPU al contenedor y establezca el tamaño de paralelismo de tensores en el número de GPU que asigne deliberadamente a ese servidor de modelos:

docker run -d \
  --name vllm-tp \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --tensor-parallel-size 4 \
  --api-key "$VLLM_API_KEY"

La guía de paralelismo y escalado de vLLM documenta el paralelismo de tensores, el paralelismo de canalización y las opciones de ejecución en un solo nodo frente a varios nodos. No copie el valor 4 del ejemplo en un nodo con dos GPU: ajuste la opción a las GPU asignadas a este servidor y valide la topología de comunicación, el equilibrio de memoria y el comportamiento ante fallos.

Para conocer los detalles de implementación, las comprobaciones de topología y cómo decidir entre paralelismo de tensores y de canalización, consulte la guía de inferencia vLLM con varias GPU de Flatkey. Para tomar una decisión sobre el entorno de ejecución de serving, en lugar de una decisión de despliegue con Docker, consulte vLLM frente a SGLang.

Estructura de un despliegue en la nube para producción

Un despliegue de vLLM Docker en producción normalmente separa el perímetro público de la ejecución en GPU:

Coloque la caché de Hugging Face en almacenamiento duradero o precalentado intencionadamente para que un reinicio normal no se convierta en una descarga inesperada del modelo. Mantenga la licencia y los controles de acceso del modelo en el registro de despliegue. Fijar únicamente la etiqueta de imagen no es suficiente si el repositorio del modelo apunta a una rama cambiante.

Para obtener contexto sobre la selección de GPU, la planificación de memoria basada en el contexto y cuándo la infraestructura en la nube es adecuada, vincule este manual operativo con la guía de requisitos de memoria GPU para LLM, la guía de GPU en la nube y el marco comparativo de GPU en la nube frente a API de modelos de Flatkey.

Solución de problemas de vLLM Docker sin adivinar

Cuando el servidor se ejecuta, pero el comportamiento de la aplicación sigue siendo diferente al de una API alojada, confirme explícitamente la compatibilidad de los endpoints y los parámetros. La guía de Flatkey sobre servidores de inferencia compatibles con OpenAI cubre la migración del lado del cliente y la superficie de pruebas de compatibilidad.

Cuándo no operar vLLM Docker por su cuenta

El autoalojamiento es un compromiso de infraestructura. Usted se encarga de las actualizaciones de imágenes, la procedencia del modelo, la capacidad de GPU, los fallos de nodos, el control de acceso, la validación de latencia y el proceso de guardia. Puede ser la decisión adecuada cuando el requisito es el control del tiempo de ejecución.

Para cargas de trabajo en las que la elección del modelo, la disponibilidad del proveedor o la simplicidad operativa importan más que el control directo de las GPU, mantenga una ruta de API administrada en la arquitectura. Flatkey está diseñado para el flujo de trabajo complementario: una única integración compatible con OpenAI para acceder a modelos de distintos proveedores con facturación centralizada, mientras que un endpoint de vLLM autoalojado sigue siendo una opción para las cargas de trabajo que realmente lo necesitan.

El siguiente paso correcto no es maximizar un benchmark de forma aislada. Antes de poner vLLM Docker detrás de tráfico de producción, fije la imagen y el modelo, compruebe el tiempo de ejecución de la GPU, establezca una política explícita de contexto y cola, pruebe con solicitudes similares a las de producción y documente la ruta de fallo.

Preguntas frecuentes

¿vLLM Docker es lo mismo que una API de LLM administrada?

No. vLLM Docker le proporciona un entorno de servicio de modelos en GPU que usted opera. Una API administrada abstrae el alojamiento de modelos y las operaciones de GPU. Ambos pueden exponer una interfaz de cliente compatible con OpenAI, pero la responsabilidad operativa es diferente.

¿vLLM Docker necesita NVIDIA Container Toolkit?

Para contenedores con GPU NVIDIA, el host necesita un controlador NVIDIA compatible y un tiempo de ejecución de contenedores de GPU configurado. NVIDIA Container Toolkit es la ruta estándar documentada por NVIDIA para poner las GPU a disposición de los contenedores Docker.

¿Qué opción de vLLM Docker debo ajustar primero?

Primero establezca una longitud máxima de contexto realista y, después, pruebe la utilización de memoria, la concurrencia y los límites de tokens por lote con una combinación representativa de solicitudes. Cambiar opciones sin una línea de base de la carga de trabajo produce, en su mayoría, resultados irrepetibles.

¿Puede vLLM Docker ejecutar un modelo en varias GPU?

Sí. vLLM admite servicio con paralelismo de tensor y paralelismo de canalización. Comience con un único host y valide el número exacto de GPU, la topología y el comportamiento de comunicación antes de ampliar el diseño.

Fuentes y lecturas adicionales

• vLLM: Uso de Docker
• vLLM: Paralelismo y escalado
• vLLM: Argumentos del motor
• Guía de instalación de NVIDIA Container Toolkit
• Gestión eficiente de memoria para el servicio de modelos de lenguaje grandes con PagedAttention