Installer vLLM sur Debian pour exécuter un LLM local

Mise à jour le 11 oct. 2026

Dans un précédent guide, j’ai expliqué comment installer et configurer un serveur Ollama pour exécuter des LLM, ou grands modèles de langage, en local. Cette solution est particulièrement pratique pour tester différents modèles sur une machine. En entreprise, lorsque plusieurs collaborateurs utilisent le serveur en même temps, la gestion des requêtes simultanées devient toutefois un critère essentiel. C’est dans ce contexte que j’ai découvert vLLM, un moteur d’inférence conçu pour exécuter des LLM avec de bonnes performances et traiter efficacement plusieurs requêtes en parallèle.

Comme souvent sur ce site, j’utiliserai une machine sous Debian. Un serveur Ubuntu LTS peut néanmoins simplifier l’installation, selon les versions des pilotes NVIDIA disponibles dans ses dépôts. Dans ce tutoriel, nous allons installer vLLM sur Debian 13, préparer le pilote NVIDIA et l’environnement CUDA, puis configurer un modèle local accessible depuis Open WebUI.

Pour ce test, j’ai pu récupérer une RTX A2000 12GB. Elle ne permet pas d’exécuter les modèles les plus volumineux, mais convient au modèle Qwen2.5-VL-3B-Instruct utilisé ici. J’aurais préféré un modèle Mistral 🇫🇷, mais… J’ai retenu Qwen car il s’agit d’un LLM multimodal, capable de traiter du texte et des images. C’est également un modèle instruct, entraîné pour comprendre et suivre les instructions de l’utilisateur.

Enfin, cet article s’inspire largement du tutoriel de ComputingForGeeks consacré à vLLM. Un grand merci à son auteur !

Architecture du serveur vLLM avec Open WebUI

Comme pour Ollama, j’utiliserai Open WebUI comme interface web afin de permettre à plusieurs utilisateurs d’interagir avec notre LLM local depuis leur navigateur. Dans cette configuration, vLLM sera installé directement sur le serveur Debian, tandis qu’Open WebUI s’exécutera dans un conteneur Docker sur la même machine. vLLM prendra en charge l’inférence du modèle, et Open WebUI fournira une interface accessible sur le réseau.

Architecture de vLLM sur Debian avec le modèle Qwen2.5-VL-3B-Instruct et Open WebUI dans Docker, accessibles à plusieurs utilisateurs depuis leur navigateur — Architecture de vLLM sur Debian : le modèle local Qwen2.5-VL-3B-Instruct est exécuté par vLLM, tandis qu’Open WebUI, installé dans Docker, permet à plusieurs utilisateurs d’y accéder depuis leur navigateur.

Installation de vLLM et de ses prérequis

Nous allons d’abord installer les pilotes NVIDIA et le CUDA Toolkit depuis le dépôt officiel NVIDIA. La version de vLLM utilisée dans ce guide nécessite un pilote et un environnement CUDA suffisamment récents, qui ne sont pas forcément disponibles dans les dépôts par défaut de Debian. Une fois ces prérequis en place, nous installerons vLLM.

Installer les pilotes NVIDIA et le CUDA Toolkit

🚨 Remarque : Sur ma machine de test, j’ai dû désactiver le Secure Boot pour que le pilote NVIDIA fonctionne correctement. Si nvidia-smi échoue après l’installation, le Secure Boot empêche peut-être le chargement du module NVIDIA dans le noyau. Sa désactivation n’est toutefois pas indispensable si le module est correctement signé et si sa signature est reconnue par le système.

Selon votre installation de Debian, seule la composante main des dépôts peut être activée par défaut. Les pilotes NVIDIA propriétaires n’y étant pas inclus, activez les composantes contrib, non-free et non-free-firmware dans le fichier /etc/apt/sources.list :

deb http://deb.debian.org/debian/ trixie main non-free-firmware contrib non-free
deb-src http://deb.debian.org/debian/ trixie main non-free-firmware contrib non-free

deb http://security.debian.org/debian-security trixie-security main non-free-firmware contrib non-free
deb-src http://security.debian.org/debian-security trixie-security main non-free-firmware contrib non-free

deb http://deb.debian.org/debian/ trixie-updates main non-free-firmware contrib non-free
deb-src http://deb.debian.org/debian/ trixie-updates main non-free-firmware contrib non-free

