vLLM Quickstart: Serving ad alte prestazioni di LLM - nel 2026

vLLM è un motore di inferenza e serving ad alto throughput ed efficiente in termini di memoria per i Large Language Models (LLM), sviluppato dal Sky Computing Lab dell’UC Berkeley.

Il suo algoritmo PagedAttention tratta la cache KV come pagine di memoria virtuale del sistema operativo e lo abbinare al continuous batching — la combinazione che ha reso vLLM il motore predefinito per il serving di LLM in produzione. Per capire come vLLM si collochi tra Ollama, Docker Model Runner, LocalAI e i provider cloud, inclusi i compromessi tra costi e infrastruttura, consulta Ospitalità LLM: confronto tra infrastruttura locale, self-hosted e cloud.

Questa guida è aggiornata alla versione vLLM v0.31.0 (ottobre 2026). Due elementi sono cambiati di recente se stai arrivando da tutorial più vecchi: python -m vllm.entrypoints.openai.api_server è deprecato e stampa un avvertimento — vllm serve è ora la CLI standard — e le wheel precompilate targettizzano per default CUDA 12.9, non 11.8.

Cos’è vLLM?

vLLM (virtual LLM) è una libreria open source per inferenza e serving di LLM veloci, che è rapidamente diventata lo standard di settore per le implementazioni in produzione. Rilasciata nel 2023, ha introdotto PagedAttention, una tecnica rivoluzionaria di gestione della memoria che migliora drasticamente l’efficienza del serving.

Caratteristiche principali

Prestazioni ad Alto Throughput: I benchmark dell’epoca del lancio di vLLM riportavano un throughput 14-24 volte superiore rispetto a HuggingFace Transformers sulla stessa hardware, e il motore ha mantenuto questo vantaggio attraverso il continuous batching, kernel CUDA ottimizzati e l’algoritmo PagedAttention che elimina la frammentazione della memoria.

Compatibilità API OpenAI: vLLM include un server API integrato completamente compatibile con il formato di OpenAI. Questo consente una migrazione seamless da OpenAI a infrastruttura self-hosted senza modificare il codice dell’applicazione. Basta puntare il tuo client API all’endpoint di vLLM e funzionerà trasparentmente.

Algoritmo PagedAttention: L’innovazione centrale dietro le prestazioni di vLLM è PagedAttention, che applica il concetto di paging della memoria virtuale ai meccanismi di attenzione. Invece di allocare blocchi di memoria contigui per le cache KV (cosa che porta a frammentazione), PagedAttention divide la memoria in blocchi di dimensioni fisse che possono essere allocati on-demand. Questo riduce lo spreco di memoria fino a 4 volte e consente dimensioni di batch molto maggiori.

Continuous Batching: A differenza dello static batching, dove si aspetta che tutte le sequenze completino, vLLM utilizza il continuous (rolling) batching. Non appena una sequenza finisce, una nuova può essere aggiunta al batch. Questo massimizza l’utilizzo della GPU e minimizza la latenza per le richieste in ingresso.

Supporto Multi-GPU: vLLM supporta tensor parallelism e pipeline parallelism per distribuire modelli grandi su più GPU. Può servire efficientemente modelli che non stanno nella memoria di una singola GPU, supportando configurazioni da 2 a 8+ GPU.

Ampio Supporto di Modelli: Compatibile con architetture di modelli popolari inclusi LLaMA, Mistral, Mixtral, Qwen, Phi, Gemma e molti altri. Supporta sia modelli istruiti (instruction-tuned) sia modelli base da HuggingFace Hub.

Quando usare vLLM

vLLM eccelle in scenari specifici dove i suoi punti di forza brillano:

Servizi API in Produzione: Quando è necessario servire un LLM a molti utenti concorrenti via API, l’alto throughput e il batching efficiente di vLLM lo rendono la scelta migliore. Le aziende che gestiscono chatbot, assistenti per codice o servizi di generazione di contenuti traggono vantaggio dalla sua capacità di gestire centinaia di richieste al secondo.

Carichi di Lavoro ad Alta Concorrenza: Se la tua applicazione ha molti utenti simultanei che fanno richieste, il continuous batching e PagedAttention di vLLM abilitano il servizio di più utenti con la stessa hardware rispetto alle alternative.

Ottimizzazione dei Costi: Quando i costi GPU sono una preoccupazione, il throughput superiore di vLLM significa che è possibile servire il traffico con meno GPU, riducendo direttamente i costi infrastrutturali. L’efficienza di memoria 4 volte di PagedAttention consente anche di utilizzare istanze GPU più piccole ed economiche.

Deployment Kubernetes: Il design stateless e l’architettura amichevole ai container di vLLM lo rendono ideale per cluster Kubernetes. Le sue prestazioni costanti sotto carico e la gestione diretta delle risorse si integrano bene con l’infrastruttura cloud-native.

