TGI – Text Generation Inference – Installation, Konfiguration, Fehlerbehebung

Text Generation Inference (TGI) hat eine sehr spezifische Energie. Es ist nicht das neueste Kind auf der Inferenz-Straße, aber es ist dasjenige, das bereits gelernt hat, wie Produktion funktioniert –

und diese Lehren in die Standardwerte eingearbeitet hat. Wenn Ihr Ziel lautet, „ein LLM hinter HTTP bereitzustellen und am Laufen zu halten", ist TGI ein pragmatisches Werkzeug.

Wenn Sie noch abwägen, wo Sie Modelle ausführen sollen, fasst dieser Vergleich von LLM-Hosting im Jahr 2026 lokale, selbst gehostete und Cloud-Setups zusammen, damit Sie TGI in den Kontext einordnen können.

Zuerst eine Realitätsprüfung. Stand 2026 befindet sich TGI im Wartungsmodus und das Upstream-Repository wurde als schreibgeschützt archiviert. Das klingt zunächst nach schlechten Nachrichten, bis man es aus einer Betriebsperspektive betrachtet. Ein stabiler Motor kann ein Merkmal sein, besonders wenn die eigentlichen Veränderungen in Modellen, Prompts und Produktanforderungen liegen.

Dieser Leitfaden konzentriert sich auf vier Dinge, die am Tag Null und am Tag Dreißig wichtig sind: Installationspfade, ein Quickstart, der tatsächlich funktioniert, Konfigurationen, die echtes Verhalten ändern, und eine Fehlerbehebungsmentalität, die Zeit spart.

Warum TGI 2026 immer noch wichtig ist

Es ist leicht, Inferenzserver als austauschbar zu behandeln. Für eine Tool-für-Tool-Übersicht gängiger lokaler Stacks, beginnen Sie mit Ollama vs. vLLM vs. LM Studio: Bestes Weg, LLMs lokal im Jahr 2026 auszuführen?.

In der Praxis gibt es nur drei Fragen, die zählen.

Erstens: Wie verhält es sich unter Last? TGI ist um kontinuierliches Batching und Token-Streaming herum aufgebaut, sodass es den Durchsatz priorisieren kann, während es den Nutzern dennoch den Anschein von Reaktionsfähigkeit gibt.

Zweitens: Kann es die Dialekt sprechen, den Ihr Tooling bereits spricht? TGI unterstützt seine eigene „benutzerdefinierte API" sowie eine Messages-API, die mit dem OpenAI Chat Completions-Schema kompatibel ist. Das bedeutet, dass Tooling, das einen OpenAI-förmigen Endpunkt erwartet, oft mit minimalen Änderungen auf TGI ausgerichtet werden kann.

Drittens: Können Sie es beobachten, ohne zu raten? TGI stellt Prometheus-Metriken bereit und unterstützt verteilte Tracing über OpenTelemetry. Das ist der Unterschied zwischen „Ich denke, es ist langsam" und „Prefill sättigt sich, die Warteschlangenzeit wächst und das Token-Budget für Batches ist zu hoch".

Installationspfade und Voraussetzungen

TGI kann über Docker oder durch eine lokale Installation aus dem Quellcode angesprochen werden. Der Docker-Pfad ist der Weg, den die meisten Menschen meinen, wenn sie „TGI installieren" sagen, weil er Router, Model-Server und Kernels in ein Image packt, das mit einem einzigen Befehl ausgeführt werden kann.

Unter der Haube ist TGI ein System mit unterschiedlichen Komponenten: ein Router, der HTTP annimmt und Batching durchführt, ein Launcher, der einen oder mehrere Model-Server-Prozesse orchestriert, und der Model-Server, der das Modell lädt und die Inferenz durchführt. Diese Trennung erklärt viel vom „Warum" hinter Konfigurationsflags und häufigen Fehlermodi.

Zwei praktische Voraussetzungen tauchen immer wieder auf: GPU-Zugriff aus Containern und eine vernünftige Caching-Strategie für Modellgewichte. GPU-Zugriff für Nvidia bedeutet typischerweise, dass das Nvidia Container Toolkit installiert ist, und Caching bedeutet, ein Host-Volume auf den Container zu mappen, damit Modellgewichte nicht jedes Mal neu heruntergeladen werden.

Lokale Installation aus dem Quellcode

