Inicio rápido de vLLM: Servicio de alto rendimiento de LLM en 2026

Instala, sirve y ajusta vLLM en 2026

Índice

vLLM es un motor de inferencia y servicio de alto rendimiento y eficiente en memoria para Modelos de Lenguaje Grandes (LLMs), desarrollado por el Sky Computing Lab de UC Berkeley.

Su algoritmo PagedAttention trata la caché KV como páginas de memoria virtual del sistema operativo y lo combina con el loteria continua (continuous batching); la combinación que hizo de vLLM el motor predeterminado para el servicio de LLMs en producción. Para ver cómo encaja vLLM entre Ollama, Docker Model Runner, LocalAI y los proveedores en la nube, incluidos los compromisos de costos e infraestructura, consulte Alojamiento de LLMs: Infraestructura local, autoalojada y en la nube comparada.

vllm logo

Esta guía está actualizada según la versión v0.31.0 de vLLM (octubre de 2026). Dos cosas cambiaron recientemente si proviene de tutoriales más antiguos: python -m vllm.entrypoints.openai.api_server está deprecated y emite una advertencia — vllm serve es ahora el CLI estándar — y las ruedas precompiladas (prebuilt wheels) apuntan a CUDA 12.9 por defecto, no a 11.8.

¿Qué es vLLM?

vLLM (LLM virtual) es una biblioteca de código abierto para la inferencia y el servicio rápido de LLMs que se ha convertido rápidamente en el estándar de la industria para despliegues de producción. Lanzada en 2023, introdujo PagedAttention, una técnica revolucionaria de gestión de memoria que mejora drásticamente la eficiencia del servicio.

Características clave

Rendimiento de alto rendimiento (High Throughput): Las pruebas de rendimiento de la época de lanzamiento de vLLM reportaron un rendimiento 14-24 veces superior al de HuggingFace Transformers en el mismo hardware, y el motor ha mantenido esa ventaja mediante la lotería continua, kernels de CUDA optimizados y el algoritmo PagedAttention que elimina la fragmentación de memoria.

Compatibilidad con la API de OpenAI: vLLM incluye un servidor API integrado que es totalmente compatible con el formato de OpenAI. Esto permite una migración sin problemas desde OpenAI a infraestructura autoalojada sin cambiar el código de la aplicación. Simplemente apunte su cliente API al punto de acceso (endpoint) de vLLM y funcionará de manera transparente.

Algoritmo PagedAttention: La innovación central detrás del rendimiento de vLLM es PagedAttention, que aplica el concepto de paginación de memoria virtual a los mecanismos de atención. En lugar de asignar bloques de memoria contiguos para las cachés KV (lo que lleva a la fragmentación), PagedAttention divide la memoria en bloques de tamaño fijo que pueden asignarse bajo demanda. Esto reduce el desperdicio de memoria hasta en 4 veces y permite tamaños de lote mucho mayores.

Lotería continua (Continuous Batching): A diferencia de la lotería estática, donde se espera a que todas las secuencias se completen, vLLM usa lotería continua (rodante). Tan pronto como una secuencia termina, se puede añadir una nueva al lote. Esto maximiza la utilización de la GPU y minimiza la latencia para las solicitudes entrantes.

Soporte multi-GPU: vLLM admite paralelismo de tensores (tensor parallelism) y paralelismo de pipeline (pipeline parallelism) para distribuir modelos grandes entre varias GPUs. Puede servir eficientemente modelos que no caben en la memoria de una sola GPU, admitiendo configuraciones de 2 a 8+ GPUs.

Amplio soporte de modelos: Compatible con arquitecturas de modelos populares, incluidas LLaMA, Mistral, Mixtral, Qwen, Phi, Gemma y muchas otras. Admite tanto modelos de instrucción (instruction-tuned) como modelos base desde HuggingFace Hub.

Cuándo usar vLLM

vLLM destaca en escenarios específicos donde sus fortalezas brillan:

Servicios de API de producción: Cuando necesite servir un LLM a muchos usuarios concurrentes mediante API, el alto rendimiento y la lotería eficiente de vLLM lo convierten en la mejor opción. Las empresas que ejecutan chatbots, asistentes de código o servicios de generación de contenido se benefician de su capacidad para manejar cientos de solicitudes por segundo.

Cargas de trabajo de alta concurrencia: Si su aplicación tiene muchos usuarios simultáneos haciendo solicitudes, la lotería continua y PagedAttention de vLLM permiten servir a más usuarios con el mismo hardware en comparación con las alternativas.

Optimización de costos: Cuando los costos de GPU sean una preocupación, el rendimiento superior de vLLM significa que puede servir el mismo tráfico con menos GPUs, reduciendo directamente los costos de infraestructura. La eficiencia de memoria de 4 veces de PagedAttention también permite usar instancias de GPU más pequeñas y baratas.