Quando NON usare vLLM: Per lo sviluppo locale, l’esperimentazione o gli scenari di singolo utente, strumenti come Ollama o llama.cpp offrono un’esperienza utente migliore con un setup più semplice. La complessità di vLLM è giustificata quando hai bisogno dei suoi vantaggi prestazionali per carichi di lavoro in produzione.

Come installare vLLM

Prerequisiti

Prima di installare vLLM, assicurati che il tuo sistema soddisfi questi requisiti:

• OS: Linux con glibc 2.35 o successivo (Ubuntu 22.04+, Debian 12+, RHEL 9+)
• GPU: GPU NVIDIA con compute capability 7.5 o superiore (T4, A10, A100, L4, H100, B200, serie RTX 20/30/40/50). Le schede vecchie della generazione 7.0 come la V100 non sono più nella lista supportata. Le GPU AMD sono supportate tramite wheel ROCm separate — consulta ROCm vs Vulkan per l’ospitalità LLM locale AMD per l’immagine specifica AMD, i flag del dispositivo e le avvertenze sulla copertura dei kernel.
• CUDA: Le wheel pip predefinite sono compilate contro CUDA 12.9; le varianti 12.8 e 13.0 sono pubblicate accanto. Le GPU Blackwell (B200, GB200) richiedono CUDA 12.8+. Il tuo driver NVIDIA deve essere abbastanza recente per la versione di CUDA che installi.
• Python: 3.10 a 3.13 — 3.12 è la versione consigliata (le wheel ROCm sono solo 3.12)
• VRAM: Minimo 16GB per modelli 7B, 24GB+ per 13B, 40GB+ per modelli più grandi

Installazione tramite pip

L’installazione consigliata usa uv per creare un ambiente Python 3.12 e selezionare automaticamente il backend CUDA PyTorch corrispondente (--torch-backend=auto ispeziona il driver installato). Per una panoramica più approfondita di uv stesso, consulta uv: Il nuovo gestore di progetti e ambienti per pacchetti Python:

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

# Verifica dell'installazione
python -c "import vllm; print(vllm.__version__)"

Il semplice pip funziona anche:

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

Le wheel predefinite sono compilate contro CUDA 12.9. Se hai bisogno di una versione CUDA diversa, recupera l’indice della wheel PyTorch corrispondente — ad esempio, CUDA 12.8:

pip install vllm --extra-index-url https://download.pytorch.org/whl/cu128

Le vecchie wheel fissate come vllm==0.4.2+cu121 non esistono più in questa forma. Mescolare vLLM in un ambiente esistente con un build di PyTorch diverso è una fonte comune di fallimenti dell’installazione; il progetto consiglia un ambiente fresco e un build da source quando hai bisogno di un target CUDA personalizzato.

Installazione con Docker

Docker fornisce il metodo di deployment più affidabile, specialmente per la produzione. Fissa l’immagine a una versione di release invece di latest in modo che gli aggiornamenti siano deliberati, e nota che esistono immagini varianti per CUDA 12.9 (suffisso tag -cu129), AMD ROCm (vllm-openai-rocm), CPU (vllm-openai-cpu) e Intel XPU (vllm-openai-xpu):

# Scarica l'immagine ufficiale vLLM
docker pull vllm/vllm-openai:v0.31.0

# Esegui vLLM con supporto GPU
docker run --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:v0.31.0 \
    --model Qwen/Qwen3-8B

Il flag --ipc=host è importante per le configurazioni multi-GPU poiché abilita una corretta comunicazione inter-processo.

Compilazione da Source

Per le funzionalità più recenti o modifiche personalizzate, compila da source:

git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .

Guida rapida vLLM

Esecuzione del tuo primo modello

Avvia vLLM con un modello usando la interfaccia a riga di comando:

# Scarica e servi un modello con l'API compatibile con OpenAI
vllm serve Qwen/Qwen3-8B \
    --port 8000

vllm serve è la CLI attuale per il server compatibile con OpenAI. La vecchia invocazione python -m vllm.entrypoints.openai.api_server esegue ancora ma stampa un avvertimento di deprecazione e potrebbe essere rimossa in un rilascio futuro, quindi aggiorna qualsiasi script o manifesto Kubernetes che lo utilizza ancora.

vLLM scaricherà automaticamente il modello da HuggingFace Hub (se non è in cache) e avvierà il server. Vedrai un output che indica che il server è pronto:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

Inviare richieste API

Una volta che il server è in esecuzione, puoi inviare richieste usando il client Python di OpenAI o curl:

Usando curl:

curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen3-8B",
        "prompt": "Explain what vLLM is in one sentence:",
        "max_tokens": 100,
        "temperature": 0.7
    }'

