Saltar al contenido
AI•5 min de lectura

Sobrevivir al tren de releases de vLLM, guía de migración para 2026

vLLM saca una versión menor cada dos semanas. Septiembre trajo la v0.29 con Model Runner V2 como default, octubre trajo la v0.31 y la v0.32 con Python 3.10 fuera y cascade attention eliminado, y noviembre llegó la v0.33 con imágenes solo para CUDA 13. Si tu servidor de inferencia vive en un pod alquilado, cada salto puede romper tu stack sin avisar.

Nadie escribe guías de migración de vLLM. Todos citan las release notes y pasan de largo. Esta guía llena ese hueco con lo que se rompió en las últimas tres versiones y el proceso para actualizar sin apagar tu servicio. - Fuente vLLM releases

Lo que se rompió en el último trimestre

Cada versión trae una lista de cambios que las release notes documentan bien y que casi nadie lee hasta que el pod no arranca.

v0.33.0, noviembre 2026. Las imágenes son solo CUDA 13.0, las -cu129 dejaron de publicarse. Medusa y el MLP speculator fueron eliminados del core. Los requests durante pausas de generación devuelven HTTP 503. El conector NIXL exige versión 1.5 o superior. LM Format Enforcer quedó deprecado. - Fuente v0.33.0 release

v0.32.0, octubre 2026. Python 3.10 quedó fuera de soporte, el rango ahora es 3.11 a 3.14. CORS ya no permite cualquier origen por default, lo que rompe frontends que llamaban tu API directo desde el browser. Cascade attention fue removido. max_tokens ya no se reserva del contexto del modelo. Los eventos de reasoning del Responses API cambiaron de nombre. - Fuente v0.32.0 release

v0.31.0, octubre 2026. tokenizer_mode="slow" eliminado, el parser online de quantization="fp8" se reemplazó por fp8_per_tensor, y --enforce-eager ahora también desactiva el warmup de kernels JIT. - Fuente v0.31.0 release

El cambio estructural es Model Runner V2. La v0.29 lo volvió default para todos los modelos y la deprecación de V1 está explícita en las release notes, con remoción programada. Si tus flags y scripts de la era V1 siguen vivos, están en el camino de la excavadora. - Fuente v0.29.0 release

El proceso de actualización que no apaga tu servicio

La regla de oro del tren de releases es simple. Nunca actualices y sirvas a la vez en el mismo pod.

Paso 1, congelar el estado actual. Antes de tocar nada, documenta el pin completo. Tag del contenedor, versión del modelo, flags exactos de arranque y la salida de un benchmark base.

# snapshot del estado actual, guardalo en el repo
docker inspect vllm-openai --format '{{.Config.Image}}' > deploy-pin.txt
ps aux | grep vllm >> deploy-pin.txt
vllm bench serve --model $MODEL --num-prompts 50 --percentile-metrics ttft,tpot \
  --save-result baseline-v032.json

Paso 2, actualizar en un contenedor nuevo, no en el pod vivo. Pull de la imagen nueva, arranca el mismo modelo con los mismos flags al lado del servicio actual y compara el /health y un bench corto antes de tocar nada de producción. En RunPod esto es barato, una hora extra de la misma GPU.

docker run --gpus all --rm -p 8001:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm:v0.33.0 --model $MODEL [tus-flags]

# smoke test contra el puerto nuevo
vllm bench serve --base-url http://localhost:8001 --num-prompts 30 \
  --percentile-metrics ttft,tpot,itl --save-result canary-v033.json

Paso 3, revisar los tres lugares donde vLLM te avisa. La sección de breaking changes de la release, los warnings de deprecación en el log de arranque y el output de vllm serve con flags desconocidos. Desde la v0.33 los flags no soportados fallan al arrancar en vez de ignorarse en silencio, un cambio pequeño que evita noches largas. - Fuente v0.33.0 release

Paso 4, cortar tráfico con canario. Enruta un porcentaje del tráfico al pod nuevo con LiteLLM o el router que uses, compara TTFT p90 y tasa de error por hora, y completa el corte cuando el canario sostenga la carga. Si algo huele mal, el rollback es apuntar el router al pod viejo, que sigue vivo.

Los tres cambios que te van a encontrar

CUDA 13 y las imágenes base. Si tu pod usa drivers de CUDA 12.9, la v0.33 no arranca. Actualiza drivers del host o quédate en la v0.32 con imagen -cu129 mientras tu proveedor de GPU mueve el stack. Los proveedores ya están rotando, pero RunPod tiene pools enteros en 12.x. - Fuente PR #62575

La muerte de Medusa. Si tu speculative decoding usaba Medusa heads, la v0.33 lo eliminó. El camino moderno es EAGLE 3.1, DFlash o DSpark con checkpoints de Speculators, y el fix del presupuesto de draft slots rinde más que el drafter que perdiste. DeepSeek-V4.1-Flash con DSpark pasó de 1373 a 3390 tokens/s de salida en GB300 con ese cambio. - Fuente PR #61701, PR #59468

El frontend Rust y los 500 de siempre. Las conversaciones largas que devolvían HTTP 500 por límites del frontend Python ya no existen en el frontend Rust, y los requests no soportados fallan al arrancar. Si mantenías workarounds por esos bugs, es momento de probar sin ellos. - Fuente PR #62374

Lo que viene y conviene anticipar

El roadmap Q4 2026 es explícito. Remoción total de Model Runner V1, frontend Rust como default, soporte FP4 de KV cache para más modelos con offloading a disco, y la aspiración declarada de activar speculative decoding por default. Cada ítem de esa lista es un cambio futuro para tu stack. - Fuente Roadmap Q4 2026

Hay dos novedades que suavizan el tren. vllm preload mantiene pesos post-cuantizados residentes en GPU entre restarts con un daemon de cache, y vllm snapshot create/restore experimental restaura un engine TP1 inicializado vía CRIU. En un pod efímero, reiniciar sin re-cargar 30 GB de pesos cambia la economía de actualizar. - Fuente v0.31.0 release, v0.30.0 release

Tips finales

  1. Una versión por vez, máximo dos. Saltar de la v0.29 a la v0.33 acumula tres sets de breaking changes y multiplica el debug.
  2. Automatiza el bench de canario en CI. Un script que arranque la imagen nueva, corra 30 prompts y compare p90 contra el baseline convierte la actualización en rutina.
  3. Lee la sección de deprecations antes que la de features. Las features venden el release, las deprecations rompen tu noche.
  4. Suscríbete al feed de releases de GitHub. Con cadencia de dos semanas, enterarte con 15 días de retraso significa estar siempre migrando de a dos versiones.
  5. Guarda la imagen vieja localmente. docker save del contenedor que funciona. Cuando el registry mueva tags, tu rollback no depende de internet.

El tren de releases no se detiene y no debería. El que se adapta es el pasajero.

¿Cada cuánto actualizas tu servidor de vLLM, o esperas a que algo se rompa? Cuéntame en los comentarios.


> Más posts