Qué hacer si vLLM KV Cache no tiene suficiente memoria: resolución de problemas de memoria de video, contexto y concurrencia

Cuando se produce el siguiente error al iniciar vLLM, normalmente no se debe a que la descarga del peso del modelo esté interrumpida:

1

The model's max seq len ... KV cache is needed, which is larger than the available KV cache memory

Significa que después de que los pesos del modelo y la sobrecarga del tiempo de ejecución ocupan la memoria de video, el espacio restante no es suficiente para preparar el caché KV para la longitud máxima de contexto que establezca. La secuencia de procesamiento más directa es: ** Primero reduzca --max-model-len, luego verifique la concurrencia y finalmente considere mejorar la utilización de la memoria, cuantificar el caché KV o expandir la capacidad. **

No lleves --gpu-memory-utilization a 1 desde el principio. Eso puede permitir que vLLM pase la inicialización, pero sea más propenso a OOM cuando solicitudes reales, gráficos CUDA u otros procesos compiten por la memoria de video.

Primero comprenda: por qué KV Cache llena la memoria de video

El peso del modelo determina “si el modelo se puede cargar” y KV Cache determina “cuántos tokens puede recordar el modelo al mismo tiempo y cuántas solicitudes atiende”. Cada vez que se genera o lee un token, la capa de atención debe guardar el estado de clave/valor correspondiente.

Por lo tanto, el uso de KV Cache aumentará con los siguientes elementos:

• max_model_len: cuanto más largo sea el contexto máximo permitido, mayores serán los requisitos de caché.
• Número de solicitudes simultáneas: cada solicitud simultánea ocupará su propio espacio de contexto.
• Estructura del modelo: la cantidad de capas, la cantidad de cabezales KV, el tamaño oculto y el tipo de datos afectan el tamaño de la caché.
• Precisión de la caché: el valor predeterminado suele seguir el tipo de datos del modelo; Las cachés de baja precisión, como las del FP8, pueden ahorrar espacio, pero tienen límites de compatibilidad y calidad.

Lo que más se pasa por alto es la concurrencia. Incluso si a cada solicitud solo se le proporciona un contexto de 8K, la demanda total de KV Cache seguirá creciendo rápidamente cuando se ejecuten varias solicitudes simultáneamente.

Primero determine qué tipo de problema es a partir de los registros.

Los registros de inicio suelen proporcionar tres datos clave:

1. La longitud máxima de secuencia especificada por el modelo o configurada por usted.
2. ¿Cuántos GiB requiere KV Cache?
3. El espacio real disponible actualmente para KV Cache y la longitud máxima factible estimada por vLLM.

Si el registro dice “La longitud máxima 32768 requiere caché KV de 10 GiB, pero actualmente solo 4 GiB”, no se preocupe primero si el modelo admite 32 K. El modelo Soporte no significa que su tarjeta pueda atender 32 000 solicitudes con la configuración actual.

Comience tomando nota de la longitud máxima estimada proporcionada por el registro, establezca su primera prueba entre el 60% y el 80% de ella y luego vaya subiendo.

Primera prioridad: menor --max-model-len

Este es el ajuste con mayor tasa de éxito y el impacto más predecible. Por ejemplo, el modelo admite de forma nativa 32K y su negocio real solo maneja conversaciones ordinarias, códigos cortos y documentos pequeños; puede comenzar con 8K:

1
2

vllm serve Qwen/Qwen3-8B \
  --max-model-len 8192

Si aún no es suficiente, inténtalo de nuevo:

1
2

vllm serve Qwen/Qwen3-8B \
  --max-model-len 4096

No escriba el contexto nominal de 128K, 256K o más de la tarjeta del modelo directamente en los parámetros de servicio. Para implementaciones de una sola tarjeta, la longitud real disponible depende del peso, la memoria de video, la simultaneidad y la precisión de la caché.

Un punto de partida práctico:

Estos valores son un punto de partida para la resolución de problemas, no compromisos de memoria. El tamaño de la caché KV puede variar significativamente entre modelos.

Segunda prioridad: limitar la simultaneidad y el procesamiento por lotes

El hecho de que el servicio pueda iniciarse no significa que será estable en condiciones de alta concurrencia. Primero, controle la concurrencia a un valor pequeño:

1
2
3