Usando il client Python di OpenAI:

from openai import OpenAI

# Punta al tuo server vLLM
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"  # vLLM ignora questo a meno che non avvieri il server con --api-key
)

response = client.completions.create(
    model="Qwen/Qwen3-8B",
    prompt="Explain what vLLM is in one sentence:",
    max_tokens=100,
    temperature=0.7
)

print(response.choices[0].text)

API Chat Completions:

response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is PagedAttention?"}
    ],
    max_tokens=200
)

print(response.choices[0].message.content)

Configurazione Avanzata

vLLM offre numerosi parametri per ottimizzare le prestazioni:

vllm serve Qwen/Qwen3-8B \
    --port 8000 \
    --gpu-memory-utilization 0.95 \  # Usa il 95% della memoria GPU
    --max-model-len 32k \            # Lunghezza sequenza massima (8192 e 32k funzionano entrambi)
    --tensor-parallel-size 2 \       # Usa 2 GPU con tensor parallelism
    --dtype float16 \                # Usa precisione FP16
    --max-num-seqs 256               # Dimensione batch massima

Spiegazione dei parametri chiave:

• --gpu-memory-utilization: Frazione di memoria GPU per l’esecutore del modello (default 0.92). Valori più alti consentono batch più grandi ma lasciano meno margine per i picchi di memoria.
• --max-model-len: Lunghezza contesto massima. Accetta conteggi di token o valori leggibili come 32k. Ridurre questo salva memoria per batch più grandi.
• --tensor-parallel-size: Numero di GPU su cui dividere il modello.
• --dtype: Tipo di dati per i pesi (auto, float16, bfloat16, float32). auto segue il dtype del checkpoint, che di solito è quello che vuoi.
• --max-num-seqs: Numero massimo di sequenze in un batch.
• --max-num-active-seqs: Limita l’ammissione RUNNING indipendentemente da max_num_seqs (nuovo in v0.31.0) — utile per limitare la latenza senza ridurre la finestra batch dello scheduler.

vLLM vs Ollama

vLLM è progettato per serving multi-utente in produzione ad alto throughput con continuous batching, PagedAttention e supporto multi-GPU. Ollama ottimizza per il setup locale veloce, la comodità per singolo utente e la gestione semplice dei modelli.

Per una guida dettagliata alle decisioni che copre segnali di migrazione, passaggi di pianificazione, setup Docker Compose e una checklist pratica, consulta Da Ollama a vLLM: Quando migrare il tuo server LLM locale.

vLLM vs Docker Model Runner

Model Runner di Docker è la loro soluzione ufficiale per il deployment locale di modelli AI. Come si confronta con vLLM?

Filosofia Architettonica

Docker Model Runner mira a essere il “Docker per l’AI” – un modo semplice e standardizzato per eseguire modelli AI localmente con la stessa facilità di eseguire container. Astrarre la complessità e fornisce un’interfaccia coerente tra diversi modelli e framework.

vLLM è un motore di inferenza specializzato focalizzato esclusivamente sul serving di LLM con prestazioni massime. È uno strumento a livello inferiore che si containerizza con Docker, piuttosto che una piattaforma completa.

Setup e Inizio Rapido

L’installazione di Docker Model Runner è diretta per gli utenti Docker:

docker model pull llama3:8b
docker model run llama3:8b

Questa somiglianza con il workflow delle immagini di Docker lo rende immediatamente familiare agli sviluppatori che già usano i container; l’insieme completo dei comandi è nella scheda rapida Docker Model Runner.

vLLM richiede più setup iniziale (Python, CUDA, dipendenze) o l’uso di immagini Docker pre-costruite:

docker pull vllm/vllm-openai:latest
docker run --runtime nvidia --gpus all vllm/vllm-openai:latest --model <model-name>

Caratteristiche delle Prestazioni

vLLM offre un throughput superiore per scenari multi-utente grazie a PagedAttention e continuous batching. Per i servizi API in produzione che gestiscono centinaia di richieste al secondo, le ottimizzazioni di vLLM forniscono un throughput 2-5 volte migliore rispetto agli approcci di serving generici.

Docker Model Runner si concentra sulla facilità d’uso piuttosto che sulle prestazioni massime. È adatto per lo sviluppo locale, il testing e carichi di lavoro moderati, ma non implementa le ottimizzazioni avanzate che rendono vLLM eccellente su scala.

Supporto dei Modelli

Docker Model Runner fornisce una libreria di modelli curata con accesso a un comando ai modelli popolari. Supporta più framework (non solo LLM) inclusi Stable Diffusion, Whisper e altri modelli AI, rendendolo più versatile per diversi carichi di lavoro AI.

