Cos'è vLLM? Una guida pratica al motore open source per la distribuzione efficiente di modelli linguistici di grandi dimensioni

vLLM è un motore open source per l'inferenza e la distribuzione di modelli linguistici di grandi dimensioni. Carica un modello su una o più GPU ed espone le sue funzionalità tramite un'API HTTP compatibile con OpenAI, utilizzando due tecniche — PagedAttention e batching continuo — per gestire molte richieste concorrenti con un throughput molto superiore rispetto a soluzioni naive. È stato sviluppato presso il Sky Computing Lab dell'Università della California a Berkeley ed è stato rilasciato nel 2023.

Cos'è vLLM e per chi è pensato

Immagina vLLM come la controparte orientata alla produzione degli strumenti desktop come Ollama. Entrambi accettano un modello e rispondono alle richieste, ma ottimizzano obiettivi opposti. Ollama è ottimizzato affinché una persona ottenga una risposta su hardware modesto. vLLM è invece ottimizzato per throughput: numero totale di token generati al secondo su decine o centinaia di richieste simultanee indirizzate alla stessa GPU.

Questo rende vLLM lo strumento giusto quando:

• Eseguire un modello linguistico di grandi dimensioni (LLM) dietro un'API interna o pubblica utilizzata da più persone o servizi
• Eseguire processi batch — classificazione, estrazione, generazione di dati sintetici — su grandi insiemi di dati
• Sostituire un'API a pagamento con un modello open-weight auto-ospitato per ridurre i costi per token (il calcolatore del punto di pareggio tra auto-ospitamento e API ti aiuta a verificare se il costo relativo alla GPU risulti effettivamente inferiore a quello dell'API, in base al tuo volume di utilizzo)

E lo strumento sbagliato quando desideri un assistente conversazionale sul tuo laptop personale, eseguire inferenze occasionali per un singolo utente o qualsiasi operazione su una macchina priva di una GPU performante. vLLM presuppone un ambiente server: Linux, una GPU NVIDIA come percorso predefinito (esistono tuttavia backend per AMD ROCm, Intel, TPU e CPU, ma sono meno consolidati), e un carico di lavoro caratterizzato da concorrenza.

Alla sua introduzione nel 2023, i benchmark di vLLM hanno mostrato un throughput fino a 24 volte superiore rispetto all'utilizzo di Hugging Face Transformers in versione base e circa 2–3,5 volte superiore rispetto ai sistemi di inferenza disponibili all'epoca. I valori esatti variano in funzione del modello, dell'hardware e del carico di lavoro — tuttavia la ragione di questo divario merita di essere compresa, poiché chiarisce esattamente quando vLLM risulta particolarmente vantaggioso.

PagedAttention, in termini semplici

Quando un LLM genera del testo, mantiene una cache KV cache KV nella memoria della GPU: le chiavi e i valori dell'attenzione per ogni token in ogni conversazione attiva. Questa cache cresce con ogni token generato e, per contesti lunghi, può occupare più VRAM rispetto ai pesi stessi del modello.

Prima di vLLM, i motori di inferenza allocavano a ciascuna richiesta un blocco contiguo di memoria dimensionato sulla base della lunghezza massima possibile della sequenza, poiché non era possibile sapere in anticipo quanto sarebbe stata lunga l'uscita. La maggior parte delle richieste termina ben prima della lunghezza massima, quindi gran parte di tale memoria riservata rimaneva inutilizzata. Il paper originale di vLLM ha rilevato che nei sistemi precedenti fino al 60–80% della memoria destinata alla cache KV veniva sprecato a causa di questo tipo di frammentazione.

PagedAttention adotta una soluzione già nota dai sistemi operativi: la paginazione della memoria virtuale. La cache KV viene suddivisa in piccoli blocchi di dimensione fissa (16 token ciascuno per impostazione predefinita), allocati su richiesta e non necessariamente contigui. Una tabella dei blocchi associa le posizioni logiche di ciascuna sequenza ai blocchi fisici disponibili — esattamente come un sistema operativo mappa pagine virtuali nella RAM fisica. Lo spreco di memoria scende sotto il 4% e i blocchi possono persino essere condivisi tra diverse sequenze (utile, ad esempio, quando si generano più completamenti a partire da un singolo prompt).