Eine Quellinstallation existiert, ist aber für Entwickler und Kernel-Bauer opinioniert. Sie erwartet Rust, Python 3.9+ und Build-Tooling und ist in der Regel ein langsamerer erster Schritt als das Ausführen des Containers. Nützlich, wenn Sie Internes ändern, Patches testen oder mit einer sehr spezifischen Umgebung integrieren müssen.

Quickstart mit Docker

Der kanonische Quickstart ist kurz, was genau der Punkt ist. Wählen Sie eine Modell-ID, mounten Sie ein Cache-Volume, exponieren Sie einen Port und starten Sie den Container.

Nvidia GPU Quickstart

Dies ist ein minimales Muster, das für den ersten Start gut funktioniert.

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

Dieser eine Befehl beantwortet implizit eine häufige FAQ-Frage, „Wie führt man TGI mit Docker auf einer Nvidia-GPU aus", indem er die drei nicht verhandelbaren Elemente zeigt: --gpus all, eine Port-Zuordnung und eine Modell-ID.

Ein subtiler, aber wichtiger Punkt ist die Port-Zuordnung. Der Container ist typischerweise so konfiguriert, dass er HTTP auf Port 80 bereitstellt, sodass Sie Host-8080 auf Container-80 mappen. Wenn Sie TGI außerhalb von Docker ausführen, ist der Standardport für den Launcher oft 3000, weshalb Verwirrung bezüglich Ports ein so häufiger Fehler am ersten Tag ist.

Erste Anfrage mit der benutzerdefinierten API

TGI stellt eine einfache JSON-API im Stil von „generate" bereit. Eine Streaming-Anfrage sieht so aus:

curl 127.0.0.1:8080/generate_stream \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"Was ist Deep Learning?","parameters":{"max_new_tokens":40}}'

Wenn Sie eine einzelne Antwort bevorzugen, verwenden Sie den nicht-streamenden Endpunkt.

curl 127.0.0.1:8080/generate \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"Erklären Sie kontinuierliches Batching in einem Absatz.","parameters":{"max_new_tokens":120}}'

Erste Anfrage mit der Messages-API

Wenn Ihr Ökosystem Chat-Anfragen im OpenAI-Stil erwartet, verwenden Sie die Messages-API. Dies steht in direktem Zusammenhang mit einer anderen FAQ-Frage: „Wie kann man TGI mit OpenAI-kompatiblen Chat-Clients verwenden".

curl 127.0.0.1:8080/v1/chat/completions \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "Du bist ein knapper Assistent."},
      {"role": "user", "content": "Geben Sie eine einzeilige Definition von Tensor-Parallelität."}
    ],
    "stream": false,
    "max_tokens": 60
  }'

Bereitstellen gated oder privater Modelle

Wenn Sie jemals gefragt haben, „Wie stellt man gated oder private Hugging Face-Modelle mit TGI bereit", ist die Antwort absichtlich langweilig: Stellen Sie ein Hub-Token über HF_TOKEN bereit.

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

Der Fehlermodus hier ist ebenfalls langweilig: fehlende Berechtigungen, ungültige Token-Bereiche oder der Versuch, ein Modell zu ziehen, das die Annahme einer Lizenz erfordert.

AMD ROCm Quickstart

TGI verfügt auch über ROCm-Images und eine andere Geräteeinrichtung. Wenn Sie AMD-GPUs verwenden, ändert sich die Startform.

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

Nur CPU-Läufe

CPU-Läufe existieren, aber sie sind nicht die Plattform, für die TGI ausgelegt ist, um brillant zu sein. Wenn Sie es dennoch tun, vermeidet das Deaktivieren benutzerdefinierter Kernels einige hardware-spezifische Probleme.

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

Konfiguration, die tatsächlich den Zeiger bewegt

TGI hat viele Flags. Die meisten davon sind nicht auswendig zu lernen. Einige sind jedoch verständlich, weil sie die am häufigsten gestellte Frage in diesem Bereich beantworten: „Welche TGI-Einstellungen steuern den GPU-Speicher und Anfragegrenzen".

Das Speicherbudget ist max_total_tokens

Das wichtigste Konzept in der TGI-Konfiguration ist, dass der Server ein Token-Budget benötigt, um Batching zu planen und Speicherüberlastungen zu vermeiden.

Es gibt zwei Obergrenzen, die die Anfrageform definieren: max_input_tokens und max_total_tokens.

