Nano-vLLM: Una implementación mínima de vLLM para inferencia local

Nano-vLLM es una reimplementación de código abierto, desde cero, del vLLM servidor de inferencia, escrita en aproximadamente 1.200 líneas de Python. Fue lanzada a mediados de 2025 por Xingkai Yu, ingeniero de DeepSeek, bajo licencia MIT en github.com/GeeeekExplorer/nano-vllm. Es una base de código orientada a la enseñanza y una herramienta rápida para inferencia por lotes — no es un reemplazo listo para usar del servidor vLLM completo.

Qué es realmente Nano-vLLM

El repositorio principal vllm-project/vllm es un servidor de inferencia de gran tamaño y listo para producción, con cientos de colaboradores, una API HTTP compatible con OpenAI, trabajadores distribuidos y soporte para docenas de arquitecturas de modelos y esquemas de cuantización. Nano-vLLM lo reduce al bucle central: carga del modelo, un gestor de caché KV, un planificador por lotes y un muestreador.

Según el archivo README del proyecto, nano-vllm conserva las optimizaciones clave que hacen que vLLM sea rápido:

• Caché de prefijos — reutiliza bloques de caché KV entre solicitudes que comparten un prefijo de indicación.
• Paralelismo tensorial — divide un modelo entre varias GPU en un solo nodo.
• Compilación con Torch — utiliza torch.compile para la fusión de kernels.
• Grafos CUDA — reduce la sobrecarga de lanzamiento por paso durante la decodificación.

Lo que deliberadamente omite: el servidor HTTP compatible con OpenAI, las APIs de transmisión continua, la mayoría de los backends de cuantización (AWQ, GPTQ, FP8), la decodificación especulativa, el intercambio dinámico de LoRA, la agrupación multi-nodo y el amplio catálogo de modelos. Se prueba principalmente con modelos densos de la clase Qwen3.

Instalación de Nano-vLLM

Nano-vLLM es un paquete de Python. No existe una ruta de soporte nativo para CUDA en Windows en el repositorio principal; en Windows use WSL2 con un controlador NVIDIA. Linux y WSL2 son las plataformas principales. macOS no está soportado porque las rutas de código asumen CUDA.

Linux y WSL2

python -m venv .venv
source .venv/bin/activate
pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install git+https://github.com/GeeeekExplorer/nano-vllm.git

Ajuste la versión de la rueda CUDA (cu121, cu124, etc.) al controlador NVIDIA instalado. Verifíquelo con nvidia-smi antes de instalar.

Windows (mediante WSL2)

Instale el controlador NVIDIA para Windows, habilite WSL2 con una distribución Ubuntu (wsl --install -d Ubuntu), luego siga los pasos para Linux dentro de WSL. No instale el kit de herramientas CUDA dentro de WSL — el controlador de Windows expone la GPU.

macOS

No está soportado. Nano-vLLM depende de kernels CUDA y primitivas de atención paginada que no tienen backend Metal. En Apple Silicon use Ollama o LM Studio en su lugar, ambos ejecutan llama.cpp bajo el capó.

Descarga de un modelo

Nano-vLLM carga directorios estándar de modelos de Hugging Face — el mismo config.json, tokenizer.json y safetensors formato que usan transformers y vLLM. Descarga un modelo con la CLI oficial de Hugging Face: huggingface_hub CLI:

pip install -U "huggingface_hub[cli]"
hf download Qwen/Qwen3-8B --local-dir ~/models/Qwen3-8B

Consulta el documentación de la CLI de Hugging Face Hub Ten en cuenta que el punto de entrada anterior huggingface-cli sigue incluido en el paquete, pero ahora Hugging Face recomienda usar el comando hf hf.

Ejecución de inferencia

La API imita de cerca la interfaz por lotes sin conexión de vLLM. Un script mínimo:

from nanovllm import LLM, SamplingParams

llm = LLM("/home/user/models/Qwen3-8B", enforce_eager=False, tensor_parallel_size=1)
sp = SamplingParams(temperature=0.7, max_tokens=256)

prompts = ["Explica la atención paginada en un solo párrafo."]
outputs = llm.generate(prompts, sp)
print(outputs[0]["text"])

Los nombres exactos de las clases y la forma de los valores devueltos pueden variar entre versiones — consulta example.py en la raíz del repositorio, que es la referencia canónica de uso.

Requisitos de hardware según el modelo

Dado que nano-vLLM ejecuta actualmente los modelos en bf16/fp16 (sin cuantización integrada de 4 bits al momento de redactar este texto), los requisitos de VRAM son aproximadamente el doble de los valores indicados a continuación para 4 bits. Usa la Calculadora de VRAM tabla de requisitos de VRAM Base de datos de modelos de Convly — para nano-vLLM en bf16, presupuesta aproximadamente el doble de estos valores más margen adicional para la caché KV.

Modelo	Contexto	VRAM (referencia de 4 bits)	GPU realista para nano-vLLM
Qwen3 8B	128 K	~5 GB	Una sola RTX 4090 (24 GB) en bf16
Qwen3 14B	128 K	~9 GB	Una sola RTX 4090 en bf16 con contexto moderado
Qwen3 32B	128 K	~20 GB	2× RTX 4090 con tensor_parallel_size=2
Llama 3.1 8B	128 K	~5 GB	Una sola RTX 4090
Llama 3.3 70B	128 K	~40 GB	2× A100 de 80 GB o 4× RTX 4090