Despliegues en Kubernetes: El diseño sin estado (stateless) y la arquitectura amigable con contenedores de vLLM lo hacen ideal para clústeres de Kubernetes. Su rendimiento consistente bajo carga y la gestión sencilla de recursos se integran bien con la infraestructura cloud-native.

Cuándo NO usar vLLM: Para el desarrollo local, la experimentación o los escenarios de un solo usuario, herramientas como Ollama o llama.cpp ofrecen una mejor experiencia de usuario con una configuración más simple. La complejidad de vLLM está justificada cuando necesita sus ventajas de rendimiento para cargas de trabajo de producción.

Cómo instalar vLLM

Requisitos previos

Antes de instalar vLLM, asegúrese de que su sistema cumpla con estos requisitos:

  • SO: Linux con glibc 2.35 o más nuevo (Ubuntu 22.04+, Debian 12+, RHEL 9+)
  • GPU: GPU de NVIDIA con capacidad de cálculo (compute capability) 7.5 o superior (T4, A10, A100, L4, H100, B200, serie RTX 20/30/40/50). Las tarjetas más antiguas de la generación 7.0, como la V100, ya no están en la lista admitida. Las GPUs de AMD son admitidas a través de ruedas ROCm separadas — consulte ROCm frente a Vulkan para el alojamiento local de LLMs de AMD para la imagen específica de AMD, las banderas de dispositivo y las advertencias sobre la cobertura de kernels.
  • CUDA: Las ruedas pip predeterminadas se compilaron contra CUDA 12.9; las variantes 12.8 y 13.0 se publican junto a ellas. Las GPUs Blackwell (B200, GB200) requieren CUDA 12.8+. Su controlador de NVIDIA debe ser lo suficientemente nuevo para la versión de CUDA que instale.
  • Python: 3.10 a 3.13 — 3.12 es la versión recomendada (las ruedas ROCm son solo 3.12)
  • VRAM: Mínimo 16GB para modelos de 7B, 24GB+ para 13B, 40GB+ para modelos más grandes

Instalación vía pip

La instalación recomendada usa uv para crear un entorno de Python 3.12 y seleccionar automáticamente el backend de CUDA de PyTorch correspondiente (--torch-backend=auto inspecciona el controlador instalado). Para una mirada más profunda a uv en sí, consulte uv: El nuevo gestor de proyectos y entornos de paquetes de Python:

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

# Verificar instalación
python -c "import vllm; print(vllm.__version__)"

El pip plano también funciona:

python3 -m venv vllm-env
source vllm-env/bin/activate
pip install vllm

Las ruedas predeterminadas se compilan contra CUDA 12.9. Si necesita una versión diferente de CUDA, obtenga el índice de ruedas de PyTorch correspondiente — por ejemplo, CUDA 12.8:

pip install vllm --extra-index-url https://download.pytorch.org/whl/cu128

Las ruedas fijas antiguas, como vllm==0.4.2+cu121, ya no existen en esta forma. Mezclar vLLM en un entorno existente con una compilación diferente de PyTorch es una fuente común de fallos de instalación; el proyecto recomienda un entorno nuevo, y una compilación desde el código fuente (source build) cuando necesita un objetivo de CUDA personalizado.

Instalación con Docker

Docker proporciona el método de despliegue más confiable, especialmente para producción. Fije la imagen a una versión de lanzamiento (release) en lugar de latest para que las actualizaciones sean deliberadas, y tenga en cuenta que existen imágenes de variantes para CUDA 12.9 (sufijo de etiqueta -cu129), AMD ROCm (vllm-openai-rocm), CPU (vllm-openai-cpu) e Intel XPU (vllm-openai-xpu):

# Descargar la imagen oficial de vLLM
docker pull vllm/vllm-openai:v0.31.0

# Ejecutar vLLM con soporte de GPU
docker run --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:v0.31.0 \
    --model Qwen/Qwen3-8B

La bandera --ipc=host es importante para configuraciones multi-GPU, ya que habilita una comunicación interproceso adecuada.

Compilación desde el código fuente

Para las características más recientes o modificaciones personalizadas, compile desde el código fuente:

git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .

Guía de inicio rápido de vLLM

Ejecutando su primer modelo

Inicie vLLM con un modelo usando la interfaz de línea de comandos:

# Descargar y servir un modelo con la API compatible con OpenAI
vllm serve Qwen/Qwen3-8B \
    --port 8000

vllm serve es el CLI actual para el servidor compatible con OpenAI. La invocación más antigua python -m vllm.entrypoints.openai.api_server aún se ejecuta, pero emite una advertencia de deprecación y podría ser eliminada en una versión futura, por lo que actualice cualquier script o manifiesto de Kubernetes que todavía lo utilice.

vLLM descargará automáticamente el modelo desde HuggingFace Hub (si no está en caché) e iniciará el servidor. Verá una salida que indica que el servidor está listo:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

Hacer solicitudes a la API

Una vez que el servidor esté en ejecución, puede hacer solicitudes usando el cliente de Python de OpenAI o curl:

Usando curl:

curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen3-8B",
        "prompt": "Explain what vLLM is in one sentence:",
        "max_tokens": 100,
        "temperature": 0.7
    }'

Usando el cliente de Python de OpenAI:

from openai import OpenAI

# Apuntar a su servidor de vLLM
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"  # vLLM ignora esto a menos que inicie el servidor con --api-key
)

response = client.completions.create(
    model="Qwen/Qwen3-8B",
    prompt="Explain what vLLM is in one sentence:",
    max_tokens=100,
    temperature=0.7
)

print(response.choices[0].text)

API de Completions de Chat:

response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is PagedAttention?"}
    ],
    max_tokens=200
)

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

Configuración avanzada

vLLM ofrece numerosos parámetros para optimizar el rendimiento:

vllm serve Qwen/Qwen3-8B \
    --port 8000 \
    --gpu-memory-utilization 0.95 \  # Usar el 95% de la memoria de la GPU
    --max-model-len 32k \            # Longitud máxima de la secuencia (8192 y 32k ambos funcionan)
    --tensor-parallel-size 2 \       # Usar 2 GPUs con paralelismo de tensores
    --dtype float16 \                # Usar precisión FP16
    --max-num-seqs 256               # Tamaño máximo del lote

Parámetros clave explicados:

  • --gpu-memory-utilization: Fracción de memoria de GPU para el executor del modelo (predeterminado 0.92). Valores más altos permiten lotes más grandes pero dejan menos margen para picos de memoria.
  • --max-model-len: Longitud de contexto máxima. Acepta recuentos de tokens o valores legibles por humanos como 32k. Reducir esto ahorra memoria para lotes más grandes.
  • --tensor-parallel-size: Número de GPUs en las que dividir el modelo.
  • --dtype: Tipo de datos para los pesos (auto, float16, bfloat16, float32). auto sigue el dtype del punto de control (checkpoint), que es lo que generalmente se desea.
  • --max-num-seqs: Número máximo de secuencias en un lote.
  • --max-num-active-seqs: Limita la admisión en RUNNING independientemente de max_num_seqs (nuevo en v0.31.0) — útil para acotar la latencia sin encoger la ventana de lote del planificador.

vLLM frente a Ollama

vLLM está diseñado para el servicio de producción de alto rendimiento y multiusuario con lotería continua, PagedAttention y soporte multi-GPU. Ollama se optimiza para una configuración local rápida, conveniencia de un solo usuario y gestión simple de modelos.

Para una guía de decisión detallada que cubre señales de migración, pasos de planificación, configuración de Docker Compose y una lista de verificación práctica, consulte De Ollama a vLLM: Cuándo migrar su servidor local de LLMs.

vLLM frente a Docker Model Runner

El Model Runner de Docker es su solución oficial para el despliegue local de modelos de IA. ¿Cómo se compara con vLLM?

Filosofía arquitectónica

Docker Model Runner busca ser el “Docker de la IA”: una forma simple y estandarizada de ejecutar modelos de IA localmente con la misma facilidad que ejecutar contenedores. Abstrae la complejidad y proporciona una interfaz consistente entre diferentes modelos y marcos de trabajo (frameworks).

vLLM es un motor de inferencia especializado enfocado exclusivamente en el servicio de LLMs con máximo rendimiento. Es una herramienta de nivel inferior que se conteneriza con Docker, en lugar de una plataforma completa.

Configuración y inicio

La instalación de Docker Model Runner es directa para los usuarios de Docker:

docker model pull llama3:8b
docker model run llama3:8b

Esta similitud con el flujo de trabajo de imágenes de Docker lo hace inmediatamente familiar para los desarrolladores que ya usan contenedores; el conjunto completo de comandos está en la hoja de referencia de Docker Model Runner.

vLLM requiere más configuración inicial (Python, CUDA, dependencias) o el uso de imágenes de Docker precompiladas:

docker pull vllm/vllm-openai:latest
docker run --runtime nvidia --gpus all vllm/vllm-openai:latest --model <model-name>

Características de rendimiento

vLLM ofrece un rendimiento superior para escenarios multiusuario debido a PagedAttention y la lotería continua. Para los servicios de API de producción que manejan cientos de solicitudes por segundo, las optimizaciones de vLLM proporcionan un rendimiento 2-5 veces mejor que los enfoques de servicio genéricos.

Docker Model Runner se enfoca en la facilidad de uso en lugar del rendimiento máximo. Es adecuado para el desarrollo local, pruebas y cargas de trabajo moderadas, pero no implementa las optimizaciones avanzadas que hacen que vLLM destaque a gran escala.

Soporte de modelos

Docker Model Runner proporciona una biblioteca de modelos curada con acceso de un comando a modelos populares. Admite múltiples marcos de trabajo (no solo LLMs), incluidas Stable Diffusion, Whisper y otros modelos de IA, lo que lo hace más versátil para diferentes cargas de trabajo de IA.

