Déployer vLLM en production

#Ce que vLLM fait, et ce qu'il exige

vLLM est un moteur d'inférence open source né au laboratoire Sky Computing de UC Berkeley. Son idée centrale, PagedAttention, gère le cache clé-valeur de l'attention par pages, comme la mémoire virtuelle d'un système d'exploitation. Selon l'annonce initiale du projet en 2023, les systèmes existants gaspillaient une grande part de leur mémoire et vLLM atteignait jusqu'à 24 fois le débit de Hugging Face Transformers et jusqu'à 3,5 fois celui de TGI, sur des tests de l'époque. Ces chiffres sont anciens et propres à ce banc : ils indiquent une direction, pas ce que vous obtiendrez avec votre modèle et votre carte.

Côté prérequis, la documentation actuelle demande Linux et Python de 3.10 à 3.13 ; sur Mac, il existe une voie séparée, vLLM-Metal, qui s'appuie sur MLX. Le serveur expose une API compatible OpenAI, écoute par défaut sur le port 8000 et ne sert qu'un modèle à la fois : pour plusieurs modèles, il faut plusieurs instances.

#Quand choisir vLLM plutôt qu'Ollama

La différence ne tient pas à la capacité de traiter des requêtes en parallèle, qu'Ollama offre aussi, mais à la façon dont la mémoire est partagée. Selon la FAQ d'Ollama, le traitement parallèle d'un modèle multiplie la taille du contexte par le nombre de requêtes : un contexte de 2 000 tokens avec 4 requêtes parallèles devient un contexte de 8 000 tokens en mémoire, réservé d'avance. vLLM alloue son cache par blocs, à la demande, et regroupe les requêtes en cours dans les mêmes calculs.

Règle pratique : si moins de trois personnes utilisent le modèle en même temps, ou si vous voulez changer de modèle souvent, Ollama suffit. Au-delà, ou avec un seul modèle servi en continu, vLLM rentabilise sa complexité. Le guide comparatif détaille le choix.

#Quand vLLM est un mauvais choix

vLLM n'apporte rien à un utilisateur seul sur un GPU de 8 à 12 Go : la mémoire manque pour un cache partagé, et Ollama ou llama.cpp démarrent plus simplement. Il convient mal si vous alternez entre cinq modèles au fil de la journée, puisqu'il faut relancer une instance par modèle. Sur un Mac, la voie est différente et repose sur MLX. Enfin, si votre besoin est une interface de chat pour l'équipe plutôt qu'une API à forte charge, une pile Ollama avec Open WebUI répond mieux et demande moins d'exploitation.

• Ollama ou vLLM en production : le comparatif
• vLLM : c'est quoi, pour qui, quand l'utiliser

#Dimensionner la mémoire : le calcul à faire avant tout

Un serveur vLLM se dimensionne par le cache clé-valeur, pas par les poids. Après avoir chargé le modèle, vLLM réserve une fraction de la mémoire du GPU, 92 % par défaut d'après le code de configuration actuel, et consacre tout ce qui reste au cache. Ce reste détermine combien de tokens de conversation peuvent coexister, donc combien d'utilisateurs simultanés vous servez.

Prenons Qwen2.5-7B-Instruct, dont la fiche indique 7,61 milliards de paramètres, 28 couches et 4 têtes clé-valeur (attention groupée). Le poids en 16 bits est d'environ 15,2 Go. Le cache d'un token vaut 2 (clés et valeurs) × 28 couches × 4 têtes × 128 dimensions × 2 octets, soit 57 344 octets, environ 56 Kio.

Ces bornes sont hautes : les tampons de calcul et les graphes CUDA consomment une partie du reste, et le modèle peut avoir un autre profil. La méthode reste valable pour tout modèle : lisez les nombres de couches et de têtes clé-valeur dans la fiche, calculez le coût par token, et divisez ce qu'il reste. Si les journaux signalent des préemptions, la documentation recommande d'augmenter gpu_memory_utilization ou de réduire max_num_seqs.

Deux leviers agrandissent le cache sans changer de carte : charger une version quantifiée du modèle, qui libère une partie des poids, ou limiter --max-model-len, ce qui évite de réserver de la place pour des contextes que personne n'utilise. Le premier levier peut coûter un peu de qualité ; le second ne coûte rien tant que vos requêtes restent courtes.

#1. Installation

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

La documentation recommande uv, qui choisit automatiquement la bonne version de PyTorch selon votre pilote CUDA. Pour un GPU AMD, l'installation passe par un index dédié ; pour Intel, TPU ou Ascend, des plugins existent. En production, l'image Docker évite les conflits de versions CUDA et se met à jour avec un simple changement d'étiquette.

#2. Lancer le serveur

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --gpu-memory-utilization 0.90 \
  --max-model-len 8192 \
  --api-key "$VLLM_API_KEY"

La commande vllm serve remplace l'ancienne invocation python -m vllm.entrypoints.openai.api_server, que la documentation actuelle n'utilise plus. Au premier lancement, les poids sont téléchargés depuis Hugging Face : prévoyez le disque (15 Go environ pour un 7B en 16 bits). Le serveur applique par défaut le fichier generation_config.json du dépôt du modèle, donc les paramètres d'échantillonnage recommandés par son éditeur ; --generation-config vllm rétablit les valeurs par défaut de vLLM.

