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

vLLM è un motore di inferenza e servizio ad alto throughput e a basso consumo di memoria per modelli linguistici su larga scala (LLM), sviluppato dal laboratorio Sky Computing dell’Università della California, Berkeley.

Grazie al rivoluzionario algoritmo PagedAttention, vLLM ottiene un throughput 14-24 volte superiore rispetto ai metodi di servizio tradizionali, rendendolo la scelta ideale per le distribuzioni di LLM in produzione. Per vedere come vLLM si inserisce tra Ollama, Docker Model Runner, LocalAI e i provider cloud—inclusi compromessi su costi e infrastruttura—consulta LLM Hosting: Local, Self-Hosted & Cloud Infrastructure Compared.

Che cos’è vLLM?

vLLM (virtual LLM) è una libreria open-source per l’inferenza e il servizio rapido di LLM che è diventata rapidamente lo standard industriale per le distribuzioni in produzione. Lanciata nel 2023, ha introdotto PagedAttention, una tecnica rivoluzionaria di gestione della memoria che migliora drasticamente l’efficienza del servizio.

Caratteristiche Principali

Prestazioni ad Alto Throughput: vLLM offre un throughput 14-24 volte superiore rispetto a HuggingFace Transformers con lo stesso hardware. Questo enorme guadagno di prestazioni deriva dal continuo batching, dai kernel CUDA ottimizzati e dall’algoritmo PagedAttention che elimina la frammentazione della memoria.

Compatibilità con l’API OpenAI: vLLM include un server API integrato pienamente compatibile con il formato OpenAI. Questo permette una migrazione senza soluzione di continuità da OpenAI a un’infrastruttura self-hosted senza modificare il codice dell’applicazione. Basta puntare il tuo client API all’endpoint di vLLM e funzionerà in modo trasparente.

Algoritmo PagedAttention: L’innovazione alla base delle 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 (che porta alla frammentazione), PagedAttention divide la memoria in blocchi di dimensione fissa che possono essere allocati su richiesta. Questo riduce lo spreco di memoria fino a 4 volte e consente dimensioni di batch molto più grandi.

Continuous Batching: A differenza del batching statico in cui aspetti che tutte le sequenze siano completate, vLLM utilizza un batching continuo (rotante). 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 arrivo.

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

Ampia Supporto ai Modelli: Compatibile con le architetture di modelli più popolari tra cui LLaMA, Mistral, Mixtral, Qwen, Phi, Gemma e molti altri. Supporta sia i modelli istruiti che i modelli base dal HuggingFace Hub.

Quando Usare vLLM

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

Servizi API in Produzione: Quando devi servire un LLM a molti utenti concorrenti tramite API, l’alto throughput e il batch efficiente di vLLM lo rendono la scelta migliore. Le aziende che eseguono chatbot, assistenti per la programmazione o servizi di generazione di contenuti beneficiano della sua capacità di gestire centinaia di richieste al secondo.

Carichi di Lavoro ad Alta Concorrenza: Se la tua applicazione ha molti utenti simultanei che inviano richieste, il continuous batching e PagedAttention di vLLM permettono di servire più utenti con lo stesso hardware rispetto alle alternative.

Ottimizzazione dei Costi: Quando i costi delle GPU sono una preoccupazione, l’alto throughput di vLLM significa che puoi servire lo stesso traffico con meno GPU, riducendo direttamente i costi infrastrutturali. L’efficienza di memoria 4 volte superiore da PagedAttention permette anche di usare istanze GPU più piccole e meno costose.

Distribuzioni Kubernetes: Il design stateless di vLLM e l’architettura friendly per container lo rendono ideale per cluster Kubernetes. Le sue prestazioni coerenti sotto carico e la gestione delle risorse semplice si integrano bene con le infrastrutture cloud-native.

Quando NON Usare vLLM: Per lo sviluppo locale, la sperimentazione o scenari a singolo utente, strumenti come Ollama o llama.cpp offrono un’esperienza utente migliore con una configurazione più semplice. La complessità di vLLM è giustificata quando hai bisogno dei suoi vantaggi di prestazioni per carichi di lavoro in produzione.

Come Installare vLLM

Prerequisiti

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

