Comment installer et optimiser vLLM : Le Guide complet sur Linux, Mac, Windows et Docker

Quand j’ai commencé à m’intéresser au déploiement local de modèles de langage, j’ai vite compris que la gestion de la mémoire et la vitesse d’inférence étaient le nerf de la guerre.

vLLM s’est rapidement imposé comme un moteur incontournable, mais selon la machine que l’on a sous la main, son installation peut réserver quelques surprises. J’ai eu l’occasion de configurer cet outil sur différents systèmes, et voici un guide de route structuré pour réussir votre installation sans encombre.

Points clés à retenir

• Le gestionnaire de paquets uv est la méthode la plus rapide et recommandée sur Linux pour installer automatiquement les bonnes dépendances PyTorch.
• Sur macOS, vLLM n’est pas supporté nativement de manière standard : il faut compiler le code source avec l’extension vllm-metal et utiliser des modèles convertis pour MLX.
• Pour Windows, l’utilisation de WSL2 ou de Docker Desktop reste la voie royale, le support natif direct étant encore expérimental.
• La quantité de mémoire vidéo (VRAM) nécessaire dépend de la taille du modèle, mais aussi d’une marge de sécurité indispensable d’environ 30 % pour stocker le cache KV de vLLM.

Matériel requis et calcul de la VRAM

Avant de lancer la moindre ligne de commande, il convient de faire un point sur la configuration matérielle. vLLM a été conçu principalement pour tourner sur des cartes graphiques NVIDIA disposant d’une capacité de calcul (compute capability) de 7.0 ou supérieure, ce qui correspond à l’architecture Volta ou plus récent.

Même si NVIDIA reste le standard de l’industrie, d’autres architectures de calcul sont désormais supportées :

• NVIDIA : Les GPU grand public comme les RTX 3080/3090, RTX 4080/4090 ou les cartes professionnelles comme la RTX A6000 sont parfaitement compatibles. Pour la production, les architectures Ampere (A100, A10), Ada Lovelace (RTX 4090, L4), Hopper (H100, H200) ou Blackwell (B200) permettent d’exploiter des formats de données optimisés tels que le FP16, le BF16 et le FP8.
• AMD : Les puces des séries Instinct MI200 et MI300, ainsi que les cartes Radeon RX 7900, sont prises en charge via le backend ROCm.
• Intel : Les puces Data Center Max Series (PVC) ainsi que les architectures Core Ultra et Arc sont utilisables via le backend Intel XPU.
• Apple Silicon : Les puces M1, M2, M3 et M4 sont gérées via le plugin vLLM-Metal.
• Processeurs classiques (CPU) : Les architectures x86 d’Intel et d’AMD permettent de tester le moteur via les moteurs d’exécution OpenVINO ou les instructions AVX-512, bien que les vitesses d’exécution soient nettement plus lentes.

Comment estimer la quantité de VRAM requise

Pour éviter les plantages dus à un manque de mémoire vidéo, j’applique toujours cette formule de calcul théorique afin d’estimer mes besoins :

VRAM minimale ≈ ((Paramètres du modèle en milliards × 2) / Facteur de quantification) × 1,3

Plusieurs facteurs expliquent cette équation :

• Les poids du modèle : Un modèle non quantifié (en FP16 ou BF16) utilise 2 octets de VRAM pour chaque milliard de paramètres. Un modèle de 7 milliards de paramètres (7B) monopolise donc environ 14 Go de VRAM uniquement pour son chargement.
• La quantification : Compresser un modèle en 4-bits permet de diviser la taille de ses poids par 4. Notre modèle 7B ne pèse alors plus que 3,5 Go environ en mémoire de base.
• Le coefficient de marge (1,3) : Par défaut, vLLM réserve une part importante de la VRAM restante (souvent jusqu’à 90 %) pour stocker l’historique des conversations et les jetons contextuels (le KV Cache). Il faut donc conserver au moins 20 à 30 % d’espace supplémentaire par rapport à la taille brute du modèle pour pouvoir mener des discussions de longueurs réalistes.

Guide de référence rapide