vLLM se especializa en la inferencia de LLMs con un soporte profundo para modelos de lenguaje basados en transformadores. Admite cualquier LLM compatible con HuggingFace, pero no se extiende a otros tipos de modelos de IA como la generación de imágenes o el reconocimiento de voz.

Despliegue de producción

vLLM ha sido probado a fondo en la producción en empresas como Anthropic, Replicate y muchas otras que sirven miles de millones de tokens a diario. Sus características de rendimiento y estabilidad bajo carga pesada lo convierten en el estándar de facto para el servicio de LLMs en producción.

Docker Model Runner es más nuevo y se posiciona más para escenarios de desarrollo y pruebas locales. Aunque podría servir tráfico de producción, carece del historial probado y las optimizaciones de rendimiento que los despliegues de producción requieren.

Ecosistema de integración

vLLM se integra con herramientas de infraestructura de producción: operadores de Kubernetes, métricas de Prometheus, Ray para servicio distribuido y una amplia compatibilidad con la API de OpenAI para aplicaciones existentes.

Docker Model Runner se integra naturalmente con el ecosistema de Docker y Docker Desktop. Para equipos que ya estandarizan en Docker, esta integración proporciona una experiencia cohesiva, pero con menos características especializadas de servicio de LLMs.

Cuándo usar cada uno

Usar vLLM para:

  • Servicios de API de LLMs de producción
  • Despliegues de alto rendimiento y multiusuario
  • Despliegues en la nube sensibles a costos que necesitan máxima eficiencia
  • Entornos de Kubernetes y cloud-native
  • Cuando necesite escalabilidad y rendimiento probados

Usar Docker Model Runner para:

  • Desarrollo y pruebas locales
  • Ejecutar varios tipos de modelos de IA (no solo LLMs)
  • Equipos profundamente invertidos en el ecosistema de Docker
  • Experimentación rápida sin configuración de infraestructura
  • Propósitos de aprendizaje y educativos

Enfoque híbrido: Muchos equipos desarrollan con Docker Model Runner localmente por conveniencia, y luego despliegan con vLLM en producción por rendimiento. Las imágenes de Docker Model Runner también pueden usarse para ejecutar contenedores de vLLM, combinando ambos enfoques.

Mejores prácticas de despliegue de producción

Despliegue de Docker

Cree una configuración de Docker Compose lista para producción:

version: '3.8'

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - CUDA_VISIBLE_DEVICES=0,1
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
      - ./logs:/logs
    ports:
      - "8000:8000"
    command: >
      --model Qwen/Qwen3-8B
      --tensor-parallel-size 2
      --gpu-memory-utilization 0.90
      --max-num-seqs 256
      --max-model-len 8192
    restart: unless-stopped
    shm_size: '16gb'
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 2
              capabilities: [gpu]

Despliegue en Kubernetes

Despliegue vLLM en Kubernetes para escala de producción:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: vllm
  template:
    metadata:
      labels:
        app: vllm
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args:
          - --model
          - Qwen/Qwen3-8B
          - --tensor-parallel-size
          - "2"
          - --gpu-memory-utilization
          - "0.90"
        resources:
          limits:
            nvidia.com/gpu: 2
        ports:
        - containerPort: 8000
        volumeMounts:
        - name: cache
          mountPath: /root/.cache/huggingface
      volumes:
      - name: cache
        hostPath:
          path: /mnt/huggingface-cache
---
apiVersion: v1
kind: Service
metadata:
  name: vllm-service
spec:
  selector:
    app: vllm
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

Monitoreo y observabilidad

El servidor compatible con OpenAI expone métricas de Prometheus en /metrics por defecto — no se necesitan banderas adicionales:

curl -s http://localhost:8000/metrics | grep '^vllm:'

Métricas clave a monitorear:

  • vllm:num_requests_running / vllm:num_requests_waiting / vllm:num_requests_swapped — solicitudes en los estados del planificador RUNNING, WAITING y SWAPPED
  • vllm:kv_cache_usage_perc — fracción de bloques de caché KV usados (0–1)
  • vllm:time_to_first_token_seconds — histograma de TTFT (Tiempo hasta el primer token)
  • vllm:time_per_output_token_seconds — velocidad de generación por token
  • vllm:num_preemptions_total — preemptions acumuladas; un contador en aumento significa que la caché KV está sobreadministrada y las solicitudes están siendo recalculadas

Para tableros, ejemplos de PromQL y umbrales de alertas en torno al servicio de LLMs, consulte Monitoreo de inferencia de LLMs en producción (2026): Prometheus & Grafana para vLLM, TGI, llama.cpp.

Ajuste de rendimiento

Optimizar la utilización de memoria de GPU: El valor predeterminado es 0.92; ajústelo según el comportamiento observado. Valores más altos permiten lotes más grandes pero representan un riesgo de errores OOM (Out Of Memory) durante picos de tráfico.

