TGI - Text Generation Inference - Installation, Configuration, Dépannage

Text Generation Inference (TGI) possède une énergie très particulière. Ce n’est pas le nouveau venu de la rue de l’inférence, mais c’est celui qui a déjà appris comment la production peut se briser -

puis intégré ces leçons dans les paramètres par défaut. Si votre objectif est « servir un LLM derrière HTTP et le maintenir en fonctionnement », TGI est un outil pragmatique.

Si vous hésitez encore sur l’endroit où faire tourner des modèles, cette comparaison de l’hébergement de LLM en 2026 rassemble les configurations locales, auto-hébergées et cloud pour vous permettre de contextualiser TGI.

Un retour à la réalité d’abord. En 2026, TGI est en mode maintenance et le dépôt amont a été archivé en lecture seule. Cela semble être une mauvaise nouvelle jusqu’à ce que l’on examine la situation du point de vue des opérations. Un moteur stable peut être une fonctionnalité, surtout lorsque le vrai changement se situe au niveau des modèles, des prompts et des exigences produit.

Ce guide se concentre sur quatre éléments qui comptent dès le jour zéro et le trentième jour : les chemins d’installation, un démarrage rapide qui fonctionne réellement, une configuration qui modifie le comportement réel, et une mentalité de dépannage qui fait gagner du temps.

Pourquoi TGI reste pertinent en 2026

Il est facile de considérer les serveurs d’inférence comme interchangeables. Pour une enquête détaillée outil par outil sur les piles locales courantes, commencez par Ollama vs vLLM vs LM Studio : La meilleure façon d’exécuter des LLM localement en 2026 ?.

En pratique, il n’y a que trois questions qui comptent.

Premièrement, comment se comporte-t-il sous charge ? TGI est construit autour du regroupement continu (continuous batching) et du streaming de tokens, ce qui lui permet de prioriser le débit tout en offrant aux utilisateurs l’illusion de réactivité.

Deuxièmement, peut-il parler le dialecte que votre outillage utilise déjà ? TGI prend en charge sa propre « API personnalisée » ainsi qu’une API Messages compatible avec le schéma de complétion de chat OpenAI. Cela signifie que les outils s’attendant à un endpoint de forme OpenAI peuvent souvent être pointés vers TGI avec des modifications minimales.

Troisièmement, pouvez-vous l’observer sans deviner ? TGI expose des métriques Prometheus et prend en charge le traçage distribué via OpenTelemetry, ce qui fait la différence entre « je pense que c’est lent » et « le préremplissage (prefill) est saturé, le temps de file d’attente augmente et le budget de tokens par lot est trop élevé ».

Chemins d’installation et prérequis

TGI peut être approché via Docker ou via une installation locale à partir des sources. La voie Docker est celle que la plupart des gens entendent lorsqu’ils disent « installer TGI », car elle regroupe le routeur, le serveur de modèle et les noyaux dans une image qui peut être exécutée avec une seule commande.

Sous le capot, TGI est un système avec des composants distincts : un routeur qui accepte les requêtes HTTP et effectue le regroupement, un lanceur (launcher) qui orchestre un ou plusieurs processus de serveur de modèle, et le serveur de modèle qui charge le modèle et effectue l’inférence. Cette séparation explique beaucoup de « pourquoi » derrière les drapeaux de configuration et les modes de défaillance courants.

Deux prérequis pratiques reviennent sans cesse : l’accès GPU depuis les conteneurs, et une stratégie de cache saine pour les poids du modèle. L’accès GPU pour Nvidia signifie généralement que le Nvidia Container Toolkit est installé, et le cache signifie mapper un volume d’hôte vers le conteneur pour que les poids du modèle ne se téléchargent pas à chaque fois.

Installation locale à partir des sources

Une installation à partir des sources existe, mais elle est orientée vers les développeurs et les constructeurs de noyaux. Elle s’attend à ce que Rust, Python 3.9+ et les outils de construction soient présents, et c’est généralement une première étape plus lente que l’exécution du conteneur. Utile lorsque vous devez modifier les composants internes, tester des correctifs ou intégrer à un environnement très spécifique.

Démarrage rapide avec Docker

