Docker vLLM : exécutez un serveur d’inférence accéléré par GPU en quelques minutes

vLLM publie une image Docker officielle, vllm/vllm-openai, qui fournit un serveur d’inférence prêt à l’emploi et compatible OpenAI. La méthode la plus rapide consiste à installer l’Outil NVIDIA Container Toolkit sur l’hôte, puis à exécuter l’image avec --gpus all et un identifiant de modèle Hugging Face. Une fois le modèle téléchargé, le serveur est actif sur le port 8000 et accepte les mêmes requêtes que l’API OpenAI.

Prérequis

• Docker Engine 20.10 ou ultérieur — Docker Desktop sur Windows et macOS fonctionne via le backend WSL2.
• GPU NVIDIA avec un pilote prenant en charge CUDA 12.x. Exécutez la commande nvidia-smi pour le vérifier ; la version « CUDA » indiquée correspond à la version maximale prise en charge par votre pilote.
• Outil NVIDIA Container Toolkit — le pont permettant à Docker d’accéder au GPU. Consultez la section suivante.
• Une quantité suffisante de VRAM pour votre modèle cible. Utilisez l’outil Calculateur de VRAM pour vérifier cela avant de télécharger définitivement un modèle.

Installation de l’Outil NVIDIA Container Toolkit

Passez cette section si docker run --gpus all nvidia/cuda:12.0-base nvidia-smi fonctionne déjà sur votre machine.

Linux (Ubuntu/Debian) :

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | 
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | 
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | 
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

RHEL/CentOS : Remplacez l’URL du dépôt deb par l’équivalent rpm indiqué dans la documentation NVIDIA, puis utilisez dnf à la place de apt-get.

Windows (WSL2) : Installez le pilote NVIDIA pour Windows sur l’hôte — aucune installation séparée du toolkit conteneur n’est nécessaire au sein de WSL2. Docker Desktop gère automatiquement le transfert des ressources GPU.

macOS : Les GPU NVIDIA ne sont pas pris en charge sur macOS. vLLM ne peut pas s’exécuter sur les processeurs Apple Silicon via Docker avec accélération GPU. Pour l’inférence locale sur du matériel Apple, envisagez une version compilée pour CPU uniquement ou un autre environnement d’exécution.

Commande minimale d’exécution

docker run --runtime nvidia --gpus all 
  --ipc=host 
  -v ~/.cache/huggingface:/root/.cache/huggingface 
  -p 8000:8000 
  vllm/vllm-openai:latest 
  --model meta-llama/Meta-Llama-3-8B-Instruct

Pour télécharger un modèle protégé (Llama 3, Mistral, etc.), transmettez également -e HUGGING_FACE_HUB_TOKEN=hf_votretoken. Stockez ce jeton dans un fichier .env et passez-le à l’aide de l’option --env-file .env plutôt que de l’intégrer directement dans l’historique de votre interpréteur de commandes.

Montage du cache Hugging Face

vLLM télécharge les poids du modèle vers le répertoire /root/.cache/huggingface à l’intérieur du conteneur. En l’absence de montage de volume, chaque exécution de la commande docker run entraîne le téléchargement complet du modèle — souvent compris entre 5 et 80 Go. La ligne de montage est la suivante :

-v ~/.cache/huggingface:/root/.cache/huggingface

Si vos modèles sont stockés dans un emplacement non standard, définissez la variable d’environnement -e HF_HOME=/votre/chemin et montez ce chemin à la place. Pour les environnements déconnectés d’internet (« air-gapped »), téléchargez d’abord le modèle à l’aide de huggingface-cli download puis transmettez l’option --model /chemin/dans/le/conteneur en combinaison avec un montage de volume du répertoire contenant les poids du modèle.

Paramètres clés du serveur vLLM

Ces options sont passées après le nom de l’image — il s’agit d’arguments destinés au processus serveur vLLM, et non à Docker.

Vous ne savez pas si votre GPU dispose de suffisamment de VRAM pour un modèle donné ? Le Guide des exigences en VRAM répertorie les modèles courants, tandis que le Calculateur de VRAM vous permet de spécifier la méthode de quantification et la taille de lot. Pour des conseils liés à l’achat de matériel, consultez le guide de recommandations pour GPU.

