vLLM Quickstart: Servizio LLM ad alta prestazione - nel 2026

vLLM è un motore di inferenza e servizio ad alta capacità di throughput e ad alta efficienza di memoria per i Large Language Models (LLMs) sviluppato dal Sky Computing Lab dell’Università di Berkeley.

Con l’algoritmo rivoluzionario PagedAttention, vLLM raggiunge un throughput 14-24 volte superiore rispetto ai metodi tradizionali di servizio, diventando così la scelta ideale per le distribuzioni di LLM in produzione.

Cos’è vLLM?

vLLM (virtual LLM) è una libreria open source per l’inferenza e il servizio rapido di LLM che è diventata rapidamente lo standard dell’industria per le distribuzioni in produzione. Rilasciata nel 2023, ha introdotto PagedAttention, una tecnica innovativa di gestione della memoria che migliora in modo significativo l’efficienza del servizio.

Funzionalità Principali

Alta capacità di throughput: vLLM consegna un throughput 14-24 volte superiore rispetto a HuggingFace Transformers con lo stesso hardware. Questo enorme guadagno di prestazioni proviene da un batch continuo, da kernel CUDA ottimizzati e dall’algoritmo PagedAttention che elimina la frammentazione della memoria.

Compatibilità con l’API di OpenAI: vLLM include un server API interno che è pienamente compatibile con il formato di OpenAI. Questo consente una migrazione senza problemi da OpenAI all’infrastruttura autohosted senza modificare il codice dell’applicazione. Basta indicare al client API l’endpoint di vLLM e funziona in modo trasparente.

Algoritmo PagedAttention: L’innovazione centrale alle spalle 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 dimensioni fisse che possono essere allocati su richiesta. Questo riduce il spreco di memoria fino a 4 volte e consente batch molto più grandi.

Batching Continuo: A differenza del batching statico in cui devi attendere che tutte le sequenze siano completate, vLLM utilizza un batching continuo (rolling). Non appena una sequenza finisce, una nuova può essere aggiunta al batch. Questo massimizza l’utilizzo della GPU e riduce la latenza per le richieste in entrata.

Supporto Multi-GPU: vLLM supporta la parallelizzazione tensoriale e la parallelizzazione a pipeline per distribuire modelli grandi su più GPU. Può servire efficacemente modelli che non entrano in una singola GPU, supportando configurazioni da 2 a 8+ GPU.

Ampio Supporto dei Modelli: Compatibile con architetture di modelli popolari come LLaMA, Mistral, Mixtral, Qwen, Phi, Gemma e molti altri. Supporta sia modelli istruiti che modelli base provenienti da HuggingFace Hub.

Quando Utilizzare vLLM

vLLM eccelle in scenari specifici in cui le sue forze brillano:

Servizi API di Produzione: Quando devi servire un LLM a molti utenti contemporanei tramite API, il throughput alto e il batching efficiente di vLLM lo rendono la scelta migliore. Le aziende che gestiscono chatbot, assistenti per il codice o servizi di generazione del contenuto traggono vantaggio dalla sua capacità di gestire centinaia di richieste al secondo.

Carichi di Lavoro ad Alta Concorrenza: Se l’applicazione ha molti utenti simultanei che fanno richieste, il batching continuo e PagedAttention di vLLM permettono di servire più utenti con lo stesso hardware rispetto agli alternative.

Ottimizzazione dei Costi: Quando i costi delle GPU sono una preoccupazione, il throughput superiore di vLLM significa che puoi servire lo stesso traffico con meno GPU, riducendo direttamente i costi dell’infrastruttura. L’efficienza della memoria del 4x da PagedAttention consente anche di utilizzare istanze GPU più piccole e economiche.

Distribuzioni su Kubernetes: La progettazione stateless e l’architettura amichevole ai container di vLLM lo rendono ideale per i cluster Kubernetes. Le sue prestazioni costanti sotto carico e la gestione semplice delle risorse si integrano bene con l’infrastruttura nativa del cloud.