La conseguenza pratica è che un numero molto maggiore di sequenze concorrenti può essere ospitato nella stessa quantità di VRAM. Più sequenze in memoria significano batch effettivi più grandi, e batch più grandi sono ciò che mantiene la GPU costantemente occupata. Questa è l’intera storia del throughput — PagedAttention non rende più veloce alcuna singola richiesta; permette semplicemente di eseguirne molte contemporaneamente.

Batching continuo

La seconda tecnica affronta la pianificazione (scheduling), anziché la gestione della memoria. Il batching naïve raggruppa le richieste, esegue l’intero batch fino al termine e poi avvia il successivo — pertanto una richiesta che termina dopo 20 token deve attendere quella che ne genera 2.000, mentre le nuove richieste restano in coda all’esterno. Batching continuo (detto anche scheduling a livello di iterazione) ricompone il batch a ogni passo di generazione: le sequenze completate escono immediatamente e le richieste in attesa entrano subito nel batch.

La GPU rimane costantemente satura, le richieste brevi non vengono ostaggio di quelle lunghe e sia la latenza sotto carico che il throughput migliorano. PagedAttention e il batching continuo si combinano sinergicamente: il primo consente di caricare più sequenze in memoria, il secondo garantisce che questa capacità venga effettivamente sfruttata.

Installazione di vLLM: i vincoli che causano problemi

L’installazione richiede un solo comando, ma tre vincoli causano la maggior parte degli errori di installazione:

1. Versione di Python. Le versioni recenti supportano approssimativamente la gamma Python 3.9–3.12, e la finestra di compatibilità può variare tra le release. Se pip restituisce l’errore «no matching distribution», la versione di Python è il primo sospettato.
2. Versione di CUDA. I pacchetti precompilati sono stati compilati contro una specifica versione principale di CUDA (CUDA 12.x per le release correnti). È necessario disporre di un driver NVIDIA recente; per alcune release esistono pacchetti compatibili con altre versioni di CUDA, accessibili tramite URL speciali indicati nella documentazione ufficiale di vLLM.
3. Conflitti con PyTorch. vLLM fissa una versione specifica di PyTorch. Installarlo in un ambiente che già contiene una versione diversa di Torch è il modo più comune per incorrere in criptici errori di importazione. Si raccomanda sempre di utilizzare un ambiente virtuale pulito.

Dal punto di vista hardware, il percorso principale richiede una GPU NVIDIA con compute capability 7.0 o superiore — V100, T4, serie RTX 20 e successive. Se stai scegliendo l’hardware, consulta la guida alle migliori GPU per eseguire LLM localmente.

Linux (piattaforma supportata)

python3 -m venv vllm-env
source vllm-env/bin/activate
pip install vllm

La documentazione ufficiale di vLLM raccomanda inoltre uv (uv venv e successivamente uv pip install vllm), che risolve le dipendenze fissate più rapidamente. In entrambi i casi, l’obiettivo è comunque quello di garantire un ambiente pulito.

Windows: utilizza WSL2 o Docker

Non esiste alcuna build nativa per Windows. Le configurazioni funzionanti sono WSL2 con una distribuzione Ubuntu (il driver NVIDIA per Windows abilita il supporto CUDA in WSL2, quindi le istruzioni Linux riportate sopra funzionano perfettamente al suo interno) oppure Docker Desktop con il supporto GPU abilitato, utilizzando l’immagine ufficiale:

docker run --gpus all -p 8000:8000 vllm/vllm-openai --model Qwen/Qwen2.5-7B-Instruct

macOS: non è lo strumento adatto

vLLM non dispone di un backend Metal/GPU Apple. Esiste una build sperimentale per CPU compilabile da codice sorgente, ma ciò vanifica completamente lo scopo di un motore ottimizzato per il throughput. Su Mac, utilizza invece LM Studio o Ollama — entrambi sfruttano correttamente la GPU della Apple Silicon.

Avvio di un server: vllm serve

Un singolo comando avvia un server di inferenza (il modello viene scaricato automaticamente da Hugging Face al primo avvio):

vllm serve Qwen/Qwen2.5-7B-Instruct

Ciò rende disponibile il modello sulla porta 8000. Le opzioni (flag) più comunemente utilizzate sono:

Si noti che vLLM prealloca la maggior parte della GPU per progettazione — una lettura della VRAM quasi piena è normale, non un problema di perdita di memoria. Prima di scegliere un modello, verificare che i pesi più la cache KV siano compatibili con la propria scheda grafica utilizzando il Calcolatore VRAM; come regola approssimativa, i pesi in FP16 richiedono circa 2 GB per miliardo di parametri, quelli a 8 bit circa la metà, più uno spazio aggiuntivo per la cache.

