Démarrage rapide de vLLM : service de LLM haute performance en 2026

vLLM est un moteur d’inférence et de service à haut débit et économe en mémoire pour les modèles de langage de grande taille (LLM), développé par le laboratoire Sky Computing de l’Université de Californie à Berkeley.

Son algorithme PagedAttention traite le cache KV comme des pages de mémoire virtuelle du système d’exploitation et l’associe à l’approvisionnement par lots continus (continuous batching) — la combinaison qui a fait de vLLM le moteur par défaut pour le service de LLM en production. Pour découvrir comment vLLM se positionne par rapport à Ollama, Docker Model Runner, LocalAI et aux fournisseurs cloud — y compris les compromis en termes de coûts et d’infrastructure —, consultez Hébergement LLM : Comparaison des infrastructures locales, auto-hébergées et cloud.

Ce guide est à jour à la version vLLM v0.31.0 (octobre 2026). Deux éléments ont récemment changé si vous arrivez depuis de plus anciens tutoriels : python -m vllm.entrypoints.openai.api_server est déprécié et affiche un avertissement — vllm serve est désormais l’interface en ligne de commande standard — et les roues précompilées ciblent par défaut la version CUDA 12.9, et non 11.8.

Qu’est-ce que vLLM ?

vLLM (LLM virtuel) est une bibliothèque open source pour l’inférence et le service rapides de LLM qui est rapidement devenue le standard de l’industrie pour les déploiements en production. Publiée en 2023, elle a introduit PagedAttention, une technique de gestion de la mémoire révolutionnaire qui améliore considérablement l’efficacité du service.

Fonctionnalités clés

Performances à haut débit : Les benchmarks de l’époque du lancement de vLLM rapportaient un débit 14 à 24 fois supérieur à celui de HuggingFace Transformers sur le même matériel, et le moteur a maintenu cette avance grâce à l’approvisionnement par lots continus, aux noyaux CUDA optimisés et à l’algorithme PagedAttention qui élimine la fragmentation de la mémoire.

Compatibilité avec l’API OpenAI : vLLM inclut un serveur API intégré entièrement compatible avec le format d’OpenAI. Cela permet une migration transparente d’OpenAI vers une infrastructure auto-hébergée sans modifier le code de l’application. Il suffit de rediriger votre client API vers le point d’accès de vLLM et cela fonctionne sans problème.

Algorithme PagedAttention : L’innovation centrale derrière les performances de vLLM est PagedAttention, qui applique le concept de pagination de la mémoire virtuelle aux mécanismes d’attention. Au lieu d’allouer des blocs de mémoire contigus pour les caches KV (ce qui entraîne une fragmentation), PagedAttention divise la mémoire en blocs de taille fixe qui peuvent être alloués à la demande. Cela réduit le gaspillage de mémoire jusqu’à 4 fois et permet des tailles de lot beaucoup plus grandes.

Approvisionnement par lots continus : Contrairement aux approvisionnements par lots statiques où l’on attend la fin de toutes les séquences, vLLM utilise un approvisionnement par lots continus (glissants). Dès qu’une séquence est terminée, une nouvelle peut être ajoutée au lot. Cela maximise l’utilisation du GPU et minimise la latence pour les entrantes requêtes.

Prise en charge multi-GPU : vLLM prend en charge le parallélisme par tenseurs et le parallélisme par pipeline pour répartir les grands modèles sur plusieurs GPU. Il peut servir efficacement des modèles qui ne tiennent pas dans la mémoire d’un seul GPU, prenant en charge des configurations allant de 2 à 8 GPU ou plus.

Large prise en charge des modèles : Compatible avec des architectures de modèles populaires, notamment LLaMA, Mistral, Mixtral, Qwen, Phi, Gemma, et bien d’autres. Prend en charge à la fois les modèles ajustés pour les instructions et les modèles de base provenant du HuggingFace Hub.

Quand utiliser vLLM

vLLM excelle dans des scénarios spécifiques où ses forces se démarquent :

Services API en production : Lorsque vous avez besoin de servir un LLM à de nombreux utilisateurs simultanés via une API, le haut débit et l’approvisionnement par lots efficaces de vLLM en font le meilleur choix. Les entreprises qui exploitent des chatbots, des assistants de code ou des services de génération de contenu bénéficient de sa capacité à traiter des centaines de requêtes par seconde.

Charge de travail à forte concurrence : Si votre application a de nombreux utilisateurs simultanés effectuant des requêtes, l’approvisionnement par lots continus et PagedAttention de vLLM permettent de servir plus d’utilisateurs avec le même matériel par rapport aux alternatives.

Optimisation des coûts : Lorsque les coûts des GPU sont un enjeu, le débit supérieur de vLLM signifie que vous pouvez servir le même trafic avec moins de GPU, réduisant directement les coûts d’infrastructure. L’efficacité mémoire 4 fois supérieure de PagedAttention permet également d’utiliser des instances GPU plus petites et moins chères.