Quando Non Utilizzare vLLM: Per lo sviluppo locale, sperimentazione o scenari a singolo utente, strumenti come Ollama offrono un’esperienza utente migliore con un setup più semplice. La complessità di vLLM è giustificata quando si necessita delle sue prestazioni avanzate per carichi di lavoro in produzione.

Come Installare vLLM

Prerequisiti

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

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

Installazione tramite pip

Il metodo più semplice di installazione è tramite pip. Questo funziona sui sistemi con CUDA 11.8 o versioni successive:

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

# Installare vLLM
pip install vllm

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

Per sistemi con diverse versioni di CUDA, installare la ruota appropriata:

# 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 deployment più affidabile, specialmente per le produzioni:

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

# Eseguire 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

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

Costruzione da Sorgente

Per le ultime funzionalità o modifiche personalizzate, costruisci da sorgente:

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

Guida Rapida a vLLM

Eseguire il Primo Modello

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

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

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

Effettuare Richieste API

Una volta che il server è in esecuzione, puoi effettuare richieste utilizzando il client Python OpenAI o curl:

Utilizzando 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
    }'

Utilizzando il client Python OpenAI:

from openai import OpenAI

# Puntare al tuo server vLLM
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"  # vLLM non richiede l'autenticazione per 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 delle Completazioni 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 \  # Utilizza il 95% della memoria della GPU
    --max-model-len 8192 \            # Lunghezza massima della sequenza
    --tensor-parallel-size 2 \        # Utilizza 2 GPU con parallelismo tensoriale
    --dtype float16 \                 # Utilizza la precisione FP16
    --max-num-seqs 256                # Dimensione massima del batch

Parametri Chiave Spiegati:

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

Confronto tra vLLM e Ollama

Sia vLLM che Ollama sono scelte popolari per l’hosting locale di LLM, ma si rivolgono a casi d’uso diversi. Comprendere quando utilizzare ciascuno strumento può influenzare significativamente il successo del tuo progetto.

Prestazioni e Throughput

vLLM è progettato per il massimo throughput in scenari multi-utente. Il suo PagedAttention e il batching continuo permettono di servire efficacemente centinaia di richieste contemporanee. I benchmark mostrano che vLLM raggiunge un throughput 14-24 volte superiore rispetto alle implementazioni standard e 2-4 volte superiore rispetto ad Ollama sotto alta concorrenza.

Ollama ottimizza per l’uso interattivo singolo-utente con focus sulla bassa latenza per singole richieste. Sebbene non eguagli le prestazioni di vLLM in termini di throughput multi-utente, fornisce prestazioni eccellenti per lo sviluppo e l’uso personale con tempi di avvio più veloci e consumo di risorse inattivo inferiore.

Facilità d’uso

Ollama vince nettamente in termini di semplicità. L’installazione è un singolo comando (curl | sh), e l’avvio dei modelli è semplice come ollama run llama2. Include una libreria dei modelli con versioni quantizzate ottimizzate per diversi profili hardware. L’esperienza utente assomiglia a Docker – scarica, avvia e vai.

vLLM richiede più configurazione: gestione dell’ambiente Python, installazione di CUDA, comprensione dei parametri di servizio e specifica manuale del modello. La curva di apprendimento è più ripida, ma si guadagna un controllo fine-grained sull’ottimizzazione delle prestazioni. Questa complessità è giustificata per le distribuzioni in produzione dove si deve sfruttare al massimo le prestazioni del hardware.

API e Integrazione

vLLM fornisce API REST compatibili con OpenAI pronte all’uso, rendendolo un sostituto immediato dell’API di OpenAI nelle applicazioni esistenti. Questo è cruciale per migrare i servizi di produzione dai provider cloud all’infrastruttura autohosted senza modifiche al codice.

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

Gestione della Memoria

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

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

Supporto Multi-GPU

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

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

Consigli per l’Uso

Scegli vLLM quando:

• Servire API di produzione con molti utenti contemporanei
• Ottimizzare il costo per richiesta in distribuzioni cloud
• Eseguire in Kubernetes o piattaforme di orchestrazione container
• Hai bisogno della compatibilità con l’API di OpenAI per le applicazioni esistenti
• Servire modelli grandi che richiedono supporto multi-GPU
• Le prestazioni e il throughput sono requisiti critici

Scegli Ollama quando:

• Sviluppo locale e sperimentazione
• Uso interattivo singolo-utente (assistenti personali, chatbot)
• Prototipazione rapida e valutazione dei modelli
• Imparare sui LLM senza complessità infrastrutturale
• Eseguire su workstation o laptop personali
• La semplicità e l’usabilità sono priorità

Molti team utilizzano entrambi: Ollama per lo sviluppo e sperimentazione, quindi vLLM per la distribuzione in produzione. Questa combinazione fornisce produttività per gli sviluppatori mantenendo le prestazioni in produzione.

Confronto tra vLLM e Docker Model Runner

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

Filosofia dell’Architettura

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

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

Configurazione e Avvio

Docker Model Runner è semplice da installare per gli utenti Docker:

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

Questa somiglianza al flusso di lavoro delle immagini Docker rende istantaneamente familiare agli sviluppatori già che usano i container.

vLLM richiede una configurazione iniziale più ampia (Python, CUDA, dipendenze) o l’uso di immagini Docker pre-built:

docker pull vllm/vllm-openai:latest
docker run --runtime nvidia --gpus all vllm/vll毛-7B-Instruct-v0.2

Caratteristiche di Prestazione

vLLM fornisce un throughput superiore per scenari multi-utente grazie a PagedAttention e al batching continuo. Per i servizi API di produzione che gestiscono centinaia di richieste al secondo, le ottimizzazioni di vLLM forniscono un miglioramento del 2-5 volte rispetto ad approcci generici di servizio.

Docker Model Runner si concentra sull’usabilità piuttosto che sulle massime prestazioni. È adatto per lo sviluppo locale, i test e i carichi di lavoro moderati, ma non implementa le ottimizzazioni avanzate che rendono eccellente vLLM su larga scala.

Supporto dei Modelli

Docker Model Runner fornisce una libreria di modelli curata con accesso in un solo comando a modelli popolari. Supporta diversi 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 LLM con un 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 è stato testato in produzione da aziende come Anthropic, Replicate e molte altre che servono miliardi di token al giorno. Le sue caratteristiche di prestazione e stabilità sotto carico pesante lo rendono lo standard de facto per il servizio LLM in produzione.

Docker Model Runner è più recente e si posiziona più per scenari di sviluppo e test locali. Sebbene possa servire il traffico in produzione, manca del record di prova e delle ottimizzazioni di prestazione necessarie per le distribuzioni in produzione.

Ecosistema di Integrazione

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

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

Quando Usare Ogni Strumento

Usa vLLM quando:

• Servire API di LLM in produzione
• Distribuzioni ad alta capacità di throughput con molti utenti
• Ottimizzazione dei costi in ambienti cloud con efficienza massima
• Ambiente Kubernetes e nativo del cloud
• Quando hai bisogno di scalabilità e prestazioni provate

Usa Docker Model Runner quando:

• Sviluppo e test locale
• Eseguire diversi tipi di modelli AI (non solo LLM)
• Team pesantemente investiti nell’ecosistema Docker
• Sperimentazione rapida senza configurazione infrastrutturale
• Per scopi educativi e di apprendimento

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

Migliori Pratiche per la Distribuzione in Produzione

Distribuzione con 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 su Kubernetes

Distribuisci vLLM su Kubernetes per la scala in 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

# Ottenere 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 GPU
• vllm:time_to_first_token - Metrica di latenza
• vllm:time_per_output_token - Velocità di generazione

Ottimizzazione delle Prestazioni

Ottimizza l’utilizzo della memoria della GPU: Inizia con --gpu-memory-utilization 0.90 e regola in base al comportamento osservato. Valori più alti permettono 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 utilizzare il massimo del modello (spesso 8K-32K).