Le démarrage rapide canonique est court, ce qui est exactement le but. Choisissez un identifiant de modèle, montez un volume de cache, exposez un port et lancez le conteneur.

Démarrage rapide GPU Nvidia

Ceci est un motif minimal qui fonctionne bien pour le premier démarrage.

model=HuggingFaceH4/zephyr-7b-beta
volume=$PWD/data

docker run --gpus all --shm-size 1g -p 8080:80 -v $volume:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id $model

Cette seule commande répond implicitement à une question FAQ fréquente, « Comment exécuter TGI avec Docker sur un GPU Nvidia », en montrant les trois éléments non négociables : --gpus all, un mappage de port et un identifiant de modèle.

Un point subtil mais important est le mappage de port. Le conteneur est généralement configuré pour servir HTTP sur le port 80, donc vous mappez l’hôte 8080 vers le conteneur 80. Si vous exécutez TGI en dehors de Docker, le port par défaut du lanceur est souvent 3000, ce qui explique pourquoi la confusion de port est une erreur si courante le premier jour.

Première requête utilisant l’API personnalisée

TGI expose une API JSON simple de style « generate ». Une requête en streaming ressemble à ceci.

curl 127.0.0.1:8080/generate_stream \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"Qu'est-ce que l'apprentissage profond ?","parameters":{"max_new_tokens":40}}'

Si vous préférez une réponse unique, utilisez l’endpoint non streamé.

curl 127.0.0.1:8080/generate \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"Expliquez le regroupement continu en un paragraphe.","parameters":{"max_new_tokens":120}}'

Première requête utilisant l’API Messages

Si votre écosystème s’attend à des requêtes de chat de style OpenAI, utilisez l’API Messages. Cela se rapporte directement à une autre question FAQ, « Comment utiliser TGI avec des clients de chat compatibles OpenAI ».

curl 127.0.0.1:8080/v1/chat/completions \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "Vous êtes un assistant concis."},
      {"role": "user", "content": "Donnez une définition en une phrase du parallélisme de tenseur."}
    ],
    "stream": false,
    "max_tokens": 60
  }'

Servir des modèles verrouillés ou privés

Si vous vous êtes déjà demandé « Comment servir des modèles Hugging Face verrouillés ou privés avec TGI », la réponse est ennuyeuse par conception : fournissez un token Hub via HF_TOKEN.

model=meta-llama/Meta-Llama-3.1-8B-Instruct
volume=$PWD/data
token=hf_your_read_token_here

docker run --gpus all --shm-size 1g -e HF_TOKEN=$token -p 8080:80 -v $volume:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id $model

Le mode de défaillance ici est également ennuyeux : permissions manquantes, plages de token invalides, ou tentative de tirage d’un modèle nécessitant l’acceptation d’une licence.

Démarrage rapide AMD ROCm

TGI possède également des images ROCm et une configuration de dispositif différente. Si vous utilisez des GPU AMD, la forme du démarrage change.

model=HuggingFaceH4/zephyr-7b-beta
volume=$PWD/data

docker run --device /dev/kfd --device /dev/dri --shm-size 1g -p 8080:80 -v $volume:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5-rocm \
  --model-id $model

Exécutions CPU uniquement

Les exécutions CPU existent, mais elles ne constituent pas la plateforme pour laquelle TGI a été conçu pour être brillant. Lorsque vous le faites quand même, désactiver les noyaux personnalisés évite certains problèmes spécifiques au matériel.

model=gpt2
volume=$PWD/data

docker run --shm-size 1g -p 8080:80 -v $volume:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id $model \
  --disable-custom-kernels

Configuration qui fait réellement bouger les aiguilles

TGI a beaucoup de drapeaux. La plupart ne valent pas la peine d’être mémorisés. Quelques-uns méritent d’être compris, car ils répondent à la question la plus recherchée dans ce domaine : « Quels réglages TGI contrôlent la mémoire GPU et les limites de requête ».

Le budget mémoire est le nombre total maximal de tokens

Le concept le plus important dans la configuration TGI est que le serveur a besoin d’un budget de tokens pour planifier le regroupement et éviter les explosions de mémoire.

Il y a deux plafonds qui définissent la forme de la requête : max_input_tokens et max_total_tokens.