• GPU: GPU NVIDIA con capacità di calcolo 7.0+ (V100, T4, A10, A100, H100, serie RTX 20/30/40)
• CUDA: Versione 11.8 o superiore
• Python: 3.8 a 3.11
• VRAM: Minimo 16GB per modelli 7B, 24GB+ per 13B, 40GB+ per modelli più grandi
• Driver: Driver NVIDIA 450.80.02 o successivo

Installazione tramite pip

Il metodo di installazione più semplice è usare pip. Questo funziona su sistemi con CUDA 11.8 o successivo:

# Crea un ambiente virtuale (consigliato)
python3 -m venv vllm-env
source vllm-env/bin/activate

# Installa vLLM
pip install vllm

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

Per sistemi con versioni CUDA diverse, installa il wheel appropriato:

# Per CUDA 12.1
pip install vllm==0.4.2+cu121 -f https://github.com/vllm-project/vllm/releases

# Per CUDA 11.8
pip install vllm==0.4.2+cu118 -f https://github.com/vllm-project/vllm/releases

Installazione con Docker

Docker fornisce il metodo di distribuzione più affidabile, specialmente per la produzione:

# Scarica l'immagine ufficiale vLLM
docker pull vllm/vllm-openai:latest

# Esegui vLLM con supporto GPU
docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model mistralai/Mistral-7B-Instruct-v0.2

Il flag --ipc=host è importante per le configurazioni multi-GPU in quanto abilita la corretta comunicazione inter-processo.

Compilazione da Sorgente

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

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

Guida Rapida a vLLM

Esecuzione del Primo Modello

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

# Scarica e servi Mistral-7B con API compatibile OpenAI
python -m vllm.entrypoints.openai.api_server \
    --model mistralai/Mistral-7B-Instruct-v0.2 \
    --port 8000

vLLM scaricherà automaticamente il modello dal HuggingFace Hub (se non è nella 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

Invio di 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": "mistralai/Mistral-7B-Instruct-v0.2",
        "prompt": "Spiega cos'è vLLM in una frase:",
        "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 non richiede autenticazione di default
)

response = client.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    prompt="Spiega cos'è vLLM in una frase:",
    max_tokens=100,
    temperature=0.7
)

print(response.choices[0].text)

API di Completamento Chat:

response = client.chat.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    messages=[
        {"role": "system", "content": "Sei un assistente utile."},
        {"role": "user", "content": "Cos'è PagedAttention?"}
    ],
    max_tokens=200
)

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

Configurazione Avanzata

vLLM offre numerosi parametri per ottimizzare le prestazioni:

python -m vllm.entrypoints.openai.api_server \
    --model mistralai/Mistral-7B-Instruct-v0.2 \
    --port 8000 \
    --gpu-memory-utilization 0.95 \  # Usa il 95% della memoria GPU
    --max-model-len 8192 \            # Lunghezza massima della sequenza
    --tensor-parallel-size 2 \        # Usa 2 GPU con parallelismo tensoriale
    --dtype float16 \                 # Usa precisione FP16
    --max-num-seqs 256                # Dimensione massima del batch

Spiegazione dei Parametri Chiave:

• --gpu-memory-utilization: Quanta memoria GPU usare (0.90 = 90%). Valori più alti consentono batch più grandi ma lasciano meno margine per picchi di memoria.
• --max-model-len: Lunghezza del contesto massima. Ridurre questo parametro salva memoria per batch più grandi.
• --tensor-parallel-size: Numero di GPU su cui suddividere il modello.
• --dtype: Tipo di dati per i pesi (float16, bfloat16 o float32). FP16 è solitamente ottimale.
• --max-num-seqs: Numero massimo di sequenze da elaborare in un batch.

Confronto vLLM vs Ollama

Sia vLLM che Ollama sono scelte popolari per l’hosting locale di LLM, ma mirano a casi d’uso diversi. Capire quando usare ciascuno strumento può impattare significativamente il successo del tuo progetto.

Prestazioni e Throughput

vLLM è progettato per il throughput massimo in scenari multi-utente. Il suo PagedAttention e il continuous batching permettono di servire centinaia di richieste concorrenti in modo efficiente. I benchmark mostrano vLLM che ottiene un throughput 14-24 volte superiore rispetto alle implementazioni standard e 2-4 volte superiore rispetto a Ollama sotto alta concorrenza.

