vLLM (vllm)

Moteur d'inférence de production avec une API compatible OpenAI : un modèle par installation, servi sur des hôtes GPU NVIDIA (parallélisme tensoriel sur plusieurs GPU d'un hôte, parallélisme de pipeline Ray entre hôtes) ou sur des hôtes CPU (build x86 AVX512 ou AVX2). Les poids du modèle sont hébergés sur l'hôte (cache Hugging Face ou dossiers importés), jamais téléchargés au démarrage en mode hors ligne. Enregistré automatiquement dans LiteLLM.

Généré depuis catalog/services/vllm.yaml : ne pas modifier à la main.

Résumé

Version	0.33.0
Usage	installer et configurer, configurer et connecter
Couche	fonctionnelle (catalogue IA)
Catégorie	Inférence IA
Méthodes d'installation	podman
Connexion externe	non
Réservé au bac à sable	non

Licence

Identifiant SPDX	Apache-2.0
Politique de licence	licence socle (MIT ou Apache-2.0)
Exception de licence	-
Composant de la plateforme	vllm

Paquets et artefacts

Un paquet que publie le projet du service (son image, son archive binaire, son paquet Python ou système) porte la licence du service ; un paquet tiers porte la licence écrite sur sa ligne, lue dans les métadonnées officielles du projet amont.

Type	Paquet	Version	Licence	Détails
image de conteneur	docker.io/vllm/vllm-openai	v0.33.0	Apache-2.0	clé d'image vllm, utilisée par server, ray-worker, condensé sha256:d825baf9ce4b1b6bfc5ecc7b79880c7e6748c65a72d697ce3d47607aafa84c6e
image de conteneur	docker.io/vllm/vllm-openai-cpu	v0.33.0-x86_64	Apache-2.0	clé d'image vllm_cpu, utilisée par server, ray-worker, condensé sha256:4154467a886f8b7ffa9dbab32f873f5ca4528409d042a6ec866e8888223263d3

Les images sont épinglées par étiquette dans le descripteur, et par condensé (digest) quand le descripteur en déclare un (le bundle hors ligne refuse alors une image téléchargée qui ne le porte pas) ; le condensé est enregistré dans le miroir du Manager à l'import du bundle hors ligne, et chaque téléchargement ou chargement est vérifié par rapport à lui.

Systèmes et architectures pris en charge

Méthode	Systèmes d'exploitation	Architectures
podman	famille RHEL (dnf), famille Debian (apt), Arch Linux (pacman)	x86_64, aarch64 (non restreintes par le descripteur)

