Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Distribuzione con vLLM

Lezione 11 di 14 Aggiornata il 29 luglio 2026 Avanzato
In questa pagina
  1. vLLM: il motore di inferenza consigliato
  2. Cosa ti serve
  3. Modalità offline: elaborazione di batch
  4. Modalità server: esposizione di un’API
  5. Distribuzione con Docker
  6. I tre flag Mistral essenziali
  7. Ottimizzazione delle prestazioni
  8. Punti chiave

vLLM: il motore di inferenza consigliato

vLLM è il motore di inferenza Python più diffuso per gli LLM. Mistral AI lo raccomanda per il self-hosting perché è facile da usare, offre ottime prestazioni e mette a disposizione un’API compatibile con quella di OpenAI. Esploreremo insieme installazione e configurazione, per poi approfondire le sue due modalità d’uso: batch (offline) e server. Queste modalità non si escludono a vicenda: molti team usano la prima per preparare i dati e la seconda per servire le applicazioni.

Cosa ti serve

Il download dei modelli avviene tramite Hugging Face, che richiede un token con permesso READ:

export HF_TOKEN="hf_your_token_here"

Prima del primo download, devi accettare i termini d’uso nella pagina Hugging Face del modello (ad esempio: huggingface.co/mistralai/Mistral-Nemo-Instruct-2407). Si tratta di un passaggio manuale, una tantum per account. Dimenticarlo causa errori di download difficili da diagnosticare, che possono richiedere un’ora di indagini perché sembrano problemi di autenticazione.

Per l’ambiente Python, usa un virtualenv dedicato per evitare conflitti di versione con gli altri progetti:

# Crea un ambiente virtuale
python -m venv vllm-env
source vllm-env/bin/activate

# Installa vLLM (versione >= 0.6.1.post1)
pip install vllm

Poi c’è l’hardware, che determina cosa puoi effettivamente servire. Mistral 7B e Nemo stanno su una singola GPU da 24 GB, tipicamente una A10G, RTX 4090 o L4. Mixtral 8x7B richiede due GPU da 80 GB, nella pratica schede A100-80GB. Mistral Large 2, nella sua versione open-weight con i suoi 123 miliardi di parametri, necessita di almeno quattro GPU A100-80GB. In tutti i casi, installa i driver NVIDIA e CUDA 12.x prima di vLLM.

Modalità offline: elaborazione di batch

La modalità offline gestisce batch di richieste senza un server HTTP. Carichi il modello in memoria, elabori le richieste e recuperi i risultati. Nota i tre argomenti tokenizer_mode, load_format e config_format: ci torneremo sopra, non sono opzionali.

from vllm import LLM
from vllm.sampling_params import SamplingParams

# Carica il modello con i flag Mistral
llm = LLM(
    model="mistralai/Mistral-Nemo-Instruct-2407",
    tokenizer_mode="mistral",
    load_format="mistral",
    config_format="mistral"
)

# Parametri di generazione
sampling = SamplingParams(
    max_tokens=8192,
    temperature=0.3
)

# Elabora un batch di richieste
messages_batch = [
    [{"role": "user", "content": "What is PagedAttention?"}],
    [{"role": "user", "content": "Explain tensor parallelism."}],
    [{"role": "user", "content": "How does the KV cache work?"}],
]

results = llm.chat(messages=messages_batch[0], sampling_params=sampling)
for output in results:
    print(output.outputs[0].text)

Questa modalità eccelle nell’elaborazione batch di documenti—riassunto, classificazione—nella valutazione del modello rispetto ai benchmark, nella generazione di dati sintetici e negli script di test o prototipazione. Ogni volta che nessuno aspetta una risposta immediata, trai vantaggio dal saltare il livello HTTP.

Modalità server: esposizione di un’API

La modalità server avvia un endpoint HTTP compatibile con l’API di OpenAI:

vllm serve mistralai/Mistral-Nemo-Instruct-2407 \
    --tokenizer_mode mistral \
    --config_format mistral \
    --load_format mistral \
    --host 0.0.0.0 \
    --port 8000

