Nano-vLLM: Un'implementazione minima di vLLM per l'inferenza locale

Nano-vLLM è una riscrittura open source, realizzata ex novo, del server di vLLM inferenza, scritta in circa 1.200 righe di Python. È stata rilasciata a metà 2025 da Xingkai Yu, ingegnere di DeepSeek, con licenza MIT su github.com/GeeeekExplorer/nano-vllm. Si tratta di un codebase pensato per fini didattici e di uno strumento efficiente per l'inferenza batch — non è un sostituto immediato del server vLLM completo.

Che cos'è realmente Nano-vLLM

Il repository upstream vllm-project/vllm è un server di inferenza di livello produttivo, ampio e maturo, con centinaia di contributori, un'API HTTP compatibile con OpenAI, worker distribuiti e supporto per decine di architetture di modelli e schemi di quantizzazione. Nano-vLLM ne estrae invece soltanto il ciclo fondamentale: caricamento del modello, gestore della cache KV, scheduler per il batching e sampler.

Secondo il README del progetto, nano-vllm mantiene le principali ottimizzazioni che rendono vLLM veloce:

• Cache dei prefissi (prefix caching) — riutilizza i blocchi della cache KV tra richieste che condividono un prefisso comune del prompt.
• Parallelismo tensoriale (tensor parallelism) — suddivide un modello su più GPU all'interno di un singolo nodo.
• Compilazione con Torch (torch compilation) — utilizza torch.compile per la fusione dei kernel.
• Grafi CUDA (CUDA graphs) — riduce l'overhead di lancio per ogni passo durante la fase di decodifica.

Ciò che intenzionalmente non include: il server HTTP compatibile con OpenAI, le API di streaming continuo, la maggior parte dei backend di quantizzazione (AWQ, GPTQ, FP8), il decoding speculativo, lo scambio dinamico di LoRA, il clustering multi-nodo e l'ampio catalogo di modelli. È testato principalmente con modelli densi di classe Qwen3.

Installare Nano-vLLM

Nano-vLLM è un pacchetto Python. Il repository upstream non prevede un percorso nativo per CUDA su Windows; su Windows utilizzare WSL2 con driver NVIDIA. Linux e WSL2 sono le piattaforme principali. macOS non è supportato perché il codice presuppone CUDA.

Linux e 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

Allineare la versione di CUDA (cu121, cu124, ecc.) al driver NVIDIA installato. Verificare con nvidia-smi prima dell'installazione.

Windows (tramite WSL2)

Installare il driver NVIDIA per Windows, abilitare WSL2 con una distribuzione Ubuntu (wsl --install -d Ubuntu), quindi seguire i passaggi per Linux all'interno di WSL. Non installare il toolkit CUDA all'interno di WSL — il driver Windows espone già la GPU.

macOS

Non supportato. Nano-vLLM dipende da kernel CUDA e primitive di attenzione a pagine (paged-attention) prive di backend Metal. Su Apple Silicon utilizzare Ollama o LM Studio invece, entrambi dei quali eseguono llama.cpp sotto il cofano.

Scaricare un modello

Nano-vLLM carica le directory standard dei modelli di Hugging Face — esattamente le stesse config.json, tokenizer.json e safetensors struttura utilizzata da transformers e vLLM. Scarica un modello con il comando ufficiale huggingface_hub CLI:

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

Consultate il documentazione della CLI di Hugging Face Hub per l'autenticazione e per i modelli soggetti a restrizioni. Nota che il vecchio huggingface-cli punto di ingresso è ancora incluso nel pacchetto, ma Hugging Face ora raccomanda l'uso del comando hf .

Eseguire l'inferenza

L'API rispecchia da vicino l'interfaccia offline per batch di vLLM. Uno script minimo:

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 = ["Spiega l'attenzione paginata in un solo paragrafo."]
outputs = llm.generate(prompts, sp)
print(outputs[0]["text"])

I nomi esatti delle classi e la forma dei valori restituiti potrebbero variare tra commit diversi — consulta example.py nella radice del repository, che costituisce il riferimento ufficiale per l'utilizzo.

Requisiti hardware per modello

Poiché nano-vllm attualmente esegue i modelli in bf16/fp16 (senza quantizzazione nativa a 4 bit al momento della stesura), i requisiti di VRAM sono approssimativamente il doppio dei valori indicati qui sotto per la quantizzazione a 4 bit. Usa la Calcolatore VRAM tabella dei requisiti di VRAM Database di modelli di Convly — per nano-vllm in bf16, prevedi circa il doppio di questi valori più una riserva per la cache KV.

Modello	Contesto	VRAM (riferimento a 4 bit)	GPU NVIDIA realistica per nano-vllm
Qwen3 8B	128K	~5 GB	Singola RTX 4090 (24 GB) in bf16
Qwen3 14B	128K	~9 GB	Singola RTX 4090 in bf16 con contesto moderato
Qwen3 32B	128K	~20 GB	2× RTX 4090 con tensor_parallel_size=2
Llama 3.1 8B	128K	~5 GB	Singola RTX 4090
Llama 3.3 70B	128K	~40 GB	2× A100 80 GB oppure 4× RTX 4090

Per una visione più ampia di quali modelli si adattano a ciascuna GPU, consulta la le migliori GPU per LLM locali e il tabella dei requisiti di VRAM.

