vLLM Docker : guide d’architecture, de performances et de déploiement cloud

vLLM Docker : guide d’architecture, de performances et de déploiement cloud

Docker est le moyen le plus direct d’exposer vLLM derrière un point de terminaison compatible avec OpenAI sur des GPU que vous contrôlez. Un bon déploiement vLLM Docker ne se résume toutefois pas à une commande docker run : il nécessite un environnement d’exécution GPU compatible, un plan maîtrisé pour la mémoire et la concurrence, une authentification en périphérie et une méthode reproductible pour tester les performances avant l’arrivée du trafic.

Ce guide présente l’architecture, un premier déploiement sécurisé, les paramètres qui modifient réellement la capacité, ainsi que le passage d’un GPU unique à une flotte de GPU dans le cloud.

Utilisez vLLM Docker lorsque vous avez besoin de contrôler les poids du modèle, l’emplacement du déploiement, les paramètres d’exécution ou une charge de travail auto-hébergée stable. Si le coût opérationnel l’emporte sur ce contrôle, une API de modèle gérée ou une passerelle unifiée constitue souvent une meilleure frontière.

Ce que vLLM Docker vous apporte

vLLM publie une image Docker officielle vllm/vllm-openai qui démarre un serveur compatible avec OpenAI. Cela fait de vLLM Docker un pont utile entre un dépôt de modèles et les applications qui utilisent déjà le format de client OpenAI : la liste des modèles, les complétions de chat, les complétions, les embeddings et les points de terminaison compatibles associés dépendent du modèle et de la version du serveur que vous déployez. La documentation Docker de vLLM présente les exemples actuels d’images et d’exécution.

L’implication pratique est simple : votre application ne devrait pas avoir besoin d’un client de serveur de modèles sur mesure simplement parce que vous déplacez une charge de travail vers votre propre GPU. Elle a néanmoins besoin d’un nom de modèle explicite, d’une clé API, d’un délai d’expiration et d’un comportement de nouvelle tentative correspondant à votre propre objectif de disponibilité.

Fonctionnement de l’architecture vLLM Docker

À haut niveau, vLLM Docker comporte cinq couches :

1. Votre client envoie une requête authentifiée à un point de terminaison compatible avec OpenAI.
2. Le serveur API valide et tokenise la requête, puis la transmet au moteur vLLM.
3. Le planificateur regroupe les tâches compatibles et les répartit sur un ou plusieurs workers GPU.
4. Les workers GPU conservent les poids du modèle et le cache clé-valeur (KV) tout en générant les tokens.
5. La réponse est transmise en flux via le serveur API jusqu’au client.

L’idée centrale en matière de performances est PagedAttention. Au lieu de réserver une grande région contiguë de cache KV pour la longueur maximale possible d’une requête, vLLM gère l’état KV par blocs. Cela facilite le placement de charges de travail de longueurs variables dans la mémoire disponible et permet aux requêtes terminées de libérer des blocs pour les tâches ultérieures. L’article original sur PagedAttention décrit le planificateur, les workers GPU, les blocs KV logiques et physiques, ainsi que le compromis entre l’utilisation du cache et le traitement par lots.

Cette architecture a une conséquence opérationnelle importante : la VRAM ne correspond pas seulement à la « taille du modèle ». Elle est partagée entre les poids du modèle, la surcharge d’exécution, les activations et un cache KV dont les besoins augmentent avec la longueur du contexte et le nombre de requêtes simultanées. Considérez le contexte, la concurrence et l’utilisation de la mémoire comme une seule décision, et non comme trois tâches de réglage distinctes.

Avant d’exécuter vLLM Docker sur un GPU cloud

Commencez par quatre vérifications :

1. Choisissez un tag d’image testé. En production, épinglez un tag de version vLLM plutôt que de suivre aveuglément latest. Consultez la documentation correspondant à ce tag avant de vous fier à un indicateur ou à une valeur par défaut.
2. Utilisez un modèle que vous êtes autorisé à télécharger et à servir. Certains dépôts nécessitent un jeton Hugging Face ou l’acceptation d’une licence de modèle. Épinglez la révision du modèle après l’avoir validée.
3. Vérifiez l’accès au GPU en dehors du conteneur de modèle. Installez le pilote NVIDIA sur l’hôte et NVIDIA Container Toolkit, puis validez un conteneur compatible GPU avec nvidia-smi. Le guide d’installation de NVIDIA couvre les prérequis côté hôte et la configuration de l’environnement d’exécution.
4. Conservez d’abord le port privé. Effectuez une liaison à la boucle locale pour une preuve de concept sur un seul hôte, ou conservez le service sur un sous-réseau privé derrière TLS, une authentification et un proxy inverse/équilibreur de charge. Ne considérez pas le serveur de modèles seul comme une frontière de sécurité exposée à Internet.

Utilisez l’exemple de commande de NVIDIA avant de déboguer vLLM lui-même :

docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

Si cette commande ne détecte pas le GPU attendu, arrêtez-vous là. Un journal de serveur de modèles ne corrigera pas un pilote manquant, un environnement d’exécution de conteneur non configuré ou un GPU qui n’a jamais été attribué à la VM cloud.

Exécuter un serveur vLLM Docker sur un seul GPU

Ce qui suit constitue volontairement un point de départ minimal. Il reprend le modèle de l’image officielle, mais ajoute une clé API et lie le port publié à l’interface de bouclage. Remplacez les espaces réservés par un modèle et une balise d’image que vous avez testés.

export HF_TOKEN="your_hugging_face_token"
export VLLM_API_KEY="replace-with-a-long-random-secret"
export VLLM_IMAGE="vllm/vllm-openai:<tested-version>"
export MODEL="Qwen/Qwen3-0.6B"

docker run -d \
  --name vllm-api \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --dtype auto \
  --api-key "$VLLM_API_KEY"

Le paramètre de mémoire partagée et le montage du cache Hugging Face suivent l’exemple officiel de vLLM Docker. Le montage du cache évite de télécharger à nouveau les mêmes poids de modèle lorsque le conteneur est recréé. La clé API est un contrôle applicatif, et ne remplace pas l’isolation réseau, TLS, les limites de débit ou un gestionnaire de secrets.

Vérifiez que le serveur sert bien le modèle attendu avant de connecter une application :

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/models \
  -H "Authorization: Bearer $VLLM_API_KEY"

Envoyez ensuite une petite requête avec le même identifiant de modèle que celui renvoyé par /v1/models :

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $VLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [{"role": "user", "content": "Reply with the word ready."}],
    "max_tokens": 16
  }'

Si votre modèle n’inclut pas de modèle de conversation exploitable, les requêtes de complétion de conversation peuvent échouer même si le conteneur a démarré. vLLM documente comment fournir --chat-template pour les modèles dont la configuration du tokenizer n’en contient pas ; testez cela avant le déploiement d’une application. Consultez les recommandations relatives au modèle de conversation.

Définir l’enveloppe de performances avant de modifier les options

Il n’existe pas de commande vLLM Docker universellement correcte. La configuration adéquate dépend de l’architecture du modèle, du type et de la mémoire du GPU, de la distribution des longueurs d’entrée et de sortie, de la concurrence et de l’objectif de latence. Établissez une référence avec une charge de travail représentative, puis ne modifiez qu’une variable à la fois.

Relevez au minimum les mesures suivantes :

• Taux de réussite/d’erreur des requêtes et événements de redémarrage/OOM.
• Temps jusqu’au premier token (TTFT) et temps par token de sortie (TPOT), segmentés selon la longueur du prompt.
• Latence de bout en bout aux p50 et p95/p99 sous la concurrence attendue.
• Tokens d’entrée, tokens de sortie, temps d’attente en file, requêtes actives et utilisation de la mémoire GPU.
• Débit uniquement en parallèle de l’objectif de latence et de qualité qu’il a satisfait.

Les options vLLM Docker qui modifient sensiblement la capacité

Les valeurs par défaut et le comportement exacts des options dépendent de la version. La référence actuelle des arguments du moteur de vLLM définit les contrôles du planificateur, du cache, du parallélisme et de la file d’attente ; sa référence de configuration du cache explique les paramètres d’utilisation de la mémoire et de cache de préfixes.

Un ordre d’ajustement pratique

1. Définissez un --max-model-len réaliste à partir des limites de l’application.
2. Commencez prudemment avec l’utilisation de la mémoire et prévoyez une marge pour la surcharge des pilotes/de l’environnement d’exécution.
3. Testez en charge --max-num-seqs et --max-num-batched-tokens avec des longueurs réelles de prompts et de complétions.
4. Ajoutez du parallélisme tensoriel uniquement lorsqu’un seul GPU ne peut pas accueillir le modèle ou atteindre l’objectif défini pour celui-ci.
5. Ajoutez des réplicas derrière un équilibreur de charge lorsque les besoins de disponibilité ou de trafic agrégé exigent des domaines de défaillance indépendants.

Cette séquence évite une erreur fréquente : ajouter des GPU ou augmenter la concurrence avant de savoir si la charge de travail est réellement limitée par le contexte, la file d’attente, la mémoire ou le calcul.

Faire évoluer vLLM Docker sur plusieurs GPU

Pour un modèle qui nécessite plusieurs GPU, vLLM prend en charge le service avec parallélisme tensoriel et par pipeline. Sur un seul hôte, exposez les GPU au conteneur et définissez la taille du parallélisme tensoriel sur le nombre de GPU que vous attribuez délibérément à ce serveur de modèles :

docker run -d \
  --name vllm-tp \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --tensor-parallel-size 4 \
  --api-key "$VLLM_API_KEY"

