- Scarica
vllm/vllm-openai:latested eseguilo con--runtime nvidia --gpus all --ipc=hostper ottenere un server compatibile con OpenAI basato su GPU. - Monta
~/.cache/huggingfaceall’interno del contenitore affinché i pesi dei modelli sopravvivano ai riavvii del contenitore. - Il server espone un’API compatibile con OpenAI sulla porta 8000; testala con
curl http://localhost:8000/v1/models. - Le tre opzioni di configurazione più importanti sono
--tensor-parallel-size,--max-model-len, e--gpu-memory-utilization.
vLLM pubblica un’immagine Docker ufficiale, vllm/vllm-openai, che include un server di inferenza compatibile con OpenAI già pronto all’uso. Il metodo più rapido consiste nell’installare NVIDIA Container Toolkit sull’host, quindi eseguire l’immagine con --gpus all e un ID modello Hugging Face. Una volta scaricato il modello, il server sarà attivo sulla porta 8000 e accetterà le stesse richieste dell’API OpenAI.
Prerequisiti
- Docker Engine 20.10 o versione successiva — Docker Desktop su Windows e macOS funziona tramite il backend WSL2.
- GPU NVIDIA con un driver che supporti CUDA 12.x. Esegui
nvidia-smiper verificare; la versione di «CUDA» indicata rappresenta la versione massima supportata dal tuo driver. - NVIDIA Container Toolkit — il ponte che consente a Docker di rilevare la GPU. Per ulteriori dettagli, consulta la sezione successiva.
- Sufficiente VRAM per il modello prescelto. Usa lo strumento Calcolatore VRAM per verificare prima di avviare il download del modello.
Installazione di NVIDIA Container Toolkit
Salta questa sezione se docker run --gpus all nvidia/cuda:12.0-base nvidia-smi funziona già sulla tua macchina.
Linux (Ubuntu/Debian):
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey |
sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list |
sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' |
sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart dockerRHEL/CentOS: Sostituisci l'URL del repository deb con l'equivalente rpm fornito dalla documentazione NVIDIA e usa dnf al posto di apt-get.
Windows (WSL2): Installa il driver NVIDIA per Windows sull’host — non è necessaria alcuna installazione separata del container toolkit all’interno di WSL2. Docker Desktop gestisce automaticamente il pass-through.
macOS: Le GPU NVIDIA non sono supportate su macOS. vLLM non può essere eseguito su Apple Silicon tramite Docker con accelerazione GPU. Per l’inferenza locale su hardware Apple, prendi in considerazione una build dedicata alla CPU oppure un runtime alternativo.
Comando minimo per l’esecuzione
docker run --runtime nvidia --gpus all
--ipc=host
-v ~/.cache/huggingface:/root/.cache/huggingface
-p 8000:8000
vllm/vllm-openai:latest
--model meta-llama/Meta-Llama-3-8B-Instruct| Segnala | Perché è importante |
|---|---|
--runtime nvidia | Indirizza le chiamate GPU attraverso il runtime container NVIDIA. |
--gpus all | Espone tutte le GPU dell’host. Usa "device=0,1" per selezionare specifiche GPU. |
--ipc=host | Condivide lo spazio dei nomi IPC dell’host. Richiesto per la memoria condivisa di PyTorch; la sua omissione causa un errore Bus error o un crash legato alla memoria condivisa. |
-v ~/.cache/huggingface:… | Monta la cache Hugging Face dell’host in modo che i pesi del modello sopravvivano ai riavvii del container. |
-p 8000:8000 | Espone il server compatibile con OpenAI sull’host. |
--model | Qualsiasi ID modello di Hugging Face oppure un percorso locale montato nel container. |
Per scaricare un modello protetto da accesso controllato (ad es. Llama 3, Mistral, ecc.), aggiungi anche -e HUGGING_FACE_HUB_TOKEN=hf_yourtoken. Memorizza il token in un file .env e passalo mediante --env-file .env anziché inserirlo direttamente nella cronologia della shell.
Montaggio della cache di Hugging Face
vLLM scarica i pesi del modello nella cartella /root/.cache/huggingface all’interno del container. Senza un volume montato, ogni comando docker run scaricherà nuovamente l’intero modello — spesso compreso tra 5 e 80 GB. La riga di montaggio è:
-v ~/.cache/huggingface:/root/.cache/huggingfaceSe i tuoi modelli risiedono in una posizione non predefinita, imposta -e HF_HOME=/your/path e montare tale percorso invece. Per ambienti isolati (air-gapped), scaricare prima il modello con huggingface-cli download , quindi passare --model /path/in/container insieme a un mount del volume della directory dei pesi.
Principali flag del server vLLM
Queste opzioni vengono specificate dopo il nome dell’immagine: sono argomenti del processo del server vLLM, non di Docker.
| Segnala | Predefinito | Quando modificarla |
|---|---|---|
--tensor-parallel-size N | 1 | Impostare al numero di GPU da utilizzare per il servizio su più GPU. Il numero di testine di attenzione del modello deve essere divisibile per N. Usare in abbinamento a --gpus "device=0,1,..." elencando esattamente N dispositivi. |
--gpu-memory-utilization 0.X | 0.90 | Ridurre a 0,75–0,80 se si verificano errori di esaurimento della memoria (OOM) o se la GPU è condivisa con altri processi. |
--max-model-len N | Configurazione del modello | Limita le dimensioni della cache KV. Utile quando il contesto predefinito del modello (es. 128k) rischia di esaurire la VRAM. Provare innanzitutto --max-model-len 8192 come prima riduzione. |
--dtype auto | auto | Sovrascrivere con bfloat16 o float16 se il rilevamento automatico seleziona una precisione non prevista. |
--quantization awq / gptq | none | Abilitare per varianti di modelli già quantizzati. Riduce approssimativamente della metà l’uso di VRAM, con un certo impatto sulla qualità. |
--port | 8000 | Modificare se la porta 8000 è già occupata sull’host. |
Non si è sicuri se la GPU disponga di sufficiente VRAM per un determinato modello? La Guida ai requisiti di VRAM tabella dei modelli comuni Calcolatore VRAM calcolatrice interattiva guida alle raccomandazioni per le GPU.
Esposizione e test dell’endpoint compatibile con OpenAI
Una volta che il contenitore visualizza INFO: Application startup complete, l’API è attiva.
# Elenco dei modelli caricati
curl http://localhost:8000/v1/models
# Completamento testuale
curl http://localhost:8000/v1/completions
-H "Content-Type: application/json"
-d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "prompt": "La capitale della Francia è", "max_tokens": 20}'
# Completamento conversazionale
curl http://localhost:8000/v1/chat/completions
-H "Content-Type: application/json"
-d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "messages": [{"role": "user", "content": "Ciao"}]}'Qualsiasi client compatibile con OpenAI — l’SDK Python, LangChain, LlamaIndex — funziona impostando openai base_url="http://localhost:8000/v1" e fornendo una stringa non vuota come chiave API. api_key.
Esempio di Docker Compose
Per distribuzioni persistenti, un file Compose è più facile da gestire rispetto a un lungo comando docker run docker run:
services:
vllm:
image: vllm/vllm-openai:latest
runtime: nvidia
environment:
- HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
volumes:
- ~/.cache/huggingface:/root/.cache/huggingface
ports:
- "8000:8000"
ipc: host
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
command: >
--model meta-llama/Meta-Llama-3-8B-Instruct
--gpu-memory-utilization 0.90
--max-model-len 8192Inizia con docker compose up -d. Il blocco deploy.resources equivale, nella versione 3 di Compose, all’opzione --gpus all.
Errori comuni e relative soluzioni
| Errore | Causa | Correggi |
|---|---|---|
| Bus error o /dev/shm troppo piccolo | La dimensione predefinita di Docker per /dev/shm è di 64 MB, insufficiente per PyTorch. | Aggiungere --ipc=host --ipc=host --shm-size=8g se non è possibile condividere lo spazio dei nomi IPC dell’host. |
| Errore CUDA: nessuna immagine del kernel disponibile | La versione di CUDA inclusa nell’immagine vLLM supera quella supportata dal driver installato. | Esegui nvidia-smi Utilizzare nvidia-smi). |
| torch.cuda.OutOfMemoryError | I pesi del modello più la cache KV superano la VRAM disponibile. | Prova --max-model-len 4096 innanzitutto. Poi riduci --gpu-memory-utilization a 0,80. Se il problema di memoria insufficiente persiste, utilizza una variante quantizzata oppure una GPU più potente. |
| permesso negato nella directory della cache | Il container viene eseguito come root; la directory host appartiene a un altro utente. | Esegui chmod -R a+rw ~/.cache/huggingface sull'host oppure usa un volume Docker denominato invece di un bind mount. |
Il container si avvia ma curl restituisce "connection refused" | Il modello è ancora in fase di caricamento oppure -p 8000:8000 manca. | Attendi la riga di log Application startup complete . Verifica che il mapping delle porte sia presente nel comando di esecuzione. |
Domande frequenti
Quale tag dell'immagine Docker vLLM devo utilizzare?
vllm/vllm-openai:latest rappresenta la versione più recente ed è adatto per sperimentazioni. Per ambienti di produzione, è consigliabile fissare un tag di versione specifico (ad esempio v0.6.0) per garantire la riproducibilità delle build. Ogni tag di rilascio su Docker Hub indica la versione di CUDA con cui l’immagine è stata compilata, che deve essere minore o uguale alla versione supportata dal driver installato.
Posso eseguire vLLM in Docker senza GPU?
L'immagine standard richiede una GPU NVIDIA. L'inferenza su CPU è possibile compilando vLLM da sorgente con VLLM_TARGET_DEVICE=cpu, ma le prestazioni sono inferiori di diversi ordini di grandezza e non risultano pratiche per servizi in produzione. Per inferenza locale su CPU, soluzioni alternative più adatte sono llama.cpp o Ollama — consulta la Guida a Ollama per un confronto.
Come posso eseguire un modello protetto (gated) che richiede un token Hugging Face?
Passa il token come variabile d'ambiente: -e HUGGING_FACE_HUB_TOKEN=hf_yourtoken. Memorizzalo in un file .env e fai riferimento ad esso con --env-file .env per evitare che venga registrato nella cronologia della shell. Il server lo utilizza durante il download iniziale del modello; non è più necessario una volta che i pesi sono stati memorizzati localmente nella cache.
A cosa serve l'opzione --tensor-parallel-size e quando ne ho bisogno?
La parallelizzazione tensoriale suddivide le matrici dei pesi del modello su più GPU, consentendo di eseguire modelli troppo grandi per una singola scheda. Impostala al numero di GPU che intendi utilizzare (2 o 4 sono valori comuni). Tale numero deve corrispondere esattamente al numero di GPU specificato tramite --gpus, e il numero di testine di attenzione del modello deve essere divisibile per tale valore.
Eseguire vLLM in Docker è conveniente dal punto di vista dei costi rispetto a un'API gestita?
Dipende interamente dal volume di richieste. L'auto-hosting comporta costi fissi elevati (istanza GPU o hardware dedicato), ma un costo marginale prossimo a zero per ogni richiesta. Le API gestite non prevedono costi fissi, ma addebitano una tariffa per ogni token elaborato. Utilizza il calcolatore self-hosting vs API per calcolare il punto di pareggio prima di impegnarti nell’acquisto dell’infrastruttura.
Come faccio a servire contemporaneamente più modelli?
Esegui un container per ogni modello, ciascuno mappato su una porta host diversa (ad esempio 8000, 8001). Attualmente vLLM non supporta il servizio multi-modello da un singolo processo. Posiziona un reverse proxy come nginx o Caddy davanti ai container per instradare le richieste, in base al nome del modello, sulla porta corretta.