Vérifiez la version du paquet nvidia-cuda-toolkit disponible dans les dépôts par défaut de Debian 13. Dans cet exemple, la version proposée est la 12.4, mais nous utiliserons un environnement CUDA plus récent pour la version de vLLM présentée dans ce guide :

root@host:~# apt update && apt policy nvidia-cuda-toolkit
nvidia-cuda-toolkit:
  Installed: (none)
  Candidate: 12.4.131~12.4.1-2

Pour accéder à une version plus récente du cuda-toolkit, ajoutez le dépôt officiel NVIDIA CUDA. Téléchargez et installez le paquet cuda-keyring depuis le site NVIDIA. Consultez la documentation officielle NVIDIA pour vérifier la dernière version disponible :

root@host:~# wget https://developer.download.nvidia.com/compute/cuda/repos/debian13/x86_64/cuda-keyring_1.1-1_all.deb

root@host:~# dpkg -i cuda-keyring_1.1-1_all.deb

Le dépôt NVIDIA CUDA doit maintenant apparaître dans le fichier /etc/apt/sources.list.d/cuda-debian13-x86_64.list :

root@host:~# cat /etc/apt/sources.list.d/cuda-debian13-x86_64.list
deb [signed-by=/usr/share/keyrings/cuda-archive-keyring.gpg] https://developer.download.nvidia.com/compute/cuda/repos/debian13/x86_64/ /

💡 Remarque : Le nom du paquet CUDA Toolkit dépend du dépôt utilisé : cuda-toolkit dans le dépôt officiel NVIDIA, contre nvidia-cuda-toolkit dans les dépôts Debian.

Mettez à jour la liste des paquets et vérifiez la version de cuda-toolkit disponible. Dans cet exemple, le dépôt NVIDIA propose une version plus récente, adaptée à l’environnement vLLM utilisé dans ce guide :

root@host:~# apt update && apt policy cuda-toolkit
cuda-toolkit:
  Installed: (none)
  Candidate: 13.4.2-1

Installez les en-têtes du noyau Linux, le pilote nvidia-open et le paquet cuda-toolkit depuis le dépôt NVIDIA :

root@host:~# apt install linux-headers-$(uname -r) linux-headers-amd64 nvidia-open cuda-toolkit

Une fois l’installation terminée, redémarrez la machine afin de charger le nouveau pilote NVIDIA :

root@host:~# reboot

Après le redémarrage, exécutez nvidia-smi pour vérifier que le pilote NVIDIA est correctement installé et que votre GPU est détecté :

root@host:~# nvidia-smi
Tue Oct 10 20:11:37 2026
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 615.71.09              KMD Version: 615.71.09     CUDA UMD Version: 13.4     |
+-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA RTX A2000 12GB          On  |   00000000:21:00.0 Off |                  Off |
| 30%   33C    P8             11W /   70W |       2MiB /  12282MiB |      0%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI        PID   Type   Process name                              GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|  No running processes found                                                             |
+-----------------------------------------------------------------------------------------+

Vérifiez l’installation du CUDA Toolkit à l’aide de la commande nvcc --version :

root@host:~# /usr/local/cuda/bin/nvcc --version
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2026 NVIDIA Corporation
Built on Tue_Sep_01_08:45:21_PDT_2026
Cuda compilation tools, release 13.4, V13.4.92
Build cuda_13.4.r13.4/compiler.38855100_0

Le résultat confirme que le CUDA Toolkit 13.4 est installé. Le pilote NVIDIA et l’environnement CUDA étant prêts, nous pouvons passer à l’installation de vLLM.

Installer vLLM sur Debian dans un environnement Python

Le pilote NVIDIA et le CUDA Toolkit sont installés, et notre GPU est correctement détecté. Nous pouvons maintenant installer vLLM sur Debian.

Installez les paquets nécessaires, notamment les outils de développement Python et ninja-build, qui peut être requis pour compiler certains composants CUDA :

root@host:~# apt install -y python3-venv curl ca-certificates python3-dev build-essential ninja-build

Créez un utilisateur système dédié nommé vllm, avec /opt/vllm comme répertoire personnel. Le serveur vLLM pourra ainsi fonctionner sans les privilèges root :

root@host:~# useradd --system --create-home --home-dir /opt/vllm --shell /bin/false vllm

Installez ensuite uv, un gestionnaire rapide de paquets et d’environnements Python recommandé par le projet vLLM. Nous l’utiliserons pour créer un environnement Python isolé et installer vLLM sans modifier les paquets Python du système :