Taille du modèle	Quantification recommandée	VRAM minimale totale	Exemples de configurations GPU
1B à 3B (ex. Llama 3.2 3B)	Non quantifié (BF16)	8 Go	1x RTX 3070 / 4060, Mac puce M
7B à 9B (ex. Llama 3 8B)	Non quantifié (BF16)	24 Go	1x RTX 3090 / 4090, 1x NVIDIA A10G
7B à 9B (ex. Llama 3 8B)	Quantifié 4-bit / 8-bit	12 Go à 16 Go	1x RTX 4070, 1x NVIDIA T4
70B (ex. Llama 3 70B)	4-bit AWQ / GPTQ	48 Go	2x RTX 3090 / 4090, 1x NVIDIA A6000
70B (ex. Llama 3 70B)	Non quantifié (BF16)	160 Go+	2x NVIDIA A100 (80 Go), 4x NVIDIA A10G

Notez que si le modèle s’avère trop volumineux pour tenir sur une seule carte, vLLM gère nativement la répartition de la charge sur plusieurs puces graphiques grâce au parallélisme de tenseurs (en utilisant par exemple l’argument --tensor-parallel-size 2).

A lire — Optimiser l’inférence des LLM : Retour d’expérience sur les Techniques et Outils indispensables

Installation sur Ubuntu (la méthode standard)

Sur Linux, et plus particulièrement sur Ubuntu (les versions 22.04 LTS ou 24.04 LTS étant idéales), l’installation est fluide si l’on prend soin de préparer correctement l’environnement.

Prérequis système

• Système d’exploitation : Linux (Ubuntu 20.04 ou 22.04 fortement recommandé pour un support natif optimal).
• Version de Python : Python 3.10 ou supérieur (je recommande vivement d’utiliser Python 3.12+).
• Pilotes : Les pilotes NVIDIA doivent être installés. On peut s’en assurer en lançant la commande nvidia-smi dans le terminal.

Méthode 1 : Utilisation de uv (Recommandée et ultra-rapide)

L’utilisation de l’utilitaire uv permet d’accélérer grandement la configuration et d’aligner automatiquement la version de PyTorch sur celle des pilotes CUDA de la machine (ce qui évite, croyez-moi, de longs moments de frustration à chercher pourquoi la carte graphique n’est pas détectée).

On met d’abord à jour le système et on installe les paquets de développement requis pour éviter les erreurs de compilation :

sudo apt-get update && sudo apt-get install -y python3-dev python3-venv curl

On installe ensuite uv puis on recharge les variables d’environnement de la session :

curl -fsSL https://astral.sh | sh
source $HOME/.local/bin/env

Il ne reste plus qu’à créer notre environnement virtuel sous Python 3.12, à l’activer, puis à installer vLLM en laissant le sélecteur automatique de backend faire son travail :

uv venv vllm_env --python 3.12
source vllm_env/bin/activate
uv pip install vllm --torch-backend auto

Méthode 2 : Installation classique avec pip

Si vous préférez vous en tenir aux outils standards de Python, vous pouvez simplement exécuter l’installation classique au sein de votre environnement de travail actif :

pip install vllm

Méthode 3 : Déploiement avec Docker

Pour s’affranchir des contraintes d’installation de dépendances locales, on peut aussi s’appuyer sur l’image Docker officielle disponible sur le dépôt GitHub de vLLM :

docker run --gpus all -it --rm vllm/vllm-openai:latest

Vérification et premier test

Une fois l’installation achevée, je lance généralement deux vérifications rapides pour m’assurer que tout fonctionne. D’abord, je teste l’accès à l’interface en ligne de commande :

vllm --help

Ensuite, j’exécute cette courte ligne de script Python pour m’assurer que la bibliothèque parvient à communiquer avec le GPU :

python -c "import vllm; print(vllm.__version__)"

Si tout est au vert, on peut démarrer un serveur local compatible avec l’API OpenAI en déployant un modèle léger :

vllm serve "HuggingFaceTB/llama3.2-3B-Instruct" --gpu-memory-utilization 0.80

Le serveur se lance et se met à l’écoute des requêtes locales, généralement sur http://localhost:8000 (la documentation officielle est également accessible sur le site vllm.ai).

Installation sur macOS (Apple Silicon)

Au début, j’ai bêtement essayé de faire tourner le vLLM standard sur mon Mac avant de réaliser qu’il fallait une approche spécifique. La version de base de vLLM est pensée pour Linux. Pour l’utiliser sur Mac, il faut passer par l’extension vllm-metal, qui permet d’exploiter la puce graphique intégrée des architectures Apple Silicon (M1/M2/M3/M4) grâce au moteur d’exécution MLX.