vLLM si specializza nell’inferenza di LLM con supporto profondo per i modelli linguistici basati su transformer. Supporta qualsiasi LLM compatibile con HuggingFace ma non si estende ad altri tipi di modelli AI come la generazione di immagini o il riconoscimento vocale.

Deployment in Produzione

vLLM è testato in produzione in aziende come Anthropic, Replicate e molte altre che servono miliardi di token al giorno. Le sue caratteristiche di prestazioni e stabilità sotto carico pesante lo rendono lo standard de facto per il serving di LLM in produzione.

Docker Model Runner è più recente e si posiziona più per scenari di sviluppo e testing locale. Sebbene potrebbe servire traffico in produzione, manca del track record comprovato e delle ottimizzazioni di prestazioni che i deployment in produzione richiedono.

Ecosistema di Integrazione

vLLM si integra con gli strumenti di infrastruttura di produzione: operatori Kubernetes, metriche Prometheus, Ray per il serving distribuito e ampia compatibilità API OpenAI per le applicazioni esistenti.

Docker Model Runner si integra naturalmente con l’ecosistema di Docker e Docker Desktop. Per i team già standardizzati su Docker, questa integrazione fornisce un’esperienza coesa ma meno funzionalità specializzate per il serving di LLM.

Quando usare ciascuno

Usa vLLM per:

• Servizi API LLM in produzione
• Implementazioni multi-utente ad alto throughput
• Implementazioni cloud sensibili ai costi che necessitano massima efficienza
• Ambienti Kubernetes e cloud-native
• Quando hai bisogno di scalabilità e prestazioni comprovate

Usa Docker Model Runner per:

• Sviluppo e testing locale
• Esecuzione di vari tipi di modelli AI (non solo LLM)
• Team fortemente investiti nell’ecosistema Docker
• Esperimentazione rapida senza setup infrastrutturale
• Scopi di apprendimento e didattici

Approccio Ibrido: Molti team sviluppano con Docker Model Runner localmente per comodità, poi deployano con vLLM in produzione per prestazioni. Le immagini di Docker Model Runner possono essere utilizzate anche per eseguire container vLLM, combinando entrambi gli approcci.

Best Practices per il Deployment in Produzione

Deployment Docker

Crea una configurazione Docker Compose pronta per la produzione:

version: '3.8'

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - CUDA_VISIBLE_DEVICES=0,1
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
      - ./logs:/logs
    ports:
      - "8000:8000"
    command: >
      --model Qwen/Qwen3-8B
      --tensor-parallel-size 2
      --gpu-memory-utilization 0.90
      --max-num-seqs 256
      --max-model-len 8192
    restart: unless-stopped
    shm_size: '16gb'
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 2
              capabilities: [gpu]

Deployment Kubernetes

Deploya vLLM su Kubernetes per scala di produzione:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: vllm
  template:
    metadata:
      labels:
        app: vllm
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args:
          - --model
          - Qwen/Qwen3-8B
          - --tensor-parallel-size
          - "2"
          - --gpu-memory-utilization
          - "0.90"
        resources:
          limits:
            nvidia.com/gpu: 2
        ports:
        - containerPort: 8000
        volumeMounts:
        - name: cache
          mountPath: /root/.cache/huggingface
      volumes:
      - name: cache
        hostPath:
          path: /mnt/huggingface-cache
---
apiVersion: v1
kind: Service
metadata:
  name: vllm-service
spec:
  selector:
    app: vllm
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

Monitoraggio e Observability

Il server compatibile con OpenAI espone metriche Prometheus in /metrics per default — non sono necessari flag extra:

curl -s http://localhost:8000/metrics | grep '^vllm:'

Metriche chiave da monitorare:

• vllm:num_requests_running / vllm:num_requests_waiting / vllm:num_requests_swapped — richieste negli stati dello scheduler RUNNING, WAITING e SWAPPED
• vllm:kv_cache_usage_perc — frazione di blocchi cache KV usati (0–1)
• vllm:time_to_first_token_seconds — istogramma TTFT
• vllm:time_per_output_token_seconds — velocità di generazione per token
• vllm:num_preemptions_total — preemption cumulative; un contatore in aumento significa che la cache KV è sovrascritta e le richieste stanno essendo ricalcolate

Per dashboard, esempi PromQL e soglie di allarme attorno al serving LLM, consulta Monitoraggio dell’inferenza LLM in produzione (2026): Prometheus & Grafana per vLLM, TGI, llama.cpp.

Tuning delle Prestazioni

Ottimizza l’Utilizzo della Memoria GPU: Il default è 0.92; regola in base al comportamento osservato. Valori più alti consentono batch più grandi ma rischiano errori OOM durante i picchi di traffico.

