Optimisez vLLM pour le débit et la latence

vLLM est le runtime open source le plus riche en fonctionnalités pour servir des grands modèles de langage sur GPU. Il propose une large gamme d’options de configuration qui affectent directement le débit, la latence et l’utilisation de la mémoire. Ce guide couvre les paramètres les plus importants et comment les régler pour votre charge de travail.

Dernière vérification : 2026-10-14 — vLLM v0.31.0.

V1 est le mode par défaut. L’architecture V1 est maintenant le mode par défaut dans vLLM v0.31.0. Elle apporte un nouveau planificateur, le chunked prefill activé par défaut et une gestion améliorée de la mémoire GPU. Si vous observez des différences de comportement par rapport aux anciens guides, V1 en est probablement la cause.

Réglage du cache KV

Le cache KV stocke les tenseurs clé-valeur pour chaque token dans chaque séquence active. C’est généralement le plus gros consommateur de mémoire GPU après les poids du modèle lui-même, donc son réglage a l’impact le plus important sur le nombre de requêtes simultanées que vous pouvez servir.

Formule de dimensionnement

vLLM calcule automatiquement la taille du cache KV, mais comprendre la formule vous aide à définir des limites :

KV memory per token = 2 × num_layers × num_kv_heads × head_dim × dtype_bytes

Le facteur 2 correspond aux clés et aux valeurs. Pour un modèle 7B avec 32 couches, 32 têtes KV, une dimension de tête de 128 et float16 :

2 × 32 × 32 × 128 × 2 = 524,288 bytes ≈ 0.5 MB per token

Avec 24 Go d’espace pour le cache KV, cela contient environ 48,000 tokens pour toutes les séquences.

Utiliser un cache KV fp8

--kv-cache-dtype fp8 réduit la mémoire du cache KV d’environ 50% par rapport au float16 par défaut. Cela double directement le nombre de tokens que vous pouvez mettre en cache, ce qui signifie plus de séquences simultanées ou des contextes plus longs.

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --kv-cache-dtype fp8

Le cache KV FP8 introduit une légère perte de précision. Pour la plupart des charges de travail de chat et de génération de code, la différence est négligeable, mais si vous exécutez des évaluations sur votre tâche spécifique, vérifiez que la qualité de sortie répond à votre seuil avant de l’activer en production.

`--max-num-seqs` vs `--max-model-len`

Ces 2 drapeaux se disputent le même pool de cache KV :

--max-model-len plafonne la longueur du contexte d’une seule séquence. La réduire libère du cache KV pour plus de séquences simultanées.
--max-num-seqs plafonne le nombre de séquences traitées en un lot. L’augmenter accroît le débit au détriment de la mémoire par séquence.

Si votre charge de travail envoie des invites courtes (moins de 2K tokens), réduisez --max-model-len et augmentez --max-num-seqs pour maximiser la concurrence. Si vous servez des requêtes à contexte long, faites l’inverse.

# Short prompts, high concurrency
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --max-model-len 4096 \
  --max-num-seqs 256

# Long context, fewer concurrent sequences
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --max-model-len 32768 \
  --max-num-seqs 32

Mise en cache des préfixes

De nombreuses charges de travail réelles envoient des requêtes qui partagent un préfixe commun : une invite système, un bloc de retrieval RAG ou des tours précédents dans une conversation multi-tours. Sans mise en cache des préfixes, vLLM recalcule le cache KV pour ce préfixe partagé à chaque requête. --enable-prefix-caching stocke les blocs KV calculés dans une table indexée par hachage. Lorsqu’une nouvelle requête arrive avec un préfixe correspondant à un bloc en cache, vLLM réutilise les tenseurs KV en cache au lieu de les recalculer.

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --enable-prefix-caching

La mise en cache des préfixes est particulièrement efficace lorsque :

Chaque requête inclut la même invite système (courant dans les applications de chat et les agents de codage).
Vous utilisez RAG avec un bloc de retrieval fixe préfixé à chaque requête.
Les conversations multi-tours réutilisent les tours précédents comme contexte.

Elle n’apporte aucun bénéfice lorsque chaque requête a un préfixe unique.

La mise en cache des préfixes est activée par défaut dans V1. Vous n’avez besoin du drapeau explicitement que si vous utilisez le mode planificateur V0.

Prefill par morceaux

