Cuando vLLM falla, el mensaje suele señalar al culpable: no hay versión lista para Windows ni macOS, no ve la tarjeta, el driver es viejo para CUDA 13, la memoria está ocupada, la caché no cabe, los pesos tampoco, no puede bajar el modelo o el puerto está ocupado. Aquí van los 8, con su texto exacto y el arreglo.
vLLM es un motor pensado para servir modelos a mucha gente a la vez, y verlo funcionar en tu propia tarjeta NVIDIA es como llevarte a casa el kit de un centro de datos para el fin de semana. La otra cara es que dice que no más a menudo que Ollama o LM Studio, y con frases más largas. Hemos comprobado cada mensaje de esta página el 15 de octubre de 2026 contra el código de vLLM 0.31.0, que ese día seguía siendo la última versión estable, y contra el PyTorch 2.13.0 que trae consigo. El 19 de octubre de 2026 los cotejamos con el código de la 0.32.0, la estable desde el 18 de octubre de 2026: los mensajes que salen del propio código de vLLM son idénticos palabra por palabra, y los pocos detalles que sí han cambiado van señalados más abajo. Los mensajes de pip y de Hugging Face los provocamos nosotros; el resto sale directamente de ese código y de su gestor de incidencias. Cómo instalarlo y arrancar el primer modelo está en nuestra guía para instalar vLLM; esta página empieza donde acaba aquella.
vLLMFicha del programaWindows y macOS: «No matching distribution found for vllm»
Muchas veces el primer muro es el propio instalador:
ERROR: Could not find a version that satisfies the requirement vllm==0.31.0 (from versions: none)
ERROR: No matching distribution found for vllm==0.31.0Nos salió exactamente eso al pedirle a pip solo versiones ya compiladas (--only-binary=:all:) de vLLM 0.31.0, primero como si estuviéramos en Windows y luego como si fuera un Mac con Apple silicon. La razón es sencilla: en PyPI, la 0.31.0 solo publica versiones compiladas para Linux, en x86_64 y en ARM, y la 0.32.0 publica las mismas 2. Un pip install vllm a secas va un paso más allá: descarga el paquete de código fuente (44,5 MB en la 0.32.0; 43,4 MB en la 0.31.0) e intenta compilarlo, y en Windows ese no es el camino hacia un vLLM que funcione. La documentación de vLLM lo dice sin rodeos: «vLLM does not support Windows natively». En Windows, la entrada es WSL 2 con un Ubuntu dentro. Un detalle de NVIDIA que te ahorra una tarde: no instales ningún driver de pantalla de Linux dentro de WSL. El driver normal de Windows ya le pasa la tarjeta a WSL, y nvidia-smi ejecutado dentro de Ubuntu tiene que mostrarla antes de seguir.
En un Mac, vLLM solo funciona en la CPU, como soporte experimental, en FP32 y FP16, y la documentación te manda compilarlo desde el código fuente. La versión 0.31.0 sí adjunta una compilación para CPU de Apple silicon y Python 3.12 que, según la documentación, todavía no existe, y la 0.32.0 adjunta una que ya no va atada a Python 3.12; no hemos probado ninguna de las dos. Para la GPU del Mac, vLLM remite a vLLM-Metal, un complemento de la comunidad que funciona sobre MLX. Si lo que quieres es un modelo rápido en un Mac, nuestra guía para instalar MLX es el camino corto.
Otro mensaje de pip que conviene conocer: pide vllm==0.32.0 con Python 3.10, o cualquier versión compilada con la 3.9, y te sale ERROR: Ignored the following versions that require a different python version, seguido de una lista que acaba en 0.32.0 Requires-Python <3.15,>=3.11 (así nos lo imprimió pip 25.1 el 21 de octubre de 2026, al pedírselo como si estuviéramos en Python 3.10). Desde la 0.32.0, la guía de vLLM pide Python 3.11 a 3.14. Ojo con la 3.10: ahí un pip install vllm a secas no falla, te instala sin avisar la 0.31.0: ni un aviso, solo el número de versión en la última línea de pip y en vllm --version.
«Failed to infer device type» o «No CUDA GPUs are available»: vLLM no ve la tarjeta
Este aparece antes de que cargue ningún modelo:
RuntimeError: Failed to infer device type, please set the environment variable `VLLM_LOGGING_LEVEL=DEBUG` to turn on verbose logging to help debug the issue.Al arrancar, vLLM busca una plataforma: una tarjeta NVIDIA (a través de la biblioteca de gestión de NVIDIA), AMD, Intel y algunas más. La CPU solo cuenta si instalaste una versión para CPU, pusiste VLLM_TARGET_DEVICE=cpu o estás en un Mac. La versión normal de PyPI, en un equipo donde no se ve ninguna tarjeta NVIDIA, no encuentra nada, y este es el resultado. La palabra clave es «se ve»: un contenedor Docker arrancado sin --gpus all, un WSL donde la tarjeta no aparece o un portátil sin NVIDIA acaban igual.
Su primo viene de PyTorch: RuntimeError: No CUDA GPUs are available. Significa que PyTorch ha contado 0 tarjetas. El propio código de vLLM usa ese mismo texto como señal de que CUDA_VISIBLE_DEVICES está vacía, así que mira esa variable lo primero: con un valor vacío, o con el número de una tarjeta que no existe, le esconde todas las tarjetas al proceso.
«The NVIDIA driver on your system is too old» o «no kernel image is available»
Aquí vLLM sí ha encontrado la tarjeta, y es PyTorch quien se para justo después:
RuntimeError: The NVIDIA driver on your system is too old (found version 12080). Please update your GPU driver by downloading and installing a new version from the URL: http://www.nvidia.com/Download/index.aspx Alternatively, go to: https://pytorch.org to install a PyTorch version that has been compiled with your version of the CUDA driver.El número es la versión de CUDA más nueva que admite tu driver, escrita como 1000 × mayor + 10 × menor: 12080 significa CUDA 12.8. Ahí está la trampa, porque el paquete de PyPI, en la 0.31.0 igual que en la 0.32.0, está compilado para CUDA 13.0, como dicen sus notas de versión (la página de instalación de esa etiqueta todavía dice 12.9). Y la regla de NVIDIA es que los programas de CUDA 13 necesitan un driver de la versión 580 o posterior. Tienes 2 salidas. La limpia: actualizar el driver a la 580 o posterior y comprobar que nvidia-smi muestra «CUDA Version: 13.0» o más en su esquina superior derecha. Si no puedes actualizar, vLLM publica una compilación para CUDA 12.9 de la misma versión en su página de versiones, y una imagen Docker vllm/vllm-openai:v0.32.0-cu129 (v0.31.0-cu129 para la 0.31.0); su guía de instalación trae el comando para elegir la compilación según la versión de CUDA.
El otro mensaje de esta familia no tiene nada que ver con el driver:
torch.AcceleratorError: CUDA error: no kernel image is available for execution on the deviceSignifica que el código no se compiló para la arquitectura de tu tarjeta: o la tarjeta es demasiado vieja, o la compilación o imagen que usas la deja fuera. vLLM pide una tarjeta NVIDIA con capacidad de cómputo 7.5 o superior: T4, RTX serie 20 y posteriores. Las tarjetas NVIDIA de nuestro catálogo están todas por encima: las RTX 3060 y 3090 son 8.6, y las RTX 4060, 4070 y 4090, 8.9. En una tarjeta más antigua, PyTorch suele avisar antes con … with CUDA capability sm_XX is not compatible with the current PyTorch installation. Si ves esa línea, no hay ajuste que lo arregle: la tarjeta no llega al listón.
«Free memory on device … is less than desired GPU memory utilization»
Esto es vLLM siendo glotón a propósito. Al arrancar quiere para sí una parte fija de la tarjeta, por defecto el 0,92 de su memoria total, y compara esa parte con la memoria que está libre en ese momento:
ValueError: Free memory on device … (X/Y GiB) on startup is less than desired GPU memory utilization (0.92, Z GiB). Decrease GPU memory utilization or reduce GPU memory used by other processes.X es lo que estaba libre, Y el total de la tarjeta y Z el 92 % que quería vLLM. Todo lo que ya ocupa la tarjeta juega en tu contra: el escritorio, un navegador que usa la GPU, Ollama con un modelo todavía cargado o un segundo vLLM. El arreglo es el que da el propio mensaje. Baja la parte con --gpu-memory-utilization 0.85, o libera antes la tarjeta: nvidia-smi enseña qué está usando memoria. El valor es un límite por proceso, así que 2 servidores de vLLM en 1 tarjeta necesitan cada uno su propio valor, más pequeño: la documentación de vLLM pone 0,5 para cada uno como ejemplo. En este vídeo corto, un desarrollador mantiene 2 modelos cargados en una sola tarjeta de 96 GB, uno a 0,7 y el otro a 0,2, y deja un 10 % libre:
Se abre en YouTube (sin cookies) solo si pulsas.
«To serve at least one request with the model’s max seq len»: la caché KV no cabe
Es el error más «vLLM» de todos y, cuando sabes leerlo, el que más ayuda:
ValueError: To serve at least one request with the model's max seq len (40960), (5.62 GiB KV cache is needed, which is larger than the available KV cache memory (Y GiB). Based on the available memory, the estimated maximum model length is Z. Try increasing `gpu_memory_utilization` (which also controls CPU memory on the CPU backend) or decreasing `max_model_len` when initializing the engine. See https://docs.vllm.ai/en/latest/configuration/conserving_memory/ for more details.La caché KV es la memoria donde el modelo guarda la conversación en la que está trabajando. vLLM no la hace crecer sobre la marcha: si no le dices otra cosa, la prepara para el contexto más largo que acepta el modelo, sacado de su propia configuración, y se niega a arrancar si no cabe una petición de esa longitud completa. Si después de los pesos no queda nada en absoluto, el mensaje es más corto: No available memory for the cache blocks. Y si usas un vLLM antiguo, el mismo problema se lee así: The model's max seq len (4096) is larger than the maximum number of tokens that can be stored in KV cache (3664).
Lo útil es la Z: vLLM ya ha calculado el contexto más largo que cabría. Úsalo, o redondéalo hacia abajo:
vllm serve Qwen/Qwen3-8B-AWQ --max-model-len 16384Ojo con la mayúscula si usas un sufijo: 16K son 16.384, y 16k, 16.000. Con --max-model-len auto (o -1), vLLM elige por su cuenta el contexto más largo que cabe y lo dice en el registro: Auto-fit max_model_len: reduced from … to … to fit in available GPU memory (… GiB available for KV cache). Y si pides más de lo que permite el modelo, se para con User-specified max_model_len (…) is greater than the derived max_model_len (…).
Cuánto contexto entra en cada GiB depende de la arquitectura del modelo, no de su tamaño. Nuestras cuentas, con la misma fórmula que usa vLLM para las capas de atención completa y una caché de 16 bits:
| Modelo | Caché por token | Tokens por GiB de caché | Contexto por defecto | Caché con ese contexto |
|---|---|---|---|---|
| Qwen3 8B | 144 KiB | 7.281 | 40.960 | 5,625 GiB |
| Qwen3 4B 2507 | 144 KiB | 7.281 | 262.144 | 36,0 GiB |
| Granite 4.2 8B | 160 KiB | 6.553 | 131.072 | 20,0 GiB |
| Qwen3 Coder 30B | 96 KiB | 10.922 | 262.144 | 24,0 GiB |
Calculado por Local AI Scope el 15 de octubre de 2026: 2 × capas × cabezas KV × tamaño de cabeza × 2 bytes por token, con la configuración de cada modelo, los datos que usa nuestro buscador de modelos. Los modelos con capas de ventana deslizante o de atención lineal siguen otras reglas y se quedan fuera.
PC con RTX 3060 12 GBFicha del equipo
Otra palanca: --kv-cache-dtype fp8 guarda la caché en 8 bits en vez de 16, la mitad de memoria por token. Con eso ganas contexto, y es un intercambio que no hemos medido, así que pruébalo con tus propias peticiones. Si quieres la foto completa, la charla del propio vLLM en la PyTorch Conference 2025 entra en cómo gestiona la caché KV a partir del minuto 10:08:
Se abre en YouTube (sin cookies) solo si pulsas. Más vídeos en su ficha →
«CUDA out of memory» al cargar: los pesos no caben
Cuando el que no cabe es el propio modelo, vLLM ni siquiera llega a la caché. PyTorch se para durante la carga:
torch.OutOfMemoryError: CUDA out of memory. Tried to allocate … GPU 0 has a total capacity of … of which … is free. …La causa habitual es un modelo en su formato original de 16 bits. vLLM carga esos ficheros safetensors tal cual, y Qwen3 8B en BF16 ocupa 15,26 GiB: en una tarjeta de 12 GB no cabe antes del primer token. Los arreglos, sacados de la guía de vLLM para ahorrar memoria, en el orden en que los probaríamos nosotros:
- Una versión cuantizada. El mismo modelo en AWQ ocupa 5,68 GiB, y en FP8, 8,79 GiB. Busca esas versiones en Hugging Face; a menudo las publican los propios autores del modelo.
- Menos contexto y menos peticiones a la vez:
--max-model-leny--max-num-seqs. - Sin grafos CUDA:
--enforce-eagerse los salta y libera su memoria, a cambio de algo de velocidad. - Más de 1 tarjeta:
--tensor-parallel-size 2reparte el modelo entre 2 GPU.
Un aviso si vienes de Ollama: los tamaños de nuestro buscador de modelos son de ficheros GGUF, como Q4_K_M, que vLLM no carga de serie. Para vLLM son una orientación, no la misma cifra.
«Invalid repository ID», modelos con acceso restringido y «trust_remote_code»
vLLM baja los modelos de Hugging Face, y de ahí vienen 3 tipos de mensaje. Una sola errata en el nombre da esto, con el Repository Not Found de Hugging Face debajo:
ValueError: Invalid repository ID or local directory specified: 'Qwen/Qwen3-8BB'.
Please verify the following requirements:
1. Provide a valid Hugging Face repository ID.
2. Specify a local directory that contains a recognized configuration file.
- For Hugging Face models: ensure the presence of a 'config.json'.
- For Mistral models: ensure the presence of a 'params.json'.Revisa el nombre letra a letra. Si el nombre está bien pero el modelo te obliga a aceptar sus condiciones antes, como hacen los Llama de Meta, el texto que aparece más arriba en la traza es este, que nos salió al pedir Llama 3.1 8B sin iniciar sesión:
Cannot access gated repo for url https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct/resolve/main/config.json.
Access to model meta-llama/Llama-3.1-8B-Instruct is restricted. You must have access to it and be authenticated to access it. Please log in.Acepta las condiciones en la página del modelo con tu cuenta y después inicia sesión una vez con hf auth login. vLLM lee el token que guarda, y también acepta uno con --hf-token o con la variable HF_TOKEN.
El tercero es un modelo que trae su propio código Python. Con la versión de transformers que instala vLLM 0.31.0 (usamos la 5.17.0, que la 0.32.0 también acepta), se lee así:
ValueError: The repository THUDM/chatglm3-6b contains custom code which must be executed to correctly load the model. You can inspect the repository content at https://hf.co/THUDM/chatglm3-6b .
You can inspect the repository content at https://hf.co/THUDM/chatglm3-6b.
Please pass the argument `trust_remote_code=True` to allow custom code to be run.En la línea de comandos, el interruptor es --trust-remote-code. Y si la arquitectura del modelo sencillamente no está en vLLM, el mensaje es Model architectures ['…'] are not supported for now. Supported architectures: …, o, para algunas antiguas, … was supported in vLLM until v0.23.0, and is not supported anymore. Los ficheros GGUF son un caso aparte: su soporte vive ahora en un complemento, vllm-gguf-plugin, que la documentación de vLLM todavía califica de «highly experimental».
Puerto 8000: «Address already in use» y «Engine core initialization failed»
vllm serve reserva su puerto antes incluso de arrancar el motor, así que un puerto ocupado falla en segundos, sin cargar nada:
OSError: [Errno 98] Address already in usePor defecto ese puerto es el 8000, en todas las interfaces de red. Hay otra cosa escuchando ahí: otro vLLM que se te olvidó o cualquier otro servidor. Averigua quién lo tiene, o usa otro puerto:
ss -ltnp | grep :8000
vllm serve Qwen/Qwen3-8B-AWQ --port 8001El último mensaje es el que más gente copia cuando pide ayuda, y no es una causa en absoluto:
RuntimeError: Engine core initialization failed. See root cause above. Failed core proc(s): {}vLLM ejecuta el modelo en un proceso aparte y, cuando ese proceso muere al arrancar, esta línea es solo el envoltorio. «See root cause above» significa exactamente eso: sube por el registro hasta el primer error, y será uno de los de esta página, muy a menudo los de memoria. Un informe del gestor de incidencias de vLLM lo muestra encima de un [Errno 98] Address already in use de uno de sus procesos de trabajo. Y cuando arranque, cierra lo que abre a la red: nuestra guía para instalar vLLM explica por qué escucha en 0.0.0.0, sin clave.
Mensajes y valores por defecto sacados del código de vLLM 0.31.0 y de PyTorch 2.13.0, de las guías de instalación y de memoria de vLLM en esa etiqueta, de la documentación de CUDA de NVIDIA, de Hugging Face, del gestor de incidencias de vLLM y de nuestras propias pruebas con pip, transformers 5.17.0 y huggingface_hub 1.33.0, el 15 de octubre de 2026. Mensajes de vLLM cotejados de nuevo con el código de la 0.32.0 el 19 de octubre de 2026, y el mensaje de Python de pip, el 21 de octubre de 2026.
¿Usas también Ollama, LM Studio o MLX? Sus errores son otros, y sus arreglos también: ¿Ollama no funciona? 9 errores, su mensaje exacto y el arreglo, ¿LM Studio no funciona? 7 errores, su mensaje exacto y el arreglo y ¿MLX no funciona? 7 errores, su mensaje exacto y el arreglo. Y para saber qué envía vLLM mientras todo esto funciona, mira su ficha: vLLM: qué manda a casa y si lo puedes auditar.