Déploiements Kubernetes : La conception sans état et l’architecture conviviale pour les conteneurs de vLLM en font un choix idéal pour les clusters Kubernetes. Ses performances constantes sous charge et sa gestion simple des ressources s’intègrent bien à l’infrastructure cloud-native.

Quand ne PAS utiliser vLLM : Pour le développement local, l’expérimentation ou les scénarios à utilisateur unique, des outils comme Ollama ou llama.cpp offrent une meilleure expérience utilisateur avec un paramétrage plus simple. La complexité de vLLM se justifie lorsque vous avez besoin de ses avantages en termes de performances pour des charge de travail en production.

Comment installer vLLM

Prérequis

Avant d’installer vLLM, assurez-vous que votre système remplit ces exigences :

• OS : Linux avec glibc 2.35 ou plus récent (Ubuntu 22.04+, Debian 12+, RHEL 9+)
• GPU : GPU NVIDIA avec une capacité de calcul 7.5 ou supérieure (T4, A10, A100, L4, H100, B200, séries RTX 20/30/40/50). Les cartes de la génération 7.0 plus anciennes, telles que la V100, ne figurent plus dans la liste des éléments pris en charge. Les GPU AMD sont pris en charge via des roues ROCm séparées — voir ROCm vs Vulkan pour l’hébergement local de LLM sur AMD pour l’image spécifique à AMD, les drapeaux de périphérique et les avertissements concernant la couverture des noyaux.
• CUDA : Les roues pip par défaut sont compilées contre CUDA 12.9 ; les variantes 12.8 et 13.0 sont publiées aux côtés de celles-ci. Les GPU Blackwell (B200, GB200) nécessitent CUDA 12.8 ou supérieur. Votre pilote NVIDIA doit être suffisamment récent pour la version de CUDA que vous installez.
• Python : 3.10 à 3.13 — la version 3.12 est recommandée (les roues ROCm sont exclusives à la version 3.12)
• Mémoire vidéo (VRAM) : Minimum 16 Go pour les modèles 7B, 24 Go ou plus pour les 13B, 40 Go ou plus pour les modèles plus grands

Installation via pip

L’installation recommandée utilise uv pour créer un environnement Python 3.12 et sélectionner automatiquement le backend PyTorch CUDA correspondant (--torch-backend=auto inspecte le pilote installé). Pour un regard plus approfondi sur uv lui-même, consultez uv : Le nouvel outil de gestion de projets et d’environnements Python:

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

# Vérifier l'installation
python -c "import vllm; print(vllm.__version__)"

Le simple pip fonctionne aussi :

python3 -m venv vllm-env
source vllm-env/bin/activate
pip install vllm

Les roues par défaut sont compilées contre CUDA 12.9. Si vous avez besoin d’une version différente de CUDA, récupérez l’index de roues PyTorch correspondant — par exemple, CUDA 12.8 :

pip install vllm --extra-index-url https://download.pytorch.org/whl/cu128

Les anciennes roues épinglées telles que vllm==0.4.2+cu121 n’existent plus sous cette forme. Mélanger vLLM dans un environnement existant avec une build PyTorch différente est une source courante d’échecs d’installation ; le projet recommande un environnement neuf, et une compilation depuis les sources si vous avez besoin d’une cible CUDA personnalisée.

Installation avec Docker

Docker fournit la méthode de déploiement la plus fiable, en particulier pour la production. Épinglez l’image à une version de publication au lieu de latest pour que les mises à niveau soient délibérées, et notez que des images variantes existent pour CUDA 12.9 (suffixe de balise -cu129), AMD ROCm (vllm-openai-rocm), CPU (vllm-openai-cpu) et Intel XPU (vllm-openai-xpu) :

# Récupérer l'image officielle vLLM
docker pull vllm/vllm-openai:v0.31.0

# Exécuter vLLM avec la prise en charge du GPU
docker run --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:v0.31.0 \
    --model Qwen/Qwen3-8B

Le drapeau --ipc=host est important pour les configurations multi-GPU car il permet une communication inter-processus appropriée.

Compilation depuis les sources

Pour les fonctionnalités les plus récentes ou des modifications personnalisées, compilez depuis les sources :

git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .

Guide de démarrage rapide vLLM

Exécution de votre premier modèle

Démarrez vLLM avec un modèle en utilisant l’interface en ligne de commande :

# Télécharger et servir un modèle avec l'API compatible OpenAI
vllm serve Qwen/Qwen3-8B \
    --port 8000

vllm serve est l’interface en ligne de commande actuelle pour le serveur compatible OpenAI. L’ancienne invocation python -m vllm.entrypoints.openai.api_server fonctionne toujours mais affiche un avertissement de dépréciation et pourrait être supprimé dans une future version, alors mettez à jour tous les scripts ou les manifests Kubernetes qui l’utilisent encore.

vLLM téléchargera automatiquement le modèle depuis HuggingFace Hub (s’il n’est pas mis en cache) et démarrera le serveur. Vous verrez une sortie indiquant que le serveur est prêt :

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

Envoi de requêtes API

