Installer vLLM avec Docker Compose sur Linux (compatible Windows WSL2)

Installer vLLM avec Docker Compose sur Linux, ou Windows via WSL, est aujourd’hui l’une des méthodes les plus simples et robustes pour exécuter un modèle d’intelligence artificielle localement, avec accélération GPU Nvidia. Ce moteur d’inférence open source, compatible avec l’API OpenAI, permet d’exploiter efficacement les modèles Hugging Face en local tout en bénéficiant d’une exécution rapide, optimisée pour le calcul parallèle.

Grâce à Docker Compose, la configuration de vLLM devient reproductible, portable et facile à maintenir. Que vous soyez sur une distribution Linux classique (Ubuntu, Debian, Fedora) ou sur Windows 11 via WSL2, cette approche offre les mêmes performances et la même flexibilité.

Dans ce guide, nous verrons comment mettre en place un environnement complet : installation des prérequis, création d’un fichier docker-compose.yml, gestion du cache Hugging Face, intégration d’une interface Web (Open WebUI) et résolution des problèmes courants tels que la mémoire GPU insuffisante ou les erreurs de chargement de modèle.

L’objectif : disposer d’un serveur IA local rapide, stable et facile à déployer, prêt à exécuter vos modèles préférés sans dépendance au cloud.

Pourquoi installer vLLM avec Docker Compose

vLLM est un moteur d’inférence open source conçu pour exploiter pleinement la puissance des GPU. Il permet d’exécuter localement des modèles de langage compatibles OpenAI (Qwen, Mistral, Llama, DeepSeek, etc.) avec une efficacité bien supérieure à celle des serveurs Python classiques.

En l’associant à Docker Compose, on obtient une solution modulaire et maintenable :

• chaque service (vLLM, Open WebUI, stockage) est isolé,
• la configuration peut être versionnée et répliquée facilement,
• la compatibilité entre Linux, WSL2 et macOS (avec GPU virtuel) est assurée.

Cette approche évite les installations complexes de dépendances CUDA ou PyTorch en local. L’environnement complet est contenu dans une image Docker prête à l’emploi, ce qui réduit considérablement les erreurs de compatibilité logicielle.

En résumé, Docker Compose offre un cadre stable et portable pour déployer vLLM sur n’importe quelle machine équipée d’un GPU Nvidia, tout en permettant d’ajouter facilement d’autres services IA comme Open WebUI ou des bases vectorielles locales.

Pré-requis système et environnement

Avant de lancer l’installation, assurez-vous que votre système dispose des outils nécessaires pour exécuter des conteneurs avec accélération GPU. Cette procédure fonctionne à l’identique sous Linux (Ubuntu, Debian, Fedora, Arch) et Windows 11 avec WSL 2.

Matériel et logiciels requis

• Carte graphique Nvidia compatible CUDA
• Pilotes Nvidia à jour
• Docker Engine et Docker Compose installés
• nvidia-container-toolkit pour permettre le GPU pass-through dans les conteneurs

Installation du toolkit Nvidia

Sous Ubuntu / Debian :

sudo apt update
sudo apt install -y nvidia-container-toolkit
sudo systemctl restart docker

Vérification du GPU dans Docker

Exécutez la commande suivante :

docker run --rm --runtime=nvidia --gpus all nvidia/cuda:12.3.1-base nvidia-smi

Vous devez voir apparaître les informations de votre GPU (nom, mémoire, pilotes). Si la commande échoue, vérifiez les pilotes et la configuration du toolkit avant de poursuivre.

Configuration du fichier .env

Créez un fichier .env à la racine du projet pour stocker votre token Hugging Face, utilisé par vLLM pour télécharger les modèles :

HF_TOKEN=ton_token_huggingface

Une fois ces pré-requis validés, votre environnement est prêt pour l’installation de vLLM via Docker Compose.

Configuration de Docker Compose

L’étape suivante consiste à créer le fichier docker-compose.yml qui va orchestrer le service vLLM. Ce fichier définit l’image Docker utilisée, les volumes à monter, les variables d’environnement et les ressources GPU réservées.

Voici un exemple complet et fonctionnel, prêt à exécuter un modèle téléchargé automatiquement depuis Hugging Face :

services:
  vllm:
    image: vllm/vllm-openai:latest
    container_name: vllm
    ports:
      - "8000:8000"
    environment:
      HF_TOKEN: ${HF_TOKEN}
      HF_HOME: /models
    volumes:
      - ./models:/models
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]
    runtime: nvidia
    shm_size: "16g"
    command: >
      --model openai/gpt-oss-20b
      --max-model-len 32768
      --gpu-memory-utilization 0.9
      --disable-log-stats