Para una visión más amplia de qué modelos caben en cada tarjeta, consulta la mejoras GPUs para modelos de lenguaje local y la tabla de requisitos de VRAM.

Nano-vLLM frente a vLLM frente a Ollama

Función	Nano-vLLM	vLLM	Ollama
Líneas de código	~1.200 líneas de Python	~100.000+ líneas de Python/C++/CUDA	Contenedor Go sobre llama.cpp
Servidor compatible con OpenAI	No	Sí	Sí (mediante /v1)
Backend	PyTorch + CUDA	PyTorch + kernels personalizados	llama.cpp (GGUF)
Cuantización	Mínima	AWQ, GPTQ, FP8, INT4	GGUF Q2–Q8
Multi-GPU	Paralelismo de tensores	Paralelismo de tensores + pipeline + expertos	Limitado
Uso principal	Aprendizaje, incrustaciones (embeddings)	Servicio en producción	Escritorio / desarrollo

Si tu objetivo es ofrecer un punto final orientado al cliente, usa vLLM completo. Si deseas integrar un bucle de inferencia por lotes dentro de un programa Python más grande con dependencias mínimas, nano-vLLM es una opción razonable. Si buscas un chatbot local con un solo comando, usa Ollama.

Cuándo tiene sentido usar Nano-vLLM

• Aprender los detalles internos. El planificador y el gestor de bloques caben en una sola pantalla. Leer el código de nano-vLLM es la forma más rápida de comprender la atención paginada en código real.
• Bifurcaciones para investigación. Modificar una base de código de 1.200 líneas para probar un nuevo muestreador o política de caché es factible; bifurcar vLLM upstream no lo es.
• Inferencia por lotes sin conexión. Calificación, generación de datos sintéticos, bucles de evaluación sobre un conjunto fijo de prompts.

Cuándo no tiene sentido: APIs en producción, servicio multiusuario, presupuestos ajustados de cuantización o cualquier hardware distinto de NVIDIA.

Autoalojamiento frente a API

Ejecutar nano-vLLM localmente implica costos reales: inversión en GPU, electricidad y tiempo de ingeniería. Los modelos alojados en la vanguardia suelen ser más económicos por token que la inferencia local amortizada a bajo volumen. Compara con la calculadora de autohospedaje frente a API y la Calculadora de costos de APItabla de precios comparativa. Qwen3 8B ejecutar Qwen3-0.6B en un punto final alojado cuesta $0,04 por entrada y $0,14 por salida por cada millón de tokens, según los datos de Convly Base de datos de modelos, mientras que una GPU de 24 GB capaz de ejecutarlo localmente cuesta mucho más de $1.500.

Preguntas frecuentes

¿Quién escribió nano-vllm?

El repositorio lo mantiene Xingkai Yu (usuario de GitHub GeeeekExplorer), ingeniero de DeepSeek. Se trata de un proyecto personal, no de una versión oficial de DeepSeek. El código está licenciado bajo MIT y se encuentra en github.com/GeeeekExplorer/nano-vllm.

¿Es nano-vllm más rápido que vLLM?

El README informa un rendimiento cercano al de vLLM en modelos densos pequeños como Qwen3-0.6B en una GPU de clase RTX 4070, e incluso ligeramente superior en algunas configuraciones de pruebas cortas debido a una menor sobrecarga del planificador. En modelos más grandes, contextos más largos o servicio con múltiples solicitudes, las optimizaciones de vLLM upstream superan claramente a nano-vLLM. Considera la equivalencia como «del mismo orden de magnitud para inferencia por lotes sin conexión», no como «un reemplazo estricto».

¿Puede nano-vllm ofrecer una API compatible con OpenAI?

No de forma nativa. El proyecto expone una API en Python LLM.generate() método para uso por lotes sin conexión. Si necesita un servidor HTTP con /v1/chat/completions, envuélvalo usted mismo con FastAPI o utilice el servidor compatible con OpenAI de vLLM o Ollama.

¿Admite nano-vllm modelos cuantizados como GGUF o AWQ?

No. La base de código carga pesos estándar de Hugging Face en formato safetensors, en bf16/fp16. Para formatos GGUF (como Q4_K_M, etc.), use herramientas basadas en llama.cpp; para AWQ o GPTQ, use vLLM oficial. Esta es una de las razones por las que la huella de VRAM de nano-vllm es mayor por parámetro que la de Ollama para el mismo modelo.

¿Qué modelos se sabe que funcionan?

Los modelos densos Qwen3 son el objetivo principal de la implementación de referencia. Otros modelos con arquitectura Llama suelen funcionar con ajustes menores en el cargador de modelos, pero arquitecturas exóticas (como mezcla de expertos o híbridas basadas en espacios de estado) generalmente no lo hacen. Consulte el directorio nanovllm/models/ del repositorio para ver la lista actual de modelos compatibles.

¿Puedo ejecutar nano-vllm en hardware AMD o Apple Silicon?

No actualmente. Los kernels asumen CUDA. ROCm podría funcionar con una compilación personalizada de PyTorch, pero no se ha probado oficialmente. En Apple Silicon no existe una ruta viable: use herramientas basadas en MLX o llama.cpp. Para una comparativa de alternativas, consulte la Clasificación de modelos de lenguaje grande (LLM) y seleccione un modelo que coincida con el perfil de su hardware.