Prérequis

• Matériel : Un Mac équipé d’une puce Apple Silicon (les processeurs Intel ne sont pas supportés).
• Python : Une installation native arm64 de Python 3.12. Les environnements émulés via Rosetta ou x86_64 ne fonctionneront pas.
• Compilateur : Les outils de ligne de commande Xcode doivent être présents sur la machine. On les installe ou vérifie leur présence avec :

xcode-select --install

Méthode 1 : Le script automatisé (Recommandé)

Le projet vLLM Metal propose un script d’installation qui prend tout en charge : le clonage du dépôt et la compilation des fichiers sources.

curl -fsSL https://raw.githubusercontent.com/vllm-project/vllm-metal/main/install.sh | bash

Méthode 2 : Compilation manuelle depuis les sources

Si vous aimez garder le contrôle sur les différentes étapes de configuration, vous pouvez compiler le projet manuellement.

On crée et on active l’environnement Python :

uv venv vllm_env --python 3.12
source vllm_env/bin/activate

On clone le dépôt de vLLM avant de basculer dans son répertoire :

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

Enfin, on installe les dépendances spécifiques CPU/Apple puis on lance l’assemblage :

pip install -r requirements/cpu.txt
pip install -e .

Note historique : Prenez une petite pause ou allez vous chercher un café, la compilation des composants natifs C++ via clang++ prend en général entre 5 et 10 minutes.

Exécution des modèles sur Mac

Puisque cette version s’appuie sur le moteur MLX, elle requiert l’usage de modèles spécifiquement convertis au format .safetensors. On en trouve une large sélection sous le profil de l’organisation mlx-community sur Hugging Face. Pour lancer le serveur d’API avec un modèle adapté, saisissez la commande suivante :

vllm serve mlx-community/Llama-3.2-3B-Instruct-4bit

L’adresse locale reste la même : http://localhost:8000. Le code source du plugin et les détails techniques se trouvent sur le dépôt officiel vllm-project/vllm-metal.

Alternative : Le Runner Docker sur macOS

Si l’idée de compiler du code localement vous rebute, Docker Desktop pour Mac (à partir de la version 4.62) gère nativement la redirection des requêtes de conteneurs vLLM directement vers le GPU Metal de l’hôte :

docker model install-runner --backend vllm

Vous pouvez consulter l’annonce de cette intégration sur l’article dédié du blog de Docker.

Installation sur Windows

Sur Windows, le support natif direct de vLLM est encore à un stade très expérimental. La méthode que je préconise systématiquement consiste à utiliser WSL2 (Windows Subsystem for Linux), qui offre de bien meilleures performances et une stabilité éprouvée.

Méthode 1 : Utilisation de WSL2 (Recommandé)

Cette approche permet d’exécuter l’environnement Linux Ubuntu de manière transparente sous Windows tout en conservant l’accès direct aux ressources matérielles de la carte graphique.

1. Installer WSL2 : Ouvrez une console PowerShell en tant qu’administrateur et exécutez la commande suivante : wsl --install -d Ubuntu Redémarrez votre PC si le système vous le demande, puis configurez votre identifiant et votre mot de passe Linux à l’ouverture de l’application Ubuntu.
2. Pilotes NVIDIA et outils de compilation : Veillez à ce que vos pilotes graphiques NVIDIA soient à jour sur votre système hôte Windows. Dans votre terminal Ubuntu WSL, préparez le terrain en tapant : sudo apt update && sudo apt upgrade -y sudo apt install -y build-essential python3-dev python3-venv nvidia-cuda-toolkit
3. Création de l’environnement : Il ne reste plus qu’à isoler l’installation et à déployer vLLM : python3 -m venv vllm_env source vllm_env/bin/activate pip install vllm

Méthode 2 : Docker Desktop sur Windows

Si vous préférez encapsuler le processus dans un conteneur, assurez-vous que Docker Desktop est installé avec l’intégration du moteur WSL2 activée. Lancez ensuite ces deux commandes dans l’invite PowerShell :

docker desktop enable model-runner --no-tcp
docker model install-runner --backend vllm --gpu cuda

Méthode 3 : Installation native sur Windows (Expérimentale)

