vLLM Quickstart: Servizio LLM ad alte prestazioni

vLLM è un motore di inferenza e servizio ad alta throughput e ad alto rendimento 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, rendendolo la scelta ideale per le deployment di LLM in produzione.

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 deployment in produzione. Rilasciata nel 2023, ha introdotto PagedAttention, una tecnica rivoluzionaria di gestione della memoria che migliora drasticamente l’efficienza del servizio.

Funzionalità Principali

Alta Prestazione di Throughput: vLLM consegna un throughput 14-24 volte superiore rispetto a HuggingFace Transformers con lo stesso hardware. Questo notevole guadagno di prestazioni proviene da un batch continuo, kernel CUDA ottimizzati e l’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 permette un’immigrazione senza problemi da OpenAI a un’infrastruttura autonoma senza modificare il codice dell’applicazione. Basta puntare il tuo client API all’endpoint di vLLM e funziona in modo trasparente.

Algoritmo PagedAttention: L’innovazione centrale dietro le prestazioni di vLLM è PagedAttention, che applica il concetto di paging della memoria virtuale ai meccanismi di attenzione. Invece di allocare blocchi di memoria continui 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 permette batch molto più grandi.

Batch Continuo: A differenza del batch statico dove devi aspettare che tutte le sequenze siano completate, vLLM utilizza un batch continuo (rolling). 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 entrata.

Supporto Multi-GPU: vLLM supporta la parallelizzazione tensoriale e la parallelizzazione pipeline per distribuire i modelli grandi su più GPU. Può servire 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 base provenienti da HuggingFace Hub.

Quando Utilizzare vLLM

vLLM eccelle in scenari specifici dove le sue forze brillano:

Servizi API di Produzione: Quando devi servire un LLM a molti utenti contemporanei tramite API, il throughput elevato e l’efficiente batching di vLLM lo rendono la scelta migliore. Le aziende che gestiscono chatbot, assistenti per codice o servizi di generazione di contenuti 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 permettono di servire più utenti con lo stesso hardware rispetto alle 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 4x da PagedAttention permette anche di utilizzare GPU più piccole e economiche.

Deploy su Kubernetes: La progettazione senza stato e l’architettura amichevole dei 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 delle 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 per carichi di lavoro in produzione.

Come Installare vLLM

Requisiti Preparatori

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 più semplice di installazione è 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 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 la produzione:

# 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": "Cosa è 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 Principali:

• --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 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

Entrambi vLLM e Ollama sono scelte popolari per l’hosting locale degli 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 il massimo throughput in scenari con molti utenti. L’algoritmo 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 a Ollama sotto alta concorrenza.

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

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-granulare sull’ottimizzazione delle prestazioni. Questa complessità è giustificata per le deployment in produzione dove si deve sfruttare al massimo le prestazioni del hardware.

API e Integrazione

vLLM fornisce API REST compatibili con OpenAI “out of the box”, rendendolo un sostituto immediato per l’API di OpenAI nelle applicazioni esistenti. Questo è cruciale per migrare i servizi di produzione dai provider di cloud all’infrastruttura autonoma 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 deployment in produzione.

Ollama utilizza una gestione della memoria più semplice adatta agli scenari a singolo utente. Gestisce automaticamente il caricamento e lo scaricamento dei modelli 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 pipeline, distribuendo efficientemente i modelli su 2-8+ GPU. Questo è essenziale per servire modelli grandi come i LLM con 70B parametri che non entrano 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 a modelli molto grandi che richiedono un’inferenza distribuita.

Consigli per l’Utilizzo

Scegli vLLM quando:

• Servire API in produzione con molti utenti contemporanei
• Ottimizzare il costo per richiesta in deployment 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
• Utilizzo interattivo a singolo utente (assistenti personali, chatbot)
• Prototipazione rapida e valutazione dei modelli
• Apprendimento sugli LLM senza complessità infrastrutturale
• Esecuzione su workstation o laptop personali
• La semplicità e l’facilità d’uso sono priorità

Molti team utilizzano entrambi: Ollama per lo sviluppo e sperimentazione, quindi vLLM per la deployment 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 a essere il “Docker per l’AI” – un modo semplice e standardizzato per eseguire localmente i modelli AI con la stessa facilità con cui si eseguono i 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 degli LLM con massima performance. È uno strumento a livello inferiore che si containerizza con Docker, piuttosto che una piattaforma completa.

Setup e Inizio

Docker Model Runner ha un’installazione semplice 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 che utilizzano già i container.

vLLM richiede più configurazione iniziale (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 batching continuo. Per i servizi API in produzione che gestiscono centinaia di richieste al secondo, le ottimizzazioni di vLLM forniscono un miglioramento del 2-5x rispetto ad approcci generici di servizio.

Docker Model Runner si concentra sull’uso facile 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 fanno eccellere vLLM su larga 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) tra cui Stable Diffusion, Whisper e altri modelli AI, rendendolo più versatile per diversi carichi di lavoro AI.

vLLM si specializza nell’inferenza degli 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 prestazione e stabilità sotto carico pesante lo rendono lo standard de facto per il servizio degli LLM in produzione.

Docker Model Runner è più recente e si posiziona più per scenari di sviluppo e test locale. Sebbene possa servire traffico in produzione, manca della provata esperienza e delle ottimizzazioni di prestazione necessarie per le deployment 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 un’ampia compatibilità con l’API di 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 degli LLM.