Il server espone l’API sulla porta 8000. La conseguenza pratica è significativa: un’applicazione scritta per l’API di OpenAI passa al tuo modello self-hosted cambiando solo due righe, base_url e api_key. Le tue librerie, i framework per agenti e gli strumenti di test continuano a funzionare.

from openai import OpenAI

# Connettiti al server vLLM locale
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"  # Nessuna auth di default
)

response = client.chat.completions.create(
    model="mistralai/Mistral-Nemo-Instruct-2407",
    messages=[
        {"role": "system", "content": "You are a DevOps expert."},
        {"role": "user", "content": "How do I monitor a vLLM server in production?"}
    ],
    temperature=0.3,
    max_tokens=1024
)
print(response.choices[0].message.content)

Il commento # Nessuna auth di default merita attenzione: un server vLLM avviato così non autentica nessuno. Su una macchina di sviluppo è comodo. Su una macchina accessibile dalla rete, è una porta aperta. Un rapido test da riga di comando conferma che tutto risponde prima di procedere:

curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "mistralai/Mistral-Nemo-Instruct-2407",
        "messages": [{"role": "user", "content": "Hello, is this working?"}],
        "temperature": 0.3
    }'

Distribuzione con Docker

Per una distribuzione riproducibile, l’immagine ufficiale evita di reinstallare su ogni macchina:

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model mistralai/Mistral-Nemo-Instruct-2407 \
    --tokenizer_mode mistral \
    --load_format mistral \
    --config_format mistral

Tre opzioni in questo comando meritano una spiegazione. --runtime nvidia --gpus all dà al container accesso alle GPU NVIDIA; senza di esso, il modello proverebbe a girare su CPU. Il mount -v ~/.cache/huggingface:... condivide la cache dei modelli con l’host, risparmiandoti il riscaricamento di decine di gigabyte ogni volta che il container si riavvia. --ipc=host concede la memoria condivisa necessaria per la comunicazione inter-processo tra GPU; ometterlo causa crash difficili da diagnosticare non appena passi a più schede.

I tre flag Mistral essenziali

FlagScopo
--tokenizer_mode mistralUsa il tokenizer nativo Mistral (non quello di HF)
--config_format mistralCarica la configurazione in formato Mistral
--load_format mistralCarica i pesi in formato nativo Mistral

Senza questi flag, il modello potrebbe girare ma con prestazioni degradate o risultati errati. Questo è l’errore più comune nel self-hosting di Mistral: nulla crasha, il server parte, le risposte arrivano—sono solo peggiori di quanto dovrebbero essere, e rischi di concludere erroneamente che il modello sia deludente.

Ottimizzazione delle prestazioni

Quando un modello non sta su una singola scheda, il parallelismo tensoriale distribuisce i suoi livelli su più GPU. Il valore passato corrisponde al numero di schede usate:

vllm serve mistralai/Mixtral-8X7B-Instruct-v0.1 \
    --tokenizer_mode mistral \
    --config_format mistral \
    --load_format mistral \
    --tensor-parallel-size 2

La seconda leva riguarda la proporzione di memoria GPU che vLLM riserva:

vllm serve mistralai/Mistral-Nemo-Instruct-2407 \
    --tokenizer_mode mistral \
    --config_format mistral \
    --load_format mistral \
    --gpu-memory-utilization 0.9

Il valore di default (0.9) funziona nella maggior parte dei casi. Riducilo se altri processi usano la GPU—un servizio di visione, un notebook dimenticato—altrimenti il primo processo prende tutta la memoria e il secondo non riesce ad avviarsi.

Infine, due chiamate bastano per verificare che un server sia attivo, rendendole ottime sonde per il tuo orchestratore:

# Elenca i modelli disponibili
curl http://localhost:8000/v1/models

# Controlla lo stato di salute del server
curl http://localhost:8000/health

Punti chiave

  • vLLM espone un’API compatibile con OpenAI: puoi usare l’SDK openai per comunicare
  • I tre flag --tokenizer_mode mistral, --config_format mistral, --load_format mistral sono obbligatori
  • La modalità offline è adatta all’elaborazione batch; la modalità server alle applicazioni in tempo reale
  • Docker semplifica la distribuzione e garantisce la riproducibilità
  • Il parallelismo tensoriale ti permette di distribuire modelli grandi su più GPU