vLLM Quickstart: Servizio LLM ad alte prestazioni - nel 2026

vLLM è un motore di inferenza e servizio ad alta capacità e ad alta efficienza di memoria per i Large Language Models (LLM) 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 implementazioni di LLM in produzione. Per vedere come vLLM si colloca tra Ollama, Docker Model Runner, LocalAI e i fornitori di cloud – inclusi i trade-off in termini di costo e infrastruttura – consulta LLM Hosting: Local, Self-Hosted & Cloud Infrastructure Compared.

Cosa è vLLM?

vLLM (virtual LLM) è una libreria open-source per l’inferenza e il servizio rapido di LLM che è rapidamente diventata lo standard industriale per le implementazioni in produzione. Rilasciata nel 2023, ha introdotto PagedAttention, una tecnica rivoluzionaria 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 la stessa hardware. Questo enorme guadagno di prestazioni proviene dal batch continuo, dai 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 completamente compatibile con il formato di OpenAI. Questo consente una migrazione senza problemi da OpenAI all’infrastruttura auto-hosted senza modificare il codice applicativo. Basta puntare il tuo client API all’endpoint di vLLM e funziona in modo trasparente.

Algoritmo PagedAttention: L’innovazione centrale alle 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 al 400% e consente batch molto più grandi.

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

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

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

Quando utilizzare vLLM

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

Servizi API in produzione: Quando devi servire un LLM a molti utenti contemporanei tramite API, l’elevato throughput 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 beneficiano della 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 consentono di servire più utenti con la stessa hardware rispetto agli alternative.

Ottimizzazione dei costi: Quando i costi delle GPU sono un problema, 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 400% di PagedAttention consente anche l’uso di istanze GPU più piccole e economiche.

Deploy su Kubernetes: La progettazione senza stato e l’architettura amichevole ai contenitori 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 ha bisogno delle sue prestazioni avanzate per carichi di lavoro in produzione.

Come installare vLLM

Requisiti preliminari

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, RTX 20/30/40 serie)
• CUDA: Versione 11.8 o superiore
• Python: 3.8 a 3.11
• VRAM: Minimo 16 GB per i modelli 7B, 24 GB+ per i 13B, 40 GB+ per i modelli più grandi
• Driver: Driver NVIDIA 450.80.02 o più recenti

Installazione tramite pip

Il metodo di installazione più semplice è utilizzare 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 l’adatto wheel:

# 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 di 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 la 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 per completamenti di 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

Spiegazione dei parametri chiave:

• --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. Ridurlo risparmia 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 è generalmente ottimale.
• --max-num-seqs: Numero massimo di sequenze da processare in un batch.

Confronto tra vLLM e Ollama

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

Prestazioni e Throughput

vLLM è progettato per massimizzare il throughput in scenari con molti utenti. Il suo PagedAttention e il batching continuo permettono di servire centinaia di richieste contemporanee in modo efficiente. I benchmark mostrano che vLLM raggiunge un throughput 14-24 volte superiore rispetto alle implementazioni standard e 2-4 volte superiore rispetto a Ollama in condizioni di alta concorrenza.

Ollama ottimizza per l’uso interattivo a singolo utente con focus sulla bassa latenza per le richieste individuali. Sebbene non si confronti con le prestazioni multi-utente di vLLM, offre prestazioni eccellenti per lo sviluppo e l’uso personale con tempi di avvio più veloci e consumo di risorse inattive più basso.

Facilità d’uso

Ollama vince nettamente in termini di semplicità. L’installazione è un singolo comando (curl | sh), e l’esecuzione dei modelli è semplice come ollama run llama2. Include una libreria di modelli con versioni quantizzate ottimizzate per diversi profili hardware. L’esperienza utente è simile a Docker – scarica, esegui 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 sull’ottimizzazione delle prestazioni. Questa complessità è giustificata per le implementazioni 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 fornitori di cloud all’infrastruttura auto-hosted 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 offre 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 implementazioni in produzione.

Ollama utilizza una gestione della memoria più semplice adatta a scenari a 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 si adattano in una singola GPU.