Explication des paramètres essentiels

• image : utilise la dernière version officielle de vLLM avec support GPU.
• HF_TOKEN : authentifie le téléchargement des modèles depuis Hugging Face.
• HF_HOME : redirige le cache Hugging Face vers le dossier ./models, pour un accès direct aux fichiers téléchargés.
• volumes : permet de conserver les modèles même après suppression du conteneur.
• runtime: nvidia : active le GPU pass-through.
• shm_size : augmente la mémoire partagée (utile pour les modèles volumineux).
• command : spécifie le modèle à charger et quelques paramètres d’exécution.

Lancement du service

Placez le fichier docker-compose.yml et le fichier .env dans le même répertoire, puis exécutez :

docker compose up -d

Le conteneur va automatiquement télécharger le modèle et le lancer. Vous pouvez suivre la progression en temps réel :

docker logs -f vllm

Une fois l’initialisation terminée, le serveur est accessible sur :

http://localhost:8000/v1

Cette API est compatible OpenAI, ce qui permet d’interagir avec vLLM via n’importe quel client OpenAI (Python, cURL, ou interface graphique).

Téléchargement et gestion des modèles Hugging Face

Lors du premier démarrage, vLLM télécharge automatiquement le modèle spécifié dans le fichier docker-compose.yml depuis Hugging Face. Grâce à la variable d’environnement HF_HOME=/models, tous les fichiers sont enregistrés dans le dossier local ./models, ce qui simplifie leur gestion.

Organisation du répertoire

Après le premier lancement, la structure typique est la suivante :

./models/
 ├── models--openai--gpt-oss-20b/
 │   ├── config.json
 │   ├── model.safetensors
 │   ├── tokenizer.json
 │   └── ...

Chaque modèle téléchargé est conservé ici et pourra être réutilisé sans nouveau téléchargement.

Supprimer un modèle manuellement

Pour libérer de l’espace :

rm -rf ./models/models--openai--gpt-oss-20b

Le modèle sera retéléchargé automatiquement si vous relancez le service.

Utiliser un modèle local déjà téléchargé

Vous pouvez également placer vos modèles manuellement dans le dossier ./models et modifier la commande de lancement :

command: >
  --model /models/Qwen3-7B-Instruct

Cela permet d’exécuter un modèle sans connexion Internet ni accès au Hub Hugging Face.

Changer de modèle

Modifiez simplement la ligne correspondante :

--model Qwen/Qwen2.5-7B-Instruct

puis redémarrez le conteneur :

docker compose down && docker compose up -d

Grâce à cette approche, vLLM conserve tous les modèles téléchargés dans un espace unique, facilement visualisable et administrable.

Ajouter Open WebUI pour interagir avec vLLM

Pour dialoguer avec votre modèle via une interface graphique semblable à ChatGPT, vous pouvez ajouter Open WebUI. Cette interface web se connecte à l’API OpenAI exposée par vLLM sur le port 8000 et permet d’envoyer des prompts, de suivre les conversations et de gérer plusieurs sessions d’inférence locales.

Exemple de configuration dans Docker Compose

Ajoutez ce service à la suite du bloc vllm :

  openwebui_vllm:
    image: ghcr.io/open-webui/open-webui:main
    container_name: openwebui_vllm
    ports:
      - "3010:8080"
    environment:
      - OPENAI_API_BASE_URL=http://vllm:8000/v1
      - OPENAI_API_KEY=none
    depends_on:
      - vllm
    volumes:
      - openwebui_data_vllm:/app/backend/data

Et à la fin du fichier :

volumes:
  openwebui_data_vllm:

Lancez ensuite :

docker compose up -d

Accès à l’interface

Une fois le conteneur démarré, ouvrez votre navigateur à l’adresse :

http://localhost:3010

Vous obtiendrez une interface moderne permettant d’interagir directement avec votre instance vLLM. Chaque requête passe par l’API OpenAI locale (/v1/chat/completions), ce qui garantit confidentialité et rapidité.

Notes utiles

• Si vous avez déjà une instance d’Open WebUI reliée à Ollama ou à une autre API, vérfiier que les ports sont bien différent pour éviter tout conflit. Le port 3010, dans notre exemple, n’est pas le port standard (3000), vous ne devriez donc pas rencontré de problème.
• Les conversations, historiques et paramètres d’affichage sont stockés dans le volume openwebui_data_vllm.
• L’interface détecte automatiquement le modèle actif exposés par vLLM. A l’inverse d’Ollama, vLLM se charge avec un modèle spécifique et ne donne pas la possibilité de changer via l’interface Open WebUI ou autre