Pour les besoins stricts d’une exécution sans surcouche Linux, une alternative communautaire fournit des fichiers d’installation pré-compilés (wheels) via le projet de dépôt SystemPanic/vllm-windows.

• Configuration nécessaire : Python 3.11 ou 3.12 (version 64 bits uniquement) et le toolkit NVIDIA CUDA 12.x ou 13.x installé de manière native sur votre Windows.
• Procédure d’installation : Allez sur la page des publications (releases) du dépôt GitHub vllm-windows pour récupérer le fichier au format .whl correspondant à votre version de Python et de CUDA, puis lancez l’installation avec pip :

pip install C:\chemin\vers\le\fichier\vllm_window_wheel.whl

Pour valider l’installation (que ce soit via WSL2 ou en natif), vous pouvez tester le chargement du modèle d’instruction léger :

vllm serve "HuggingFaceTB/llama3.2-3B-Instruct" --gpu-memory-utilization 0.80

Déploiement complet avec Docker

En production, j’ai tendance à privilégier l’usage de Docker. Cela évite d’avoir à installer Python, d’installer des paquets ou d’avoir à gérer manuellement des étapes de compilation complexes. La seule contrainte est d’avoir configuré le moteur de conteneurisation ainsi que le module d’extension NVIDIA Container Toolkit.

Validation de l’accès au GPU

Avant d’instancier vLLM, vérifiez que Docker accède bien à la carte graphique de votre machine hôte en lançant ce conteneur de test :

docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

Si l’affichage classique des processus GPU apparaît à l’écran, vous pouvez passer au déploiement du conteneur vLLM.

Démarrage de l’image de production

Le projet met à disposition des images prêtes à l’emploi. Pour lancer l’instance avec le modèle d’exemple, utilisez la commande suivante :

docker run --gpus all \
    -p 8000:8000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model HuggingFaceTB/llama3.2-3B-Instruct

Voici l’explication des différentes options utilisées dans cette commande :

• --gpus all : Permet au conteneur de s’approprier l’ensemble des ressources de calcul des cartes graphiques de la machine hôte.
• -p 8000:8000 : Lie le port d’écoute 8000 du conteneur au port 8000 de votre machine locale.
• -v ~/.cache/huggingface... : Monte le répertoire de cache Hugging Face local dans le conteneur. Cela évite d’avoir à retélécharger l’intégralité des fichiers de poids du modèle à chaque redémarrage du conteneur.
• --ipc=host : Indique au conteneur d’utiliser l’espace de mémoire partagée de l’hôte. C’est un paramètre critique pour vLLM, indispensable pour réaliser des transferts de données ultra-rapides en mémoire (notamment lors de l’usage de NCCL pour le parallélisme multi-GPU).
• vllm/vllm-openai:latest : L’image officielle configurée pour servir des API compatibles avec la structure d’OpenAI.
• --model ... : Tous les arguments saisis après le nom de l’image sont directement transmis à la commande d’initialisation du service de vLLM.

Test de l’API

Dès que le message d’initialisation de l’outil serveur de type Uvicorn s’affiche à l’écran, vous pouvez solliciter le modèle en lui envoyant une requête HTTP depuis votre machine locale :

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "HuggingFaceTB/llama3.2-3B-Instruct",
    "messages": [{"role": "user", "content": "Tell me a short joke."}]
  }'

Configuration avancée : Multi-GPU et Docker Compose

Si vous disposez de plusieurs cartes graphiques et que vous devez diviser la charge de traitement d’un grand modèle (comme Llama 3 70B), indiquez les identifiants des périphériques de calcul ainsi que le niveau de découpage souhaité :

docker run --gpus '"device=0,1"' \
    -p 8000:8000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model meta-llama/Llama-3-70B-Instruct \
    --tensor-parallel-size 2

Pour les déploiements pérennes au sein d’architectures plus complexes, je configure généralement un fichier docker-compose.yml :

version: '3.8'

services:
  vllm:
    image: vllm/vllm-openai:latest
    ports:
      - "8000:8000"
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    ipc: host
    environment:
      - HUGGING_FACE_HUB_TOKEN=your_token_here   # Requis uniquement pour les modèles à accès restreint
    command: --model HuggingFaceTB/llama3.2-3B-Instruct
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Pour démarrer ce service en tâche de fond, lancez simplement la commande habituelle :

docker compose up -d

Maîtriser les commandes de l’interface CLI de vLLM