L'API compatibile con OpenAI

Il server implementa l’interfaccia API OpenAI: /v1/chat/completions, /v1/completions, /v1/models, e /v1/embeddings (per modelli di embedding). Qualsiasi strumento basato sull’SDK OpenAI funziona semplicemente modificando l’URL base:

curl http://localhost:8000/v1/chat/completions 
  -H "Content-Type: application/json" 
  -d '{
    "model": "Qwen/Qwen2.5-7B-Instruct",
    "messages": [{"role": "user", "content": "Spiega PagedAttention in una frase."}]
  }'

In Python, OpenAI(base_url="http://localhost:8000/v1", api_key="none") è l’intera operazione di migrazione. Questa compatibilità rappresenta una parte fondamentale dell’adozione di vLLM: gli strumenti esistenti, gli agenti e i framework funzionano senza modifiche.

Quando Ollama o llama.cpp rappresentano una scelta migliore

Seleziona Ollama quando il numero di utenti è uno e l’hardware è un laptop o un desktop — la sua configurazione richiede un solo programma di installazione ed esegue comodamente modelli quantizzati GGUF su CPU e Apple Silicon (vedi il Guida completa a Ollama). Scegliere llama.cpp direttamente quando si necessita di massima portabilità o si desidera integrare l’inferenza all’interno di un’altra applicazione. Scegliere vLLM quando le richieste arrivano in modo concorrente e la metrica chiave è il numero di token al secondo per dollaro speso. Un carico di lavoro mono-utente trae pochi vantaggi da PagedAttention; un carico di lavoro con 50 utenti ne trae enormi benefici.

Domande frequenti

vLLM è gratuito?

Sì. vLLM è open source sotto licenza Apache 2.0, originariamente sviluppato dall’Università della California a Berkeley e ora gestito come progetto comunitario sotto la PyTorch Foundation. Non esiste una versione a pagamento; i costi sono relativi all’hardware e al consumo elettrico.

vLLM può eseguire modelli GGUF come fa Ollama?

Il supporto GGUF esiste ma è sperimentale e non rappresenta il percorso previsto. vLLM è costruito intorno ai checkpoint standard di Hugging Face (safetensors), con quantizzazione tramite checkpoint AWQ, GPTQ o FP8. Se i propri modelli esistono esclusivamente in formato GGUF, Ollama o llama.cpp rappresentano scelte più naturali.

vLLM funziona senza una GPU NVIDIA?

Esistono backend per AMD ROCm, hardware Intel, Google TPUs, AWS Neuron e CPU, ma il percorso CUDA per NVIDIA è di gran lunga il più maturo e meglio documentato. vLLM su CPU funziona per test preliminari, ma non per il throughput richiesto dal servizio per cui è stato progettato.

Quanta VRAM richiede vLLM?

Sufficiente per i pesi del modello più la cache KV: circa 2 GB per miliardo di parametri in FP16, circa la metà in 8 bit, più spazio aggiuntivo per la cache, che cresce con la lunghezza del contesto e la concorrenza. Un modello da 7 miliardi di parametri in FP16 si adatta comodamente su una scheda da 24 GB; un modello da 70 miliardi richiede più GPU o una quantizzazione aggressiva. La tabella di riferimento requisiti di VRAM per modello contiene i valori specifici per ciascun modello.

Come si confronta vLLM con TensorRT-LLM, SGLang o TGI?

Appartengono tutti alla stessa categoria — motori di inferenza per ambienti produttivi. vLLM offre generalmente il supporto più ampio per modelli, la configurazione più semplice e la comunità più vasta; TensorRT-LLM può ottenere prestazioni di picco superiori sull’hardware NVIDIA, ma richiede un processo di compilazione e ottimizzazione più complesso; SGLang è un forte concorrente, specialmente per output strutturati. Eseguire benchmark sul proprio modello e carico di lavoro prima di impegnarsi definitivamente — le classifiche possono variare tra le diverse versioni.

È possibile effettuare il fine-tuning di modelli con vLLM?

No — vLLM è dedicato esclusivamente all’inferenza. Viene spesso utilizzato come backend di generazione veloce all’interno di framework di training RLHF, ma il training vero e proprio avviene altrove. Effettuare il fine-tuning con strumenti come Hugging Face TRL, Axolotl o Unsloth, quindi distribuire il checkpoint risultante con vLLM.