Exposition et test du point de terminaison compatible OpenAI

Une fois que le conteneur affiche le message INFO: Application startup complete, l’API est opérationnelle.

# Lister les modèles chargés
curl http://localhost:8000/v1/models

# Génération de texte
curl http://localhost:8000/v1/completions 
  -H "Content-Type: application/json" 
  -d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "prompt": "La capitale de la France est", "max_tokens": 20}'

# Génération de dialogue
curl http://localhost:8000/v1/chat/completions 
  -H "Content-Type: application/json" 
  -d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "messages": [{"role": "user", "content": "Bonjour"}]}'

Tout client compatible OpenAI — le SDK Python openai , LangChain, LlamaIndex — fonctionne en définissant base_url="http://localhost:8000/v1" et en fournissant n’importe quelle chaîne non vide comme api_key.

Exemple avec Docker Compose

Pour les déploiements persistants, un fichier Compose est plus facile à gérer qu’une longue commande docker run :

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    ports:
      - "8000:8000"
    ipc: host
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    command: >
      --model meta-llama/Meta-Llama-3-8B-Instruct
      --gpu-memory-utilization 0.90
      --max-model-len 8192

Commencez par docker compose up -d. Le bloc deploy.resources correspond, dans Compose v3, à l’option --gpus all.

Erreurs courantes et solutions

Questions fréquemment posées

Quelle balise d’image Docker vLLM dois-je utiliser ?

vllm/vllm-openai:latest suit la version la plus récente et convient bien aux expérimentations. Pour la production, privilégiez une balise de version spécifique (par exemple, v0.6.0) afin de garantir la reproductibilité des builds. Chaque balise de version publiée sur Docker Hub indique la version CUDA contre laquelle l’image a été compilée, qui doit être inférieure ou égale à celle prise en charge par votre pilote.

Puis-je exécuter vLLM dans Docker sans GPU ?

L’image standard requiert une carte graphique NVIDIA. L’inférence sur CPU uniquement est possible en compilant vLLM depuis les sources avec VLLM_TARGET_DEVICE=cpu, mais le débit est alors plusieurs ordres de grandeur plus lent et peu adapté au déploiement en production. Pour une inférence locale sur CPU uniquement, llama.cpp ou Ollama constituent des alternatives plus adaptées — consultez le Guide Ollama pour une comparaison.

Comment exécuter un modèle restreint nécessitant un jeton Hugging Face ?

Transmettez le jeton sous forme de variable d’environnement : -e HUGGING_FACE_HUB_TOKEN=hf_votretoken. Stockez-le dans un fichier .env et référencez-le à l’aide de --env-file .env afin d’éviter toute fuite dans l’historique du shell. Le serveur l’utilise lors du téléchargement initial du modèle ; il n’est plus requis une fois les poids mis en cache localement.

À quoi sert l’option –tensor-parallel-size et quand dois-je l’utiliser ?

La parallélisation tensorielle fragmente les matrices de poids du modèle sur plusieurs GPU, permettant ainsi d’exécuter des modèles trop volumineux pour une seule carte. Définissez-la sur le nombre de GPU que vous souhaitez utiliser (2 ou 4 sont courants). Ce nombre doit correspondre au nombre de GPU spécifié via --gpus, et le nombre de têtes d’attention du modèle doit être divisible par ce chiffre.

L’exécution de vLLM dans Docker est-elle économiquement avantageuse comparée à une API gérée ?

Cela dépend entièrement de votre volume de requêtes. L’auto-hébergement implique des coûts fixes élevés (instance GPU ou matériel dédié), mais un coût marginal quasi nul par requête. Les API gérées, quant à elles, ne comportent aucun coût fixe, mais facturent chaque jeton généré. Utilisez le calculateur auto-hébergement vs API pour identifier votre seuil de rentabilité avant de vous engager dans une infrastructure.

Comment servir plusieurs modèles simultanément ?

Exécutez un conteneur par modèle, chacun étant mappé sur un port hôte différent (par exemple 8000, 8001). vLLM ne prend actuellement pas en charge le service multi-modèles depuis un seul processus. Placez un proxy inverse tel que nginx ou Caddy devant les conteneurs afin de router les requêtes, selon le nom du modèle, vers le port approprié.