Ollama si ottimizza per l’uso interattivo a singolo utente con focus sulla bassa latenza per richieste individuali. Sebbene non eguagli il throughput multi-utente di vLLM, offre prestazioni eccellenti per lo sviluppo e l’uso personale con tempi di avvio a freddo più veloci e un consumo di risorse in idle inferiore.

Facilità d’Uso

Ollama vince decisa sulla semplicità. L’installazione è un singolo comando (curl | sh) ed eseguire modelli è semplice come ollama run llama2. Include una libreria di modelli con versioni quantizzate ottimizzate per diversi profili hardware. L’esperienza utente assomiglia a Docker – pull, run, e vai.

vLLM richiede più configurazione: gestione dell’ambiente Python, installazione di CUDA, comprensione dei parametri di servizio e specificazione manuale del modello. La curva di apprendimento è più ripida, ma ottieni un controllo granulare sull’ottimizzazione delle prestazioni. Questa complessità è giustificata per distribuzioni in produzione dove devi spremere il massimo dalle prestazioni del tuo hardware.

API e Integrazione

vLLM fornisce API REST compatibili con OpenAI out of the box, rendendolo una sostituzione drop-in per l’API OpenAI nelle applicazioni esistenti. Questo è cruciale per migrare servizi di produzione dai provider cloud a infrastrutture self-hosted senza modifiche al codice.

Ollama offre un’API REST più semplice e una libreria dedicata Python/JavaScript. Sebbene funzionale, non è compatibile con OpenAI, richiedendo modifiche al codice quando si integra con applicazioni che si aspettano il formato OpenAI. Tuttavia, progetti community come gli adapter Ollama-OpenAI colmano questo divario.

Gestione della Memoria

L’algoritmo PagedAttention di vLLM fornisce un’efficienza di memoria superiore per le richieste concorrenti. Può servire 2-4 volte più utenti concorrenti con la stessa VRAM rispetto alle implementazioni naive. Questo si traduce direttamente in risparmi sui costi per le distribuzioni in produzione.

Ollama utilizza una gestione della memoria più semplice adatta per scenari a singolo utente. Gestisce automaticamente il caricamento/scaricamento dei modelli in base all’attività, il che è conveniente per lo sviluppo ma non ottimale per l’uso in produzione ad alta concorrenza.

Supporto Multi-GPU

vLLM eccelle con parallelismo tensoriale nativo e parallelismo pipeline, distribuendo efficientemente i modelli su 2-8+ GPU. Questo è essenziale per servire modelli grandi come LLM da 70B parametri che non entrano in una singola GPU.

Ollama ha attualmente un supporto multi-GPU limitato, funzionando principalmente meglio con una singola GPU. Questo lo rende meno adatto per modelli molto grandi che richiedono inferenza distribuita.

Raccomandazioni per l’Uso

Scegli vLLM quando:

• Servendo API di produzione con molti utenti concorrenti
• Ottimizzando il costo per richiesta in distribuzioni cloud
• Esecuzione in piattaforme di orchestrazione Kubernetes o container
• Hai bisogno di compatibilità API OpenAI per applicazioni esistenti
• Servendo modelli grandi che richiedono supporto multi-GPU
• Le prestazioni e il throughput sono requisiti critici

Scegli Ollama quando:

• Sviluppo locale e sperimentazione
• Uso interattivo a singolo utente (assistenti personali, chatbot)
• Prototipazione rapida e valutazione dei modelli
• Apprendimento degli LLM senza complessità infrastrutturale
• Esecuzione su workstation personali o laptop
• La semplicità e la facilità d’uso sono prioritarie

Molte team usano entrambi: Ollama per lo sviluppo e la sperimentazione, poi vLLM per la distribuzione in produzione. Questa combinazione fornisce produttività allo sviluppatore mantenendo le prestazioni in produzione.

vLLM vs Docker Model Runner

Docker ha recentemente introdotto Model Runner (precedentemente GenAI Stack) come soluzione ufficiale per la distribuzione locale di modelli AI. Come si confronta con vLLM?

Filosofia Architetturale

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

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

Configurazione e Iniziare

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

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

Questa somiglianza con il flusso di lavoro delle immagini Docker lo rende immediatamente familiare agli sviluppatori che usano già i container.

vLLM richiede più configurazione 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 di produzione che gestiscono centinaia di richieste al secondo, le ottimizzazioni di vLLM forniscono un throughput 2-5 volte migliore rispetto agli approcci di servizio generici.

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

Supporto ai Modelli

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