vllm serve Qwen/Qwen3-8B \
  --max-model-len 8192 \
  --max-num-seqs 4

--max-num-seqs limita el número de secuencias que se pueden procesar en una iteración. Un número mayor puede dar como resultado un mayor rendimiento, pero también una mayor caché KV y presión de programación.

Si las solicitudes suelen contener mensajes largos, también debe prestar atención a --max-num-batched-tokens. Determina la cantidad máxima de tokens que se pueden procesar al mismo tiempo; si es demasiado alto, la fase de precarga puede ocupar más recursos al instante. Sea conservador al solucionar problemas y luego amplíelo gradualmente después de confirmar la estabilidad.

Se recomienda realizar pruebas de estrés en este orden:

1. Solicitud única, contexto 4K, estabilidad del servicio confirmada.
2. Solicitud única, contexto de 8K, observe la latencia del primer token y la memoria de video.
3. Dos solicitudes simultáneas confirman que no habrá OOM.
4. Luego, aumente gradualmente max_num_seqs o la cantidad de tokens por lotes.

No ajuste la cuantificación de contexto, concurrencia, lote y modelo al mismo tiempo; de lo contrario, será difícil localizar qué parámetro está provocando que se agote la memoria de vídeo.

Tercera prioridad: --gpu-memory-utilization configurado correctamente

--gpu-memory-utilization especifica la proporción de memoria GPU que puede utilizar la instancia vLLM actual, con un valor entre 0 y 1. vLLM planificará el peso, el tiempo de ejecución y la caché KV en función de esta parte del espacio.

Por ejemplo:

1
2
3
4

vllm serve Qwen/Qwen3-8B \
  --gpu-memory-utilization 0.90 \
  --max-model-len 8192 \
  --max-num-seqs 4

Cuando el mensaje de error dice claramente “Muy poca caché KV disponible” y no hay otros procesos en la GPU, puede mejorarlo en pequeños pasos, como intentar de 0.90 a 0.92 o 0.94. Agregue poco a poco y pruebe con solicitudes reales.

No se recomienda hacer peso muerto alto en las siguientes situaciones:

• En la misma tarjeta también se ejecuta un programa de escritorio, otro servicio de inferencia o una tarea de capacitación.
• La memoria de video disponible fluctuará después del inicio.
• Es probable que se produzcan picos cuando se utilizan gráficos CUDA, modelos de visión o precargas de alta concurrencia.
• Ha encontrado un CUDA OOM sobre la marcha, no solo una verificación de inicialización fallida.

Si varias instancias comparten la misma GPU, debes tener un presupuesto explícito para cada instancia en lugar de configurarlas todas en 0,9.

Caché FP8 KV: confirme el modelo y la versión antes de guardar la memoria gráfica

vLLM admite cambiar el tipo de datos de la caché mediante --kv-cache-dtype. Los entornos CUDA 11.8+ están disponibles con opciones relacionadas con FP8, como:

1
2
3

vllm serve Qwen/Qwen3-8B \
  --kv-cache-dtype fp8 \
  --max-model-len 16384

FP8 KV Cache puede reducir significativamente el uso de caché, pero no lo considere un cambio completamente gratuito:

• Primero confirme que el vLLM, CUDA y el hardware actuales admitan este tipo de datos.
• Si el punto de control del modelo proporciona una escala KV adecuada afectará los resultados; su ausencia debe evaluarse con cautela.
• Los contextos extensos, el razonamiento complejo, las llamadas a herramientas y la salida estructurada deben probarse con la precisión de la caché predeterminada.
• Si simplemente desea colocar un modelo grande inadecuado en la tarjeta gráfica, suele ser más estable bajar el contexto primero o cambiar a un modelo más adecuado.

Por lo tanto, el orden más recomendado es: primero usar la precisión predeterminada para ejecutar 4K/8K de manera estable y luego probar si FP8 realmente puede permitir que la empresa obtenga el contexto o la simultaneidad requerida.

Conozca las prioridades al especificar manualmente el tamaño de la caché KV

Los vLLM más nuevos proporcionan kv_cache_memory_bytes para especificar el tamaño de la caché KV con precisión en bytes por GPU. Es adecuado para escenarios en los que varios servicios comparten una tarjeta y requieren un presupuesto fijo de memoria gráfica.