Ajustar la longitud máxima de secuencia: Si su caso de uso no necesita la longitud de contexto completa, reduzca --max-model-len. Esto libera memoria para lotes más grandes. Por ejemplo, si solo necesita un contexto de 4K, establezca --max-model-len 4096 en lugar de usar el máximo del modelo (a menudo 8K-32K).

Elegir una cuantización apropiada: Para los modelos que lo admiten, use versiones cuantizadas (8 bits, 4 bits) para reducir la memoria y aumentar el rendimiento:

--quantization awq  # Para modelos cuantizados con AWQ
--quantization gptq # Para modelos cuantizados con GPTQ

Caché de prefijo (Prefix Caching): La caché de prefijo está habilitada por defecto en el motor actual, por lo que las solicitudes que comparten un prefijo de prompt (un prompt de sistema fijo, una plantilla de contexto de RAG) reutilizan su caché KV sin ninguna bandera. Desactívelo con --no-enable-prefix-caching para cargas de trabajo con muchos prompts largos y únicos donde la administración de la caché no aporta nada.

Solución de problemas comunes

Errores de memoria insuficiente (Out of Memory)

Síntomas: El servidor se crasha con errores de memoria insuficiente de CUDA.

Soluciones:

  • Reduzca --gpu-memory-utilization a 0.85 o 0.80
  • Disminuya --max-model-len si su caso de uso lo permite
  • Baje --max-num-seqs para reducir el tamaño del lote
  • Use una versión cuantizada del modelo
  • Habilite el paralelismo de tensores para distribuir entre más GPUs

Dos formas distintas de OOM necesitan correcciones diferentes. Un OOM de inicio (startup) ocurre antes de cualquier solicitud: vLLM perfila la memoria y falla al asignar incluso la caché KV mínima, por lo que reducir --max-num-seqs no ayuda — reduzca --max-model-len o aumente --gpu-memory-utilization si tiene margen. Un OOM en tiempo de ejecución bajo carga puede provenir de la memoria de captura de gráficos de CUDA, que escala con --max-num-seqs pero se encuentra fuera de la contabilidad de la caché KV; ejecute una vez con --enforce-eager para verificar si los gráficos de CUDA son la memoria faltante, y vuelva a probar la misma configuración exacta antes de culpar a la caché. Si los arranques en hardware idéntico continúan teniendo éxito con la misma asignación, devuelva el valor de --kv-cache-memory-bytes que vLLM registra al inicio para saltar la pasada de perfilado en los arranques subsiguientes.

En una tarjeta de 16 GB única, la mayoría de estos errores de OOM se remontan al presupuesto de la caché KV más que a los pesos solos — Caché KV en GPUs de 16 GB cubre la fórmula exacta, el dtype de caché KV FP8 y los compromisos de la caché de prefijo detrás de --max-model-len y --max-num-seqs antes de recurrir a un modelo más pequeño.

Inicio lento

Síntomas: El servidor tarda minutos desde el lanzamiento hasta “Application startup complete”.

Soluciones:

  • La carga de pesos, la compilación y la captura de gráficos de CUDA dominan el inicio — --enforce-eager omite tanto la compilación como la captura y le dice cuánto del arranque cuestan, al precio de la velocidad de decodificación en estado estacionario
  • Reutilice el valor registrado de --kv-cache-memory-bytes para saltar las pasadas de perfilado de memoria y estimación de gráficos de CUDA en los arranques repetidos
  • En v0.30.0+, el comando vllm preload ejecuta un demonio persistente de caché de pesos que mantiene los pesos cuantizados residentes en la memoria de la GPU, por lo que los reinicios del motor mapean los pesos sobre CUDA IPC en lugar de recargarlos desde el disco (--load-format ipc_cache)
  • Para los puntos de control NVFP4 que sufren OOM durante la compilación de inicio, limitar los hilos de compilación con MAX_JOBS=4 y NVCC_THREADS=4 es una corrección ampliamente utilizada — ralentiza la compilación JIT pero detiene el OOM

Bajo rendimiento (Throughput)

Síntomas: El servidor maneja menos solicitudes de las esperadas.

Soluciones:

  • Aumente --max-num-seqs para permitir lotes más grandes
  • Eleve --gpu-memory-utilization si tiene margen
  • Verifique si la CPU es el cuello de botella con htop – considere CPUs más rápidas
  • Verifique la utilización de la GPU con nvidia-smi – debería ser del 95%+
  • Habilite FP16 si está usando FP32: --dtype float16

Tiempo de primer token lento

Síntomas: Alta latencia antes de que comience la generación.

Soluciones:

  • Use modelos más pequeños para aplicaciones críticas en latencia
  • La caché de prefijo está activada por defecto — verifique que esté activa en lugar de volver a añadir la bandera
  • Reduzca --max-num-seqs para priorizar la latencia sobre el rendimiento
  • Considere la decodificación especulativa para modelos admitidos
  • Optimice la configuración de paralelismo de tensores

Fallos en la carga del modelo