Le prefill — le traitement de l’invite d’entrée — est intensif en calcul. Une longue invite (8K+ tokens) peut monopoliser le GPU pendant des centaines de millisecondes, bloquant les étapes de décodage pour les autres séquences et provoquant des pics de latence. Le chunked prefill divise le prefill en plus petits morceaux entrelacés avec des étapes de décodage. Le GPU traite un morceau de l’invite, puis exécute une étape de décodage pour les autres séquences actives, puis continue avec le morceau de prefill suivant. Cela rend la latence de décodage prévisible. Dans V1, le chunked prefill est activé par défaut. Vous pouvez contrôler la taille des morceaux :

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --max-num-batched-tokens 8192

--max-num-batched-tokens définit le nombre maximum de tokens traités en une seule étape du planificateur. Des valeurs plus basses réduisent l’impact du prefill sur la latence de décodage mais augmentent le temps total jusqu’au premier token (TTFT). Des valeurs plus élevées améliorent le débit de prefill au prix d’un jitter occasionnel du décodage.

Si vous avez désactivé le chunked prefill dans une ancienne version de vLLM et que vous passez à V1, supprimez le drapeau --enable-chunked-prefill — il est toujours actif dans V1 et le drapeau est ignoré.

Service LoRA

vLLM peut servir plusieurs adaptateurs LoRA depuis un seul processus sans les fusionner dans le modèle de base. Cela vous permet d’exécuter un modèle de base et de router les requêtes vers différentes variantes fine-tunées — par exemple, un adaptateur de codage, un adaptateur de résumé et un adaptateur de chat général — tous partageant les mêmes poids de base en mémoire GPU.

Activer le service LoRA

vllm serve meta-llama/Llama-3.1-8B \
  --enable-lora \
  --lora-modules \
    coder=./lora-adapter-coder \
    summarizer=./lora-adapter-summarizer

Chaque entrée dans --lora-modules associe un nom visible par les requêtes à un chemin local. Les clients sélectionnent l’adaptateur dans le champ model :

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "coder",
    "messages": [
      { "role": "user", "content": "Write a Python function that sorts a list." }
    ]
  }'

Chargement dynamique

vLLM prend en charge le chargement dynamique de LoRA — vous pouvez ajouter ou supprimer des adaptateurs au runtime via l’API sans redémarrer le serveur. C’est utile lorsque vous avez de nombreux adaptateurs mais que seuls quelques-uns sont actifs à un moment donné.

# Load a new adapter at runtime
curl http://localhost:8000/v1/load_lora_adapter \
  -H "Content-Type: application/json" \
  -d '{
    "lora_name": "translator",
    "lora_path": "./lora-adapter-translator"
  }'

Utilisez --max-lora-rank pour limiter le rang des adaptateurs LoRA acceptés par le serveur. Les adaptateurs de rang inférieur utilisent moins de mémoire. Si tous vos adaptateurs partagent le même rang, réglez cette valeur sur ce rang pour éviter de sur-allouer de la mémoire pour une capacité inutilisée.

Options de quantification

La quantification réduit la précision des poids du modèle en dessous de 16 bits, échangeant une petite quantité de précision contre des gains significatifs en mémoire et en vitesse. vLLM prend en charge plusieurs formats de quantification :

Format	Précision	Matériel	Idéal pour
AWQ	4-bit integer	Tout GPU	Quantification 4 bits à usage général. Bonne rétention de précision. Modèles pré-quantifiés largement disponibles sur Hugging Face.
GPTQ	4-bit integer	Tout GPU	Format plus ancien, similaire à AWQ. Préférez AWQ pour les nouvelles quantifications — GPTQ reste pour la compatibilité avec les modèles existants.
FP8	8-bit float	Ampere+ (A100, H100, L40, RTX 4090)	Précision proche de FP16 avec la moitié de la mémoire. Bon choix par défaut quand votre GPU le prend en charge.
NVFP4	4-bit float	Blackwell (B200, GB200, RTX 5090)	Format le plus récent. Économies de mémoire maximales sur le matériel Blackwell.

Utiliser des modèles quantifiés

Pour les modèles pré-quantifiés, vLLM détecte automatiquement le format depuis le config.json du modèle :

# AWQ model — auto-detected
vllm serve TheBloke/Llama-2-7B-Chat-AWQ

# FP8 model — auto-detected on Ampere+ GPUs
vllm serve neuralmagic/Meta-Llama-3.1-8B-Instruct-FP8

Le raccourci FP8 a changé dans v0.31. L’identifiant de quantification FP8 est maintenant fp8_per_tensor. Si vous passez --quantization fp8 explicitement dans un script ou un pipeline CI, mettez-le à jour vers le nouvel identifiant. Les modèles avec FP8 dans leur config.json ne sont pas affectés — l’auto-détection fonctionne toujours.