Scegli una quantizzazione appropriata: Per i modelli che lo supportano, utilizza 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 il caching delle prefissi: Per le applicazioni con prompt ripetuti (come chatbot con messaggi di sistema), abilita il caching delle prefissi:

--enable-prefix-caching

Questo 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 di Memoria

Sintomi: Il server crasha con errori di memoria CUDA.

Soluzioni:

• Riduci --gpu-memory-utilization a 0.85 o 0.80
• Riduci --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 distribuirlo su più GPU

Throughput Basso

Sintomi: Il server gestisce meno richieste del previsto.

Soluzioni:

• Aumenta --max-num-seqs per permettere batch più grandi
• Alza --gpu-memory-utilization se hai margine
• Controlla se il 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

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 delle prefissi per prompt ripetuti
• Riduci --max-num-seqs per prioritizzare la latenza rispetto al throughput
• Considera la decodifica speculativa per i modelli supportati
• Ottimizza la configurazione del parallelismo tensoriale

Fallimenti nel Caricamento del Modello

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

Soluzioni:

• Verifica che il nome del modello corrisponda esattamente al formato HuggingFace
• Controlla la connettività di rete con HuggingFace Hub
• Assicurati che ci sia spazio sufficiente su ~/.cache/huggingface
• Per i modelli gated, imposta la variabile d’ambiente HF_TOKEN
• Prova a scaricarlo manualmente con huggingface-cli download <model>

Funzionalità Avanzate

Decodifica Speculativa

vLLM supporta la decodifica speculativa, dove un modello draft più piccolo propone token che un modello target più grande verifica. Questo può accelerare la generazione del 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

Servire diversi adattatori LoRA su un modello base senza caricare diversi 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 utilizzare per richiesta:

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

Servizio Multi-LoRA

Il servizio multi-LoRA di vLLM permette di ospitare decine di adattatori finemente sintonizzati con un overhead di memoria minimo. Questo è ideale per servire varianti di modelli specifici per clienti o compiti:

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

Caching delle Prefissi

Abilita il caching automatico delle prefissi per evitare il ricalcolo della cache KV per prefissi di prompt ripetuti:

--enable-prefix-caching

Questo è particolarmente efficace per:

• Chatbot con prompt di sistema fissi
• Applicazioni RAG con modelli di contesto coerenti
• Prompt di pochi esempi ripetuti tra le richieste

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

Esempi di Integrazione

Integrazione con 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 con 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

Dati reali sulle prestazioni aiutano a illustrare gli vantaggi di vLLM:

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

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

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

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

Latenza sotto carico (Mixtral-8x7B su 2xA100):

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

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

Analisi dei Costi

Comprendere le implicazioni dei costi di scegliere vLLM:

Scenario: Servire 1 milione di richieste/giorno

Con Servizio Standard:

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

Con vLLM:

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

Considerazioni sulla Sicurezza

Autenticazione

vLLM non include l’autenticazione per default. Per la produzione, implementa l’autenticazione al livello del proxy inverso:

# 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;
}

O utilizza gateway API come Kong, Traefik o AWS API Gateway per l’autenticazione e il rate limiting a livello aziendale.

Isolamento della Rete

Esegui vLLM in reti private, non esposto 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 l’abuso:

# Esempio utilizzando 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="Limite di velocità superato")
    
    return await call_next(request)

Controllo dell’Accesso ai Modelli

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

Dall’OpenAI a vLLM

Migrare dall’OpenAI a vLLM autohosted è 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 l'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 model name. Tutto il resto del codice rimane identico.

Dall’Ollama a vLLM

Ollama utilizza 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 codicebase, ma le librerie client OpenAI forniscono un miglior controllo degli errori e funzionalità.

Dall’HuggingFace Transformers a vLLM