max_total_tokens agit comme un budget mémoire par requête car il borne les tokens d’entrée plus les tokens générés. S’il est trop élevé, chaque requête devient coûteuse, le regroupement devient gênant et la pression mémoire augmente. S’il est trop bas, les utilisateurs rencontrent des limites de longueur tôt, et le serveur rejette des charges de travail autrement valides.

Une configuration qui rend le budget explicite ressemble à ceci.

docker run --gpus all --shm-size 1g -p 8080:80 -v $PWD/data:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id HuggingFaceH4/zephyr-7b-beta \
  --max-input-tokens 2048 \
  --max-total-tokens 3072

Les boutons de regroupement qui comptent

Une fois les budgets de tokens définis, le contrôle du regroupement est le prochain levier.

max_batch_prefill_tokens limite le travail de préremplissage, qui est souvent la phase la plus gourmande en mémoire et en calcul. max_batch_total_tokens définit combien de tokens le serveur essaie de faire entrer dans un lot au total. C’est l’un des vrais contrôles de débit.

Le bouton intéressant est waiting_served_ratio. Il encode une décision de politique, pas une contrainte matérielle. Il contrôle quand le serveur met en pause le travail de décodage en cours pour amener les requêtes en attente dans un nouveau préremplissage afin qu’elles puissent rejoindre le groupe de décodage. Les valeurs basses ont tendance à favoriser les requêtes existantes, les valeurs élevées ont tendance à réduire la latence de la queue pour les nouvelles requêtes, et les deux peuvent être « corrects » selon la forme du trafic.

Sharding, num shard, et pourquoi NCCL apparaît

Si votre modèle ne tient pas sur un seul GPU, ou si vous voulez un débit plus élevé via le parallélisme de tenseur, le sharding est l’étape suivante.

Le modèle mental est simple : --sharded true active le sharding, et --num-shard contrôle le nombre de shards. Le serveur peut utiliser tous les GPU visibles par défaut, ou utiliser un sous-ensemble.

Un motif utile sur les hôtes multi-GPU consiste à diviser les GPU en groupes et à exécuter plusieurs répliques TGI, chaque réplique étant sharded sur son propre sous-ensemble de GPU. Cela répartit la charge tout en gardant la topologie de sharding simple.

C’est aussi là où la question FAQ « Pourquoi TGI échoue avec des erreurs NCCL ou de mémoire partagée sur plusieurs GPU » devient pertinente. Les configurations multi-GPU reposent sur une communication collective, et les conteneurs ont besoin d’assez de mémoire partagée pour un fonctionnement sûr lorsque la bascule SHM est utilisée.

Choix de quantification et ce qu’ils échan

La quantification est le paramètre « faire tenir » le plus incompris car il mélange deux objectifs différents : la réduction de mémoire et la vitesse.

TGI prend en charge des poids pré-quantifiés pour des schémas comme GPTQ et AWQ, ainsi qu’une quantification à la volée pour certaines méthodes comme bitsandbytes et EETQ. Certaines méthodes réduisent la mémoire mais sont plus lentes que la précision native demi-précision, c’est pourquoi la quantification ne doit pas être traitée comme une mise à niveau de performance gratuite.

Un exemple simple de quantification 8 bits à la volée ressemble à ceci.

docker run --gpus all --shm-size 1g -p 8080:80 -v $PWD/data:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id HuggingFaceH4/zephyr-7b-beta \
  --quantize bitsandbytes

Et une variante 4 bits ressemble à ceci.

docker run --gpus all --shm-size 1g -p 8080:80 -v $PWD/data:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id HuggingFaceH4/zephyr-7b-beta \
  --quantize bitsandbytes-nf4

Façonnage de l’API et garde-fous de base

TGI peut être exécuté comme un service interne, ou exposé plus largement. Si l’exposition est possible, deux drapeaux comptent : max_concurrent_requests et api_key.

max_concurrent_requests fournit une contre-pression. Il fait refuser au serveur les requêtes excessives plutôt que de laisser tout s’accumuler dans la file d’attente et expirer.

Une clé API fournit une barrière d’authentification grossière. Ce n’est pas un système d’auth complet, mais cela empêche une utilisation publique accidentelle.