vLLM si specializza nell’inferenza 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.

Distribuzione in Produzione

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

Docker Model Runner è più nuovo e si posiziona più per scenari di sviluppo e test locali. Sebbene possa servire traffico di produzione, non ha il track record provato e le ottimizzazioni delle prestazioni che le distribuzioni in produzione richiedono.

Ecosistema di Integrazione

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

Docker Model Runner si integra naturalmente con l’ecosistema Docker e Docker Desktop. Per i team che hanno già standardizzato su Docker, questa integrazione fornisce un’esperienza coerente ma meno funzionalità specializzate per il servizio LLM.

Quando Usare Ciascuno

Usa vLLM per:

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

Usa Docker Model Runner per:

• Sviluppo locale e test
• Esecuzione di vari tipi di modelli AI (non solo LLM)
• Team fortemente investiti nell’ecosistema Docker
• Sperimentazione rapida senza configurazione infrastrutturale
• Scopi di apprendimento e educativi

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

Migliori Pratiche per la Distribuzione in Produzione

Distribuzione 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 mistralai/Mistral-7B-Instruct-v0.2
      --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]

Distribuzione Kubernetes

Distribuisci vLLM su Kubernetes per la 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
          - mistralai/Mistral-7B-Instruct-v0.2
          - --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 Osservabilità

vLLM espone metriche Prometheus per il monitoraggio:

import requests

# Ottieni le metriche
metrics = requests.get("http://localhost:8000/metrics").text
print(metrics)

Metriche chiave da monitorare:

• vllm:num_requests_running - Richieste attive
• vllm:gpu_cache_usage_perc - Utilizzo della cache KV
• vllm:time_to_first_token - Metrica di latenza
• vllm:time_per_output_token - Velocità di generazione

Ottimizzazione delle Prestazioni

Ottimizza l’Utilizzo della Memoria GPU: Inizia con --gpu-memory-utilization 0.90 e aggiusta in base al comportamento osservato. Valori più alti consentono batch più grandi ma rischiano errori OOM durante i picchi di traffico.

Regola la Lunghezza Massima della Sequenza: Se il tuo caso d’uso non richiede la lunghezza completa del contesto, riduci --max-model-len. Questo libera memoria per batch più grandi. Ad esempio, se hai bisogno solo di 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 la 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

Abilita la Caching del Prefisso: Per le applicazioni con prompt ripetuti (come chatbot con messaggi di sistema), abilita il caching del prefisso:

--enable-prefix-caching

Questo memorizza nella cache i valori KV per i prefissi comuni, riducendo il calcolo per le richieste che condividono lo stesso prefisso del prompt.

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
• Diminuisci --max-model-len se il tuo caso d’uso lo permette
• Abbassa --max-num-seqs per ridurre la dimensione del batch
• Usa una versione quantizzata del modello
• Abilita il parallelismo tensoriale per distribuire su più GPU

Throughput Basso

Sintomi: Il server gestisce meno richieste del previsto.

Soluzioni:

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

Tempo di Primo Token Lento

Sintomi: Alta latenza prima che inizi la generazione.

Soluzioni:

• Usa modelli più piccoli per applicazioni critiche per la latenza
• Abilita il caching del prefisso per prompt ripetuti
• Riduci --max-num-seqs per privilegiare la latenza sul throughput
• Considera il speculative decoding per i modelli supportati
• Ottimizza la configurazione del parallelismo tensoriale

Fallimenti nel Caricamento del Modello

Sintomi: Il server non avvia, non riesce a caricare il modello.

Soluzioni:

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

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:

python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-2-70b-chat-hf \
    --speculative-model meta-llama/Llama-2-7b-chat-hf \
    --num-speculative-tokens 5

Adattatori LoRA

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

python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-2-7b-hf \
    --enable-lora \
    --lora-modules sql-lora=./path/to/sql-adapter \
                   code-lora=./path/to/code-adapter

Poi specifica quale adattatore usare per richiesta:

response = client.completions.create(
    model="sql-lora",  # Usa l'adattatore SQL
    prompt="Converto questo in SQL: Mostra tutti gli utenti creati questo mese"
)

Servizio Multi-LoRA

Il servizio multi-LoRA di vLLM permette di ospitare dozzine di adattatori affinati con minimo overhead di memoria. Questo è ideale per servire varianti di modelli specifiche per cliente o per compito:

# Richiesta con adattatore LoRA specifico
response = client.chat.completions.create(
    model="meta-llama/Llama-2-7b-hf",
    messages=[{"role": "user", "content": "Scrivi query SQL"}],
    extra_body={"lora_name": "sql-lora"}
)

Caching del Prefisso

Abilita il caching automatico del prefisso per evitare di ricalcolare la cache KV per i prefissi del prompt ripetuti:

--enable-prefix-caching

Questo è particolarmente efficace per:

• Chatbot con prompt di sistema fissi
• Applicazioni RAG con template di contesto coerenti
• Prompt di few-shot learning ripetuti attraverso le richieste

Il caching del prefisso può ridurre il tempo al primo token del 50-80% per le richieste che condividono i prefissi del prompt.

Esempi di Integrazione

Integrazione LangChain

from langchain.llms import VLLMOpenAI

llm = VLLMOpenAI(
    openai_api_key="EMPTY",
    openai_api_base="http://localhost:8000/v1",
    model_name="mistralai/Mistral-7B-Instruct-v0.2",
    max_tokens=512,
    temperature=0.7,
)

response = llm("Spiega PagedAttention in termini semplici")
print(response)

Integrazione LlamaIndex

from llama_index.llms import VLLMServer

llm = VLLMServer(
    api_url="http://localhost:8000/v1",
    model="mistralai/Mistral-7B-Instruct-v0.2",
    temperature=0.7,
    max_tokens=512
)

response = llm.complete("Cos'è vLLM?")
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="mistralai/Mistral-7B-Instruct-v0.2",
        prompt=prompt,
        max_tokens=200
    )
    return {"result": response.choices[0].text}

Benchmark delle Prestazioni

I dati reali delle prestazioni aiutano a illustrare i vantaggi di vLLM:

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

• vLLM: ~3.500 token/secondo con 64 utenti concorrenti
• HuggingFace Transformers: ~250 token/secondo con la stessa concorrenza
• Ollama: ~1.200 token/secondo con la stessa concorrenza
• Risultato: vLLM offre un miglioramento 14x 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

Latency Under Load (Mixtral-8x7B su 2xA100):

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

Questi benchmark dimostrano perché vLLM è diventato lo standard de facto per il servizio LLM in produzione dove le prestazioni contano.

Analisi dei Costi

Capire le implicazioni dei costi di scegliere vLLM:

Scenario: Servire 1M richieste/giorno

Con Servizio Standard:

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

Con vLLM:

• Richiesto: 2x GPU A100 (80GB)
• Costo AWS: ~$8/ora × 24 × 30 = $5.760/mese
• Costo per 1M 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 mensili risparmiano centinaia di migliaia di dollari usando il servizio ottimizzato di vLLM invece di implementazioni naive.

Considerazioni sulla Sicurezza

Autenticazione

vLLM non include autenticazione di default. Per la produzione, 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 l’autenticazione e il rate limiting di livello enterprise.

Isolamento di Rete

Esegui vLLM in reti private, non esposte direttamente a Internet:

# Esempio di 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 abusi:

# 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 superato")
    
    return await call_next(request)

Controllo di Accesso al Modello

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

ALLOWED_MODELS = {
    "user_tier_1": ["mistralai/Mistral-7B-Instruct-v0.2"],
    "user_tier_2": ["mistralai/Mistral-7B-Instruct-v0.2", "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

Migrare da OpenAI a vLLM self-hosted è semplice 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": "Ciao"}]
)

Dopo (vLLM):

from openai import OpenAI

client = OpenAI(
    base_url="https://your-vllm-server.com/v1",
    api_key="your-internal-key"  # Se hai aggiunto autenticazione
)
response = client.chat.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    messages=[{"role": "user", "content": "Ciao"}]
)

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

Da Ollama a vLLM

Ollama usa un formato API diverso. Ecco la conversione:

API Ollama:

import requests

response = requests.post('http://localhost:11434/api/generate',
    json={
        'model': 'llama2',
        'prompt': 'Perché il cielo è blu?'
    })

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="Perché il cielo è blu?"
)

Dovrai aggiornare le chiamate API in tutto il tuo codice, ma le librerie client OpenAI forniscono un migliore gestione degli errori e funzionalità.

Da HuggingFace Transformers a vLLM

Migrazione dell’uso Python diretto:

HuggingFace:

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-Instruct-v0.2")
tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-Instruct-v0.2")

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="mistralai/Mistral-7B-Instruct-v0.2")
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 batch.

Futuro di vLLM

vLLM continua lo sviluppo rapido con funzionalità entusiasmanti nella roadmap:

Serving Disaggregato: Separare il prefill (elaborazione del prompt) e il decode (generazione del token) su GPU diverse per ottimizzare l’utilizzo delle risorse. Il prefill è compute-bound mentre il decode è memory-bound, quindi eseguirli su hardware specializzato migliora l’efficienza.

Inferenza Multi-Node: Distribuire modelli molto grandi (100B+ parametri) su più macchine, abilitando il servizio di modelli troppo grandi per configurazioni a singolo nodo.

Quantizzazione Migliorata: Supporto per nuovi formati di quantizzazione come GGUF (usato da llama.cpp) e integrazione migliorata AWQ/GPTQ per prestazioni migliori con modelli quantizzati.

Miglioramenti al Speculative Decoding: Modelli draft più efficienti e strategie di speculazione adattive per ottenere ritardi di velocità più alti senza perdita di accuratezza.

Ottimizzazioni dell’Attenzione: FlashAttention 3, ring attention per contesti estremamente lunghi (100K+ token) e altri meccanismi di attenzione all’avanguardia.

Migliore Copertura dei Modelli: Espansione del supporto per modelli multimodali (modelli visione-linguaggio), modelli audio e architetture specializzate man mano che emergono.

Il progetto vLLM mantiene uno sviluppo attivo con contributi da UC Berkeley, Anyscale e la più ampia community open-source. Man mano che la distribuzione LLM diventa più critica per i sistemi di produzione, il ruolo di vLLM come standard di prestazioni continua a crescere. Per un confronto più ampio di vLLM con altre infrastrutture LLM locali e cloud, consulta la nostra LLM Hosting: Local, Self-Hosted & Cloud Infrastructure Compared.

Link Utili

Articoli Correlati su Questo Sito

• Local LLM Hosting: Complete 2026 Guide - Ollama, vLLM, LocalAI, Jan, LM Studio & More - Confronto completo di 12+ strumenti di hosting LLM locali inclusa l’analisi dettagliata di vLLM insieme a Ollama, LocalAI, Jan, LM Studio e altri. Copre la maturità API, il supporto al tool calling, la compatibilità GGUF e i benchmark delle prestazioni per aiutare a scegliere la soluzione giusta.

• Ollama Cheatsheet - Riferimento completo ai comandi Ollama e cheatsheet che copre installazione, gestione dei modelli, uso API e migliori pratiche per la distribuzione locale di LLM. Essenziale per gli sviluppatori che usano Ollama insieme o invece di vLLM.

• llama.cpp Quickstart with CLI and Server - Inferenza leggera C/C++ per modelli GGUF con llama-cli e llama-server compatibile OpenAI. Ideale quando hai bisogno di controllo granulare, distribuzione offline o uno stack minimale senza Python.

• Docker Model Runner vs Ollama: Which to Choose? - Confronto approfondito del Model Runner di Docker e Ollama per la distribuzione locale di LLM, analizzando prestazioni, supporto GPU, compatibilità API e casi d’uso. Aiuta a comprendere il panorama competitivo in cui opera vLLM.

• Docker Model Runner Cheatsheet: Commands & Examples - Pratica Docker Model Runner cheatsheet con comandi ed esempi per la distribuzione di modelli AI. Utile per i team che confrontano l’approccio di Docker con le capacità specializzate di servizio LLM di vLLM.

Risorse Esterne e Documentazione

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

• vLLM Documentation - Documentazione ufficiale che copre tutti gli aspetti di vLLM dalla configurazione di base a quella avanzata. Include riferimenti API, guide di tuning delle prestazioni e migliori pratiche di distribuzione.

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

• vLLM Blog - Blog ufficiale vLLM che presenta annunci di rilascio, benchmark delle prestazioni, approfondimenti tecnici e studi di casi della community dalle distribuzioni in produzione.

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

• Ray Serve Documentation - Documentazione del framework Ray Serve per costruire distribuzioni vLLM scalabili e distribuite. Ray fornisce funzionalità avanzate come autoscaling, servizio multi-modello e gestione delle risorse per i sistemi di produzione.

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

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