root@host:~# curl -LsSf https://astral.sh/uv/install.sh | sudo -u vllm sh

Placez-vous dans le répertoire /opt/vllm/, puis créez un environnement virtuel Python dédié avec Python 3.12 :

root@host:~# cd /opt/vllm/

root@host:~# sudo -u vllm /opt/vllm/.local/bin/uv venv /opt/vllm/.venv --python 3.12 --seed

Installez vLLM dans cet environnement virtuel. L’option --torch-backend=auto permet à uv de sélectionner automatiquement un moteur de calcul PyTorch adapté au matériel disponible et aux versions de CUDA prises en charge :

root@host:~# sudo -u vllm /opt/vllm/.local/bin/uv pip install --python /opt/vllm/.venv/bin/python vllm --torch-backend=auto

Vérifiez que vLLM est bien installé en affichant sa version :

root@host:~# sudo -u vllm /opt/vllm/.venv/bin/vllm --version

Télécharger et lancer le modèle Qwen avec vLLM

Ma machine de test dispose d’un GPU un peu ancien avec seulement 12 Go de VRAM. J’ai donc choisi Qwen/Qwen2.5-VL-3B-Instruct, un LLM relativement léger capable de traiter du texte et des images.

Contrairement à Ollama, qui permet de passer facilement d’un modèle à un autre au sein d’une même instance, vLLM sert généralement un modèle par processus. Pour proposer plusieurs modèles simultanément, il faut donc lancer des instances vLLM distinctes. Vous pourriez, par exemple, utiliser mistralai/Ministral-3-3B-Instruct-2512 sur le port 8000 et Qwen/Qwen2.5-VL-3B-Instruct sur le port 8001. Les deux modèles occuperaient alors la mémoire du GPU en même temps, sauf à les répartir sur des GPU différents.

Avec seulement 12 Go de VRAM, je me limiterai donc à un seul modèle dans ce guide.

Recherchez le modèle Qwen/Qwen2.5-VL-3B-Instruct sur Hugging Face avec l’outil en ligne de commande hf :

root@host:~# sudo -u vllm /opt/vllm/.venv/bin/hf models list --search Qwen/Qwen2.5-VL-3B-Instruct
ID                                      CREATED_AT DOWNLOADS LIBRARY_NAME LIKES PIPELINE_TAG       PRIVATE TAGS                                     TRENDING_SCORE
--------------------------------------- ---------- --------- ------------ ----- ------------------ ------- ---------------------------------------- --------------
Qwen/Qwen2.5-VL-3B-Instruct             2025-01-26   2115754 transformers   712 image-text-to-text         transformers, safetensors, qwen2_5_vl...              2
Qwen/Qwen2.5-VL-3B-Instruct-AWQ         2025-02-13    441614 transformers    68 image-text-to-text         transformers, safetensors, qwen2_5_vl...              0
DevQuasar-6/Qwen.Qwen2.5-VL-3B-Instr... 2025-03-26      1404                  5 image-text-to-text         gguf, image-text-to-text, base_model:...              0
MscAbdelrahman1/Qwen-Qwen2.5-VL-3B-I... 2026-09-19         0                  0                            safetensors, region:us                                0
Hint: Use `--no-truncate` or `--format json` to display full values.

Téléchargez le modèle Qwen/Qwen2.5-VL-3B-Instruct depuis Hugging Face. Les fichiers seront enregistrés dans le cache local Hugging Face pour pouvoir être chargés par vLLM :

root@host:~# sudo -u vllm /opt/vllm/.venv/bin/hf download Qwen/Qwen2.5-VL-3B-Instruct

💡 Remarque : Selon votre GPU, la quantité de VRAM disponible et le modèle utilisé, vous devrez peut-être ajuster les paramètres --max-model-len et --gpu-memory-utilization pour éviter les erreurs de mémoire insuffisante.