Systèmes hôtes certifiés : RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). Le contrôle préalable des hôtes accepte ces systèmes (une autre version d'une famille connue donne un avertissement, une version en fin de vie est refusée) et les architectures x86_64 et aarch64.

GPU : GPU NVIDIA donnés au composant comme périphériques CDI (nvidia.com/gpu) : server (quand la configuration le demande), ray-worker (quand la configuration le demande).

Prérequis

Hôte

• au moins 8192 Mo de mémoire (bloquant, memory).
• au moins 1 GPU NVIDIA avec 8000 Mo de mémoire, seulement quand accelerator vaut gpu (bloquant, gpu).
• au moins 8 CPU, seulement quand accelerator vaut cpu (avertissement, cpu_cores).
• le programme podman installé sur l'hôte (bloquant, podman).
• au moins 51200 Mo libres pour /var/lib/navin (avertissement, model_disk).

Programmes que les commandes et les contrôles du service lancent sur l'hôte, hors des racines gérées : les ajouter à allowed_commands de l'agent (voir Sécurité de l'agent Navin), sinon l'agent les refuse avec command_not_allowed : /usr/bin/nvidia-smi, /usr/bin/podman.

Réseau et ports

Composant	Nom du port	Port	Ouvert dans le pare-feu de l'hôte
server	api	8000/tcp	oui
server	ray	6379/tcp	oui
server	ray_node	6381-6382/tcp	oui
server	ray_workers	20000-20199/tcp	oui
ray-worker	ray_node	6381-6382/tcp	oui
ray-worker	ray_workers	20000-20199/tcp	oui

Services et connexions nécessaires

Ce service n'a aucune dépendance.

Méthodes et modes d'installation

Méthode	Défaut	Ce que la méthode utilise
podman	oui	les images de conteneur du descripteur, exécutées par Podman sous systemd

Composants

Composant	Type	Méthodes d'installation	Ports
Serveur vLLM (server)	maître	podman	8000/tcp, 6379/tcp, 6381-6382/tcp, 20000-20199/tcp
Worker Ray (ray-worker)	travailleur	podman	6381-6382/tcp, 20000-20199/tcp

Instance unique (bac à sable) (single) (par défaut)

Un moteur sur un hôte CPU ou GPU.

Ce que le mode déploie :

Composant	Placement
server	min 1, max 1
ray-worker	non utilisé

Répliqué (haute disponibilité) (replicated)

Instances indépendantes du même modèle sur des hôtes distincts ; LiteLLM répartit, réessaie et bascule entre elles.

Ce que le mode déploie :

Composant	Placement
server	min 2, recommandé 2
ray-worker	non utilisé

Multi nœud (gros modèle) (distributed)

Un gros modèle réparti entre hôtes GPU avec Ray (parallélisme de pipeline) : un hôte serveur et des hôtes workers Ray. Pas de haute disponibilité à lui seul.

Ce que le mode déploie :

Composant	Placement
server	min 1, max 1
ray-worker	min 1, recommandé 1

Installer ce service

L'assistant d'installation du Navin Manager planifie, valide et exécute l'installation ; il faut la permission services:install sur le cluster.

1. Ouvrez l'assistant. Dans Clusters, choisissez l'action de ligne Installer des services du cluster cible. L'assistant s'ouvre sur sa première étape, Service.

2. Choisissez le service. À l'étape Service, sélectionnez vLLM. La carte affiche la licence Apache-2.0.

3. Choisissez les hôtes et le mode. À l'étape Hôtes, cochez les hôtes, puis choisissez le Mode : single (par défaut), replicated, distributed. Chaque mode déploie les composants listés dans Méthodes et modes d'installation. Avec plusieurs composants, placez chacun sur ses hôtes dans Répartition des composants (Proposer un placement propose un placement qui respecte les cardinalités).

4. Liaisons. Ce service n'a aucune dépendance : l'étape Liaisons n'a rien à lier.

5. Configurez. À l'étape Configuration, relisez les paramètres (voir Paramètres de configuration) ; les paramètres obligatoires sont model. Les mots de passe laissés vides avec une valeur générée par défaut sont générés et scellés par le Manager.

6. Relisez et installez. À l'étape Installation, le Manager valide le plan et affiche l'ordre d'installation ; quand il indique « Le plan est valide. Prêt pour l'installation. », choisissez Installer. Un mode hautement disponible n'est installé que si ses contrôles HA réussissent.

7. Vérifiez. L'opération se termine quand les contrôles de santé de chaque instance réussissent (voir Contrôles de santé) ; le service apparaît alors en marche dans Services.

Connecter un service existant

Schémas	https, http
Port par défaut	8000
Authentification	facultative
Contrôle de santé	/health

Méthode d'authentification	Champs	Description
bearer	token	Clé de --api-key (ou VLLM_API_KEY), envoyée en Authorization: Bearer sur l'API compatible OpenAI.
none	-	Sans --api-key, l'API compatible OpenAI de vLLM est ouverte à quiconque l'atteint.

Documentation officielle : https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html

Haute disponibilité

Cluster	réplicas (replication)
Haute disponibilité	redondance (redundancy)
Bascule	côté client (client)
Réplication	aucun (none)
Quorum	aucun (none)
Découverte	statique (static)
Point d'entrée	n'importe quel nœud (any-node)
Documentation officielle	https://docs.vllm.ai/en/latest/serving/parallelism_scaling.html
Références	https://docs.vllm.ai/en/latest/deployment/k8s.html, https://docs.litellm.ai/docs/routing

Prérequis

Prérequis	Doit être hautement disponible	Modes	Description
litellm	oui	replicated	LiteLLM hautement disponible (deux proxys ou plus) : il répartit, réessaie et bascule entre les répliques ; les agents et les applications n'appellent jamais vLLM directement.

Topologie par mode

Modes	Niveau le plus haut du catalogue	Répartition	Composant du quorum	Domaines de panne	Description
single	autonome (standalone)	unique (single)	-	1	Un moteur sur un hôte CPU ou GPU, sans tolérance aux pannes.
replicated	ha (ha)	actif-actif (active-active)	-	2	Répliques indépendantes du même modèle sur des hôtes distincts, chacune avec ses GPU et sa copie des poids ; LiteLLM bascule entre elles.
distributed	autonome (standalone)	unique (single)	-	1	Un gros modèle réparti entre hôtes GPU avec Ray : chaque hôte est nécessaire et la perte d'un seul arrête le modèle.

Remarques

• Répartir un modèle sur plusieurs GPU ou hôtes n'est pas de la haute disponibilité : un modèle critique demande le mode répliqué, ou une deuxième installation indépendante sous le même nom de modèle servi derrière LiteLLM.
• Le paramètre TLS protège l'API compatible OpenAI du serveur (avec /health, /metrics et /docs). Les ports Ray du mode distribué (tête, gestionnaire de nœud, gestionnaire d'objets et ports des workers) et le trafic NCCL entre les étapes du pipeline restent en clair : garder les hôtes du mode distribué sur un réseau interne de confiance. La page /docs charge Swagger UI depuis un CDN public : sur un hôte sans Internet, ajouter --enable-offline-docs à extra_args.

Paramètres de configuration

Modèle et hébergement

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
Modèle (model)	string	Qwen/Qwen3-0.6B	-	oui	non	oui	Identifiant Hugging Face du modèle (source cache, conservé dans le cache Hugging Face de l'hôte sous /var/lib/navin/vllm/models/hf) ou nom du dossier des poids importés sous /var/lib/navin/vllm/models/local (source local).
Source du modèle (model_source)	enum	cache	cache, local	non	non	oui	cache : cache Hugging Face de l'hôte (rempli par la commande download_model ou copié) ; local : poids validés importés dans un dossier de l'hôte.
Nom du modèle servi (served_model_name)	string	qwen-local	^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$	non	non	oui	Nom du modèle dans l'API et dans l'entrée LiteLLM ; les répliques d'un même modèle le partagent pour que LiteLLM répartisse entre elles.
Exécuteur (runner)	enum	auto	auto, generate, pooling	non	non	oui	generate pour les modèles de conversation et de complétion, pooling pour les modèles de plongement et de reclassement (enregistrés comme embedding dans LiteLLM).
Modèle de vision (VLM) (vision)	bool	false	-	non	non	non	Le modèle lit des images et des vidéos (par exemple Qwen3-VL, ou un VLM affiné avec LLaMA-Factory) : LiteLLM le déclare avec supports_vision. Le nombre d'images ou de vidéos par requête va dans extra_args, par exemple --limit-mm-per-prompt puis {"image": 4, "video": 1}.
Hors ligne (offline)	bool	true	-	non	non	oui	Ne jamais télécharger au démarrage (HF_HUB_OFFLINE=1) : les poids doivent déjà être sur l'hôte. Obligatoire pour un hôte de production sans Internet.
Miroir du dépôt de modèles (hf_endpoint)	string	(vide)	-	non	non	non	Miroir interne compatible Hugging Face utilisé par download_model (HF_ENDPOINT), vide pour huggingface.co.
Jeton du dépôt (hf_token)	password	-	-	non	oui	non	Jeton des modèles à accès restreint du dépôt (HF_TOKEN), facultatif.

Hôte CPU ou GPU

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
Type d'hôte (accelerator)	enum	gpu	gpu, cpu	non	non	oui	gpu : hôte GPU NVIDIA (pilote et spécification CDI du NVIDIA Container Toolkit requis) ; cpu : hôte CPU x86 (AVX512 recommandé), pour les petits modèles et les bacs à sable.
GPU (gpu_devices)	string	all	^(all|[A-Za-z0-9-]+(,[A-Za-z0-9-]+)*)$	non	non	oui	GPU donnés au moteur : all, ou une liste d'index ou d'UUID séparés par des virgules (GPU dédiés d'un pool de locataire).
VRAM minimale par GPU (min_gpu_memory_mb)	int	8000	min 0, max 1048576	non	non	non	Prévérification : VRAM qu'un GPU de l'hôte doit avoir (Mo).
Cache KV CPU (cpu_kvcache_space_gb)	int	8	min 1, max 1024	non	non	oui	Cache KV d'un hôte CPU en Go (VLLM_CPU_KVCACHE_SPACE).
Cœurs CPU (cpu_threads_bind)	string	auto	-	non	non	oui	Cœurs des threads OpenMP d'un hôte CPU (VLLM_CPU_OMP_THREADS_BIND) : auto, ou une plage comme 0-31.

Service et mémoire

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
GPU par instance (tensor_parallel_size)	int	1	min 1, max 16	non	non	oui	Parallélisme tensoriel : le modèle est réparti sur ce nombre de GPU de chaque hôte. Répartir n'est pas de la haute disponibilité : utiliser le mode répliqué pour cela.
Part de mémoire GPU (gpu_memory_utilization)	float	0.85	min 0.1, max 0.98	non	non	oui	Part de la VRAM de chaque GPU que vLLM réserve aux poids et au cache KV.
Longueur de contexte (max_model_len)	int	8192	min 256, max 1048576	non	non	oui	Nombre maximal de jetons d'une requête (invite et réponse).
Séquences simultanées (max_num_seqs)	int	128	min 1, max 4096	non	non	oui	Requêtes regroupées par l'ordonnanceur.
Type de données (dtype)	enum	auto	auto, bfloat16, float16, float32	non	non	oui	Précision des poids et des activations (bfloat16 sur les hôtes CPU).
Quantification (quantization)	string	(vide)	^(|awq|gptq|fp8|compressed-tensors|awq_marlin|gptq_marlin)$	non	non	oui	Méthode de quantification des poids, vide pour la détecter depuis le modèle.
Mémoire partagée (shm_size)	string	8g	^[0-9]+[mg]$	non	non	oui	Taille de /dev/shm du conteneur (le parallélisme tensoriel l'utilise).
Arguments supplémentaires (extra_args)	list	[]	-	non	non	oui	Autres arguments de vllm serve, un par élément (par exemple --enable-prefix-caching).

Multi nœud (Ray)

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
Étapes du pipeline (pipeline_parallel_size)	int	2	min 2, max 64	non	non	oui	Hôtes entre lesquels le modèle est réparti (serveur et workers Ray) ; en général le nombre d'hôtes du mode distribué. (distributed)
Port de la tête Ray (ray_port)	port	6379	-	non	non	oui	Port de la tête Ray (GCS) sur l'hôte serveur. (distributed)
Port du nœud Ray (ray_node_port)	port	6381	-	non	non	oui	Port du gestionnaire de nœud de chaque nœud Ray (le gestionnaire d'objets utilise le port suivant). (distributed)
Premier port des workers Ray (ray_worker_port_start)	port	20000	-	non	non	oui	Premier port des processus de travail Ray (autorisé entre les hôtes du service). (distributed)
Dernier port des workers Ray (ray_worker_port_end)	port	20199	-	non	non	oui	Dernier port des processus de travail Ray. (distributed)

Réseau

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
Port de l'API (port)	port	8000	-	non	non	oui	Port de l'API compatible OpenAI, de /health et de /metrics ; atteint par LiteLLM uniquement.

Sécurité

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
Clé d'API (api_key)	password	généré	-	non	oui	non	Clé exigée sur /v1 (VLLM_API_KEY) ; transmise à LiteLLM par la liaison, jamais aux agents.
TLS (tls_enabled)	bool	false	-	non	non	oui	Servir l'API compatible OpenAI, /health, /metrics et /docs en TLS avec le certificat que le Manager émet pour chaque hôte depuis son autorité (--ssl-certfile, --ssl-keyfile, --ssl-ca-certs, rechargés au renouvellement par --enable-ssl-refresh) ; LiteLLM appelle alors le moteur en https et vérifie l'autorité du Manager. Les ports Ray du mode distribué restent en clair entre les hôtes du service.
Niveau de journalisation (log_level)	enum	INFO	DEBUG, INFO, WARNING, ERROR	non	non	non	Verbosité du journal du moteur (VLLM_LOGGING_LEVEL).

Points d'accès

Point d'accès	Schéma	Composant	Port	Chemin	Paramètre TLS	Paramètres de liaison	Secrets de liaison	Commande de provisionnement
api	http	server	8000 (port)	/v1	tls_enabled	model, mode, engine, vision	api_key	-

Commandes

Commande	Composant	Cible	Description
Modèles servis (models)	server	tous les hôtes	Liste les modèles que sert chaque instance (GET /v1/models avec la clé d'API).
Télécharger un modèle (download_model)	server	tous les hôtes	Télécharge les poids d'un modèle Hugging Face dans le cache de chaque hôte du service (depuis huggingface.co ou le miroir interne) ; régler ensuite le paramètre model.
Télécharger un modèle sur les workers Ray (download_model_workers)	ray-worker	tous les hôtes	Même téléchargement sur chaque hôte worker Ray du mode distribué.
Modèles hébergés (hosted_models)	server	tous les hôtes	Modèles stockés sur chaque hôte : cache Hugging Face et dossiers importés, avec leur taille.
Supprimer un modèle hébergé (delete_model)	server	tous les hôtes	Supprime les poids d'un modèle qui n'est plus servi du cache et des dossiers importés de chaque hôte. (demande une confirmation)
État des GPU (gpu_status)	server	tous les hôtes	Utilisation, mémoire et température des GPU de chaque hôte (nvidia-smi).
État du cluster Ray (ray_status)	server	premier hôte	Nœuds et ressources du cluster Ray du mode distribué.
Journaux récents (logs)	server	hôte choisi	Dernières lignes du journal du moteur.

Paramètres des commandes

Commande	Paramètre	Type	Défaut	Obligatoire	Description
download_model	Dépôt (repo)	string	-	oui	Identifiant Hugging Face, par exemple Qwen/Qwen3-8B.
download_model	Révision (revision)	string	main	non	Branche, étiquette ou commit des poids validés.
download_model_workers	Dépôt (repo)	string	-	oui	Identifiant Hugging Face, par exemple Qwen/Qwen3-8B.
download_model_workers	Révision (revision)	string	main	non	Branche, étiquette ou commit des poids validés.
delete_model	Modèle (repo)	string	-	oui	Identifiant Hugging Face (cache) ou nom du dossier importé.

Contrôles de santé

Vivacité (par instance)

Composant	Contrôle	Détails
server	HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn if config.tls_enabled else (host.ip or '127.0.0.1') }}:{{ config.port }}/health	Attendu 200 ; 120 tentatives ; intervalle 10 s ; délai 5 s
ray-worker	TCP {{ host.ip or '127.0.0.1' }}:{{ config.ray_node_port }}	60 tentatives ; intervalle 5 s ; délai 5 s

Disponibilité (contrôle du service)

Contrôle	Détails
HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn if config.tls_enabled else (host.ip or '127.0.0.1') }}:{{ config.port }}/health	Attendu 200 ; 10 tentatives ; intervalle 5 s ; délai 10 s

Contrôles préalables

Contrôle	Type	Signification	Sévérité	Composants
memory	memory_mb {"min": 8192}	au moins 8192 Mo de mémoire	bloquant	tous les composants
gpu	gpu {"min_count": 1, "min_memory_mb": 8000}	au moins 1 GPU NVIDIA avec 8000 Mo de mémoire, seulement quand accelerator vaut gpu	bloquant	tous les composants
cpu_cores	cpu_count {"min": 8}	au moins 8 CPU, seulement quand accelerator vaut cpu	avertissement	tous les composants
podman	binary {"name": "podman"}	le programme podman installé sur l'hôte	bloquant	tous les composants
model_disk	disk_free_mb {"path": "/var/lib/navin", "min": 51200}	au moins 51200 Mo libres pour /var/lib/navin	avertissement	tous les composants
api_port_free	port_free {"param": "port"}	port 8000 libre sur l'hôte	bloquant	server

Désinstallation

Chemins supprimés quand les données sont purgées : {{ paths.data }}, {{ paths.log }}.

Liens rapides

• Métriques : {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/metrics
• Documentation de l'API : {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/docs

Documentation amont

• Site : https://docs.vllm.ai
• Sources : https://github.com/vllm-project/vllm
• Haute disponibilité : https://docs.vllm.ai/en/latest/serving/parallelism_scaling.html
• Haute disponibilité : https://docs.vllm.ai/en/latest/deployment/k8s.html
• Haute disponibilité : https://docs.litellm.ai/docs/routing
• Authentification : https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html