Síntomas: El servidor falla al iniciar, no puede cargar el modelo.

Soluciones:

  • Verifique que el nombre del modelo coincida exactamente con el formato de HuggingFace
  • Verifique la conectividad de red con HuggingFace Hub
  • Asegúrese de tener suficiente espacio en disco en ~/.cache/huggingface
  • Para modelos restringidos (gated), establezca la variable de entorno HF_TOKEN
  • Intente descargar manualmente con hf download <model> (o huggingface-cli download <model> en instalaciones más antiguas)

Características avanzadas

Decodificación especulativa

vLLM admite la decodificación especulativa, donde un modelo de borrador (draft model) más pequeño propone tokens que un modelo objetivo más grande verifica. Esto puede acelerar la generación de 1.5 a 2 veces. Para una guía integral de métodos de decodificación especulativa — modelos de borrador, EAGLE-3, P-EAGLE y n-gram — consulte Decodificación especulativa: Inferencia más rápida sin pérdida de calidad.

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --speculative-config '{"method": "draft_model", "model": "meta-llama/Llama-3.2-1B-Instruct", "num_speculative_tokens": 4}'

Las banderas antiguas --speculative-model y --num-speculative-tokens han desaparecido — la configuración se trasladó al único argumento JSON --speculative-config, que también selecciona el método (draft_model, ngram, familia EAGLE, o MTP para modelos con cabezas nativas de predicción multi-token).

Adaptadores LoRA

Sirva múltiples adaptadores LoRA sobre un modelo base sin cargar múltiples modelos completos:

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --enable-lora \
    --lora-modules sql-lora=/path/to/sql-adapter \
                   code-lora=/path/to/code-adapter

Luego especifique qué adaptador usar por solicitud poniendo su nombre en el campo model — el mismo mecanismo escala a docenas de adaptadores específicos de tarea (variantes específicas de cliente o por dominio) con solo el modelo base residente en la memoria:

response = client.completions.create(
    model="sql-lora",  # Usar el adaptador de SQL
    prompt="Convert this to SQL: Show me all users created this month"
)

Caché de prefijo (Prefix Caching)

La caché de prefijo evita recalcular la caché KV para prefijos de prompt compartidos y está habilitada por defecto en el motor actual.

Reporta mayores beneficios para:

  • Chatbots con prompts de sistema fijos
  • Aplicaciones de RAG con plantillas de contexto consistentes
  • Prompts de aprendizaje de pocos ejemplos (few-shot) repetidos entre solicitudes

Para solicitudes que comparten un prefijo, el tiempo hasta el primer token (time-to-first-token) disminuye sustancialmente porque el prefill para la parte compartida se omite.

Ejemplos de integración

Integración de LangChain

from langchain_community.llms import VLLMOpenAI

llm = VLLMOpenAI(
    openai_api_key="EMPTY",
    openai_api_base="http://localhost:8000/v1",
    model_name="Qwen/Qwen3-8B",
    max_tokens=512,
    temperature=0.7,
)

response = llm("Explain PagedAttention in simple terms")
print(response)

Aplicación de FastAPI

from fastapi import FastAPI
from openai import AsyncOpenAI

app = FastAPI()
client = AsyncOpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"
)

@app.post("/generate")
async def generate(prompt: str):
    response = await client.completions.create(
        model="Qwen/Qwen3-8B",
        prompt=prompt,
        max_tokens=200
    )
    return {"result": response.choices[0].text}

Benchmarks de rendimiento

Los datos de rendimiento del mundo real ayudan a ilustrar las ventajas de vLLM. Las cifras a continuación provienen de la documentación de la época de lanzamiento del proyecto y mediciones iniciales de la comunidad — trátelas como indicaciones de orden de magnitud del efecto de la arquitectura, no como resultados actuales para la generación de modelos de hoy:

Comparación de rendimiento (Mistral-7B en GPU A100):

  • vLLM: ~3,500 tokens/segundo con 64 usuarios concurrentes
  • HuggingFace Transformers: ~250 tokens/segundo con la misma concurrencia
  • Ollama: ~1,200 tokens/segundo con la misma concurrencia
  • Resultado: vLLM proporciona una mejora de 14 veces sobre las implementaciones básicas

Eficiencia de memoria (LLaMA-2-13B):

  • Implementación estándar: 24GB VRAM, 32 secuencias concurrentes
  • vLLM con PagedAttention: 24GB VRAM, 128 secuencias concurrentes
  • Resultado: 4 veces más solicitudes concurrentes con la misma memoria

Latencia bajo carga (Mixtral-8x7B en 2xA100):

  • vLLM: Latencia P50 180ms, Latencia P99 420ms a 100 req/s
  • Servicio estándar: Latencia P50 650ms, Latencia P99 3,200ms a 100 req/s
  • Resultado: vLLM mantiene una latencia consistente bajo carga alta

Análisis de costos

Comprender las implicaciones de costos de elegir vLLM:

