Aller au contenu

⚙️ Configurer vLLM en production multi-GPU


1. Installation

Via pip (recommandé)

Fenêtre de terminal
# 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érification
python -c "import vllm; print(vllm.__version__)"

Via Docker (production recommandée)

L’image officielle évite les conflits de dépendances CUDA1 :

Fenêtre de terminal
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 auto

2. Configuration mono-GPU

Démarrage minimal

Fenêtre de terminal
vllm serve meta-llama/Llama-3.1-8B-Instruct \
--host 0.0.0.0 \
--port 8000

Paramètres essentiels

Fenêtre de terminal
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)

Fenêtre de terminal
# 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 GPTQ
vllm 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_tensor

3. 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.

Fenêtre de terminal
# 2 GPU — modèle 70B dans 2 × 40 Go
vllm serve meta-llama/Llama-3.1-70B-Instruct \
--tensor-parallel-size 2 \
--dtype bfloat16
# 4 GPU — modèle 70B avec marges confortables
vllm serve meta-llama/Llama-3.1-70B-Instruct \
--tensor-parallel-size 4
# 8 GPU — modèle 405B ou MoE massif
vllm serve meta-llama/Llama-3.1-405B-Instruct \
--tensor-parallel-size 8 \
--pipeline-parallel-size 1 \
--dtype bfloat16

Règle de dimensionnement :

  • tensor-parallel-size doit 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_size de 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

Fenêtre de terminal
# === Sur le nœud HEAD (nœud 0) ===
pip install ray vllm
# Démarrer le processus Ray head
ray 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 disponibles

Lancer vLLM sur le cluster

Fenêtre de terminal
# Sur le nœud HEAD — vLLM utilise Ray pour distribuer automatiquement
vllm 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 8000

vLLM 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.

Fenêtre de terminal
# 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

Fenêtre de terminal
vllm serve ... \
--api-key "VOTRE-TOKEN-A-REMPLACER"

Ou via variable d’environnement :

Fenêtre de terminal
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

Fenêtre de terminal
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 :

Fenêtre de terminal
vllm serve ... \
--kv-cache-dtype fp8

La 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.

Fenêtre de terminal
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énarioSans APCAvec APC
20 agents parallèles, même system prompt 800 tokensTTFT 3-8s chacunTTFT < 100ms dès la 2e requête
Pipeline RAG : même contexte document partagérecalcul intégral × Nhit cache : ~96% VRAM économisée sur le préfixe

Systemd service (Linux)

/etc/systemd/system/vllm.service
[Unit]
Description=vLLM Inference Server
After=network.target
[Service]
Type=simple
User=vllm
Environment="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 8000
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target

Sur 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.

Fenêtre de terminal
sudo systemctl daemon-reload
sudo systemctl enable --now vllm
sudo journalctl -u vllm -f # suivre les logs

6. Vérification et tests

Fenêtre de terminal
# Health check
curl http://localhost:8000/health
# Liste des modèles chargés
curl http://localhost:8000/v1/models | python3 -m json.tool
# Test de génération
curl 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 Prometheus
curl http://localhost:8000/metrics | grep vllm

Prochaines étapes


Sources et Références

Footnotes

  1. 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 variante cu129), consulté le 2026-10-09. https://docs.vllm.ai/en/stable/getting_started/installation/gpu/ ↩ ↩2

  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 -cu129 retiré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 ↩

  3. 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

  4. vLLM Project, Release v0.34.0 (« Before you upgrade » : Model Runner V1 retiré ; --block-size 64 par défaut au lieu de 16 ; cache KV extensible actif par défaut et gpu_memory_utilization à 1.0, ancien dimensionnement via --gpu-memory-utilization 0.9 ou --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 ↩

  5. 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/ ↩

  6. 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

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

  8. 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

  9. 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

  10. vLLM Project, Release v0.32.0 (« Default CORS settings no longer allow every origin in the Python and Rust frontends; set --allowed-origins to 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 ↩

  11. vLLM Project, Quantized KV Cache (--kv-cache-dtype fp8 / fp8_e5m2, CUDA 11.8+ et ROCm, calibration llm-compressor, --kv-cache-dtype-skip-layers), consulté le 2026-10-09. https://docs.vllm.ai/en/stable/features/quantization/quantized_kvcache/ ↩

  12. 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

  13. vLLM Project, Release v0.24.0 (vLLM ne positionne plus CUDA_VISIBLE_DEVICES ; argument device_ids ; variable dépréciée sur ROCm), 2026-06-29. https://github.com/vllm-project/vllm/releases/tag/v0.24.0 ↩

Donner mon avis

Tout est facultatif : une seule réponse suffit. Ce site n'envoie rien : c'est vous qui envoyez, par le moyen de votre choix.

Votre notePas de note
Votre avis porte sur
Sur quoi ? (plusieurs choix possibles)
Ce qui sera envoyé
Envoyer par e-mail

Privé, sans compte : ouvre votre messagerie avec le message prêt, pour ia-on-prem@damien.becherini.fr.

Ouvrir un ticket GitHub ↗

Public, avec un compte GitHub. Vous relisez le ticket avant de le publier.

Pour le coller où vous voulez.

Donnez au moins une note, un sujet ou un message pour pouvoir envoyer.