CORS est également configurable via cors_allow_origin, ce qui est important si une interface utilisateur basée sur un navigateur appelle le serveur directement.

Opérations et observabilité

Cette section répond à la vraie question de l’opérateur : « Où pouvez-vous scraper les métriques Prometheus d’un serveur TGI ».

Documentation OpenAPI et documentation interactive

TGI expose son OpenAPI et son interface Swagger sous la route /docs, ce qui est pratique lorsque vous voulez confirmer rapidement les formes de requête et de réponse ou tester des endpoints sans écrire un client.

Métriques Prometheus

TGI exporte des métriques Prometheus sur l’endpoint /metrics. Ces métriques couvrent la taille de la file d’attente, la latence des requêtes, les décomptes de tokens et les temps de niveau de lot. Le résultat est que vous pouvez observer si le système est limité par le préremplissage, le décodage ou la file d’attente.

La surveillance de bout en bout en production — PromQL, tableaux de bord Grafana, alertes, et configurations de scraping Docker ou Kubernetes pour ces piles — est couverte dans Surveiller l’inférence LLM en production (2026) : Prometheus & Grafana pour vLLM, TGI, llama.cpp.

Traçage et logs structurés

TGI prend en charge le traçage distribué via OpenTelemetry. Les logs peuvent également être émis en JSON, ce qui rend les pipelines de logs plus faciles.

Playbook de dépannage

Les défaillances de TGI ont tendance à se regrouper en quelques catégories, et chaque catégorie a une correction très différente.

Le conteneur tourne mais aucun GPU n’est détecté

La cause la plus courante est que le runtime du conteneur n’est pas configuré pour la transparence GPU. Sur Nvidia, cela corrèle souvent avec un manque de support pour Nvidia Container Toolkit, ou une exécution sur une pile de pilotes d’hôte qui ne correspond pas aux attentes.

Échecs de téléchargement de modèle et erreurs de permission

Si le serveur ne peut pas télécharger les fichiers de modèle, les coupables habituels sont un token d’auth manquant pour les modèles verrouillés, un token sans permissions de lecture de modèle, ou des limites de taux. Définir correctement HF_TOKEN résout le cas des modèles verrouillés.

CUDA out of memory ou redémarrages soudains sous charge

La cause la plus courante est des budgets de tokens trop permissifs. Si max_total_tokens est grand et que les clients demandent de longues générations, le serveur réservera de la mémoire pour les requêtes de pire cas. Réduisez le budget, réduisez la concurrence, ou choisissez une méthode de quantification qui correspond à vos contraintes.

Erreurs NCCL multi-GPU, blocages ou ralentissements extrêmes

Lors du sharding sur plusieurs GPU, la mémoire partagée et NCCL comptent. Une mémoire partagée insuffisante à l’intérieur des conteneurs crée souvent une instabilité. Augmenter l’allocation de mémoire partagée ou désactiver le partage SHM via NCCL_SHM_DISABLE peut changer le comportement, avec un compromis de performance.

Les problèmes NCCL deviennent également plus faciles à déboguer lorsque le journal de débogage NCCL est activé, car les rapports d’erreur sont plus explicites.

Erreurs de noyau bizarres sur du matériel non A100

Certains modèles utilisent des noyaux personnalisés qui ont été testés sur du matériel spécifique en premier. Si vous voyez des échecs de noyau inexpliqués, --disable-custom-kernels est fréquemment le moyen le plus simple de confirmer si des noyaux personnalisés sont impliqués.

Confusion de port et « ça tourne mais je ne peux pas y accéder »

Une classique erreur est de mélanger le modèle de mappage de port Docker avec le modèle de port par défaut local. Dans les exemples Docker, le conteneur sert communément sur 80, tandis que les exécutions locales par défaut sur 3000. Si vous mappez le mauvais port, vos requêtes curl atterrissent sur rien, et le système semble cassé alors qu’il est en fait juste inaccessible.

Note de clôture

TGI ressemble à une infrastructure. C’est un compliment. C’est un système conçu pour rendre la génération de texte assez ennuyeuse pour être exploitée, assez mesurable pour être déboguée, et assez flexible pour s’intégrer dans les piles de clients existants de forme OpenAI.