Escenario: Servir 1M de solicitudes/día

Con servicio estándar:

  • Requerido: 8x GPUs A100 (80GB)
  • Costo de AWS: ~$32/hora × 24 × 30 = $23,040/mes
  • Costo por 1M de tokens: ~$0.75

Con vLLM:

  • Requerido: 2x GPUs A100 (80GB)
  • Costo de AWS: ~$8/hora × 24 × 30 = $5,760/mes
  • Costo por 1M de tokens: ~$0.19
  • Ahorros: $17,280/mes (reducción del 75%)

Esta ventaja de costos crece con la escala. Las organizaciones que sirven miles de millones de tokens mensualmente ahorran cientos de miles de dólares al usar el servicio optimizado de vLLM en lugar de implementaciones ingenuas.

Consideraciones de seguridad

Autenticación

vLLM incluye una bandera --api-key integrada, pero según la documentación oficial solo autentica los puntos de acceso (endpoints) bajo los prefijos de ruta /v1, /v2 e /inference — otros puntos de acceso en el mismo servidor permanecen sin autenticar. Trátelo como una capa, no como la respuesta completa; para una cobertura completa, implemente la autenticación a nivel de proxy inverso:

# Configuración de Nginx
location /v1/ {
    auth_request /auth;
    proxy_pass http://vllm-backend:8000;
}

location /auth {
    proxy_pass http://auth-service:8080/verify;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

O use puertas de enlace de API como Kong, Traefik o AWS API Gateway para autenticación y limitación de tasa de grado empresarial.

Aislamiento de red

Ejecute vLLM en redes privadas, no expuesto directamente a internet:

# Ejemplo de NetworkPolicy de Kubernetes
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: vllm-access
spec:
  podSelector:
    matchLabels:
      app: vllm
  policyTypes:
  - Ingress
  ingress:
  - from:
    - podSelector:
        matchLabels:
          role: api-gateway
    ports:
    - protocol: TCP
      port: 8000

Limitación de tasa (Rate Limiting)

Implemente la limitación de tasa para prevenir el abuso:

# Ejemplo usando Redis para la limitación de tasa
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
import redis
from datetime import datetime, timedelta

app = FastAPI()
redis_client = redis.Redis(host='localhost', port=6379)

@app.middleware("http")
async def rate_limit_middleware(request, call_next):
    client_ip = request.client.host
    key = f"rate_limit:{client_ip}"
    
    requests = redis_client.incr(key)
    if requests == 1:
        redis_client.expire(key, 60)  # Ventana de 60 segundos
    
    if requests > 60:  # 60 solicitudes por minuto
        raise HTTPException(status_code=429, detail="Rate limit exceeded")
    
    return await call_next(request)

Control de acceso al modelo

Para despliegues multi-inquilino, controle qué usuarios pueden acceder a qué modelos:

ALLOWED_MODELS = {
    "user_tier_1": ["Qwen/Qwen3-8B"],
    "user_tier_2": ["Qwen/Qwen3-8B", "meta-llama/Llama-2-13b-chat-hf"],
    "admin": ["*"]  # Todos los modelos
}

def verify_model_access(user_tier: str, model: str) -> bool:
    allowed = ALLOWED_MODELS.get(user_tier, [])
    return "*" in allowed or model in allowed

Guía de migración

De OpenAI a vLLM

Migrar de OpenAI a vLLM autoalojado es sencillo gracias a la compatibilidad de la API:

Antes (OpenAI):

from openai import OpenAI

client = OpenAI(api_key="sk-...")
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello"}]
)

Después (vLLM):

from openai import OpenAI

client = OpenAI(
    base_url="https://your-vllm-server.com/v1",
    api_key="your-internal-key"  # Si añadió autenticación
)
response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[{"role": "user", "content": "Hello"}]
)

Solo se necesitan dos cambios: actualizar base_url y el nombre del model. Todo el otro código permanece idéntico.

De Ollama a vLLM

Ollama usa un formato de API diferente. El cambio básico del lado del cliente es pasar del punto de acceso REST de Ollama a la API compatible con OpenAI de vLLM:

API de Ollama:

import requests

response = requests.post('http://localhost:11434/api/generate',
    json={'model': 'llama2', 'prompt': 'Why is the sky blue?'})

Equivalente en vLLM:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
response = client.completions.create(
    model="meta-llama/Llama-2-7b-chat-hf",
    prompt="Why is the sky blue?"
)

La API de Ollama es REST plano con su propia forma de solicitud, mientras que vLLM habla el protocolo de OpenAI — esa diferencia de formato de API es el principal cambio del lado del cliente, y el enfoque por etapas (ejecutar ambos servidores, desplazar el tráfico punto de acceso por punto de acceso) se cubre en la guía de migración enlazada anteriormente en este artículo.

De HuggingFace Transformers a vLLM

Migración de uso directo de Python:

HuggingFace:

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-8B")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B")