Le guide du parallélisme et de la mise à l’échelle de vLLM documente le parallélisme tensoriel, le parallélisme par pipeline et les choix d’exécution sur un seul nœud ou sur plusieurs nœuds. Ne copiez pas la valeur 4 de l’exemple sur un nœud à deux GPU : adaptez le paramètre aux GPU alloués à ce serveur et validez la topologie de communication, l’équilibre mémoire et le comportement en cas de défaillance.

Pour les détails d’implémentation, les vérifications de topologie et le choix entre parallélisme tensoriel et par pipeline, consultez le guide d’inférence vLLM multi-GPU de Flatkey. Pour une décision concernant le runtime de service plutôt qu’un déploiement Docker, consultez vLLM vs. SGLang.

Architecture d’un déploiement cloud en production

Un déploiement vLLM Docker en production sépare normalement la périphérie publique de l’exécution sur GPU :

Placez le cache Hugging Face sur un stockage durable ou intentionnellement préchauffé afin qu’un redémarrage ordinaire ne déclenche pas un téléchargement inattendu du modèle. Conservez la licence du modèle et les contrôles d’accès dans l’enregistrement de votre déploiement. Épingler uniquement le tag de l’image ne suffit pas si le dépôt du modèle pointe vers une branche mobile.

Pour des informations sur la sélection de GPU, la planification mémoire guidée par le contexte et les cas où l’infrastructure cloud est le bon choix, associez ce runbook au guide des exigences mémoire GPU pour les LLM, au guide du cloud GPU et au cadre comparatif cloud GPU vs. API de modèle de Flatkey.

Dépanner vLLM Docker sans procéder au hasard

Lorsque le serveur fonctionne mais que le comportement de l’application diffère encore de celui d’une API hébergée, vérifiez explicitement la compatibilité des endpoints et des paramètres. Le guide de Flatkey sur les serveurs d’inférence compatibles avec OpenAI couvre la migration côté client et les tests de compatibilité.

Quand ne pas exploiter vLLM Docker vous-même

L’auto-hébergement est un engagement en matière d’infrastructure. Vous êtes responsable des mises à jour d’images, de la provenance des modèles, de la capacité GPU, des défaillances de nœuds, du contrôle d’accès, de la validation de la latence et de la procédure d’astreinte. Cela peut être le bon compromis lorsque le contrôle du runtime est une exigence.

Pour les charges de travail où le choix des modèles, la disponibilité des fournisseurs ou la simplicité opérationnelle comptent davantage que le contrôle direct des GPU, conservez une voie d’API managée dans l’architecture. Flatkey est conçu pour le workflow complémentaire : une intégration unique compatible avec OpenAI pour accéder aux modèles de différents fournisseurs avec une facturation centralisée, tandis qu’un endpoint vLLM auto-hébergé reste une option pour les charges de travail qui en ont réellement besoin.

La bonne prochaine étape n’est pas de maximiser un benchmark de manière isolée. Avant de placer vLLM Docker derrière du trafic de production, épinglez l’image et le modèle, validez le runtime GPU, définissez une politique explicite de contexte et de file d’attente, testez avec des requêtes représentatives de la production et documentez le chemin de défaillance.

Questions fréquemment posées

vLLM Docker est-il équivalent à une API LLM managée ?

Non. vLLM Docker vous fournit un runtime de service de modèles sur des GPU que vous exploitez. Une API managée abstrait l’hébergement des modèles et les opérations GPU. Les deux peuvent exposer une interface client compatible avec OpenAI, mais la responsabilité opérationnelle est différente.

vLLM Docker nécessite-t-il NVIDIA Container Toolkit ?

Pour les conteneurs GPU NVIDIA, l’hôte doit disposer d’un pilote NVIDIA compatible et d’un runtime de conteneur GPU configuré. NVIDIA Container Toolkit est la voie standard documentée par NVIDIA pour rendre les GPU disponibles dans les conteneurs Docker.

Quel paramètre vLLM Docker dois-je régler en premier ?

Définissez d’abord une longueur de contexte maximale réaliste, puis testez l’utilisation de la mémoire, la concurrence et les limites de tokens par lot avec un mélange de requêtes représentatif. Modifier des paramètres sans référence de charge de travail produit principalement des résultats non reproductibles.

vLLM Docker peut-il exécuter un modèle sur plusieurs GPU ?

Oui. vLLM prend en charge le service avec parallélisme de tenseurs et parallélisme de pipeline. Commencez avec un seul hôte et validez le nombre exact de GPU, la topologie et le comportement de communication avant d’étendre la conception.

Sources et lectures complémentaires

• vLLM : utilisation de Docker
• vLLM : parallélisme et mise à l’échelle
• vLLM : arguments du moteur
• Guide d’installation de NVIDIA Container Toolkit
• Gestion efficace de la mémoire pour le service de grands modèles de langage avec PagedAttention