Nano-vLLM vs vLLM vs Ollama

Funzionalità	Nano-vLLM	vLLM	Ollama
Numero di righe	~1.200 righe Python	~100.000+ righe Python/C++/CUDA	Wrapper Go su llama.cpp
Server compatibile con OpenAI	No	Sì	Sì (tramite /v1)
Backend	PyTorch + CUDA	PyTorch + kernel personalizzati	llama.cpp (GGUF)
Quantizzazione	Minimale	AWQ, GPTQ, FP8, INT4	Q2–Q8 GGUF
Multi-GPU	Parallelismo tensoriale	Parallelismo tensoriale + pipeline + esperto	Limitato
Utilizzo principale	Apprendimento, embedding	Servizio in produzione	Desktop / sviluppo

Se il tuo obiettivo è servire un endpoint rivolto ai clienti, usa vLLM completo. Se desideri integrare un ciclo di inferenza batch all'interno di un programma Python più ampio con dipendenze minime, nano-vllm è una scelta ragionevole. Se invece cerchi un chatbot locale avviabile con un singolo comando, usa Ollama.

Quando ha senso utilizzare Nano-vLLM

• Studio degli aspetti interni. Lo scheduler e il gestore di blocchi occupano una sola schermata. Leggere il codice di nano-vllm è il modo più rapido per comprendere concretamente l'attenzione paginata.
• Fork per ricerca. Modificare un codebase di 1.200 righe per testare un nuovo sampler o una nuova politica di cache è fattibile; fare un fork di vLLM upstream non lo è.
• Inferenza batch offline. Valutazione automatica, generazione di dati sintetici, cicli di valutazione su un insieme fisso di prompt.

Quando non ha senso: API in produzione, servizio multi-tenant, budget stringenti per la quantizzazione o qualsiasi hardware non NVIDIA.

Auto-hosting vs API

Eseguire nano-vllm localmente comporta costi reali — investimento in GPU, consumo elettrico e tempo ingegneristico. I modelli ospitati sui servizi avanzati sono spesso meno costosi per token rispetto all'inferenza locale ammortizzata, specialmente a basso volume. Confronta con la calcolatore self-hosting vs API e il Calcolatore dei costi APItabella dei costi Qwen3 8B l'esecuzione di Qwen3-8B su un endpoint ospitato costa $0,04 in ingresso / $0,14 in uscita ogni milione di token secondo i dati di Convly Database di modelli, mentre una GPU da 24 GB in grado di eseguirlo localmente costa ben oltre $1.500.

Domande frequenti

Chi ha scritto nano-vllm?

Il repository è mantenuto da Xingkai Yu (nickname GitHub GeeeekExplorer), ingegnere presso DeepSeek. Si tratta di un progetto personale, non di un rilascio ufficiale di DeepSeek. Il codice è rilasciato con licenza MIT ed è disponibile su github.com/GeeeekExplorer/nano-vllm.

Nano-vllm è più veloce di vLLM?

Il README riporta un throughput vicino a quello di vLLM su piccoli modelli densi come Qwen3-0.6B su una singola GPU di classe RTX 4070, e in alcune configurazioni di benchmark brevi risulta leggermente più veloce grazie alla minore sovracarica dello scheduler. Su modelli più grandi, contesti più lunghi o servizio multiplo richieste, le ottimizzazioni di vLLM upstream prendono il sopravvento. Considera la parità come «nello stesso ordine di grandezza per l'inferenza batch offline», non come «sostituto rigoroso».

Nano-vllm può esporre un'API compatibile con OpenAI?

Non nativamente. Il progetto espone un'interfaccia Python LLM.generate() metodo per l’uso offline in batch. Se hai bisogno di un server HTTP con /v1/chat/completions, implementalo autonomamente con FastAPI oppure utilizza il completo server OpenAI-compatibile di vLLM o Ollama.

Nano-vllm supporta modelli quantizzati come GGUF o AWQ?

No. Il codice carica i pesi standard di Hugging Face in formato safetensors, in bf16/fp16. Per i formati GGUF (ad esempio Q4_K_M) utilizza strumenti basati su llama.cpp; per AWQ o GPTQ usa invece vLLM upstream. Questo è uno dei motivi per cui l’occupazione di VRAM di nano-vllm è maggiore per parametro rispetto a quella di Ollama per lo stesso modello.

Quali modelli sono noti per funzionare?

I modelli densi Qwen3 sono l’obiettivo principale dell’implementazione di riferimento. Altri modelli basati sull’architettura Llama funzionano spesso con piccoli adattamenti al caricatore di modelli, ma architetture particolari (ad esempio mixture-of-experts o ibride state-space) in genere non sono supportate. Consulta la directory nanovllm/models/ del repository per l’elenco aggiornato dei modelli supportati.

Posso eseguire nano-vllm su hardware AMD o Apple Silicon?

Non al momento. I kernel presuppongono CUDA. ROCm potrebbe funzionare con una build personalizzata di PyTorch, ma non è stato testato ufficialmente. Su Apple Silicon non esiste alcuna soluzione — utilizza strumenti basati su MLX o llama.cpp. Per una panoramica delle alternative, consulta la Classifica LLM e scegli un modello compatibile con il tuo profilo hardware.