Tuning della Lunghezza Sequenza Massima: Se il tuo caso d’uso non richiede l’intera lunghezza del contesto, riduci --max-model-len. Questo libera memoria per batch più grandi. Ad esempio, se hai bisogno di solo 4K di contesto, imposta --max-model-len 4096 invece di usare il massimo del modello (spesso 8K-32K).

Scegli la Quantizzazione Appropriata: Per i modelli che lo supportano, usa versioni quantizzate (8-bit, 4-bit) per ridurre la memoria e aumentare il throughput:

--quantization awq  # Per modelli quantizzati AWQ
--quantization gptq # Per modelli quantizzati GPTQ

Prefix Caching: Il prefix caching è abilitato per default nel motore attuale, quindi le richieste che condividono un prefisso di prompt (un system prompt fisso, una template di contesto RAG) riutilizzano la sua cache KV senza alcun flag. Disabilitalo con --no-enable-prefix-caching per carichi di lavoro con molti prompt lunghi unici dove il bookkeeping della cache non porta benefici.

Risoluzione dei problemi comuni

Errori Out of Memory

Sintomi: Il server crasha con errori CUDA out of memory.

Soluzioni:

• Riduci --gpu-memory-utilization a 0.85 o 0.80
• Riduci --max-model-len se il tuo caso d’uso lo consente
• Abbassa --max-num-seqs per ridurre la dimensione del batch
• Usa una versione quantizzata del modello
• Abilita il tensor parallelism per distribuire su più GPU

Due forme distinte di OOM richiedono correzioni diverse. Un OOM di avvio avviene prima di qualsiasi richiesta: vLLM effettua il profiling della memoria e fallisce nell’allocare anche la cache KV minima, quindi ridurre --max-num-seqs non aiuta — riduci --max-model-len o aumenta --gpu-memory-utilization se hai margine. Un OOM in esecuzione sotto carico può derivare dalla memoria di cattura CUDA-graph, che scala con --max-num-seqs ma si trova fuori dal conteggio della cache KV; esegui una volta con --enforce-eager per verificare se i grafici CUDA sono la memoria mancante, e riesegui esattamente la stessa configurazione prima di incolpare la cache. Se gli avvi su hardware identico continuano ad avere successo con la stessa allocazione, passa indietro il valore di --kv-cache-memory-bytes che vLLM logga all’avvio per saltare il passaggio di profiling negli avvi successivi.

Su una singola scheda da 16 GB, la maggior parte di questi errori OOM deriva dal budget della cache KV piuttosto che dai soli pesi — Cache KV su GPU da 16 GB copre la formula esatta, il dtype FP8 della cache KV e i compromessi del prefix-caching dietro --max-model-len e --max-num-seqs prima di ricorrere a un modello più piccolo.

Avvio Lento

Sintomi: Il server richiede minuti dall’avvio a “Application startup complete”.

Soluzioni:

• Il caricamento dei pesi, la compilazione e la cattura CUDA-graph dominano l’avvio — --enforce-eager salta sia la compilazione sia la cattura e ti dice quanto costano dell’avvio, al prezzo della velocità di decodifica in stato stazionario
• Riutilizza il valore loggato di --kv-cache-memory-bytes per saltare i passaggi di profiling della memoria e stima CUDA-graph negli avvi ripetuti
• Da v0.30.0+, il comando vllm preload esegue un daemon persistente di cache dei pesi che mantiene i pesi post-quantizzati residenti nella memoria GPU, in modo che i riavvii del motore mappino i pesi su CUDA IPC invece di ricaricarli dal disco (--load-format ipc_cache)
• Per checkpoint NVFP4 che OOM durante la compilazione di avvio, limitare i thread di build con MAX_JOBS=4 e NVCC_THREADS=4 è una correzione ampiamente usata — rallenta la build JIT ma ferma l’OOM

Throughput Basso

Sintomi: Il server gestisce meno richieste del previsto.

Soluzioni:

• Aumenta --max-num-seqs per consentire batch più grandi
• Aumenta --gpu-memory-utilization se hai margine
• Verifica se la CPU è il collo di bottiglia con htop – considera CPU più veloci
• Verifica l’utilizzo della GPU con nvidia-smi – dovrebbe essere 95%+
• Abilita FP16 se usi FP32: --dtype float16

Latenza Prima Token Lenta

Sintomi: Alta latenza prima che la generazione inizi.

Soluzioni:

• Usa modelli più piccoli per applicazioni sensibili alla latenza
• Il prefix caching è attivo per default — verifica che sia attivo invece di riaggiungere il flag
• Riduci --max-num-seqs per privilegiare la latenza rispetto al throughput
• Considera il speculative decoding per i modelli supportati
• Ottimizza la configurazione del tensor parallelism

Fallimenti nel Caricamento del Modello

