Los 5 flags de vLLM que importan de verdad

vLLM tiene más de cien flags de configuración. Cinco deciden cuánto contexto aguantas, cuánto gastas y si tu agente funciona. Los demás son tuning fino para cuando ya mides. Este capítulo abre esos cinco con el número real que cada uno mueve.

La regla mental antes de empezar: vLLM reparte tu VRAM en dos montones. Uno fijo para los pesos del modelo, uno variable para la KV cache (el contexto de tus sesiones). Casi todos los flags son maneras de repartir ese pastel.

1. --max-model-len 65536

La ventana de contexto máxima que aceptará el servidor, en tokens.

Con la KV cache en FP8, cada token de contexto cuesta 48 KB de VRAM (la matemática completa está en 48 KB por token). Una sesión de 64K cuesta 64.536 × 48 KB ≈ 3,1 GB. Una de 128K, el doble.

Qué rompe si lo subes sin pensar: el arranque muere con No available memory for the cache blocks, porque prometes más memoria de la que queda después de los pesos. Qué rompe si lo bajas demasiado: tus agentes con sesiones largas mueren con "context length exceeded".

En mi PoC: 65536. Con ~175K tokens de KV cache en la L40S, caben 2 sesiones llenas de 64K.

2. --gpu-memory-utilization 0.92

El porcentaje de VRAM que vLLM puede usar. Con 48 GB, 0,92 son ~44 GB para pesos + KV cache + activaciones.

• 31 GB se van en los pesos del modelo de 30B en FP8.
• Lo que queda (~13 GB antes de overhead) es tu KV cache: los ~150-200K tokens que viste en el log del capítulo 4.

Si te topas con OOM al arrancar, bájalo a 0,88 antes que recortar contexto. Y no lo pongas en 1.0: el runtime necesita margen para CUDA y los buffers, y un arranque con 0 MB libres es un arranque que falla.

3. --kv-cache-dtype fp8

Guarda la KV cache en 8 bits en lugar de 16. Duplica tu capacidad de contexto al costo de un poco de precisión: 96 KB por token en FP16 pasan a 48 KB en FP8.

Para agentes que leen código, el impacto en calidad es prácticamente invisible; el impacto en capacidad es el doble de sesiones. Este flag es la razón por la que la guía exige una GPU Ada o superior: las Ampere (A40, A100, A6000) no soportan FP8 por hardware y el arranque falla. Si te pasa, quítalo y sigue: pierdes la mitad del contexto, pero funciona.

4. --enable-prefix-caching

Reutiliza la KV cache de prefijos ya procesados. Si todos tus requests empiezan con el mismo system prompt y el mismo historial (que es exactamente lo que hace un agente en cada turno), vLLM no vuelve a procesar ese texto: lo reutiliza.

Este es el flag con el mejor retorno de la lista. Mi medición del PoC, mismo escenario de 10 usuarios con 16K de contexto:

El desglose completo está en Prefix caching: la misma carga, 3× más rápido. En un workload agéntico, donde cada turno reenvía el historial, este flag domina la factura de latencia.

5. --enable-auto-tool-choice --tool-call-parser qwen3_coder

Sin estos dos flags, tu agente no funciona. El modelo genera las llamadas a herramientas como texto y el cliente las recibe como prosa en lugar de ejecutarlas. Es el bug más silencioso de la lista: todo "parece" funcionar hasta que el agente intenta editar un archivo.

El parser depende del modelo: qwen3_coder para los Qwen3 Coder; si vLLM se queja del nombre, vllm serve --help | grep -A5 tool-call-parser y prueba hermes. Cada familia de modelos tiene el suyo.

El comando completo, con lo que cada flag controla

nohup vllm serve Qwen/Qwen3-Coder-30B-A3B-Instruct-FP8 \
  --served-model-name qwen3-coder-30b \
  --max-model-len 65536 \
  --gpu-memory-utilization 0.92 \
  --kv-cache-dtype fp8 \
  --enable-prefix-caching \
  --enable-auto-tool-choice --tool-call-parser qwen3_coder \
  --api-key $VLLM_API_KEY \
  --host 0.0.0.0 --port 8000 \
  > /workspace/vllm.log 2>&1 &

Cada flag ya está explicado arriba. La versión corta: el alias es para clientes, la ventana es por sesión, el porcentaje reparte la VRAM, FP8 cobra 48 KB por token, prefix caching reutiliza contexto repetido y los dos últimos despiertan a los agentes.

Checkpoint y el error típico

Checkpoint: entiendes cada flag de tu comando de arranque y el número que controla. La prueba: ¿podrías decir cuántas sesiones de 64K aguantas antes de correr vllm serve?

El error típico: copiar flags de un tutorial sin revisar tu VRAM. Los números de esta guía corresponden a 48 GB; en una GPU de 24 GB, el mismo comando no arranca. Siempre nvidia-smi primero, después el comando.

Siguiente capítulo

Ahora que el servidor está bien configurado, lo medimos como se debe: TTFT, tokens/s y concurrencia, con los mismos scripts que usé en mi PoC.

¿Cuántos tokens de KV cache te dio el log? Déjalo en los comentarios, es el número que define tu capacidad real.

---