inputs = tokenizer("Hello", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=100)
result = tokenizer.decode(outputs[0])

vLLM:

from vllm import LLM, SamplingParams

llm = LLM(model="Qwen/Qwen3-8B")
sampling_params = SamplingParams(max_tokens=100)

outputs = llm.generate("Hello", sampling_params)
result = outputs[0].outputs[0].text

La API de Python de vLLM es más simple y mucho más rápida para la inferencia por lotes.

Lanzamientos recientes: Qué cambió en 2026

Tres lanzamientos en septiembre–octubre de 2026 (v0.29.0, v0.30.0, v0.31.0) muestran hacia dónde se dirige el desarrollo:

Reinicios rápidos: vllm preload lanza un demonio persistente de caché de pesos por GPU que mantiene los pesos cuantizados y fragmentados por TP residentes en la memoria de la GPU, por lo que los motores reiniciados los mapean sobre CUDA IPC (--load-format ipc_cache) en lugar de recargarlos desde el disco. Las funciones experimentales vllm snapshot create/restore toman instantáneas de un motor completamente inicializado con CRIU.

Decodificación especulativa en Model Runner V2: la decodificación especulativa de modelos de borrador, los procesadores de logits personalizados y la verificación adaptativa se trasladaron al nuevo model runner, con el borrador LiLiCorr añadido y la programación asíncrona para el borrador DFlash.

Servicio de MoE a gran escala: nuevos backends all2all de paralelismo de expertos equilibrados (--all2all-backend moonep), DeepEPv2 con paralelismo de secuencia, EPLB con superposición de expertos compartidos y paralelismo de contexto de prefill combinado con paralelismo de datos.

Control de programación: --max-num-active-seqs limita la admisión en RUNNING independientemente de max_num_seqs, y la cola de espera ahora programa primero las solicitudes que ya poseen bloques KV.

Los elementos de la hoja de ruta de las guías antiguas de vLLM se han lanzado hace mucho — el soporte de GGUF, el servicio multimodal, el prefill/decodificación desintegrado y la inferencia multi-nodo son parte de las versiones actuales, por lo que trate cualquier tutorial que los liste como “próximamente” como desactualizado. Las notas de lanzamiento de cada versión están en la página de lanzamientos de vLLM.

Enlaces útiles

Artículos relacionados en este sitio

  • Hoja de referencia de Ollama - Referencia completa de comandos y hoja de referencia de Ollama que cubre instalación, gestión de modelos, uso de API y mejores prácticas para el despliegue local de LLMs. Esencial para desarrolladores que usan Ollama junto o en lugar de vLLM.

  • Docker Model Runner frente a Ollama: ¿Cuál elegir? - Comparación exhaustiva del Model Runner de Docker y Ollama para el despliegue local de LLMs, analizando rendimiento, soporte de GPU, compatibilidad de API y casos de uso. Ayuda a entender el panorama competitivo en el que opera vLLM.

Recursos y documentación externos

  • Repositorio de GitHub de vLLM - Repositorio oficial de vLLM con código fuente, documentación integral, guías de instalación y discusiones de la comunidad activas. Recurso esencial para estar al día con las últimas características y resolver problemas.

  • Documentación de vLLM - Documentación oficial que cubre todos los aspectos de vLLM desde la configuración básica hasta la configuración avanzada. Incluye referencias de API, guías de ajuste de rendimiento y mejores prácticas de despliegue.

  • Artículo de PagedAttention - Artículo académico que introduce el algoritmo PagedAttention que impulsa la eficiencia de vLLM. Lectura esencial para comprender las innovaciones técnicas detrás de las ventajas de rendimiento de vLLM.

  • Blog de vLLM - Blog oficial de vLLM con anuncios de lanzamientos, benchmarks de rendimiento, profundizaciones técnicas y estudios de casos de la comunidad desde despliegues de producción.

  • HuggingFace Model Hub - Repositorio integral de LLMs de código abierto que funcionan con vLLM. Busque modelos por tamaño, tarea, licencia y características de rendimiento para encontrar el modelo adecuado para su caso de uso.

  • Documentación de Ray Serve - Documentación del marco Ray Serve para construir despliegues escalables y distribuidos de vLLM. Ray proporciona características avanzadas como escalado automático, servicio multi-modelo y gestión de recursos para sistemas de producción.

  • NVIDIA TensorRT-LLM - TensorRT-LLM de NVIDIA para inferencia altamente optimizada en GPUs de NVIDIA. Alternativa a vLLM con estrategias de optimización diferentes, útil para comparar y comprender el panorama de optimización de inferencia.

  • Referencia de la API de OpenAI - Documentación oficial de la API de OpenAI con la que la API de vLLM es compatible. Consulte esto al construir aplicaciones que necesitan funcionar tanto con endpoints de OpenAI como con vLLM autoalojado de forma intercambiable.

Suscribirse

Recibe nuevas publicaciones sobre sistemas, infraestructura e ingeniería de IA.