Nota: Establecer explícitamente el número de bytes de caché anulará la inferencia automática del tamaño de caché a través de gpu_memory_utilization. No piense en ambos como ganancias aditivas; Primero decida si utilizará un “presupuesto proporcional” o un “presupuesto de caché fijo”.

El presupuesto fijo es adecuado para servidores con restricciones claras de operación y mantenimiento. Es más intuitivo utilizar --gpu-memory-utilization y --max-model-len para solucionar problemas de una sola máquina.

¿Qué puede resolver la descarga de CPU y qué no?

La nueva versión de vLLM admite la descarga de parte de KV Cache a la CPU o su combinación con capas de caché de procesamiento back-end como LMCache. Esto puede ampliar la capacidad cuando la caché de la GPU es insuficiente, pero a costa de las transferencias de memoria/PCIe y la latencia.

Es más adecuado para:

• Ocasionalmente solicitudes de contexto muy largas;
• La empresa puede aceptar un mayor retraso del token inicial;
• Hay suficiente memoria en el sistema y se han realizado pruebas de estrés reales;
• Quiere crear una ruta de degradación para mensajes largos en lugar de buscar el mayor rendimiento.

No es adecuado para encubrir el problema de que “el peso del modelo no se puede reducir”, ni puede reemplazar la gestión de la concurrencia y los límites superiores del contexto. Si todas las solicitudes se intercambian con frecuencia, el rendimiento a menudo disminuirá significativamente.

Una plantilla de solución de problemas replicable

Comience con una configuración conservadora:

1
2
3
4

vllm serve Qwen/Qwen3-8B \
  --gpu-memory-utilization 0.90 \
  --max-model-len 4096 \
  --max-num-seqs 2

Después de confirmar que la solicitud de pedido se puede procesar de manera estable, ajuste en el siguiente orden:

1
2
3
4
5

4096 上下文稳定
-> 8192 上下文稳定
-> max_num_seqs 从 2 调到 4
-> 调整 max_num_batched_tokens
-> 再测试 FP8 KV Cache 或 CPU offload

En cada ronda se registran cuatro datos: número de tokens de caché KV disponibles, retraso del primer token, tokens generados y memoria de video máxima. De esta manera, puede saber si una optimización mejora el rendimiento o simplemente difiere los OOM hacia una mayor concurrencia.

Malentendidos comunes

Malentendido 1: el modelo admite contexto largo, por lo que el servicio debe estar completamente habilitado

El límite superior de capacidades del modelo y el límite superior de capacidad de servicio de su tarjeta gráfica son dos cosas diferentes. El max_model_len del servidor debe configurarse de acuerdo con el límite superior empresarial y de hardware.

Malentendido 2: establezca gpu_memory_utilization en 1 para resolver el problema

Esto reduce el margen de seguridad y no reduce la necesidad del caché KV en sí. Es más probable que los picos de tiempo de ejecución activen CUDA OOM.

Malentendido 3: Reducir solo la cuantificación de peso, independientemente de la concurrencia

La cuantificación del peso puede liberar memoria de vídeo, pero la concurrencia y el contexto seguirán haciendo que la caché KV se expanda rápidamente. Las configuraciones del servicio deben limitar tanto la duración como el número de solicitudes.

Mito 4: descargar la CPU es definitivamente mejor que rechazar solicitudes largas

Si la latencia es sensible, la descarga frecuente puede ser peor que enrutar explícitamente solicitudes largas a nodos con mayor memoria. Primero defina los límites de demora y costos del negocio.

Resumir

vLLM KV Cache no tiene suficiente memoria. La prioridad de procesamiento más confiable es:

1
2
3
4
5

降低 max_model_len
-> 限制 max_num_seqs 与 batch
-> 小步调整 gpu_memory_utilization
-> 验证 FP8 KV Cache
-> 最后考虑固定缓存预算或 CPU offload

Primero deje que un contexto breve y una configuración de baja concurrencia funcionen de manera estable y luego amplíelos gradualmente de acuerdo con los datos comerciales. Siempre que el peso del modelo, la caché KV, la concurrencia y la longitud del contexto real se analicen por separado, la mayoría de los problemas de “falta de memoria” se pueden localizar más rápidamente.

referirse a:

• Configuración de caché de vLLM
• Lógica de informe de errores y cálculo de caché de vLLM KV
• Argumentos del motor vLLM
• Guía práctica de LMCache