max_total_tokens wirkt wie ein Speicherbudget pro Anfrage, da es Eingabetoken plus generierte Token begrenzt. Wenn es zu hoch ist, wird jede Anfrage teuer, Batching wird unangenehm und der Speicherdruck wächst. Wenn es zu niedrig ist, stoßen Nutzer früh an Längenlimits, und der Server lehnt ansonsten gültige Workloads ab.

Eine Konfiguration, die das Budget explizit macht, sieht so aus:

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

Batching-Regler, die zählen

Sobald Token-Budgets festgelegt sind, ist die Batching-Steuerung der nächste Hebel.

max_batch_prefill_tokens begrenzt die Prefill-Arbeit, die oft die speicherintensivste und rechengebundene Phase ist. max_batch_total_tokens legt fest, wie viele Token der Server insgesamt in ein Batch zu pressen versucht. Dies ist eine der echten Durchsatzsteuerungen.

Der interessante Regler ist waiting_served_ratio. Er kodiert eine Politikentscheidung, keine Hardwarebeschränkung. Er steuert, wann der Server die laufende Decode-Arbeit pausiert, um wartende Anfragen in ein neues Prefill aufzunehmen, damit sie sich der Decode-Gruppe anschließen können. Niedrige Werte tendieren dazu, bestehende Anfragen zu bevorzugen, hohe Werte neigen dazu, die Tail-Latenz für neu in die Warteschlange eingereihte Anfragen zu reduzieren, und beide können je nach Verkehrsform „korrekt" sein.

Sharding, num shard und warum NCCL auftaucht

Wenn Ihr Modell auf einer GPU nicht passt oder Sie höheren Durchsatz über Tensor-Parallelität wünschen, ist Sharding der nächste Schritt.

Das mentale Modell ist einfach: --sharded true aktiviert Sharding, und --num-shard steuert die Shard-Anzahl. Der Server kann standardmäßig alle sichtbaren GPUs verwenden oder eine Teilmenge.

Ein nützliches Muster bei Multi-GPU-Hosts ist das Aufteilen von GPUs in Gruppen und das Ausführen mehrerer TGI-Replikate, wobei jedes Replikat über seine eigene GPU-Teilmenge sharded ist. Das verteilt die Last und hält gleichzeitig die Sharding-Topologie einfach.

Dies ist auch der Punkt, an dem die FAQ-Frage „Warum TGI bei mehreren GPUs mit NCCL- oder Shared-Memory-Fehlern fehlschlägt" relevant wird. Multi-GPU-Setups verlassen sich auf kollektive Kommunikation, und Container benötigen genügend Shared Memory für einen sicheren Betrieb, wenn SHM-Fallback verwendet wird.

Quantisierungsentscheidungen und was sie trade-off

Quantisierung ist das am meisten missverstandene „machen Sie es passen"-Setting, weil es zwei verschiedene Ziele mischt: Speicherreduktion und Geschwindigkeit.

TGI unterstützt vorquantisierte Gewichte für Schemata wie GPTQ und AWQ sowie On-the-Fly-Quantisierung für bestimmte Methoden wie bitsandbytes und EETQ. Einige Methoden reduzieren den Speicher, sind aber langsamer als native Halbe-Genauigkeit, weshalb Quantisierung nicht als kostenlose Leistungssteigerung behandelt werden sollte.

Ein einfaches On-the-Fly-8-Bit-Quantisierungsbeispiel sieht so aus:

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

Und eine 4-Bit-Variante sieht so aus:

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

API-Formung und grundlegende Sicherheitsvorkehrungen

TGI kann als interner Dienst ausgeführt oder breiter exponiert werden. Wenn Exposition möglich ist, sind zwei Flags wichtig: max_concurrent_requests und api_key.

max_concurrent_requests bietet Rückdruck. Es zwingt den Server, überschüssige Anfragen abzulehnen, anstatt alles in die Warteschlange zu lassen und auf Timeout zu warten.

Ein API-Schlüssel bietet eine grobe Authentifizierungsbarriere. Es ist kein vollständiges Auth-System, aber es verhindert versehentliche öffentliche Nutzung.

CORS ist auch über cors_allow_origin konfigurierbar, was wichtig ist, wenn eine browserbasierte UI den Server direkt aufruft.

Betrieb und Observabilität

Dieser Abschnitt beantwortet die echte Operator-Frage: „Wo können Sie Prometheus-Metriken von einem TGI-Server scrapen".

OpenAPI-Dokumente und interaktive Dokumente