curl http://localhost:8000/v1/models \
  -H "Authorization: Bearer $VLLM_API_KEY"

#3. Docker et systemd

L'image officielle vllm/vllm-openai est la voie la plus sûre. Montez le cache Hugging Face pour ne pas retélécharger les poids, et un volume pour le cache de compilation : chaque nouveau conteneur démarre sinon avec un cache vide et recompile les artefacts de son modèle. Notez que l'image s'exécute en root par défaut ; la documentation décrit une exécution avec un utilisateur non privilégié (--user 2000:0).

docker run --rm --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -v vllm-cache:/root/.cache/vllm \
  -p 8000:8000 \
  --ipc=host \
  -e VLLM_API_KEY=$VLLM_API_KEY \
  vllm/vllm-openai:latest \
  Qwen/Qwen2.5-7B-Instruct

[Unit]
Description=vLLM OpenAI API
After=network.target

[Service]
Type=simple
User=vllm
EnvironmentFile=/etc/vllm/env
ExecStart=/opt/vllm/bin/vllm serve Qwen/Qwen2.5-7B-Instruct --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

#4. Les paramètres qui comptent

Un principe de la documentation : si le modèle tient sur un seul GPU, la distribution est probablement inutile ; s'il ne tient pas mais tient sur un nœud, on utilise le parallélisme tensoriel avec --tensor-parallel-size. Les modèles déjà quantifiés se chargent directement depuis le Hub, sans option particulière : l'option --quantization ne sert que pour la quantification dynamique.

• Quantifier le KV cache : gagner de la VRAM
• Flash Attention : l'activer dans llama.cpp, Ollama, vLLM

#5. Mesurer le débit correctement

La commande vllm bench serve envoie des requêtes au serveur et rapporte le débit, le délai avant le premier token (TTFT) et la latence entre tokens. La documentation précise que ces bancs servent surtout à évaluer des fonctions et à détecter des régressions, et recommande GuideLLM pour tester un serveur de production.

vllm bench serve \
  --backend vllm \
  --model Qwen/Qwen2.5-7B-Instruct \
  --endpoint /v1/completions \
  --dataset-name sharegpt \
  --dataset-path CHEMIN/ShareGPT_V3_unfiltered_cleaned_split.json \
  --num-prompts 200

#Mise en service et exploitation

Une fois le dimensionnement fait, la mise en service suit toujours la même séquence. Elle vaut pour une équipe d'une vingtaine de personnes interrogeant un même modèle de 7 à 8 milliards de paramètres sur une carte de 24 ou 48 Go.

1. 01
   Choisir le modèle et le format

   Un seul modèle par instance. Préférez un dépôt déjà quantifié ou en 16 bits, selon la mémoire disponible.
2. 02
   Calculer le cache

   Appliquez le calcul par token de la section de dimensionnement pour fixer --max-model-len et --max-num-seqs.
3. 03
   Démarrer dans Docker

   Utilisez l'image officielle avec le cache Hugging Face monté et une étiquette de version figée plutôt que latest, pour éviter qu'une mise à jour change le comportement.
4. 04
   Ajouter le proxy

   Reverse proxy avec liste blanche des routes, TLS et limitation de débit, puis la clé d'API en complément.
5. 05
   Mesurer

   Lancez un banc de charge avec vllm bench serve en variant la graine, et notez le TTFT et le débit total.
6. 06
   Surveiller

   Branchez la collecte du point d'accès /metrics sur votre outil de supervision.

Les signaux à surveiller sont ceux qui annoncent un manque de cache : préemptions dans les journaux, TTFT qui grimpe, files d'attente qui s'allongent. La documentation signale que la préemption, dont le mode par défaut est le recalcul, protège le service mais dégrade la latence de bout en bout. Si elle devient fréquente, montez gpu_memory_utilization, réduisez le contexte ou limitez le nombre de requêtes simultanées. En dernier recours, ajoutez un GPU et répartissez le modèle avec le parallélisme tensoriel.

#6. Sécurité et exposition : --api-key ne suffit pas

Contrairement à ce que l'on lit souvent, vLLM sait vérifier une clé d'API, avec --api-key ou la variable VLLM_API_KEY. Mais la documentation de sécurité insiste : la clé ne protège que les routes sous /v1, /v2, /inference et /cohere. D'autres routes restent sans authentification, dont des routes d'inférence hors /v1, des routes de contrôle comme /pause ou /abort_requests, et /health. Ne comptez donc jamais sur --api-key seule.

Reverse proxy

Placez nginx, Envoy ou une passerelle Kubernetes devant vLLM, avec une liste blanche des seules routes à exposer, et bloquez toutes les autres.

Réseau

Un VPN ou un réseau isolé : la communication entre les nœuds d'un déploiement distribué n'est pas sécurisée par défaut.

Mode développement

N'activez jamais VLLM_SERVER_DEV_MODE=1 en production : il expose des routes dangereuses.

Limites

Appliquez la limitation de débit et la validation des requêtes au niveau du proxy, comme le recommande la documentation.

Journaux

Consignez qui envoie quoi, pour le débogage et l'audit.

• Sécuriser un serveur d'IA locale : authentification, reverse proxy, exposition

• Source : démarrage rapide de vLLM
• Source : sécurité de vLLM
• Source : vLLM avec Docker
• Source : annonce de vLLM et PagedAttention