Quantification en ligne

Vous pouvez aussi quantifier un modèle à la volée pendant le chargement, bien que les modèles pré-quantifiés soient préférés pour la production :

vllm serve meta-llama/Llama-3.1-70B \
  --quantization awq

Débit vs latence

Votre stratégie d’optimisation dépend de si vous privilégiez le débit (total de tokens par seconde pour toutes les requêtes) ou la latence (temps jusqu’au premier token et latence inter-tokens pour les requêtes individuelles).

Maximiser le débit

Augmentez les tailles de lot pour packer plus de travail par étape GPU :

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --max-num-seqs 256 \
  --max-num-batched-tokens 16384 \
  --enable-prefix-caching \
  --kv-cache-dtype fp8

--max-num-seqs 256 permet jusqu’à 256 séquences simultanées dans un lot.
--max-num-batched-tokens 16384 permet plus de tokens par étape du planificateur.
--kv-cache-dtype fp8 libère de la mémoire pour plus de séquences.

Minimiser la latence

Réduisez les tailles de lot et désactivez les optimisations qui échangent la latence contre le débit :

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --max-num-seqs 16 \
  --max-num-batched-tokens 4096 \
  --enforce-eager

--max-num-seqs 16 garde les lots petits pour que chaque requête obtienne du temps GPU plus rapidement.
--enforce-eager désactive les graphes CUDA. Les graphes CUDA capturent et rejouent un graphe de calcul fixe, ce qui améliore le débit mais ajoute de la latence au premier lancement de chaque nouvelle forme de lot. Utilisez --enforce-eager pour le débogage ou quand chaque milliseconde de TTFT compte.

Pour les applications interactives où les utilisateurs attendent une réponse, visez un TTFT inférieur à 500ms. Commencez avec --max-num-seqs 32 et --max-num-batched-tokens 4096, puis ajustez en fonction de votre TTFT mesuré sous charge.

Changements de l’architecture V1

V1 est le planificateur par défaut dans vLLM v0.31.0. Si vous utilisiez vLLM auparavant, voici ce qui a changé : Nouveau planificateur. Le planificateur V1 remplace le gestionnaire de blocs V0 par un gestionnaire de mémoire unifié qui gère le cache KV, la mise en cache des préfixes et le chunked prefill en une seule passe. Cela réduit la surcharge de planification et élimine plusieurs cas limites où V0 pouvait fragmenter la mémoire GPU. Le chunked prefill est le mode par défaut. Le prefill et le décodage sont entrelacés automatiquement. Vous n’avez plus besoin de --enable-chunked-prefill — il est toujours actif. Meilleure gestion de la mémoire. V1 suit la mémoire GPU avec une granularité plus fine, réduisant l’espace gaspillé par le padding et l’alignement. Attendez-vous à 5-15% de cache KV utilisable en plus sur le même matériel par rapport à V0. Améliorations des graphes CUDA. V1 capture les graphes CUDA de manière plus agressive sur une plus large gamme de formes de lot, améliorant le débit sans réglage manuel.

Si vous rencontrez une régression avec V1, vous pouvez revenir à V0 en définissant la variable d’environnement VLLM_USE_V1=0 avant de démarrer le serveur. Signalez le problème à l’équipe vLLM — V0 ne recevra pas de nouvelles fonctionnalités.

Nouveau dans v0.31 : cache de poids persistant et snapshots

vLLM v0.31 introduit 2 nouvelles commandes CLI :

vllm preload démarre un démon de cache de poids persistant qui maintient les poids du modèle en mémoire GPU entre les redémarrages du serveur. Au lieu de recharger un modèle de plusieurs gigaoctets depuis le disque à chaque redémarrage, le serveur se connecte au démon et réutilise les poids en cache. Cela réduit le temps de démarrage à froid de plusieurs minutes à quelques secondes.
vllm snapshot create capture l’état actuel du serveur (modèle chargé, adaptateurs, configuration) et vllm snapshot restore le restaure instantanément. Utile pour revenir en arrière après un mauvais changement de configuration ou pour répliquer une configuration connue comme fonctionnelle entre machines.

# Start the weight-cache daemon
vllm preload meta-llama/Llama-3.1-8B-Instruct

# Create a snapshot of the current state
vllm snapshot create my-production-config

# Restore it on another machine
vllm snapshot restore my-production-config

Changements incompatibles dans v0.31