Une fois le serveur en cours d’exécution, vous pouvez effectuer des requêtes à l’aide du client Python OpenAI ou curl :

En utilisant curl :

curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen3-8B",
        "prompt": "Explain what vLLM is in one sentence:",
        "max_tokens": 100,
        "temperature": 0.7
    }'

En utilisant le client Python OpenAI :

from openai import OpenAI

# Pointer vers votre serveur vLLM
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"  # vLLM ignore ceci à moins que vous ne démarriez le serveur avec --api-key
)

response = client.completions.create(
    model="Qwen/Qwen3-8B",
    prompt="Explain what vLLM is in one sentence:",
    max_tokens=100,
    temperature=0.7
)

print(response.choices[0].text)

API des complétions de chat :

response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is PagedAttention?"}
    ],
    max_tokens=200
)

print(response.choices[0].message.content)

Configuration avancée

vLLM offre de nombreux paramètres pour optimiser les performances :

vllm serve Qwen/Qwen3-8B \
    --port 8000 \
    --gpu-memory-utilization 0.95 \  # Utiliser 95 % de la mémoire du GPU
    --max-model-len 32k \            # Longueur de séquence maximale (8192 et 32k fonctionnent tous les deux)
    --tensor-parallel-size 2 \       # Utiliser 2 GPU avec le parallélisme par tenseurs
    --dtype float16 \                # Utiliser la précision FP16
    --max-num-seqs 256               # Taille de lot maximale

Paramètres clés expliqués :

• --gpu-memory-utilization : Fraction de la mémoire du GPU pour l’interpréteur de modèle (par défaut 0.92). Des valeurs plus élevées permettent des lots plus grands mais laissent moins de marge pour les pics de mémoire.
• --max-model-len : Longueur de contexte maximale. Accepte des comptes de jetons ou des valeurs lisibles par l’homme comme 32k. Réduire cela libère de la mémoire pour des lots plus grands.
• --tensor-parallel-size : Nombre de GPU sur lesquels diviser le modèle.
• --dtype : Type de données pour les poids (auto, float16, bfloat16, float32). auto suit le type de données du point de contrôle (checkpoint), ce qui est généralement ce que vous voulez.
• --max-num-seqs : Nombre maximal de séquences dans un lot.
• --max-num-active-seqs : Limite l’admission en cours d’exécution (RUNNING) indépendamment de max_num_seqs (nouveau dans v0.31.0) — utile pour limiter la latence sans réduire la fenêtre de lot de l’ordonnanceur.

vLLM vs Ollama

vLLM est conçu pour le service en production à haut débit, multi-utilisateurs, avec l’approvisionnement par lots continus, PagedAttention et la prise en charge multi-GPU. Ollama optimise pour la configuration locale rapide, la commodité à utilisateur unique et la gestion simple des modèles.

Pour un guide de décision détaillé couvrant les signaux de migration, les étapes de planification, la configuration Docker Compose et une liste de contrôle pratique, consultez D’Ollama à vLLM : Quand migrer votre serveur LLM local.

vLLM vs Docker Model Runner

Le Model Runner de Docker est leur solution officielle pour le déploiement local de modèles d’IA. Comment se compare-t-il à vLLM ?

Philosophie d’architecture

Docker Model Runner vise à être le « Docker pour l’IA » – une manière simple et standardisée d’exécuter des modèles d’IA localement avec la même facilité que l’exécution de conteneurs. Il abstrait la complexité et fournit une interface cohérente entre différents modèles et frameworks.

vLLM est un moteur d’inférence spécialisé axé exclusivement sur le service de LLM avec des performances maximales. C’est un outil de bas niveau que vous conteneurisez avec Docker, plutôt qu’une plateforme complète.

Installation et prise en main

L’installation de Docker Model Runner est simple pour les utilisateurs de Docker :

docker model pull llama3:8b
docker model run llama3:8b

Cette similitude avec le flux de travail d’images de Docker le rend immédiatement familier aux développeurs qui utilisent déjà des conteneurs ; l’ensemble des commandes se trouve dans la fiche récapitulative Docker Model Runner.

vLLM nécessite plus de configuration initiale (Python, CUDA, dépendances) ou l’utilisation d’images Docker préconstruites :

docker pull vllm/vllm-openai:latest
docker run --runtime nvidia --gpus all vllm/vllm-openai:latest --model <model-name>

Caractéristiques de performance

vLLM offre un débit supérieur pour les scénarios multi-utilisateurs grâce à PagedAttention et à l’approvisionnement par lots continus. Pour les services API en production traitant des centaines de requêtes par seconde, les optimisations de vLLM offrent un débit 2 à 5 fois meilleur que les approches de service génériques.

Docker Model Runner se concentre sur la facilité d’utilisation plutôt que sur les performances maximales. Il convient au développement local, aux tests et aux charges de travail modérées, mais n’implémente pas les optimisations avancées qui font exceller vLLM à grande échelle.

Prise en charge des modèles