Open WebUI offre ainsi un environnement complet : vous bénéficiez de la performance de vLLM tout en conservant une ergonomie conviviale pour tester, comparer ou développer vos prompts.

Problèmes fréquents et solutions

Même si l’installation via Docker Compose est stable, plusieurs erreurs peuvent apparaître selon le modèle ou la configuration GPU. Voici les cas les plus courants rencontrés avec vLLM et leurs correctifs.

Problème	Cause probable	Solution
Erreur “out of memory” au lancement	Modèle trop volumineux pour la VRAM disponible	Choisir un modèle plus léger (ex. Qwen3-7B au lieu de 30B) ou utiliser une version quantifiée (4-bit, 8-bit, mxfp4).
Téléchargement incomplet ou erreur Model not found	Modèle Hugging Face non finalisé ou format expérimental	Utiliser une version stable ou vérifier la présence des fichiers complets sur le Hub.
Aucun modèle visible dans l’API	Mauvais chemin dans la commande –model	Vérifier le nom du répertoire et le point de montage /models.
Le GPU n’est pas détecté	Toolkit ou pilotes manquants	Réinstaller nvidia-container-toolkit, vérifier docker run –gpus all nvidia/cuda:12.3.1-base nvidia-smi.
Erreur mémoire partagée (shm)	Taille insuffisante du segment mémoire partagé	Augmenter shm_size dans Docker Compose : shm_size: « 16g » voire « 32g ».
Conflit de ports avec une autre instance Open WebUI	Port déjà occupé	Modifier le port dans Docker Compose (ex. 3011:8080).

Commandes utiles pour le diagnostic

• Suivre les logs du conteneur vLLM : docker logs -f vllm
• Vérifier les modèles disponibles : curl http://localhost:8000/v1/models
• Surveiller l’usage mémoire GPU : nvidia-smi
• Supprimer les fichiers de cache problématiques : rm -rf ./models/models–NomDuModele

Avec ces vérifications simples, la plupart des erreurs liées à vLLM se résolvent rapidement, sans avoir à reconstruire l’environnement Docker.

Le fichier docker compose complet avec vLLM et Open WebUI

    services:
    vllm:
        image: vllm/vllm-openai:latest
        container_name: vllm
        ports:
        - "8000:8000"
        environment:
        HF_TOKEN: ${HF_TOKEN}
        volumes:
        - ~/.cache/huggingface:/root/.cache/huggingface
        - ./models:/models
        deploy:
        resources:
            reservations:
            devices:
                - capabilities: [gpu]
        runtime: nvidia
        shm_size: "16g"
        command: >
        --model openai/gpt-oss-20b
        --max-model-len 32768
        --gpu-memory-utilization 0.9
        --disable-log-stats

    openwebui_vLLM:
        image: ghcr.io/open-webui/open-webui:main
        container_name: openwebui_vLLM
        ports:
        - "3010:8080"
        environment:
        - OPENAI_API_BASE_URL=http://vllm:8000/v1
        - OPENAI_API_KEY=none
        depends_on:
        - vllm
        volumes:
        - openwebui_data_vllm:/app/backend/data

    volumes:
    openwebui_data_vllm:

Si nécessaire, vous pouvez ajouter un réseau docker dédié

networks:
  default:
    name: vllm_net

Vérifier le bon fonctionnement de vLLM

Une fois vos conteneurs démarrés, il est essentiel de s’assurer que vLLM fonctionne correctement et que l’API OpenAI est bien accessible.

Vérification via l’API

Exécutez cette commande :

curl http://localhost:8000/v1/models

Si l’installation est réussie, la réponse renverra une liste contenant le nom du modèle chargé :

{
  "object": "list",
  "data": [
    {
      "id": "openai/gpt-oss-20b",
      "object": "model",
      "owned_by": "vllm"
    }
  ]
}

Cela confirme que le modèle est actif et prêt à répondre aux requêtes.

Test d’une requête de complétion

curl http://localhost:8000/v1/completions 
  -H "Content-Type: application/json" 
  -d '{
    "model": "openai/gpt-oss-20b",
    "prompt": "Explique la différence entre CPU et GPU en une phrase.",
    "max_tokens": 50
  }'

Une réponse textuelle doit apparaître dans le terminal.

Test depuis Open WebUI