L’outil s’articule autour de trois commandes majeures : l’hébergement de modèles, l’interrogation rapide et l’évaluation des performances.

1. vllm serve (Hébergement de modèles)

C’est l’outil central de vLLM. Il permet de mettre à disposition un serveur de modèle compatible avec l’API OpenAI. Exemple d’usage basique :

vllm serve "HuggingFaceTB/llama3.2-3B-Instruct"

Voici les principaux arguments pour ajuster le comportement du serveur :

• --port <int> : Permet de modifier le port d’écoute (8000 par défaut).
• --host <str> : Permet d’ouvrir les accès réseau. Utilisez l’adresse --host 0.0.0.0 pour rendre le serveur accessible depuis d’autres postes de votre réseau local.
• --gpu-memory-utilization <float> : Ajuste le taux d’allocation mémoire graphique initiale réservée au chargement et au cache KV (0.90 par défaut). En cas de crash pour cause de dépassement de capacité (OOM), je conseille d’abaisser cette valeur à 0.75 ou 0.80.
• --max-model-len <int> : Fixe une limite haute au nombre de jetons pris en compte dans le contexte. Réduire cette longueur permet de diminuer drastiquement la mémoire requise pour les requêtes longues.
• --tensor-parallel-size <int> : Permet de scinder un modèle sur plusieurs cartes (ex : --tensor-parallel-size 2 pour deux cartes graphiques).
• --quantization <str> : Spécifie le mode de compression utilisé pour charger un modèle optimisé (par exemple awq, gptq ou fp8).
• --enable-chunked-prefill : Indispensable pour le traitement de longs textes. Cet argument découpe les requêtes volumineuses en morceaux afin de lisser l’usage de la mémoire de calcul.
• --api-key <str> : Permet de restreindre l’accès à l’API en ajoutant une clé de validation lors des requêtes HTTP.
• --chat-template <path> : Permet d’injecter un fichier de structure Jinja personnalisé pour modifier l’encapsulation des messages.

2. vllm chat (Interrogation rapide via le terminal)

Si vous souhaitez simplement valider le comportement d’un modèle en discutant directement avec lui sans déployer de client d’API externe, la commande suivante ouvre un terminal interactif :

vllm chat "HuggingFaceTB/llama3.2-3B-Instruct"

Cette commande accepte exactement les mêmes paramètres de configuration mémoire ou de quantification que l’outil vllm serve.

3. vllm benchmark (Analyse et mesures de performance)

vLLM embarque des outils de diagnostic pour analyser le comportement de vos instances en situation réelle.

Test de débit (Throughput) : Mesure le volume global de jetons générés par seconde par votre matériel sous une charge simulée importante :

python3 -m vllm.entrypoints.benchmark_throughput \
    --model "HuggingFaceTB/llama3.2-3B-Instruct" \
    --dataset /path/to/sharegpt_dataset.json \
    --num-prompts 1000

Test de latence : Permet d’évaluer la vitesse de réponse lors d’un échange unitaire :

python3 -m vllm.entrypoints.benchmark_latency \
    --model "HuggingFaceTB/llama3.2-3B-Instruct" \
    --input-len 32 \
    --output-len 128 \
    --batch-size 1

Injections de variables d’environnement

Pour ajuster le comportement global du moteur avant son exécution, on peut utiliser des variables de configuration système en début de ligne :

• CUDA_VISIBLE_DEVICES=0 vllm serve ... : Limite la détection de vLLM à la seule première carte graphique du système.
• VLLM_ATTENTION_BACKEND=FLASH_ATTN : Impose l’usage de FlashAttention (ou XFORMERS selon vos préférences d’optimisation).
• HF_TOKEN=hf_xxx vllm serve ... : Permet d’injecter votre jeton d’authentification pour charger les modèles à accès restreint (comme la famille Llama 3).

Se perfectionner en MLOps

Si vous souhaitez vous lancer plus sérieusement dans le déploiement de modèles locaux à l’échelle de l’entreprise, dans la conception de l’architecture ou l’optimisation des flux de travail, nous proposons chez Deep Learn Academy des cursus spécialisés en MLOps débouchant sur une certification.

Les sessions se déroulent en ligne et intègrent des temps d’échange en direct avec des formateurs chevronnés. N’hésitez pas à nous solliciter pour affiner votre parcours d’apprentissage.