Quando Utilizzare Ognuno

Utilizza vLLM quando:

• Servire API in produzione degli LLM
• Deployment ad alta capacità e multi-utente
• Deployment cloud cost-sensibili che richiedono massima efficienza
• Ambienti Kubernetes e nativi cloud
• Quando hai bisogno di scalabilità e prestazioni provate

Utilizza Docker Model Runner quando:

• Sviluppo e test locale
• Esecuzione di diversi tipi di modelli AI (non solo LLM)
• Team pesantemente investiti nell’ecosistema Docker
• Sperimentazione rapida senza configurazione dell’infrastruttura
• 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 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

Deploy vLLM su Kubernetes per una 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

# 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 della 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 necessita della lunghezza completa del contesto, riduci --max-model-len. Questo libera memoria per batch più grandi. Per 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 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 applicazioni con prompt ripetuti (come chatbot con messaggi di sistema), abilita il caching dei 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 Non Disponibile

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 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
• 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 stai usando FP32: --dtype float16

Tempo di Prima Token Lento

Sintomi: Alta latenza prima che inizi la generazione.

Soluzioni:

• Usa 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 dei Modelli

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 sufficiente spazio su disco in ~/.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-2x:

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 sintonizzati con un overhead di memoria minimo. Questo è ideale per servire varianti di modelli specifici per clienti o task:

# 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 su richieste

Il caching dei prefissi può ridurre il tempo per il 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 di Prestazioni

Dati reali di 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 14x rispetto alle implementazioni 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 180ms, P99 latenza 420ms a 100 richieste/s
• Servizio standard: P50 latenza 650ms, P99 latenza 3.200ms a 100 richieste/s
• Risultato: vLLM mantiene una latenza coerente sotto carico elevato

Questi benchmark dimostrano perché vLLM è diventato lo standard de facto per il servizio degli 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 (80 GB)
• Costo AWS: ~$32/ora × 24 × 30 = $23.040/mese
• Costo per 1 milione di token: ~$0,75

Con vLLM:

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

Considerazioni sulla Sicurezza

Autenticazione

Per default, vLLM non include l’autenticazione. Per la produzione, implementa l’autenticazione a livello del 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 enterprise.

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 deployment 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 Migración

Da OpenAI a vLLM

La migrazione da OpenAI a vLLM autohostato è 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 l’altro codice rimane identico.

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

Da HuggingFace Transformers a vLLM

Migrazione diretta dell’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 in batch.

Futuro di vLLM

vLLM continua lo sviluppo rapido con funzionalità eccitanti in programma:

Servizio Disaggregato: Separare il prefill (elaborazione del prompt) e decode (generazione dei token) su GPU diverse per ottimizzare l’utilizzo delle risorse. Il prefill è limitato dal calcolo mentre la decode è limitata 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 single-node.

Quantizzazione migliorata: Supporto per nuovi formati di quantizzazione come GGUF (usato da llama.cpp) e miglior integrazione AWQ/GPTQ per una migliore performance con modelli quantizzati.

Miglioramenti alla Decodifica Speculativa: Modelli di draft più efficienti e strategie di speculazione adattive per ottenere un miglioramento della velocità senza perdita di accuratezza.

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

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

Il progetto vLLM mantiene uno sviluppo attivo con contributi da UC Berkeley, Anyscale e la comunità open-source più ampia. Mentre il deployment degli LLM diventa sempre più critico 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 2025 - Ollama, vLLM, LocalAI, Jan, LM Studio & Altri - Confronto completo di 12+ strumenti per l’ospitazione di LLM locali, tra cui un’analisi dettagliata di vLLM insieme a Ollama, LocalAI, Jan, LM Studio e altri. Copre la maturità dell’API, il supporto per le chiamate agli strumenti, la compatibilità GGUF e i benchmark di prestazioni per aiutare a scegliere la soluzione giusta.

• Ollama: Foglio di Istruzioni - Riferimento completo dei comandi di Ollama e foglio di istruzioni che copre l’installazione, la gestione dei modelli, l’uso dell’API e le best practice per l’ospitazione 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 il Model Runner di Docker e Ollama per l’ospitazione di LLM locali, analizzando prestazioni, supporto GPU, compatibilità API e casi d’uso. Aiuta a comprendere il contesto competitivo in cui opera vLLM.

• Foglio di Istruzioni Docker Model Runner: Comandi & Esempi - Foglio di istruzioni 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 l’ospitazione 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, dall’installazione di base alla configurazione avanzata. 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 compatibili con vLLM. Cerca i modelli per dimensione, compito, licenza e caratteristiche di prestazione 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 sistemi di produzione.

• NVIDIA TensorRT-LLM - TensorRT-LLM di NVIDIA per un’ottimizzazione altamente efficiente dell’inferenza su GPU NVIDIA. Alternativa a vLLM con strategie di ottimizzazione diverse, utile per confronti e comprensione del panorama dell’ottimizzazione dell’inferenza.

• Riferimento API OpenAI - Documentazione ufficiale API OpenAI con cui l’API di vLLM è compatibile. Utilizza questo riferimento quando si costruiscono applicazioni che devono funzionare con entrambi gli endpoint OpenAI e vLLM self-hosted in modo intercambiabile.