Ollama attualmente ha un supporto limitato per le GPU multiple, funzionando meglio 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 in produzione con molti utenti contemporanei
• Ottimizzare il costo per richiesta in implementazioni cloud
• Eseguire in Kubernetes o in piattaforme di orchestrazione container
• Hai bisogno della compatibilità con l’API 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
• Utilizzo interattivo a singolo utente (assistenti personali, chatbot)
• Prototipazione rapida e valutazione dei modelli
• Imparare sulle LLM senza complessità infrastrutturale
• Eseguire su workstation o laptop personali
• La semplicità e la facilità d’uso sono priorità

Molti team utilizzano entrambi: Ollama per lo sviluppo e la sperimentazione, e vLLM per l’implementazione 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 l’AI” – un modo semplice e standardizzato per eseguire modelli AI localmente con la stessa facilità di eseguire i container. Astrae la complessità e fornisce un’interfaccia coerente tra diversi modelli e framework.

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

Setup e inizio rapido

Docker Model Runner ha un’installazione 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 rende istantaneamente familiare agli sviluppatori che già utilizzano i container.

vLLM richiede un setup iniziale più ampio (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毛-开-ai:latest --model <model-name>

Caratteristiche delle prestazioni

vLLM fornisce un throughput superiore per scenari multi-utente grazie a PagedAttention e al batching continuo. Per i servizi API in 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 sviluppo locale, test e carichi di lavoro moderati, ma non implementa le ottimizzazioni avanzate che rendono vLLM eccellente a grande scala.

Supporto dei modelli

Docker Model Runner fornisce una libreria di modelli curata con accesso in un solo comando ai modelli popolari. Supporta diversi framework (non solo LLM) come 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 la riconoscimento vocale.

Deployment in produzione

vLLM è stato 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 servizio di LLM in produzione.

Docker Model Runner è più recente e si posiziona più per scenari di sviluppo e test locali. Sebbene possa servire traffico in produzione, manca del record provato e delle ottimizzazioni di prestazioni necessarie per i deployment in produzione.

Ecosistema di integrazione

vLLM si integra con gli strumenti di infrastruttura in produzione: operatori Kubernetes, metriche Prometheus, Ray per il servizio distribuito e un’ampia 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 utilizzare ciascuno

Utilizza vLLM per:

• Servizi API in produzione per LLM
• Deploy ad alta capacità e multi-utente
• Deploy cloud a basso costo che richiedono massima efficienza
• Ambienti Kubernetes e nativi del cloud
• Quando hai bisogno di scalabilità e prestazioni provate

Utilizza Docker Model Runner per:

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

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

Migliori pratiche per il deployment in produzione

Deployment 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]

Deployment su Kubernetes

Deploya vLLM su Kubernetes per una 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 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 necessita della lunghezza completa del contesto, riduci --max-model-len. Questo libera memoria per batch più grandi. Ad esempio, se hai bisogno solo di un contesto di 4K, imposta --max-model-len 4096 invece di utilizzare il massimo del modello (spesso 8K-32K).

Scegli la 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 dei prefissi: Per le applicazioni con prompt ripetuti (come chatbot con messaggi di sistema), abilita il caching dei prefissi:

--enable-prefix-caching

Questo memorizza 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 insufficiente

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
• Utilizza 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 permettere batch più grandi
• Alza --gpu-memory-utilization se hai spazio
• Verifica se il 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 utilizzando FP32: --dtype float16

Tempo di primo token lento

Sintomi: Alta latenza prima che inizi la generazione.

Soluzioni:

• Utilizza modelli più piccoli per applicazioni critiche per la latenza
• Abilita il caching dei prefissi per prompt ripetuti
• Riduci --max-num-seqs per privilegiare 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 protetti, imposta la variabile d’ambiente HF_TOKEN
• Prova a scaricare 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",  # Utilizza 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 sintonizzati con un minimo overhead di memoria. Questo è ideale per servire varianti di modelli specifiche 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 dei prefissi