Ouvrez http://localhost:3010, saisissez votre prompt dans la barre de discussion et validez. La réponse doit s’afficher instantanément. Si l’interface reste bloquée, vérifiez que :

• le service vLLM est bien lancé (docker ps)
• l’adresse API est correcte (http://vllm:8000/v1)
• le log de vLLM doit afficher : (APIServer pid=1) INFO: XXX.XX.X.X:XXXXX – « GET /v1/models HTTP/1.1 » 200 OK. Ce message confirme que vLLM a bien effectué les opérations, chargé le modèle, effectuez les calculs et écoute sur le port
• aucun pare-feu local ne bloque le port 8000

Ces vérifications assurent que le moteur d’inférence est opérationnel et prêt à être utilisé dans vos applications ou tests de modèles IA.

Conclusion

Déployer vLLM avec Docker Compose sous Linux (ou WSL2 sous Windows 11) offre une méthode simple, reproductible et performante pour exécuter des modèles d’intelligence artificielle en local. Cette approche combine la puissance de vLLM, moteur d’inférence optimisé GPU compatible avec l’API OpenAI, et la flexibilité de Docker Compose, qui permet de gérer facilement les services, volumes et dépendances.

Au-delà de la simple exécution locale, vLLM se distingue par sa vocation orientée production. Il prend en charge des formats optimisés comme le récent NVFP4, permettant des chargements plus rapides et une utilisation mémoire plus efficace. S’il demande une configuration plus technique qu’un outil comme Ollama, il offre en contrepartie un contrôle précis des paramètres, une meilleure extensibilité et une stabilité adaptée aux environnements professionnels. Dans une optique de performance, d’optimisation et de déploiement à grande échelle, vLLM fait figure de référence.

Pour aller plus loin : Ollama vs vLLM : quelle solution choisir pour servir vos modèles LLM en local ?

Grâce à ce guide, vous disposez d’un environnement complet :

• vLLM configuré pour utiliser votre GPU Nvidia,
• gestion centralisée des modèles Hugging Face,
• interface web Open WebUI pour interagir avec vos modèles,
• et une compatibilité totale entre Linux natif et WSL2.

Cette architecture convient aussi bien aux développeurs qu’aux chercheurs souhaitant tester rapidement différents modèles open source (Qwen, Mistral, Llama, DeepSeek, etc.) sans dépendre du cloud. Elle peut également servir de base à une infrastructure IA locale, extensible avec d’autres outils (Ollama, LangChain, bases vectorielles).

En résumé, vLLM + Docker Compose constitue aujourd’hui l’une des solutions les plus efficaces pour exécuter une IA en local : rapide à mettre en place, stable et parfaitement adaptée à un usage professionnel ou expérimental.

Ressources complémentaires

Pour aller plus loin et adapter cette installation à d’autres usages, voici une sélection de ressources utiles :

Documentation officielle

• vLLM : https://docs.vllm.ai → Détails sur les options de lancement, les optimisations GPU et la compatibilité API OpenAI.
• Docker Compose : https://docs.docker.com/compose/ → Syntaxe complète du fichier YAML, gestion des volumes, réseaux et dépendances.
• Open WebUI : https://github.com/open-webui/open-webui → Guide d’intégration, personnalisation de l’interface et compatibilité avec différents backends IA.

Articles et outils recommandés

• Hugging Face Hub : pour explorer et télécharger d’autres modèles open source (Qwen, Mistral, Llama, DeepSeek…).
• NVIDIA Container Toolkit : documentation officielle pour vérifier la compatibilité GPU et la configuration CUDA.
• Ollama : alternative pratique pour charger plusieurs modèles et basculer entre eux.
• LM Studio : outil desktop permettant de tester localement les modèles et comparer les performances.

Commandes pratiques à retenir

# Lancer tous les services
docker compose up -d

# Consulter les logs du moteur vLLM
docker logs -f vllm

# Vérifier les modèles disponibles
curl http://localhost:8000/v1/models

# Supprimer un modèle du cache
rm -rf ./models/models--NomDuModele

---

Prochaines étapes possibles

• • Intégrer une base vectorielle locale (ex. ChromaDB ou Qdrant) pour stocker des embeddings.
• Coupler vLLM avec un orchestrateur d’agents (LangChain, LlamaIndex, n8n …) pour construire des assistants autonomes.

Cette installation forme une base solide pour toute infrastructure IA locale : performante, modulaire et facile à maintenir, que ce soit sur un serveur Linux ou une machine Windows via WSL2.