Sintomi: Il server non riesce ad avviarsi, non può caricare il modello.

Soluzioni:

• Verifica che il nome del modello corrisponda esattamente al formato HuggingFace
• Controlla la connettività di rete a HuggingFace Hub
• Assicurati di avere spazio su disco sufficiente in ~/.cache/huggingface
• Per modelli gated, imposta la variabile d’ambiente HF_TOKEN
• Prova a scaricare manualmente con hf download <model> (o huggingface-cli download <model> su installazioni vecchie)

Funzionalità Avanzate

Speculative Decoding

vLLM supporta il speculative decoding, dove un modello draft più piccolo propone token che un modello target più grande verifica. Questo può accelerare la generazione di 1.5-2 volte. Per una guida completa ai metodi di speculative decoding — modelli draft, EAGLE-3, P-EAGLE e n-gram — consulta Speculative Decoding: Inferenza più veloce senza perdita di qualità.

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --speculative-config '{"method": "draft_model", "model": "meta-llama/Llama-3.2-1B-Instruct", "num_speculative_tokens": 4}'

I vecchi flag --speculative-model e --num-speculative-tokens sono spariti — la configurazione è passata nell’argomento JSON singolo --speculative-config, che seleziona anche il metodo (draft_model, ngram, famiglia EAGLE, o MTP per modelli con teste multi-token-prediction native).

Adattatori LoRA

Servi più adattatori LoRA sopra un modello base senza caricare più modelli completi:

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --enable-lora \
    --lora-modules sql-lora=/path/to/sql-adapter \
                   code-lora=/path/to/code-adapter

Poi specifica quale adattatore usare per richiesta mettendo il suo nome nel campo model — lo stesso meccanismo scala a dozzine di adattatori specifici per task (varianti specifiche per cliente o per dominio) con solo il modello base residente in memoria:

response = client.completions.create(
    model="sql-lora",  # Usa l'adattatore SQL
    prompt="Convert this to SQL: Show me all users created this month"
)

Prefix Caching

Il prefix caching evita il ricalcolo della cache KV per i prefissi di prompt condivisi ed è abilitato per default nel motore attuale.

È più utile per:

• Chatbot con system prompt fissi
• Applicazioni RAG con template di contesto coerenti
• Prompt di few-shot learning ripetuti tra richieste

Per richieste che condividono un prefisso, il tempo al primo token cala sensibilmente perché il prefill per la parte condivisa viene saltato.

Esempi di Integrazione

Integrazione LangChain

from langchain_community.llms import VLLMOpenAI

llm = VLLMOpenAI(
    openai_api_key="EMPTY",
    openai_api_base="http://localhost:8000/v1",
    model_name="Qwen/Qwen3-8B",
    max_tokens=512,
    temperature=0.7,
)

response = llm("Explain PagedAttention in simple terms")
print(response)

Applicazione FastAPI

from fastapi import FastAPI
from openai import AsyncOpenAI

app = FastAPI()
client = AsyncOpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"
)

@app.post("/generate")
async def generate(prompt: str):
    response = await client.completions.create(
        model="Qwen/Qwen3-8B",
        prompt=prompt,
        max_tokens=200
    )
    return {"result": response.choices[0].text}

Benchmark delle Prestazioni

I dati sulle prestazioni del mondo reale aiutano a illustrare i vantaggi di vLLM. Le cifre seguenti provengono dalla documentazione dell’epoca del lancio del progetto e dalle prime misure della community — trattale come indicazioni dell’ordine di grandezza dell’effetto dell’architettura, non come risultati attuali per la generazione di modelli di oggi:

Confronto Throughput (Mistral-7B su GPU A100):

• vLLM: ~3.500 token/secondo con 64 utenti concorrenti
• HuggingFace Transformers: ~250 token/secondo con stessa concorrenza
• Ollama: ~1.200 token/secondo con stessa concorrenza
• Risultato: vLLM fornisce un miglioramento di 14 volte rispetto alle implementazioni di base

Efficienza della Memoria (LLaMA-2-13B):

• Implementazione standard: 24GB VRAM, 32 sequenze concorrenti
• vLLM con PagedAttention: 24GB VRAM, 128 sequenze concorrenti
• Risultato: 4 volte più richieste concorrenti con la stessa memoria

Latenza Sotto Carico (Mixtral-8x7B su 2xA100):

• vLLM: Latenza P50 180ms, Latenza P99 420ms a 100 req/s
• Serving standard: Latenza P50 650ms, Latenza P99 3.200ms a 100 req/s
• Risultato: vLLM mantiene latenza costante sotto alto carico

Analisi dei Costi

Capire le implicazioni di costo di scegliere vLLM:

Scenaro: Serving di 1M di richieste/giorno

Con Serving Standard:

• Richiesto: 8x GPU A100 (80GB)
• Costo AWS: ~32$/ora × 24 × 30 = 23.040$/mese
• Costo per 1M di token: ~0,75$

Con vLLM:

• Richiesto: 2x GPU A100 (80GB)
• Costo AWS: ~8$/ora × 24 × 30 = 5.760$/mese
• Costo per 1M di token: ~0,19$
• Risparmio: 17.280$/mese (riduzione del 75%)

Questo vantaggio di costo cresce con la scala. Le organizzazioni che servono miliardi di token mensilmente risparmiano centinaia di migliaia di dollari usando il serving ottimizzato di vLLM invece di implementazioni naive.

Considerazioni di Sicurezza

Autenticazione

vLLM include un flag --api-key integrato, ma secondo la documentazione ufficiale autentica solo gli endpoint sotto i prefissi di percorso /v1, /v2 e /inference — gli altri endpoint sullo stesso server rimangono non autenticati. Trattalo come un livello, non come la risposta completa; per una copertura completa, implementa l’autenticazione a livello di reverse proxy:

# Configurazione Nginx
location /v1/ {
    auth_request /auth;
    proxy_pass http://vllm-backend:8000;
}

location /auth {
    proxy_pass http://auth-service:8080/verify;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

Oppure usa gateway API come Kong, Traefik o AWS API Gateway per autenticazione enterprise-grade e rate limiting.

Isolamento di Rete

Esegui vLLM in reti private, non direttamente esposto a internet:

# Esempio NetworkPolicy Kubernetes
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: vllm-access
spec:
  podSelector:
    matchLabels:
      app: vllm
  policyTypes:
  - Ingress
  ingress:
  - from:
    - podSelector:
        matchLabels:
          role: api-gateway
    ports:
    - protocol: TCP
      port: 8000

Rate Limiting

Implementa il rate limiting per prevenire l’abuso:

# Esempio usando Redis per il rate limiting
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
import redis
from datetime import datetime, timedelta

app = FastAPI()
redis_client = redis.Redis(host='localhost', port=6379)

@app.middleware("http")
async def rate_limit_middleware(request, call_next):
    client_ip = request.client.host
    key = f"rate_limit:{client_ip}"
    
    requests = redis_client.incr(key)
    if requests == 1:
        redis_client.expire(key, 60)  # Finestra di 60 secondi
    
    if requests > 60:  # 60 richieste al minuto
        raise HTTPException(status_code=429, detail="Rate limit exceeded")
    
    return await call_next(request)

Controllo Accessi ai Modelli

Per deployment multi-tenant, controlla quali utenti possono accedere a quali modelli:

ALLOWED_MODELS = {
    "user_tier_1": ["Qwen/Qwen3-8B"],
    "user_tier_2": ["Qwen/Qwen3-8B", "meta-llama/Llama-2-13b-chat-hf"],
    "admin": ["*"]  # Tutti i modelli
}

def verify_model_access(user_tier: str, model: str) -> bool:
    allowed = ALLOWED_MODELS.get(user_tier, [])
    return "*" in allowed or model in allowed

Guida alla Migrazione

Da OpenAI a vLLM

La migrazione da OpenAI a vLLM self-hosted è diretta grazie alla compatibilità API:

Prima (OpenAI):

from openai import OpenAI

client = OpenAI(api_key="sk-...")
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello"}]
)

Dopo (vLLM):

from openai import OpenAI

client = OpenAI(
    base_url="https://your-vllm-server.com/v1",
    api_key="your-internal-key"  # Se hai aggiunto l'autenticazione
)
response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[{"role": "user", "content": "Hello"}]
)

Servono solo due modifiche: aggiorna base_url e il nome del model. Tutto il resto del codice rimane identico.

Da Ollama a vLLM

Ollama usa un formato API diverso. La modifica client-side di base è il passaggio dall’endpoint REST di Ollama all’API compatibile con OpenAI di vLLM:

API Ollama:

import requests

response = requests.post('http://localhost:11434/api/generate',
    json={'model': 'llama2', 'prompt': 'Why is the sky blue?'})

Equivalente vLLM:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
response = client.completions.create(
    model="meta-llama/Llama-2-7b-chat-hf",
    prompt="Why is the sky blue?"
)

L’API di Ollama è REST puro con la sua propria forma di richiesta, mentre vLLM parla il protocollo OpenAI — quella differenza di formato API è la principale modifica client-side, e l’approccio graduale (eseguire entrambi i server, spostare il traffico endpoint per endpoint) è coperto nella guida alla migrazione linkata prima in questo articolo.

Da HuggingFace Transformers a vLLM

Migrazione dell’uso diretto di Python:

HuggingFace:

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-8B")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B")

inputs = tokenizer("Hello", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=100)
result = tokenizer.decode(outputs[0])