Lancez vLLM avec le modèle Qwen2.5-VL-3B-Instruct. Voici le rôle des principales options utilisées dans cet exemple :
- --host 127.0.0.1 : limite l’écoute de vLLM à l’interface de boucle locale. Comme Open WebUI s’exécutera sur la même machine avec le mode réseau hôte de Docker, il n’est pas nécessaire d’exposer directement l’API sur le réseau.
- --port 8000 : définit le port TCP d’écoute du serveur d’API vLLM.
- --max-model-len 5120 : fixe la longueur maximale du contexte à 5 120 tokens, en incluant la requête d’entrée et la réponse générée. Une valeur plus élevée nécessite davantage de mémoire GPU, notamment pour le cache KV.
- --gpu-memory-utilization 0.98 : fixe à 98 % la part de mémoire GPU que vLLM peut utiliser pour exécuter le modèle et gérer les ressources associées. Cette valeur laisse très peu de marge aux autres processus utilisant le GPU.
- --enforce-eager : désactive les graphes CUDA et utilise le mode d’exécution immédiate de PyTorch. Cela peut réduire la consommation de mémoire GPU, au prix d’une baisse des performances d’inférence.
- --mm-processor-cache-gb 0 : désactive le cache du processeur multimodal pour réduire l’utilisation de la mémoire vive du système. Cela peut affecter les performances lorsque les mêmes images sont traitées plusieurs fois.
- --enable-auto-tool-choice : active la sélection automatique des outils, permettant au modèle de décider quand appeler les outils mis à disposition par des applications comme Open WebUI.
- --tool-call-parser hermes : utilise l’analyseur Hermes pour interpréter les appels d’outils générés par le modèle Qwen2.5 et les renvoyer au format attendu par l’API.

root@host:~# sudo -u vllm env \
  CUDA_HOME=/usr/local/cuda \
  HF_HOME=/opt/vllm/hf-cache \
  PATH=/usr/local/cuda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
  /opt/vllm/.venv/bin/vllm serve Qwen/Qwen2.5-VL-3B-Instruct \
  --host 127.0.0.1 \
  --port 8000 \
  --max-model-len 5120 \
  --gpu-memory-utilization 0.98 \
  --enforce-eager \
  --mm-processor-cache-gb 0 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

Connecter vLLM à Open WebUI

Notre instance vLLM fonctionne. Nous allons maintenant la connecter à Open WebUI pour disposer d’une interface web conviviale. Plusieurs utilisateurs pourront ainsi interagir avec notre LLM local directement depuis leur navigateur.

Si vous disposez déjà d’une instance Open WebUI, ouvrez Paramètres (Settings) > Connexions (Connections), cliquez sur le bouton + dans la section OpenAI API, puis ajoutez votre serveur vLLM avec les paramètres suivants :
- URL : http://127.0.0.1:8000/v1
- Auth : None (aucune authentification de l’API n’a encore été configurée).
- API Type : Chat Completions
Enregistrez la connexion, puis cliquez sur le bouton principal Enregistrer (Save) pour appliquer les modifications.

Paramètres de connexion Open WebUI à l’API vLLM compatible OpenAI sur 127.0.0.1:8000 — Configuration de la connexion à l’API vLLM compatible OpenAI dans Open WebUI.

Si Open WebUI n’est pas encore installé, installez Docker, puis lancez le conteneur :

root@host:~# apt update && apt install docker.io

root@host:~# systemctl enable --now docker

root@host:~# docker run -d \
    --name open-webui \
    --network host \
    -v open-webui:/app/backend/data \
    -e OPENAI_API_BASE_URL=http://127.0.0.1:8000/v1 \
    --restart always \
    ghcr.io/open-webui/open-webui:main

Vous pouvez maintenant accéder à Open WebUI depuis votre navigateur à l’adresse http://DEBIAN_IP_ADDRESS:8080. Remplacez DEBIAN_IP_ADDRESS par l’adresse IP de votre serveur Debian.

Configurer le démarrage automatique de vLLM avec systemd

Notre instance vLLM fonctionne, mais elle ne redémarre pas automatiquement avec le serveur. Pour y remédier, nous allons créer un service systemd qui exécutera vLLM en arrière-plan et le lancera au démarrage de la machine.

Créez le répertoire de configuration /etc/vllm et le répertoire de journaux /var/log/vllm :

root@host:~# install -d -m 0755 -o root -g root /etc/vllm

root@host:~# touch /etc/vllm/env

root@host:~# chown root:vllm /etc/vllm/env && chmod 640 /etc/vllm/env

root@host:~# install -d -m 0755 -o vllm -g vllm /var/log/vllm

Modifiez ensuite le fichier /etc/vllm/env. Il permettra de définir le cache Hugging Face et d’activer le mode hors ligne, pour éviter que vLLM contacte Hugging Face lors du chargement du modèle déjà téléchargé :

# Répertoire de stockage des modèles téléchargés depuis Hugging Face.
HF_HOME=/opt/vllm/hf-cache

