⚙️ Configurer vLLM en production multi-GPU
1. Installation
Via pip (recommandé)
# Python 3.11-3.14 ; roue par défaut CUDA 13.0# (depuis vLLM 0.33 : CUDA 13.0 uniquement, plus de variante CUDA 12.9)pip install vllm
# Vérificationpython -c "import vllm; print(vllm.__version__)"Via Docker (production recommandée)
L’image officielle évite les conflits de dépendances CUDA1 :
docker pull vllm/vllm-openai:latest
docker run --runtime nvidia --gpus all \ -p 8000:8000 \ -v ~/.cache/huggingface:/root/.cache/huggingface \ vllm/vllm-openai:latest \ --model meta-llama/Llama-3.1-8B-Instruct \ --dtype auto2. Configuration mono-GPU
Démarrage minimal
vllm serve meta-llama/Llama-3.1-8B-Instruct \ --host 0.0.0.0 \ --port 8000Paramètres essentiels
vllm serve meta-llama/Llama-3.1-70B-Instruct \ --host 0.0.0.0 \ --port 8000 \ --dtype bfloat16 \ # bf16 natif sur Ampere+, plus stable que fp16 --max-model-len 8192 \ # fenêtre de contexte max (limite le KV Cache) --gpu-memory-utilization 1.0 \ # fraction de VRAM allouée à vLLM (défaut 1.0 depuis la 0.34 ; à omettre sur un GPU dédié) --max-num-seqs 256 \ # requêtes concurrentes max en continuous batching --served-model-name llama-70b # alias dans l'API (évite d'exposer le chemin HF)Paramètre critique — gpu-memory-utilization :
vLLM réserve la fraction indiquée de VRAM pour l’ensemble du moteur (poids, activations et KV Cache). Depuis la 0.34, le cache KV extensible est actif par défaut : vLLM mesure la mémoire libre après la capture des graphes CUDA, et gpu-memory-utilization vaut 1.0 par défaut (0.92 auparavant). Sur un GPU dédié, ne fixez plus de valeur : une valeur explicite comme 0.92 donne désormais un cache plus petit. Fixez une valeur (0.85-0.9) seulement si d’autres processus partagent le GPU ou la mémoire (DGX Spark) ; --no-enable-extensible-kv-cache rétablit l’ancien dimensionnement34.
Modèles quantifiés (AWQ / GPTQ / FP8)
# Modèle AWQ (meilleure qualité à iso-mémoire vs GGUF Q4)vllm serve TheBloke/Llama-2-70B-Chat-AWQ \ --quantization awq \ --dtype auto
# Modèle GPTQvllm serve TheBloke/Llama-2-70B-GPTQ \ --quantization gptq \ --dtype float16
# FP8 en ligne, sans checkpoint pré-quantifié (Ada Lovelace / Hopper / Blackwell)# vLLM ≥ 0.31 : la méthode s'appelle fp8_per_tensor ; l'ancien nom "fp8" redirige[^13]vllm serve meta-llama/Llama-3.1-70B-Instruct \ --quantization fp8_per_tensor3. Configuration multi-GPU (Tensor Parallelism)
Le Tensor Parallelism répartit les poids d’une même couche sur plusieurs GPU du même serveur via NVLink ou PCIe. C’est le mode recommandé pour les modèles qui ne tiennent pas dans une seule carte6.
# 2 GPU — modèle 70B dans 2 × 40 Govllm serve meta-llama/Llama-3.1-70B-Instruct \ --tensor-parallel-size 2 \ --dtype bfloat16
# 4 GPU — modèle 70B avec marges confortablesvllm serve meta-llama/Llama-3.1-70B-Instruct \ --tensor-parallel-size 4
# 8 GPU — modèle 405B ou MoE massifvllm serve meta-llama/Llama-3.1-405B-Instruct \ --tensor-parallel-size 8 \ --pipeline-parallel-size 1 \ --dtype bfloat16Règle de dimensionnement :
tensor-parallel-sizedoit diviser le nombre de têtes d’attention du modèle (en pratique 1, 2, 4 ou 8 pour les modèles courants)6- Chaque GPU doit avoir accès à
taille_modèle / tensor_parallel_sizede VRAM - L’interconnexion décide de l’efficacité : NVLink >> PCIe (voir Stations Multi-GPU)
graph LR
A[Requête API] --> B[vLLM Scheduler]
B --> C[GPU 0 — 1/4 des poids de chaque couche 0-79]
B --> D[GPU 1 — 1/4 des poids de chaque couche 0-79]
B --> E[GPU 2 — 1/4 des poids de chaque couche 0-79]
B --> F[GPU 3 — 1/4 des poids de chaque couche 0-79]
C & D & E & F -->|all-reduce à chaque couche (NVLink ou PCIe)| G[Réponse]
4. Déploiement multi-nœuds avec Ray
Pour dépasser la capacité d’un seul serveur, vLLM s’appuie sur Ray pour distribuer le modèle entre plusieurs machines7.
Prérequis réseau
Les nœuds doivent se voir sur un réseau à faible latence. Idéalement RoCE/InfiniBand : la doc vLLM recommande d’activer InfiniBand (--privileged -e NCCL_IB_HCA=mlx5 dans run_cluster.sh) et de vérifier avec NCCL_DEBUG=TRACE que NCCL utilise NET/IB/GDRDMA et non NET/Socket7. Un Ethernet 25 Gb reste exploitable pour du Pipeline Parallelism (moins exigeant en bande passante que le Tensor Parallelism), au prix d’un TTFT plus élevé — la doc vLLM ne donne pas de seuil chiffré, mesurez sur votre charge.
Configuration du cluster Ray
# === Sur le nœud HEAD (nœud 0) ===pip install ray vllm
# Démarrer le processus Ray headray start --head --port=6379
# === Sur chaque nœud WORKER (nœuds 1, 2, ...) ===pip install ray vllm
# Rejoindre le cluster (remplacer HEAD_IP par l'IP du nœud head)ray start --address='HEAD_IP:6379'
# === Vérifier le cluster ===ray status# → affiche les nœuds connectés et les GPU disponiblesLancer vLLM sur le cluster
# Sur le nœud HEAD — vLLM utilise Ray pour distribuer automatiquementvllm serve meta-llama/Llama-3.1-405B-Instruct \ --tensor-parallel-size 4 \ # 4 GPU par nœud --pipeline-parallel-size 2 \ # 2 nœuds --distributed-executor-backend ray \ --host 0.0.0.0 \ --port 8000vLLM et Ray gèrent automatiquement la répartition : les 4 premiers GPU (nœud 0) traitent les premières couches, les 4 suivants (nœud 1) les suivantes7. La doc officielle fournit examples/ray_serving/run_cluster.sh pour démarrer head et workers dans l’image vllm/vllm-openai (une VLLM_HOST_IP par nœud) ; sans Ray, lancez vllm serve … --nnodes 2 --node-rank 0 --master-addr HEAD_IP sur le head et --node-rank 1 --headless sur le worker7.
Désagrégation Prefill / Decode
Architecture avancée (expérimentale) qui isole des nœuds dédiés au Prefill (lecture du prompt, compute-bound) et d’autres au Decode (génération, memory-bandwidth-bound)8. Le gain de TTFT dépend du connecteur KV et de la longueur des prompts — la doc vLLM ne publie pas de chiffre : mesurez-le avec vllm bench serve8.
# Désagrégation P/D — même flag sur les deux rôles, connecteur NIXL# (kv_role : "kv_producer" côté Prefill, "kv_consumer" côté Decode, "kv_both" pour les deux)vllm serve ... \ --kv-transfer-config '{"kv_connector":"NixlConnector","kv_role":"kv_both"}'Les connecteurs disponibles au T4 2026 sont NixlConnector, LMCacheConnectorV1, MooncakeConnector, OffloadingConnector (déport CPU) et MultiConnector ; la fonctionnalité est documentée comme « expérimentale et susceptible de changer »8. Les flags --role et --num-speculative-tokens n’existent pas dans vllm serve (la spéculation se configure via --speculative-config)9.
5. Configuration production — paramètres avancés
Authentification API
vllm serve ... \ --api-key "VOTRE-TOKEN-A-REMPLACER"Ou via variable d’environnement :
export VLLM_API_KEY="VOTRE-TOKEN-A-REMPLACER"vllm serve ...Les clients doivent envoyer Authorization: Bearer VOTRE-TOKEN-A-REMPLACER. Attention : --api-key ne couvre pas toutes les routes : en production, placez un reverse proxy authentifiant devant tous les chemins (voir Sécurité). Depuis vLLM 0.32.0 (18 octobre 2026), --allowed-origins vaut [] par défaut au lieu de ["*"] (CVE-2026-115917). Une interface web qui appelle vLLM directement depuis le navigateur doit déclarer son origine (--allowed-origins '["https://chat.interne.example"]'). Les clients côté serveur (SDK, curl, LiteLLM) ne sont pas concernés10.
Limites et timeouts
vllm serve ... \ --max-num-seqs 512 \ # séquences traitées par itération (batch continu) --max-num-queued-reqs 1024 # requêtes en vol max ; au-delà : HTTP 503 (vLLM ≥ 0.29)# Les logs de requêtes sont désactivés par défaut (--enable-log-requests pour déboguer)[^8]--max-num-seqs borne le nombre de séquences traitées par itération, pas la file d’attente (illimitée par défaut) : c’est --max-num-queued-reqs (vLLM 0.29) qui produit le 503, à dimensionner autour de data_parallel_size × max_num_seqs plus la profondeur de file souhaitée39. vLLM n’a pas de timeout par requête côté moteur : fixez-le dans le reverse proxy (Caddy reverse_proxy … { transport http { response_header_timeout 120s } }, Nginx proxy_read_timeout 120s) ou côté client9.
Optimisation KV Cache — quantification FP8
Sur GPU NVIDIA (CUDA 11.8+) et AMD ROCm, la quantification du KV Cache en FP8 divise par deux son empreinte par rapport au BF16 ; sans calibration, toutes les échelles valent 1.0 — la doc recommande de calibrer avec llm-compressor et d’exclure les couches à fenêtre glissante (--kv-cache-dtype-skip-layers sliding_window)11 :
vllm serve ... \ --kv-cache-dtype fp8La taille du KV Cache effectivement allouée est écrite dans les logs de démarrage (« GPU KV cache size: … tokens ») ; il n’existe pas de flag dédié pour l’afficher9.
Automatic Prefix Caching (APC) — indispensable pour RAG et agents
En environnement multi-utilisateurs ou multi-agents, plusieurs requêtes partagent souvent le même System Prompt (500-2000 tokens) ou le même document RAG en contexte. Sans APC, vLLM calcule et stocke le KV Cache de ce préfixe N fois — une fois par requête — gaspillant VRAM et temps de calcul. Depuis l’architecture V1, l’APC est activé par défaut : il n’y a rien à faire pour en bénéficier12.
vllm serve meta-llama/Llama-3.1-70B-Instruct \ --max-model-len 8192# L'APC est actif par défaut ; --no-enable-prefix-caching pour le couper,# --prefix-caching-hash-algo xxhash pour un hachage plus rapide (sha256 par défaut)Fonctionnement : vLLM hache chaque bloc de KV Cache (taille --block-size, 64 tokens par défaut depuis la 0.34 au lieu de 16 ; seuls les blocs complets sont réutilisés, donc un préfixe partagé court peut ne plus profiter du cache : comparez avec --block-size 16)3. Si une nouvelle requête commence par la même séquence de blocs qu’une requête précédente encore en cache GPU, les vecteurs Key/Value sont réutilisés directement — sans recalcul du Prefill12.
Impact mesuré :
| Scénario | Sans APC | Avec APC |
|---|---|---|
| 20 agents parallèles, même system prompt 800 tokens | TTFT 3-8s chacun | TTFT < 100ms dès la 2e requête |
| Pipeline RAG : même contexte document partagé | recalcul intégral × N | hit cache : ~96% VRAM économisée sur le préfixe |
Systemd service (Linux)
[Unit]Description=vLLM Inference ServerAfter=network.target
[Service]Type=simpleUser=vllmEnvironment="HF_HOME=/data/models"Environment="CUDA_VISIBLE_DEVICES=0,1,2,3"# `python -m vllm.entrypoints.openai.api_server` est déprécié depuis vLLM 0.29 : utiliser `vllm serve`# (adapter le chemin de `vllm` à l'environnement virtuel ; le modèle est l'argument positionnel)ExecStart=/usr/local/bin/vllm serve meta-llama/Llama-3.1-70B-Instruct \ --tensor-parallel-size 4 \ --host 127.0.0.1 \ --port 8000Restart=alwaysRestartSec=10
[Install]WantedBy=multi-user.targetSur ROCm, CUDA_VISIBLE_DEVICES est déprécié depuis vLLM 0.24 (le moteur ne positionne plus lui-même cette variable) ; utilisez l’argument device_ids. Rien ne change pour NVIDIA13.
sudo systemctl daemon-reloadsudo systemctl enable --now vllmsudo journalctl -u vllm -f # suivre les logs6. Vérification et tests
# Health checkcurl http://localhost:8000/health
# Liste des modèles chargéscurl http://localhost:8000/v1/models | python3 -m json.tool
# Test de générationcurl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer VOTRE-TOKEN-A-REMPLACER" \ -d '{ "model": "llama-70b", "messages": [{"role": "user", "content": "Bonjour, tu fonctionnes ?"}], "max_tokens": 100 }'
# Métriques Prometheuscurl http://localhost:8000/metrics | grep vllmProchaines étapes
- Monitoring → 📊 Monitoring Prometheus + Grafana
- Migration depuis Ollama → 🔄 Migrer d'Ollama vers vLLM
- Sécurisation → 🔒 Sécurité de l'inférence locale
Sources et Références
Footnotes
-
vLLM Project, Installation — GPU (image officielle
vllm/vllm-openai, Python 3.11–3.14, capacité de calcul ≥ 7.5, roue par défaut CUDA 13.0 et variantecu129), consulté le 2026-10-09. https://docs.vllm.ai/en/stable/getting_started/installation/gpu/ ↩ ↩2 -
vLLM Project, Release v0.28.0 (roue PyPI et image Docker par défaut en CUDA 13.0, variantes
-cu129), 2026-08-26 · Release v0.33.0 (roues et images CUDA 13.0 uniquement, variantes-cu129retirées), 2026-11-02. https://github.com/vllm-project/vllm/releases/tag/v0.28.0 · https://github.com/vllm-project/vllm/releases/tag/v0.33.0rc3 ↩ -
vLLM Project, Engine Arguments (
--gpu-memory-utilization,--max-model-len,--max-num-seqs,--max-num-queued-reqs, comportement KV Cache), consulté le 2026-10-09. https://docs.vllm.ai/en/stable/configuration/engine_args/ ↩ ↩2 ↩3 -
vLLM Project, Release v0.34.0 (« Before you upgrade » : Model Runner V1 retiré ;
--block-size64 par défaut au lieu de 16 ; cache KV extensible actif par défaut etgpu_memory_utilizationà 1.0, ancien dimensionnement via--gpu-memory-utilization 0.9ou--no-enable-extensible-kv-cache; artefacts ROCm 7.2 retirés), 16 novembre 2026. https://github.com/vllm-project/vllm/releases/tag/v0.34.0 ↩ -
vLLM Project, GGUF (plugin
vllm-gguf-plugin, support « highly experimental and under-optimized », tokenizer du modèle de base), consulté le 2026-10-09. https://docs.vllm.ai/en/stable/features/quantization/gguf/ ↩ -
vLLM Project, Parallelism and Scaling — Tensor Parallelism (
--tensor-parallel-size, sharding des poids, recommandations NVLink). https://docs.vllm.ai/en/stable/serving/parallelism_scaling/ ↩ ↩2 -
vLLM Project, Parallelism and Scaling — Multi-node deployment (
run_cluster.sh,--distributed-executor-backend ray,--nnodes/--node-rank/--headless, InfiniBand et NCCL), consulté le 2026-10-09. https://docs.vllm.ai/en/stable/serving/parallelism_scaling/ ↩ ↩2 ↩3 ↩4 -
vLLM Project, Disaggregated Prefill and Decode (
--kv-transfer-config, connecteurs NIXL / LMCache / Mooncake / Offloading, statut expérimental), consulté le 2026-10-09. https://docs.vllm.ai/en/stable/features/disagg_prefill/ ↩ ↩2 ↩3 ↩4 -
vLLM Project, CLI Reference —
vllm serve(liste exhaustive des flags : absence de--role,--request-timeout,--calculate-kv-cache-size;--speculative-config), consulté le 2026-10-09 · vLLM Project, Release v0.29.0 (ajout de--max-num-queued-reqs), 2026-09-09. https://docs.vllm.ai/en/stable/cli/serve/ · https://github.com/vllm-project/vllm/releases/tag/v0.29.0 ↩ ↩2 ↩3 ↩4 -
vLLM Project, Release v0.32.0 (« Default CORS settings no longer allow every origin in the Python and Rust frontends; set
--allowed-originsto permit browser origins », #61009 ; liste vide par défaut ; corrige CVE-2026-115917, vLLM ≤ 0.31.x), 18 octobre 2026. https://github.com/vllm-project/vllm/releases/tag/v0.32.0 · https://github.com/vllm-project/vllm/pull/61009 ↩ -
vLLM Project, Quantized KV Cache (
--kv-cache-dtype fp8/fp8_e5m2, CUDA 11.8+ et ROCm, calibrationllm-compressor,--kv-cache-dtype-skip-layers), consulté le 2026-10-09. https://docs.vllm.ai/en/stable/features/quantization/quantized_kvcache/ ↩ -
vLLM Project, Automatic Prefix Caching (hachage par blocs de KV Cache, impact TTFT, compatibilité tensor parallelism), consulté le 2026-10-10. https://docs.vllm.ai/en/stable/features/automatic_prefix_caching/ ↩ ↩2 ↩3
-
vLLM Project, Release v0.24.0 (vLLM ne positionne plus
CUDA_VISIBLE_DEVICES; argumentdevice_ids; variable dépréciée sur ROCm), 2026-06-29. https://github.com/vllm-project/vllm/releases/tag/v0.24.0 ↩