Docker Model Runner fournit une bibliothèque de modèles soigneusement sélectionnée avec un accès en une commande à des modèles populaires. Il prend en charge plusieurs frameworks (pas seulement des LLM), notamment Stable Diffusion, Whisper et d’autres modèles d’IA, ce qui le rend plus polyvalent pour différentes charges de travail d’IA.

vLLM se spécialise dans l’inférence de LLM avec un soutien approfondi pour les modèles de langage basés sur les transformeurs. Il prend en charge tout LLM compatible HuggingFace, mais ne s’étend pas à d’autres types de modèles d’IA comme la génération d’images ou la reconnaissance vocale.

Déploiement en production

vLLM est éprouvé en production dans des entreprises comme Anthropic, Replicate, et bien d’autres, servant des milliards de jetons quotidiennement. Ses caractéristiques de performance et sa stabilité sous forte charge en font la norme de fait pour le service de LLM en production.

Docker Model Runner est plus récent et se positionne davantage pour les scénarios de développement et de tests locaux. Bien qu’il puisse servir du trafic en production, il manque de l’historique éprouvé et des optimisations de performance que les déploiements en production exigent.

Écosystème d’intégration

vLLM s’intègre avec des outils d’infrastructure de production : opérateurs Kubernetes, métriques Prometheus, Ray pour le service distribué, et une compatibilité étendue avec l’API OpenAI pour les applications existantes.

Docker Model Runner s’intègre naturellement à l’écosystème de Docker et à Docker Desktop. Pour les équipes déjà standardisées sur Docker, cette intégration offre une expérience cohérente, mais avec moins de fonctionnalités spécialisées pour le service de LLM.

Quand utiliser chacun

Utiliser vLLM pour :

• Les services API de LLM en production
• Les déploiements à haut débit, multi-utilisateurs
• Les déploiements cloud sensibles aux coûts nécessitant l’efficacité maximale
• Les environnements Kubernetes et cloud-native
• Lorsque vous avez besoin d’une évolutivité et de performances éprouvées

Utiliser Docker Model Runner pour :

• Le développement et les tests locaux
• L’exécution de divers types de modèles d’IA (pas seulement des LLM)
• Les équipes fortement investies dans l’écosystème Docker
• Les expérimentations rapides sans configuration d’infrastructure
• Les objectifs d’apprentissage et éducatifs

Approche hybride : De nombreuses équipes développent avec Docker Model Runner localement pour la commodité, puis déploient avec vLLM en production pour la performance. Les images Docker Model Runner peuvent également être utilisées pour exécuter des conteneurs vLLM, combinant ainsi les deux approches.

Bonnes pratiques de déploiement en production

Déploiement Docker

Créez une configuration Docker Compose prête pour la production :

version: '3.8'

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - CUDA_VISIBLE_DEVICES=0,1
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
      - ./logs:/logs
    ports:
      - "8000:8000"
    command: >
      --model Qwen/Qwen3-8B
      --tensor-parallel-size 2
      --gpu-memory-utilization 0.90
      --max-num-seqs 256
      --max-model-len 8192
    restart: unless-stopped
    shm_size: '16gb'
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 2
              capabilities: [gpu]

Déploiement Kubernetes

Déployez vLLM sur Kubernetes à l’échelle de la production :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: vllm
  template:
    metadata:
      labels:
        app: vllm
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args:
          - --model
          - Qwen/Qwen3-8B
          - --tensor-parallel-size
          - "2"
          - --gpu-memory-utilization
          - "0.90"
        resources:
          limits:
            nvidia.com/gpu: 2
        ports:
        - containerPort: 8000
        volumeMounts:
        - name: cache
          mountPath: /root/.cache/huggingface
      volumes:
      - name: cache
        hostPath:
          path: /mnt/huggingface-cache
---
apiVersion: v1
kind: Service
metadata:
  name: vllm-service
spec:
  selector:
    app: vllm
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

Supervision et observabilité

Le serveur compatible OpenAI expose des métriques Prometheus sur /metrics par défaut — aucun drapeau supplémentaire n’est nécessaire :

curl -s http://localhost:8000/metrics | grep '^vllm:'

Métriques clés à surveiller :

• vllm:num_requests_running / vllm:num_requests_waiting / vllm:num_requests_swapped — requêtes dans les états d’ordonnancement RUNNING, WAITING et SWAPPED
• vllm:kv_cache_usage_perc — fraction de blocs du cache KV utilisés (0–1)
• vllm:time_to_first_token_seconds — histogramme du TTFT (Time To First Token)
• vllm:time_per_output_token_seconds — vitesse de génération par jeton
• vllm:num_preemptions_total — préemptions cumulées ; un compteur croissant signifie que le cache KV est suralloué et que les requêtes sont recalculées

Pour les tableaux de bord, les exemples PromQL et les seuils d’alerte autour du service de LLM, consultez Surveiller l’inférence LLM en production (2026) : Prometheus & Grafana pour vLLM, TGI, llama.cpp.

Réglage des performances