TGI stellt seine OpenAPI- und Swagger-UI unter der /docs-Route bereit, was hilfreich ist, wenn Sie schnell Anfrage- und Antwortformen bestätigen oder Endpunkte testen möchten, ohne einen Client zu schreiben.

Prometheus-Metriken

TGI exportiert Prometheus-Metriken am /metrics-Endpunkt. Diese Metriken decken Warteschlangenlänge, Anfrage-Latenz, Token-Anzahlen und Batch-Ebene-Zeitangaben ab. Das Ergebnis ist, dass Sie beobachten können, ob das System durch Prefill, Decode oder Warteschlangen begrenzt ist.

End-to-End-Produktionsüberwachung – PromQL, Grafana-Dashboards, Alarme und Docker- oder Kubernetes-Scrape-Layouts für diese Stacks – wird in LLM-Inferenz in der Produktion überwachen (2026): Prometheus & Grafana für vLLM, TGI, llama.cpp behandelt.

Tracing und strukturierte Logs

TGI unterstützt verteiltes Tracing über OpenTelemetry. Logs können auch in JSON ausgegeben werden, was Log-Pipelines einfacher macht.

Fehlerbehebungs-Playbook

TGI-Fehler neigen dazu, in wenigen Buckets zu clustern, und jeder Bucket hat eine sehr unterschiedliche Lösung.

Der Container läuft, aber keine GPU wird erkannt

Die häufigste Ursache ist, dass der Container-Runtime nicht für GPU-Passthrough konfiguriert ist. Bei Nvidia korreliert dies oft mit fehlender Nvidia Container Toolkit-Unterstützung oder dem Betrieb auf einem Host-Treiber-Stack, der nicht den Erwartungen entspricht.

Modell-Download-Fehler und Berechtigungsfehler

Wenn der Server Modell-Dateien nicht herunterladen kann, sind die üblichen Verdächtigen ein fehlendes Auth-Token für gated Modelle, ein Token ohne Modell-Leseberechtigungen oder Rate-Limits. Das korrekte Setzen von HF_TOKEN löst den Fall von gated Modellen.

CUDA Out of Memory oder plötzliche Neustarts unter Last

Die häufigste Ursache sind zu großzügige Token-Budgets. Wenn max_total_tokens groß ist und Clients lange Generationen anfordern, reserviert der Server Speicher für Worst-Case-Anfragen. Reduzieren Sie das Budget, verringern Sie die Parallelität oder wählen Sie eine Quantisierungsmethode, die Ihren Einschränkungen entspricht.

Multi-GPU NCCL-Fehler, Hänge oder extreme Verlangsamungen

Beim Sharding über mehrere GPUs hinweg sind Shared Memory und NCCL wichtig. Unzureichender Shared Memory innerhalb von Containern verursacht oft Instabilität. Eine Erhöhung der Shared-Memory-Allokation oder das Deaktivieren des SHM-Sharing über NCCL_SHM_DISABLE kann das Verhalten ändern, mit einem Leistungs-Trade-off.

NCCL-Probleme werden auch leichter zu debuggen, wenn NCCL-Debug-Logging aktiviert ist, da die Fehlerberichte expliziter sind.

Seltsame Kernel-Fehler auf nicht-A100-Hardware

Einige Modelle verwenden benutzerdefinierte Kernel, die zuerst auf spezifischer Hardware getestet wurden. Wenn Sie unerklärliche Kernel-Fehler sehen, ist --disable-custom-kernels häufig der einfachste Weg, zu bestätigen, ob benutzerdefinierte Kernel beteiligt sind.

Port-Verwirrung und „es läuft, aber ich kann es nicht erreichen"

Ein klassischer Fehler ist das Vermischen des Docker-Port-Mapping-Modells mit dem lokalen Standardport-Modell. In Docker-Beispielen dient der Container häufig auf Port 80, während lokale Läufe standardmäßig auf 3000 enden. Wenn Sie den falschen Port mappen, landen Ihre curl-Anfragen im Nirgendwo, und das System sieht kaputt aus, obwohl es eigentlich nur unerreichbar ist.

Abschließende Anmerkung

TGI fühlt sich wie Infrastruktur an. Das ist das Kompliment. Es ist ein System, das so konzipiert ist, dass Textgenerierung langweilig genug zum Betreiben, messbar genug zum Debuggen und flexibel genug ist, um in bestehende OpenAI-förmige Client-Stacks zu passen.