--trust-request-mm-kwargs est maintenant requis quand les clients envoient des entrées multimodales (images, audio) via le corps de la requête. Sans ce drapeau, vLLM rejette les kwargs multimodaux pour des raisons de sécurité. Ajoutez-le si votre application envoie des images ou d’autres médias dans les requêtes API.
--grpc active le service gRPC en parallèle du serveur HTTP. Si vous utilisez des clients gRPC, démarrez vLLM avec ce drapeau pour exposer le point de terminaison gRPC.

Configurations exemples

Traitement par lots à haut débit

Pour les charges de travail de traitement par lots hors ligne où le total de tokens par seconde compte plus que la latence de chaque requête individuelle :

vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --tensor-parallel-size 4 \
  --kv-cache-dtype fp8 \
  --enable-prefix-caching \
  --max-num-seqs 512 \
  --max-num-batched-tokens 32768 \
  --max-model-len 8192

Cette configuration maximise la concurrence sur un setup à 4 GPU. Le cache KV équivalent à 4 bits et les limites de lot élevées poussent le débit au détriment d’une latence par requête plus longue.

Service interactif à faible latence

Pour les applications de chat où les utilisateurs attendent des réponses et le TTFT doit être inférieur à 500ms :

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --kv-cache-dtype fp8 \
  --enable-prefix-caching \
  --max-num-seqs 32 \
  --max-num-batched-tokens 4096 \
  --max-model-len 8192

Des tailles de lot petites et des limites de tokens modérées gardent le GPU réactif. La mise en cache des préfixes accélère les invites système répétées sans ajouter de latence.

Service LoRA multi-adaptateurs

Pour servir plusieurs variantes fine-tunées depuis un modèle de base unique :

vllm serve meta-llama/Llama-3.1-8B \
  --enable-lora \
  --lora-modules \
    coder=./adapters/coder \
    reviewer=./adapters/reviewer \
    summarizer=./adapters/summarizer \
  --max-lora-rank 64 \
  --kv-cache-dtype fp8 \
  --enable-prefix-caching \
  --max-num-seqs 128

Les clients sélectionnent l’adaptateur par nom dans le champ model. Les 3 adaptateurs partagent les mêmes poids du modèle de base, donc l’utilisation de la mémoire GPU est proche de servir le modèle de base seul — chaque adaptateur LoRA n’ajoute que quelques mégaoctets.

Après avoir modifié la configuration de vLLM, ré-enregistrez votre déploiement Tokios pour que le connecteur récupère le nouveau point de terminaison upstream. Voir Register Model.

Matériel et compatibilité

Servir et connecter votre runtime

Connecter un client ou une app

Comparer

Optimisez vLLM pour le débit et la latence

Réglage du cache KV

Formule de dimensionnement

Utiliser un cache KV fp8

`--max-num-seqs` vs `--max-model-len`

Mise en cache des préfixes

Prefill par morceaux

Service LoRA

Activer le service LoRA

Chargement dynamique

Options de quantification

Utiliser des modèles quantifiés

Quantification en ligne

Débit vs latence

Maximiser le débit

Minimiser la latence

Changements de l’architecture V1

Nouveau dans v0.31 : cache de poids persistant et snapshots

Changements incompatibles dans v0.31

Configurations exemples

Traitement par lots à haut débit

Service interactif à faible latence

Service LoRA multi-adaptateurs

​Réglage du cache KV

​Formule de dimensionnement

​Utiliser un cache KV fp8

​--max-num-seqs vs --max-model-len

​Mise en cache des préfixes

​Prefill par morceaux

​Service LoRA

​Activer le service LoRA

​Chargement dynamique

​Options de quantification

​Utiliser des modèles quantifiés

​Quantification en ligne

​Débit vs latence

​Maximiser le débit

​Minimiser la latence

​Changements de l’architecture V1

​Nouveau dans v0.31 : cache de poids persistant et snapshots

​Changements incompatibles dans v0.31

​Configurations exemples

​Traitement par lots à haut débit

​Service interactif à faible latence

​Service LoRA multi-adaptateurs

Réglage du cache KV

Formule de dimensionnement

Utiliser un cache KV fp8

`--max-num-seqs` vs `--max-model-len`

Mise en cache des préfixes

Prefill par morceaux

Service LoRA

Activer le service LoRA

Chargement dynamique

Options de quantification

Utiliser des modèles quantifiés

Quantification en ligne

Débit vs latence

Maximiser le débit

Minimiser la latence

Changements de l’architecture V1

Nouveau dans v0.31 : cache de poids persistant et snapshots

Changements incompatibles dans v0.31

Configurations exemples

Traitement par lots à haut débit

Service interactif à faible latence

Service LoRA multi-adaptateurs