vLLM Docker: esegui un server di inferenza con GPU in pochi minuti

vLLM pubblica un'immagine Docker ufficiale, vllm/vllm-openai, che fornisce un server di inferenza OpenAI-compatibile pronto all'uso. Il percorso più veloce: installa NVIDIA Container Toolkit sull'host, quindi esegui l'immagine con --gpus all e un ID modello di Hugging Face. Una volta scaricato il modello, il server è live sulla porta 8000 e accetta le stesse richieste dell'API OpenAI.

Prerequisiti

• Docker Engine 20.10+ — Docker Desktop su Windows e macOS funziona tramite il backend WSL2.
• GPU NVIDIA con un driver che supporta CUDA 12.x. Esegui nvidia-smi per confermare; la «CUDA Version» mostrata è il massimo supportato dal tuo driver.
• NVIDIA Container Toolkit — il bridge che consente a Docker di vedere la GPU. Vedi la sezione successiva.
• VRAM sufficiente per il tuo modello target. Usa Calcolatore VRAM per controllare prima di procedere con 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 docker

RHEL/CentOS: Sostituisci l'URL del repository deb con l'equivalente rpm dalla documentazione di NVIDIA e usa dnf al posto di apt-get.

Windows (WSL2): Installa il driver NVIDIA per Windows sull'host — non è necessaria un'installazione separata del container toolkit all'interno di WSL2. Docker Desktop gestisce il passthrough automaticamente.

macOS: Le GPU NVIDIA non sono supportate su macOS. vLLM non funziona su Apple Silicon tramite Docker con accelerazione GPU. Per l'inferenza locale su hardware Apple, considera una build CPU-only o un runtime diverso.

Il Comando di Esecuzione Minimo

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

Flag	Perché è importante
--runtime nvidia	Instrada le chiamate GPU attraverso il runtime del container NVIDIA.
--gpus all	Espone tutte le GPU host. Usa "device=0,1" per targeting GPU specifiche.
--ipc=host	Condivide lo spazio dei nomi IPC dell'host. Obbligatorio per la memoria condivisa PyTorch; ometterlo causa un Bus error o un crash della memoria condivisa.
-v ~/.cache/huggingface:…	Monta la cache HF dell'host in modo che i pesi sopravvivano ai riavvii del container.
-p 8000:8000	Espone il server compatibile con OpenAI sull'host.
--model	Un ID modello di Hugging Face o un percorso locale montato nel container.

Per scaricare un modello protetto (Llama 3, Mistral, ecc.), passa anche -e HUGGING_FACE_HUB_TOKEN=hf_yourtoken. Memorizza il token in un .env file e passalo con --env-file .env piuttosto che inserirlo direttamente nella cronologia della shell.

Montaggio della Cache di Hugging Face

vLLM scarica i pesi del modello in /root/.cache/huggingface dentro il container. Senza un volume mount, ogni docker run scarica nuovamente il modello completo — spesso 5–80 GB. La riga del mount è:

-v ~/.cache/huggingface:/root/.cache/huggingface

Se i tuoi modelli si trovano in una posizione non predefinita, imposta -e HF_HOME=/your/path e monta invece quel percorso. Per ambienti air-gapped, scarica il modello con huggingface-cli download prima, quindi passa --model /path/in/container insieme a un volume mount della directory dei pesi.

Flag Principali del Server vLLM

Questi flag vengono passati dopo il nome dell'immagine — sono argomenti del processo server vLLM, non di Docker.

Flag	Predefinito	Quando modificarlo
--tensor-parallel-size N	1	Imposta al numero di GPU per il serving multi-GPU. Le teste di attenzione del modello devono essere divisibili per N. Abbinalo a --gpus "device=0,1,..." elencando esattamente N dispositivi.
--gpu-memory-utilization 0.X	0.90	Abbassa a 0.75–0.80 se vedi errori OOM o condividi la GPU con altri processi.
--max-model-len N	Configurazione del modello	Limita la dimensione della cache KV. Utile quando il contesto predefinito di un modello (ad es. 128 k) esaurirebbe la VRAM. Prova --max-model-len 8192 come prima riduzione.
--dtype auto	auto	Sovrascrivi con bfloat16 o float16 se il rilevamento automatico seleziona una precisione inaspettata.
--quantization awq / gptq	none	Abilita per varianti di modelli pre-quantizzati. Dimezza approssimativamente la VRAM con una perdita di qualità.
--port	8000	Modifica se 8000 è già occupata sull'host.

Non sei sicuro che la tua GPU abbia abbastanza VRAM per un dato modello? La Guida ai requisiti di VRAM elenca i modelli comuni, e il Calcolatore VRAM ti permette di inserire la quantizzazione e la dimensione del batch. Per decisioni di acquisto di hardware, consulta la guida alle raccomandazioni GPU.

Esposizione e Test dell'Endpoint Compatibile con OpenAI

Una volta che il container stampa INFO: Application startup complete, l'API è live.

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

# Completamento del testo
curl http://localhost:8000/v1/completions 
  -H "Content-Type: application/json" 
  -d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "prompt": "The capital of France is", "max_tokens": 20}'

# Completamento chat
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": "Hello"}]}'

Qualsiasi client compatibile con OpenAI — l'SDK Python openai , LangChain, LlamaIndex — funziona impostando base_url="http://localhost:8000/v1" e fornendo qualsiasi stringa non vuota come api_key.

Esempio Docker Compose

Per implementazioni persistenti, un file Compose è più facile da gestire di un lungo 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 8192

Inizia con docker compose up -d. Il blocco deploy.resources equivale, nella versione 3 di Compose, all’opzione --gpus all.

Errori Comuni e Soluzioni

Errore	Causa	Soluzione
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, but throughput is orders of magnitude slower and not practical for serving. For CPU-only local inference, llama.cpp or Ollama are more suitable alternatives — see the guida 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.