Migrazione diretta del uso Python:

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("Ciao", 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("Ciao", sampling_params)
result = outputs[0].outputs[0].text

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

Il Futuro di vLLM

vLLM continua lo sviluppo rapido con caratteristiche eccitanti in programma:

Servizio Disaggregato: Separare il prefill (elaborazione del prompt) e il decode (generazione dei token) su GPU diverse per ottimizzare l’utilizzo delle risorse. Il prefill è limitato dal calcolo mentre il decode è limitato dalla memoria, quindi eseguendoli su hardware specializzato si migliora l’efficienza.

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

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

Miglioramenti alla Decodifica Speculativa: Modelli draft più efficienti e strategie di speculazione adattive per ottenere accelerazioni più elevate senza perdita di accuratezza.

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

Maggiore Copertura dei Modelli: Espansione del supporto a modelli multimodali (modelli linguaggio-immagine), modelli audio e architetture specializzate man mano che emergono.

Il progetto vLLM mantiene uno sviluppo attivo con contributi da parte di UC Berkeley, Anyscale e della comunità open source più ampia. Mentre l’implementazione di LLM diventa sempre più critica per i sistemi di produzione, il ruolo di vLLM come standard di prestazioni continua a crescere.

Link Utili

Articoli Correlati su Questo Sito

• Ospitare LLM Locali: Guida Completa 2026 - Ollama, vLLM, LocalAI, Jan, LM Studio & Altri - Confronto completo di 12+ strumenti per l’ospitaggio locale di LLM, incluso un’analisi dettagliata di vLLM insieme a Ollama, LocalAI, Jan, LM Studio e altri. Copre la maturità dell’API, il supporto per l’invocazione degli strumenti, la compatibilità GGUF e i benchmark di prestazioni per aiutare a scegliere la soluzione giusta.

• Ollama: Foglio di Trucchi - Riferimento completo ai comandi di Ollama e foglio di trucchi che copre l’installazione, la gestione dei modelli, l’uso dell’API e le best practice per l’implementazione locale di LLM. Essenziale per gli sviluppatori che utilizzano Ollama insieme o al posto di vLLM.

• Docker Model Runner vs Ollama: Quale Scegliere? - Confronto approfondito tra il Model Runner di Docker e Ollama per l’ospitaggio locale di LLM, analizzando prestazioni, supporto GPU, compatibilità API e casi d’uso. Aiuta a comprendere il contesto competitivo in cui opera vLLM.

• Foglio di Trucchi Docker Model Runner: Comandi & Esempi - Foglio di trucchi pratico per Docker Model Runner con comandi e esempi per la distribuzione di modelli AI. Utile per i team che confrontano l’approccio di Docker con le capacità specializzate di vLLM per il servizio di LLM.

Risorse Esterne e Documentazione

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

• Documentazione vLLM - Documentazione ufficiale che copre tutti gli aspetti di vLLM, dalla configurazione di base alle funzionalità avanzate. Include riferimenti API, guide per l’ottimizzazione delle prestazioni e best practice per la distribuzione.

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

• Blog vLLM - Blog ufficiale di vLLM che presenta annunci di rilascio, benchmark di prestazioni, analisi tecniche approfondite e studi di caso della comunità da distribuzioni in produzione.

• HuggingFace Model Hub - Repository completo di modelli LLM open source che funzionano con vLLM. Cerca i modelli in base alle dimensioni, alle attività, ai licenziamenti e alle caratteristiche di prestazioni per trovare il modello giusto per il tuo caso d’uso.

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

• NVIDIA TensorRT-LLM - TensorRT-LLM di NVIDIA per un’ottimizzazione altamente efficiente sull’hardware GPU NVIDIA. Alternativa a vLLM con strategie di ottimizzazione diverse, utile per il confronto e la comprensione del paesaggio dell’ottimizzazione dell’inferenza.

• Riferimento API OpenAI - Documentazione ufficiale dell’API OpenAI con cui l’API di vLLM è compatibile. Riferimento da utilizzare quando si costruiscono applicazioni che devono funzionare con entrambi gli endpoint OpenAI e vLLM autoospitati in modo intercambiabile.