Abilita il caching automatico dei prefissi per evitare di ricalcolare la cache KV per i prefissi dei 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 dei prefissi può ridurre il tempo al primo token del 50-80% per le richieste che condividono prefissi dei 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("Cosa è 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 di 14 volte rispetto alle implementazioni di base

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

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

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

• vLLM: P50 latenza 180 ms, P99 latenza 420 ms a 100 richieste/secondo
• Servizio standard: P50 latenza 650 ms, P99 latenza 3.200 ms 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 di LLM in produzione dove contano le prestazioni.

Analisi dei costi

Capire le implicazioni dei costi di scegliere vLLM:

Scenario: Servire 1 milione di richieste/giorno

Con servizio standard:

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

Con vLLM:

• Richiesto: 2x GPU A100 (80 GB)
• 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 l’ottimizzato servizio di vLLM invece delle implementazioni naive.

Considerazioni sulla sicurezza

Autenticazione

vLLM non include l’autenticazione per 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;
}

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

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

Controllo dell’accesso ai modelli

Per le implementazioni 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

La migrazione da OpenAI a vLLM auto-hosted è semplice grazie alla compatibilità dell’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. Tutte le altre righe di codice rimangono identiche.

Da 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 tuo codicebase, ma le librerie client OpenAI forniscono un migliore gestione degli errori e funzionalità.

Da HuggingFace Transformers a vLLM

Migrazione diretta dell’utilizzo 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 eccitanti funzionalità in programma:

Servizio disgregato: Separare il prefill (elaborazione del prompt) e il decode (generazione dei token) su GPU diverse per ottimizzare l’utilizzo delle risorse. Il prefill è limitato da calcolo mentre il decode è limitato da memoria, quindi eseguirli su hardware specializzato 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 single-node.

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

Miglioramenti alla decodifica speculativa: Modelli draft più efficienti e strategie di speculazione adattative per ottenere speedup più elevati senza perdita di accuratezza.

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

Maggiore copertura dei modelli: Espansione del supporto a modelli multimodali (modelli vision-language), modelli audio e architetture specializzate all’uscita.

Il progetto vLLM mantiene uno sviluppo attivo con contributi da UC Berkeley, Anyscale e la comunità open-source più ampia. Mentre il deployment di LLM diventa sempre più critico per i sistemi in produzione, il ruolo di vLLM come standard delle prestazioni continua a crescere. Per un confronto più ampio tra vLLM e altre infrastrutture locali e cloud di LLM, consulta la nostra LLM Hosting: Local, Self-Hosted & Cloud Infrastructure Compared.

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 di LLM locali, incluso un’analisi dettagliata di vLLM insieme ad Ollama, LocalAI, Jan, LM Studio e altri. Copre la maturità dell’API, il supporto per le chiamate degli strumenti, la compatibilità GGUF e i benchmark di prestazioni per aiutare a scegliere la soluzione giusta.

• Ollama Cheatsheet - Riferimento completo ai comandi di Ollama e cheat sheet che copre l’installazione, la gestione dei modelli, l’uso dell’API e le best practice per l’ospitaggio di LLM locali. Essenziale per gli sviluppatori che utilizzano Ollama insieme o al posto di vLLM.

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

• Docker Model Runner Cheatsheet: Comandi & Esempi - Cheat sheet pratico per Docker Model Runner con comandi e esempi per l’ospitaggio 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

• 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, dall’installazione di base alla configurazione avanzata. Include riferimenti API, guide per l’ottimizzazione delle prestazioni e best practice per l’ospitaggio.

• Paper PagedAttention - Articolo accademico che introduce l’algoritmo PagedAttention che alimenta l’efficienza di vLLM. Lettura essenziale per comprendere le innovazioni tecniche dietro gli vantaggi di prestazioni 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 deployment 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 deployment scalabili e distribuiti di vLLM. Ray fornisce funzionalità avanzate come scalabilità automatica, servizio multi-modello e gestione delle risorse per sistemi di 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 confronti e comprensione del paesaggio di ottimizzazione dell’inferenza.

• Riferimento API OpenAI - Documentazione ufficiale 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 autohostati in modo intercambiabile.