vLLM:

from vllm import LLM, SamplingParams

llm = LLM(model="Qwen/Qwen3-8B")
sampling_params = SamplingParams(max_tokens=100)

outputs = llm.generate("Hello", sampling_params)
result = outputs[0].outputs[0].text

L’API Python di vLLM è più semplice e molto più veloce per l’inferenza a batch.

Rilasci Recenti: Cosa è cambiato nel 2026

Tre rilasci tra settembre-ottobre 2026 (v0.29.0, v0.30.0, v0.31.0) mostrano dove si sta andando lo sviluppo:

Riavvii rapidi: vllm preload avvia un daemon persistente di cache pesi per GPU che mantiene i pesi post-quantizzati e sharded TP residenti nella memoria GPU, in modo che i motori riavviati li mappino su CUDA IPC (--load-format ipc_cache) invece di ricaricarli dal disco. Sperimentalmente, vllm snapshot create/restore fa snapshot di un motore completamente inizializzato con CRIU.

Speculative decoding su Model Runner V2: Il speculative decoding draft-model, i processori di logits personalizzati e la verifica adattiva sono passati sul nuovo model runner, con l’aggiunta del drafter LiLiCorr e la schedulazione asincrona per il drafter DFlash.

Serving MoE su larga scala: Nuovi backend all2all esperto-parallel bilanciati (--all2all-backend moonep), DeepEPv2 con parallelismo delle sequenze, EPLB con overlap esperto-condiviso e parallelismo del contesto prefill combinato con parallelismo dei dati.

Controllo della schedulazione: --max-num-active-seqs limita l’ammissione RUNNING indipendentemente da max_num_seqs, e la coda di attesa ora schedula prima le richieste che già detengono blocchi KV.

Gli elementi della roadmap delle vecchie guide vLLM sono stati da tempo rilasciati — il supporto GGUF, il serving multimodale, il prefill/decode disaccoppiato e l’inferenza multi-nodo fanno tutti parte dei rilasci attuali, quindi tratta qualsiasi tutorial che li elenca come “in arrivo” come datato. Le note di rilascio per ogni versione sono sulla pagina dei rilasci vLLM.

Link Utili

Articoli Correlati su Questo Sito

• Scheda Rapida Ollama - Riferimento completo e scheda rapida dei comandi Ollama che copre installazione, gestione modelli, uso API e best practices per il deployment locale di LLM. Essenziale per gli sviluppatori che usano Ollama insieme o al posto di vLLM.

• Docker Model Runner vs Ollama: Quale scegliere? - Confronto in profondità di Model Runner di Docker e Ollama per il deployment locale di LLM, analizzando prestazioni, supporto GPU, compatibilità API e casi d’uso. Aiuta a comprendere il panorama competitivo in cui opera vLLM.

Risorse Esterne e Documentazione

• Repository GitHub vLLM - Repository ufficiale vLLM con codice sorgente, documentazione completa, guide di installazione e discussioni della community attive. Risorse essenziali per restare aggiornati sulle ultime funzionalità e risolvere i problemi.

• Documentazione vLLM - Documentazione ufficiale che copre tutti gli aspetti di vLLM dal setup base alla configurazione avanzata. Include riferimenti API, guide di tuning delle prestazioni e best practices di deployment.

• Paper PagedAttention - Paper accademico che introduce l’algoritmo PagedAttention che alimenta l’efficienza di vLLM. Lettura essenziale per comprendere le innovazioni tecniche dietro i vantaggi prestazionali di vLLM.

• Blog vLLM - Blog ufficiale vLLM che presenta annunci di rilascio, benchmark delle prestazioni, approfondimenti tecnici e casi studio della community da deployment in produzione.

• HuggingFace Model Hub - Repository completo di LLM open source che funzionano con vLLM. Cerca modelli per dimensione, task, licenza e caratteristiche prestazionali per trovare il modello giusto per il tuo caso d’uso.

• Documentazione Ray Serve - Documentazione del framework Ray Serve per costruire deployment vLLM scalabili e distribuiti. Ray fornisce funzionalità avanzate come autoscaling, serving multi-modello e gestione delle risorse per sistemi in produzione.

• NVIDIA TensorRT-LLM - TensorRT-LLM di NVIDIA per inferenza altamente ottimizzata su GPU NVIDIA. Alternativa a vLLM con strategie di ottimizzazione diverse, utile per il confronto e per comprendere il panorama di ottimizzazione dell’inferenza.

• Riferimento API OpenAI - Documentazione API OpenAI ufficiale con cui l’API di vLLM è compatibile. Riferisciti a questa quando costruisci applicazioni che devono funzionare in modo intercambiabile con endpoint OpenAI e vLLM self-hosted.