Optimiser l’utilisation de la mémoire GPU : La valeur par défaut est 0.92 ; ajustez-la en fonction du comportement observé. Des valeurs plus élevées permettent des lots plus grands mais risquent des erreurs de mémoire insuffisante (OOM) lors des pics de trafic.

Ajuster la longueur maximale de séquence : Si votre cas d’utilisation n’a pas besoin de la longueur de contexte complète, réduisez --max-model-len. Cela libère de la mémoire pour des lots plus grands. Par exemple, si vous n’avez besoin que d’un contexte de 4K, réglez --max-model-len 4096 au lieu d’utiliser la valeur maximale du modèle (souvent 8K-32K).

Choisir une quantification appropriée : Pour les modèles qui la prennent en charge, utilisez des versions quantifiées (8 bits, 4 bits) pour réduire la mémoire et augmenter le débit :

--quantization awq  # Pour les modèles quantifiés AWQ
--quantization gptq # Pour les modèles quantifiés GPTQ

Cache de préfixes : Le cache de préfixes est activé par défaut dans le moteur actuel, de sorte que les requêtes partageant un préfixe de prompt (un prompt système fixe, un modèle de contexte RAG) réutilisent son cache KV sans aucun drapeau. Désactivez-le avec --no-enable-prefix-caching pour les charge de travail avec de nombreux prompts longs uniques où le suivi du cache n’apporte rien.

Dépannage des problèmes courants

Erreurs de mémoire insuffisante (Out of Memory)

Symptômes : Le serveur s’arrête avec des erreurs CUDA de mémoire insuffisante.

Solutions :

• Réduire --gpu-memory-utilization à 0.85 ou 0.80
• Diminuer --max-model-len si votre cas d’utilisation le permet
• Baisser --max-num-seqs pour réduire la taille du lot
• Utiliser une version quantifiée du modèle
• Activer le parallélisme par tenseurs pour répartir sur plus de GPU

Deux formes distinctes d’erreurs OOM nécessitent des correctifs différents. Un OOM au démarrage se produit avant toute requête : vLLM profile la mémoire et échoue à allouer même le cache KV minimal, donc baisser --max-num-seqs n’aide pas — réduisez --max-model-len ou augmentez --gpu-memory-utilization si vous avez de la marge. Un OOM en cours d’exécution sous charge peut provenir de la mémoire de capture de graphes CUDA, qui évolue avec --max-num-seqs mais se situe en dehors de la comptabilité du cache KV ; exécutez une fois avec --enforce-eager pour vérifier si les graphes CUDA sont la mémoire manquante, et retestez la configuration exacte la même avant de blâmer le cache. Si les démarrages sur un matériel identique continuent de réussir avec la même allocation, passez la valeur de --kv-cache-memory-bytes que vLLM journalise au démarrage pour passer l’étape de profilage lors des démarrages suivants.

Sur une carte de 16 Go unique, la plupart de ces erreurs OOM se rattachent au budget du cache KV plutôt qu’aux poids seuls — Cache KV sur GPU 16 Go couvre la formule exacte, le type de données KV-cache FP8 et les compromis du cache de préfixes derrière --max-model-len et --max-num-seqs avant de recourir à un modèle plus petit.

Démarrage lent

Symptômes : Le serveur met des minutes entre le lancement et « Application startup complete ».

Solutions :

• Le chargement des poids, la compilation et la capture des graphes CUDA dominent le démarrage — --enforce-eager saute à la fois la compilation et la capture et vous indique combien de démarrage ils coûtent, au prix de la vitesse de décodage en régime permanent
• Réutilisez la valeur de --kv-cache-memory-bytes journalisée pour passer les étapes de profilage de la mémoire et d’estimation des graphes CUDA lors des démarrages répétés
• Sur v0.30.0+, la commande vllm preload exécute un démon de cache de poids persistant qui maintient les poids post-quantification résidents dans la mémoire du GPU, de sorte que les redémarrages du moteur cartographient les poids via l’IPC CUDA au lieu de les recharger depuis le disque (--load-format ipc_cache)
• Pour les points de contrôle NVFP4 qui déclenchent un OOM pendant la compilation au démarrage, limiter les threads de compilation avec MAX_JOBS=4 et NVCC_THREADS=4 est un correctif largement utilisé — il ralentit la compilation JIT mais stoppe l’OOM

Faible débit

Symptômes : Le serveur traite moins de requêtes que prévu.

Solutions :

• Augmenter --max-num-seqs pour permettre des lots plus grands
• Augmenter --gpu-memory-utilization si vous avez de la marge
• Vérifier si le CPU est le goulot d’étranglement avec htop – envisager des CPU plus rapides
• Vérifier l’utilisation du GPU avec nvidia-smi – devrait être de 95 % ou plus
• Activer FP16 si vous utilisez FP32 : --dtype float16

Latence élevée avant le premier jeton

Symptômes : Latence élevée avant le début de la génération.

Solutions :

