vLLM Producción: Checklist Comparación y Fixes

Parte 5 de 6. En la Parte 4 cubrimos ajuste de rendimiento y monitoreo. Aquí comparamos vLLM con Ollama, revisamos el checklist de producción y solucionamos problemas comunes. Continúa en Parte 6: Conclusión y FAQ.

vLLM vs Ollama: Comparación de motores de inferencia

Usa vLLM para servir usuarios externos. Usa Ollama para prototipado local. Ambos son excelentes, pero sus arquitecturas apuntan a entornos completamente diferentes.

Factor	vLLM	Ollama
Caso de uso	Inferencia en producción a escala	Desarrollo local
Throughput	3–5× mayor (continuous batching)	Moderado
API	Compatible con OpenAI	API REST propia
Multi-GPU	Tensor parallelism nativo	Limitado
Cuantización	AWQ, GPTQ, FP8	GGUF (Q4_0, Q4_K_M)
Kubernetes	Soporte first-class	Orquestación manual
Ideal para	100+ usuarios concurrentes	Prototipado en laptop

Mi regla: ¿Sirviendo usuarios externos? vLLM. ¿Prototipando local? Ollama. Uso ambos.

Para más detalles, lee Ollama vs vLLM: Choosing the Right LLM Inference Engine.

Checklist de producción: 10 ítems antes de salir a producción

Marca cada ítem de este checklist antes de exponer tu despliegue de vLLM a tráfico real:

#	Ítem	Verificación
1	Nodos GPU etiquetados con nvidia.com/gpu.present=true	kubectl get nodes -l nvidia.com/gpu.present=true
2	Pesos del modelo pre-descargados a un PVC local	kubectl get pvc -n llm-serving + verificar mount
3	Resource limits coinciden con --tensor-parallel-size	nvidia.com/gpu == --tensor-parallel-size
4	Liveness y readiness probes configurados	kubectl describe pod muestra ambos probes
5	Graceful shutdown con hook preStop + período de gracia 60s	kubectl get pod -o yaml | grep preStop
6	Cuantización habilitada si el modelo excede la VRAM de una sola GPU	Verificar bandera --quantization en el manifiesto
7	Métricas personalizadas de HPA conectadas a Prometheus Adapter	kubectl get hpa muestra valor TARGET
8	Anotaciones de scraping de Prometheus en el template del Pod	prometheus.io/scrape: "true" presente
9	Timeouts de proxy de NGINX extendidos a 3600s	kubectl get ingress -o yaml | grep timeout
10	Script de warm-up ejecutado antes del tráfico	Primeras 5–10 requests excluidas de SLIs

Imprime este checklist. Marca cada casilla. Solo entonces enruta tráfico de producción. El ítem #3, discrepancia de tensor parallelism, es la causa más común de fallos multi-GPU que veo.

Solución de problemas comunes de vLLM

Esta tabla mapea síntomas comunes directamente a causas raíz y soluciones. Estos son los fallos que más encuentro en despliegues de vLLM production.

Error / Síntoma	Causa raíz	Solución
CUDA out of memory	--gpu-memory-utilization muy alto o batch size muy grande	Reducir a 0.85, bajar --max-num-seqs, o activar cuantización
NCCL error durante arranque	Discrepancia de --tensor-parallel-size con el conteo de GPUs	Asegurar que nvidia.com/gpu sea igual a --tensor-parallel-size
Descarga de modelo se cuelga en arranque	Rate limit de HuggingFace o sin acceso a internet	Pre-descargar a PVC, configurar HF_HUB_OFFLINE=1
Primera request muy lenta	Compilación JIT de kernels CUDA	Ejecutar requests de warm-up antes del tráfico de producción
TTFT alto, GPU util baja	Batch size muy pequeño	Incrementar --max-num-seqs o la tasa de requests
TPOT alto, GPU util alta	KV cache lleno o modelo muy grande para la GPU	Reducir --max-model-len, activar AWQ/GPTQ, o agregar GPUs
HPA no escala	Prometheus Adapter mal configurado	Verificar que el nombre de la métrica coincida con la regla del adapter; revisar kubectl describe hpa
Ingress 504 Gateway Timeout	Timeout de proxy NGINX muy bajo	Configurar proxy-read-timeout y proxy-send-timeout a 3600s
Pod atascado en Terminating	Sin handler de graceful shutdown	Agregar hook preStop sleep y terminationGracePeriodSeconds: 60
Fallo de kernel FP8 en H100	Discrepancia de versión CUDA	Actualizar a CUDA 12.4+; verificar vLLM 0.8.4+

Modo debug: Activa VLLM_LOGGING_LEVEL=DEBUG y NCCL_DEBUG=INFO para logs detallados de arranque. Para problemas de topología NCCL, agrega NCCL_DEBUG_SUBSYS=GRAPH.

Continúa en Parte 6: Conclusión y FAQ para la conclusión y preguntas frecuentes.