# Empêcher les requêtes vers Hugging Face Hub au chargement des modèles en cache.
# Les fichiers nécessaires au modèle doivent déjà être téléchargés.
HF_HUB_OFFLINE=1

# Authentification facultative de l’API (désactivée pour cette installation locale).
# VLLM_API_KEY=sk-cfg-please-rotate-me

Créez le fichier /etc/systemd/system/vllm.service pour configurer le service systemd. Il permettra d’exécuter vLLM en arrière-plan et de le lancer automatiquement au démarrage du serveur :

[Unit]
Description=vLLM OpenAI-compatible inference server
After=network-online.target nvidia-persistenced.service
Wants=network-online.target

[Service]
Type=simple
User=vllm
Group=vllm
WorkingDirectory=/opt/vllm
EnvironmentFile=/etc/vllm/env
Environment=CUDA_HOME=/usr/local/cuda
Environment=PATH=/usr/local/cuda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

ExecStart=/opt/vllm/.venv/bin/vllm serve Qwen/Qwen2.5-VL-3B-Instruct \
  --host 127.0.0.1 \
  --port 8000 \
  --gpu-memory-utilization 0.98 \
  --max-model-len 5120 \
  --enforce-eager \
  --mm-processor-cache-gb 0 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

Restart=on-failure
RestartSec=10
TimeoutStartSec=600
TimeoutStopSec=60
LimitNOFILE=1048576

NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/opt/vllm
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true

StandardOutput=journal
StandardError=journal
SyslogIdentifier=vllm

[Install]
WantedBy=multi-user.target

Avant d’activer le service, vérifiez que le fichier d’unité systemd ne contient pas d’erreurs de configuration :

root@host:~# systemd-analyze verify /etc/systemd/system/vllm.service

Rechargez la configuration de systemd pour prendre en compte le nouveau service :

root@host:~# systemctl daemon-reload

Activez le lancement automatique du service vLLM au démarrage et démarrez-le immédiatement :

root@host:~# systemctl enable --now vllm

Vérifiez que le service vLLM fonctionne correctement :

root@host:~# systemctl status vllm --no-pager

Vous pouvez également consulter les journaux du service pour suivre le chargement du modèle ou diagnostiquer un problème :

root@host:~# journalctl -u vllm -f

Une fois le modèle chargé, vérifiez que l’API vLLM répond correctement. La commande python3 -m json.tool permet de mettre en forme la réponse JSON pour la rendre plus lisible :

root@host:~# curl -sS http://127.0.0.1:8000/v1/models | python3 -m json.tool
{
    "object": "list",
    "data": [
        {
            "id": "Qwen/Qwen2.5-VL-3B-Instruct",
            "object": "model",
            "created": 1791835661,
            "owned_by": "vllm",
            "root": "Qwen/Qwen2.5-VL-3B-Instruct",
            "parent": null,
            "max_model_len": 5120,
            "permission": [
                {
                    "id": "modelperm-8be568c37905e68b",
                    "object": "model_permission",
                    "created": 1791835661,
                    "allow_create_engine": false,
                    "allow_sampling": true,
                    "allow_logprobs": true,
                    "allow_search_indices": false,
                    "allow_view": true,
                    "allow_fine_tuning": false,
                    "organization": "*",
                    "group": null,
                    "is_blocking": false
                }
            ]
        }
    ]
}

L’API vLLM répond correctement et notre modèle Qwen2.5-VL-3B-Instruct est disponible, avec une longueur maximale de contexte de 5120 tokens.

Conclusion

Nous disposons maintenant d’un serveur vLLM sur Debian, avec un LLM local exécuté sur notre GPU NVIDIA et accessible depuis Open WebUI. Cette installation permet à plusieurs utilisateurs d’interagir avec un modèle d’intelligence artificielle hébergé localement, directement depuis leur navigateur, sans recourir à un service d’IA externe dans le cloud.

Les performances et le nombre d’utilisateurs simultanés dépendent principalement du GPU, de la quantité de VRAM disponible et du modèle utilisé. Ma RTX A2000 12GB convient pour tester vLLM et expérimenter, mais un GPU plus puissant serait préférable pour un environnement de production accueillant de nombreux utilisateurs.

Pour aller plus loin, nous pourrions renforcer la sécurité de cette installation. Une première étape serait d’activer le HTTPS sur l’interface Open WebUI afin de chiffrer les échanges entre les utilisateurs et le serveur. Nous pourrions également restreindre les accès réseau et activer l’authentification de l’API vLLM.