• Utiliser des modèles plus petits pour les applications sensibles à la latence
• Le cache de préfixes est activé par défaut — vérifiez qu’il est actif plutôt que de réajouter le drapeau
• Réduire --max-num-seqs pour privilégier la latence par rapport au débit
• Envisager le décodage spéculatif pour les modèles pris en charge
• Optimiser la configuration du parallélisme par tenseurs

Échecs de chargement du modèle

Symptômes : Le serveur échoue à démarrer, ne peut pas charger le modèle.

Solutions :

• Vérifier que le nom du modèle correspond exactement au format HuggingFace
• Vérifier la connectivité réseau vers HuggingFace Hub
• S’assurer que l’espace disque suffisant est disponible dans ~/.cache/huggingface
• Pour les modèles à accès restreint, définir la variable d’environnement HF_TOKEN
• Essayer de télécharger manuellement avec hf download <model> (ou huggingface-cli download <model> sur les installations plus anciennes)

Fonctionnalités avancées

Décodage spéculatif

vLLM prend en charge le décodage spéculatif, où un modèle de brouillon plus petit propose des jetons qu’un modèle cible plus grand vérifie. Cela peut accélérer la génération de 1,5 à 2 fois. Pour un guide complet des méthodes de décodage spéculatif — modèles de brouillon, EAGLE-3, P-EAGLE et n-gram — consultez Décode spéculatif : Inférence plus rapide sans perte de qualité.

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --speculative-config '{"method": "draft_model", "model": "meta-llama/Llama-3.2-1B-Instruct", "num_speculative_tokens": 4}'

Les anciens drapeaux --speculative-model et --num-speculative-tokens ont disparu — la configuration a été déplacée vers le seul argument JSON --speculative-config, qui sélectionne également la méthode (draft_model, ngram, famille EAGLE, ou MTP pour les modèles avec des têtes de prédiction multi-jetons natives).

Adaptateurs LoRA

Servir plusieurs adaptateurs LoRA par-dessus un modèle de base sans charger plusieurs modèles complets :

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --enable-lora \
    --lora-modules sql-lora=/path/to/sql-adapter \
                   code-lora=/path/to/code-adapter

Ensuite, spécifiez quel adaptateur utiliser par requête en plaçant son nom dans le champ model — le même mécanisme s’étend à des dizaines d’adaptateurs spécifiques à une tâche (variantes spécifiques au client ou par domaine) avec seulement le modèle de base résident en mémoire :

response = client.completions.create(
    model="sql-lora",  # Utiliser l'adaptateur SQL
    prompt="Convert this to SQL: Show me all users created this month"
)

Cache de préfixes

Le cache de préfixes évite de recalculer le cache KV pour les préfixes de prompts partagés et est activé par défaut dans le moteur actuel.

C’est le plus rentable pour :

• Les chatbots avec des prompts système fixes
• Les applications RAG avec des modèles de contexte cohérents
• Les prompts d’apprentissage par exemple (few-shot) répétés entre les requêtes

Pour les requêtes partageant un préfixe, le temps avant le premier jeton (time-to-first-token) diminue considérablement parce que la préremplissage (prefill) pour la partie partagée est sautée.

Exemples d’intégration

Intégration LangChain

from langchain_community.llms import VLLMOpenAI

llm = VLLMOpenAI(
    openai_api_key="EMPTY",
    openai_api_base="http://localhost:8000/v1",
    model_name="Qwen/Qwen3-8B",
    max_tokens=512,
    temperature=0.7,
)

response = llm("Explain PagedAttention in simple terms")
print(response)

Application FastAPI

from fastapi import FastAPI
from openai import AsyncOpenAI

app = FastAPI()
client = AsyncOpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"
)

@app.post("/generate")
async def generate(prompt: str):
    response = await client.completions.create(
        model="Qwen/Qwen3-8B",
        prompt=prompt,
        max_tokens=200
    )
    return {"result": response.choices[0].text}

Benchmarks de performance

Les données de performance du monde réel aident à illustrer les avantages de vLLM. Les chiffres ci-dessous proviennent de la documentation de l’époque du lancement du projet et de mesures communautaires précoces — considérez-les comme des indications d’ordre de grandeur de l’effet de l’architecture, et non comme des résultats actuels pour la génération de modèles actuelle :

Comparaison du débit (Mistral-7B sur GPU A100) :

• vLLM : ~3 500 jetons/seconde avec 64 utilisateurs simultanés
• HuggingFace Transformers : ~250 jetons/seconde avec la même concurrence
• Ollama : ~1 200 jetons/seconde avec la même concurrence
• Résultat : vLLM offre une amélioration de 14 fois par rapport aux implémentations de base

Efficacité mémoire (LLaMA-2-13B) :

• Implémentation standard : 24 Go de VRAM, 32 séquences simultanées
• vLLM avec PagedAttention : 24 Go de VRAM, 128 séquences simultanées
• Résultat : 4 fois plus de requêtes simultanées avec la même mémoire

Latence sous charge (Mixtral-8x7B sur 2xA100) :

• vLLM : latence P50 180 ms, latence P99 420 ms à 100 req/s
• Service standard : latence P50 650 ms, latence P99 3 200 ms à 100 req/s
• Résultat : vLLM maintient une latence constante sous forte charge

Analyse des coûts

Comprendre les implications en termes de coûts du choix de vLLM :

Scénario : Servir 1 million de requêtes/jour

Avec un service standard :

• Requis : 8x GPU A100 (80 Go)
• Coût AWS : ~32 $/heure × 24 × 30 = 23 040 $/mois
• Coût par million de jetons : ~0,75 $

Avec vLLM :

• Requis : 2x GPU A100 (80 Go)
• Coût AWS : ~8 $/heure × 24 × 30 = 5 760 $/mois
• Coût par million de jetons : ~0,19 $
• Économies : 17 280 $/mois (réduction de 75 %)

Avantage en coût augmente avec l’échelle. Les organisations servant des milliards de jetons par mois économisent des centaines de milliers de dollars en utilisant le service optimisé de vLLM au lieu des implémentations naïves.

Considérations de sécurité

Authentification

vLLM fournit un drapeau --api-key intégré, mais selon la documentation officielle, il n’authentifie que les points d’accès sous les préfixes de chemin /v1, /v2 et /inference — les autres points d’accès sur le même serveur restent non authentifiés. Traitez-le comme une couche parmi d’autres, pas comme la réponse complète ; pour une couverture complète, implémentez l’authentification au niveau du proxy inverse :

# Configuration Nginx
location /v1/ {
    auth_request /auth;
    proxy_pass http://vllm-backend:8000;
}

location /auth {
    proxy_pass http://auth-service:8080/verify;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

Ou utilisez des passerelles API comme Kong, Traefik, ou AWS API Gateway pour l’authentification et la limitation de débit de niveau entreprise.

Isolation réseau

Exécutez vLLM dans des réseaux privés, pas exposés directement à Internet :

# Exemple de NetworkPolicy Kubernetes
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: vllm-access
spec:
  podSelector:
    matchLabels:
      app: vllm
  policyTypes:
  - Ingress
  ingress:
  - from:
    - podSelector:
        matchLabels:
          role: api-gateway
    ports:
    - protocol: TCP
      port: 8000

Limitation de débit

Implémentez la limitation de débit pour empêcher les abus :

# Exemple utilisant Redis pour la limitation de débit
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
import redis
from datetime import datetime, timedelta

app = FastAPI()
redis_client = redis.Redis(host='localhost', port=6379)

@app.middleware("http")
async def rate_limit_middleware(request, call_next):
    client_ip = request.client.host
    key = f"rate_limit:{client_ip}"
    
    requests = redis_client.incr(key)
    if requests == 1:
        redis_client.expire(key, 60)  # Fenêtre de 60 secondes
    
    if requests > 60:  # 60 requêtes par minute
        raise HTTPException(status_code=429, detail="Rate limit exceeded")
    
    return await call_next(request)

Contrôle d’accès aux modèles

Pour les déploiements multi-locataires, contrôlez quels utilisateurs peuvent accéder à quels modèles :

ALLOWED_MODELS = {
    "user_tier_1": ["Qwen/Qwen3-8B"],
    "user_tier_2": ["Qwen/Qwen3-8B", "meta-llama/Llama-2-13b-chat-hf"],
    "admin": ["*"]  # Tous les modèles
}

def verify_model_access(user_tier: str, model: str) -> bool:
    allowed = ALLOWED_MODELS.get(user_tier, [])
    return "*" in allowed or model in allowed

Guide de migration

D’OpenAI à vLLM

La migration d’OpenAI à vLLM auto-hébergé est simple grâce à la compatibilité de l’API :

Avant (OpenAI) :

from openai import OpenAI

client = OpenAI(api_key="sk-...")
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello"}]
)

Après (vLLM) :

from openai import OpenAI

client = OpenAI(
    base_url="https://your-vllm-server.com/v1",
    api_key="your-internal-key"  # Si vous avez ajouté une authentification
)
response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[{"role": "user", "content": "Hello"}]
)

Seulement deux modifications nécessaires : mettre à jour base_url et le nom du model. Tout le reste du code reste identique.

D’Ollama à vLLM

Ollama utilise un format d’API différent. Le changement de base côté client consiste à passer du point d’accès REST d’Ollama à l’API compatible OpenAI de vLLM :

API Ollama :

import requests

response = requests.post('http://localhost:11434/api/generate',
    json={'model': 'llama2', 'prompt': 'Why is the sky blue?'})

Équivalent vLLM :

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
response = client.completions.create(
    model="meta-llama/Llama-2-7b-chat-hf",
    prompt="Why is the sky blue?"
)

L’API Ollama est du REST pur avec sa propre forme de requête, tandis que vLLM utilise le protocole OpenAI — cette différence de format d’API est le principal changement côté client, et l’approche progressive (faire tourner les deux serveurs, déplacer le trafic point d’accès par point d’accès) est couverte dans le guide de migration lié plus tôt dans cet article.

De HuggingFace Transformers à vLLM

Migration d’utilisation Python directe :

HuggingFace :

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-8B")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B")

inputs = tokenizer("Hello", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=100)
result = tokenizer.decode(outputs[0])

vLLM :

from vllm import LLM, SamplingParams

llm = LLM(model="Qwen/Qwen3-8B")
sampling_params = SamplingParams(max_tokens=100)

outputs = llm.generate("Hello", sampling_params)
result = outputs[0].outputs[0].text

L’API Python de vLLM est plus simple et beaucoup plus rapide pour l’inférence par lots.

Versions récentes : Ce qui a changé en 2026

Trois versions en septembre-octobre 2026 (v0.29.0, v0.30.0, v0.31.0) montrent vers où se dirige le développement :

Redémarrages rapides : vllm preload lance un démon de cache de poids persistant par GPU qui maintient les poids post-quantification, fractionnés en TP, résidents dans la mémoire du GPU, de sorte que les moteurs redémarrés les cartographient via l’IPC CUDA (--load-format ipc_cache) au lieu de les recharger depuis le disque. Les instantanés vllm snapshot create/restore expérimentaux capturent un moteur entièrement initialisé avec CRIU.

Décodage spéculatif sur Model Runner V2 : le décodage spéculatif par modèle de brouillon, les processeurs de logits personnalisés et la vérification adaptative ont été déplacés sur le nouveau modèle d’exécution, avec l’ajout du brouilleur LiLiCorr et de l’ordonnancement asynchrone pour le brouilleur DFlash.

Service MoE à grande échelle : de nouveaux backends all2all experts parallèles équilibrés (--all2all-backend moonep), DeepEPv2 avec le parallélisme de séquence, EPLB avec chevauchement d’expert partagé, et le parallélisme de contexte de préremplissage combiné au parallélisme de données.

Contrôle d’ordonnancement : --max-num-active-seqs limite l’admission en cours d’exécution (RUNNING) indépendamment de max_num_seqs, et la file d’attente attend maintenant d’ordonnancer en premier les requêtes qui détiennent déjà des blocs KV.

Les éléments du plan de route des anciens guides vLLM ont depuis longtemps été livrés — la prise en charge GGUF, le service multimodal, la préremplissage/décodage désintégrée et l’inférence multi-nœuds font tous partie des versions actuelles, donc considérez tout tutoriel qui les liste comme « à venir » comme obsolète. Les notes de version pour chaque version sont sur la page des versions vLLM.

Liens utiles

Articles connexes sur ce site

• Fiche récapitulative Ollama - Référence et fiche récapitulative complète des commandes Ollama couvrant l’installation, la gestion des modèles, l’utilisation de l’API et les bonnes pratiques pour le déploiement local de LLM. Indispensable pour les développeurs utilisant Ollama en parallèle ou à la place de vLLM.

• Docker Model Runner vs Ollama : Lequel choisir ? - Comparaison approfondie du Model Runner de Docker et d’Ollama pour le déploiement local de LLM, analysant les performances, la prise en charge GPU, la compatibilité API et les cas d’utilisation. Aide à comprendre le paysage concurrentiel dans lequel opère vLLM.

Ressources et documentation externes

• Dépôt GitHub vLLM - Dépôt officiel vLLM avec le code source, une documentation complète, des guides d’installation et des discussions communautaires actives. Ressource essentielle pour rester à jour avec les dernières fonctionnalités et dépanner les problèmes.

• Documentation vLLM - Documentation officielle couvrant tous les aspects de vLLM, de la configuration de base à la configuration avancée. Inclut des références API, des guides de réglage des performances et des bonnes pratiques de déploiement.

• Article PagedAttention - Article académique introduisant l’algorithme PagedAttention qui alimente l’efficacité de vLLM. Lecture essentielle pour comprendre les innovations techniques derrière les avantages de performance de vLLM.

• Blog vLLM - Blog officiel vLLM mettant en vedette les annonces de versions, les benchmarks de performance, les analyses techniques et les études de cas communautaires à partir de déploiements en production.

• HuggingFace Model Hub - Dépôt complet de LLM open source fonctionnant avec vLLM. Recherchez des modèles par taille, tâche, licence et caractéristiques de performance pour trouver le bon modèle pour votre cas d’utilisation.

• Documentation Ray Serve - Documentation du framework Ray Serve pour construire des déploiements vLLM évolutifs et distribués. Ray fournit des fonctionnalités avancées comme l’auto-échelle, le service multi-modèles et la gestion des ressources pour les systèmes de production.

• NVIDIA TensorRT-LLM - TensorRT-LLM de NVIDIA pour une inférence hautement optimisée sur les GPU NVIDIA. Alternative à vLLM avec différentes stratégies d’optimisation, utile pour la comparaison et la compréhension du paysage de l’optimisation de l’inférence.

• Référence API OpenAI - Documentation officielle de l’API OpenAI avec laquelle l’API de vLLM est compatible. Référez-vous à celle-ci lors de la construction d’applications devant fonctionner à la fois avec OpenAI et des points d’accès vLLM auto-hébergés de manière interchangeable.