TGI - Text Generation Inference - Installeren, configureren en oplossen van problemen

Text Generation Inference (TGI) heeft een zeer specifieke energie. Het is niet de nieuwste speler op de inference-straat, maar het is wel degene die al heeft geleerd hoe productie faalt en

die lessen vervolgens heeft verwerkt in de standaardinstellingen. Als je doel is “een LLM achter HTTP draaien en het draaiend houden”, is TGI een pragmatische tool.

Als je nog steeds weegt waar je modellen moet draaien, brengt dit vergelijkende overzicht van LLM-hosting in 2026 lokale, zelfgehoste en cloud-oplossingen bij elkaar, zodat je TGI in context kunt plaatsen.

Eerst een realiteitscheck. Per 2026 is TGI in onderhoudsmodus en is het upstream-repository archiverd als read-only. Dat klinkt als slecht nieuws, tot je het vanuit een operationeel perspectief bekijkt. Een stabiele engine kan een voordeel zijn, vooral wanneer de echte veranderingen zich in modellen, prompts en producteisen voordoen.

Deze gids focust op vier dingen die op dag nul en dag dertig van belang zijn: installatiepaden, een quickstart die daadwerkelijk werkt, configuratie die echt gedrag verandert, en een probleemoplossende mindset die tijd bespaart.

Waarom TGI in 2026 nog steeds belangrijk is

Het is makkelijk om inference-servers als uitwisselbaar te behandelen. Voor een tool-voor-tool overzicht van veelvoorkomende lokale stacks, begin je bij Ollama vs vLLM vs LM Studio: Beste manier om LLMs lokaal te draaien in 2026?.

In de praktijk zijn er slechts drie vragen die er toe doen.

Ten eerste, hoe gedraagt het zich onder belasting? TGI is gebouwd rondom continu batching en token streaming, waardoor het doorvoer kan prioriteren terwijl het gebruikers de illusie van responsiviteit geeft.

Ten tweede, kan het de dialect spreken die je tooling al spreekt? TGI ondersteunt zijn eigen “custom API” en ook een Messages API die compatibel is met het OpenAI Chat Completions-schema. Dat betekent dat tooling die een OpenAI-achtig endpoint verwacht, vaak met minimale aanpassingen op TGI kan worden gewezen.

Ten derde, kun je het observeren zonder te raden? TGI exposeert Prometheus-metrics en ondersteunt gedistribueerd tracing via OpenTelemetry. Dit is het verschil tussen “ik denk dat het traag is” en “prefill verzadigt, de wachttijd groeit en het batch-token-budget is te hoog”.

Installatiepaden en vereisten

TGI kan benaderd worden via Docker of via een lokale installatie van de broncode. De Docker-route is het pad dat de meeste mensen bedoelen als ze zeggen “TGI installeren”, omdat het de router, model server en kernels inpakt in een image dat met één commando kan worden gedraaid.

Anderzijds is TGI een systeem met onderscheiden componenten: een router die HTTP accepteert en batching uitvoert, een launcher die één of meerdere model server-processen orchestreert, en de model server die het model laadt en inference uitvoert. Die scheiding verklaart veel van het “waarom” achter configuratievlaggen en veelvoorkomende faalmodes.

Twee praktische vereisten komen steeds weer naar voren: GPU-toegang vanuit containers, en een gezonde cache-strategie voor modelgewichten. GPU-toegang voor Nvidia betekent doorgaans dat de Nvidia Container Toolkit is geïnstalleerd, en caching betekent dat een host-volume aan de container wordt gekoppeld, zodat modelgewichten niet elke keer opnieuw worden gedownload.

Lokale installatie van broncode

Er bestaat een installatie van broncode, maar deze is opgezet voor ontwikkelaars en kernelbouwers. Het verwacht Rust, Python 3.9+ en build-tooling, en het is doorgaans een langzamere eerste stap dan het container draaien. Dit is nuttig als je interne onderdelen moet wijzigen, patches moet testen of integratie met een zeer specifieke omgeving nodig hebt.

Quickstart met Docker

De canonieke quickstart is kort, wat precies het punt is. Kies een model-id, mount een cache-volume, expose een poort en draai de container.

Nvidia GPU quickstart

Dit is een minimaal patroon dat goed werkt voor de eerste boot.

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

Dat ene commando beantwoordt impliciet een veelgestelde FAQ-vraag, “Hoe draai je TGI met Docker op een Nvidia GPU”, door de drie niet-onderhandelbare elementen te tonen: --gpus all, een poortmapping en een model-id.

Een subtiel maar belangrijk punt is de poortmapping. De container is doorgaans geconfigureerd om HTTP op poort 80 te serveren, dus je mappt host-poort 8080 naar container-poort 80. Als je TGI buiten Docker draait, is de standaardpoort voor de launcher vaak 3000, wat de reden is dat poortverwarring een veelvoorkomende eerste-dag bug is.

Eerste request met behulp van de custom API

TGI exposeert een eenvoudige JSON “generate”-stijl API. Een streaming-request ziet er als volgt uit.

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

Als je een enkele respons prefereert, gebruik dan het niet-streamende endpoint.

curl 127.0.0.1:8080/generate \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"Leg continu batching uit in één paragraaf.","parameters":{"max_new_tokens":120}}'

Eerste request met behulp van de Messages API

Als je ecosysteem OpenAI-achtige chat-requests verwacht, gebruik dan de Messages API. Dit heeft direct betrekking op een andere FAQ-vraag, “Hoe kun je TGI gebruiken met OpenAI-compatibele chat-clients”.

curl 127.0.0.1:8080/v1/chat/completions \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "Je bent een beknopte assistent."},
      {"role": "user", "content": "Geef een definitie van tensor parallelisme in één zin."}
    ],
    "stream": false,
    "max_tokens": 60
  }'

Serveren van gated of privémodellen

Als je ooit hebt gevraagd “Hoe server je gated of privé Hugging Face-modellen met TGI”, is het antwoord saai door ontwerp: lever een Hub-token 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

De faalmode hier is ook saai: ontbrekende machtigingen, ongeldige token-scopes, of het proberen om een model te halen dat acceptatie van een licentie vereist.

AMD ROCm quickstart

TGI heeft ook ROCm-images en een andere device-setup. Als je op AMD-GPU’s draait, verandert de boot-vorm.

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

Alleen CPU-runs

CPU-runs bestaan, maar ze zijn niet het platform waarvoor TGI is ontworpen om briljant in te zijn. Als je het toch doet, voorkomt het uitschakelen van custom kernels sommige hardware-specifieke problemen.

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

Configuratie die daadwerkelijk verschil maakt

TGI heeft veel vlaggen. De meeste zijn het niet waard om te onthouden. Een paar zijn het waard om te begrijpen, omdat ze de meest gezochte vraag in dit domein beantwoorden: “Welke TGI-instellingen bepalen GPU-geheugen en request-limieten”.

Geheugenbudget is max totale tokens

Het allerbelangrijkste concept in TGI-configuratie is dat de server een token-budget nodig heeft om batching te plannen en geheugen-explosies te voorkomen.

Er zijn twee limieten die de vorm van requests definiëren: max_input_tokens en max_total_tokens.

max_total_tokens fungeert als een geheugenbudget per request omdat het input-tokens plus gegenereerde tokens begrenst. Als het te hoog is, wordt elke request duur, wordt batching onhandig en groeit de gehegendruk. Als het te laag is, botsen gebruikers vroeg tegen lengtelimieten en verwijdert de server anders geldige werklasten.

Een configuratie die het budget expliciet maakt, ziet er als volgt uit.

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-regelaars die ertoe doen

Zodra token-budgets zijn ingesteld, is batching-controle de volgende hefboom.

max_batch_prefill_tokens limiteert prefill-werk, wat vaak de meest geheugen-intensieve en compute-gelimiteerde fase is. max_batch_total_tokens stelt in hoeveel tokens de server probeert in een batch te passen. Dit is een van de echte doorvoercontroles.

De interessante regelaar is waiting_served_ratio. Het codeert een beleidsbeslissing, geen hardware-beperking. Het beheert wanneer de server stopt met het uitvoeren van decode-werk om wachtende requests in een nieuwe prefill te brengen, zodat ze zich kunnen aansluiten bij de decode-groep. Lage waarden gunstigen bestaande requests, hoge waarden verminderen de tail-latency voor nieuw gekwantificeerde requests, en beide kunnen “correct” zijn afhankelijk van de verkeersvorm.

Sharding, num_shard en waarom NCCL verschijnt

Als je model niet op één GPU past, of als je hogere doorvoer wilt via tensor-parallelisme, is sharding de volgende stap.

Het mentale model is simpel: --sharded true schakelt sharding in, en --num-shard bepaalt het aantal shards. De server kan standaard alle zichtbare GPU’s gebruiken, of een subset.

Een nuttig patroon op multi-GPU-hosts is het splitsen van GPU’s in groepen en het draaien van meerdere TGI-replica’s, waarbij elke replica gesharded is over zijn eigen GPU-subset. Dit verspreidt de belasting terwijl het sharding-topologie eenvoudig houdt.

Dit is ook waar de FAQ-vraag “Waarom faalt TGI met NCCL- of shared memory-fouten op meerdere GPU’s” relevant wordt. Multi-GPU-opstellingen vertrouwen op collectieve communicatie, en containers hebben voldoende shared memory nodig voor veilige werking wanneer SHM-fallback wordt gebruikt.

Kwantiseringskeuzes en wat ze afwegen

Kwantisering is de meest misverstandige “maak het passen”-instelling omdat het twee verschillende doelen mengt: geheugenreductie en snelheid.

TGI ondersteunt vooraf gekwantiseerde gewichten voor schema’s zoals GPTQ en AWQ, en ook kwantisering op het moment voor bepaalde methoden zoals bitsandbytes en EETQ. Sommige methoden reduceren geheugen maar zijn langzamer dan native half-precision, wat de reden is dat kwantisering niet als een gratis prestatie-upgrade moet worden behandeld.

Een eenvoudig voorbeeld van op het moment 8-bit kwantisering ziet er als volgt uit.

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

En een 4-bit variant ziet er als volgt uit.

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-vormgeving en basisveiligheidsmaatregelen

TGI kan worden gedraaid als een interne service, of breder worden blootgesteld. Als blootstelling mogelijk is, zijn twee vlaggen belangrijk: max_concurrent_requests en api_key.

max_concurrent_requests biedt backpressure. Het zorgt ervoor dat de server excessieve requests weigert in plaats van alles in de wachtrij te laten staan en time-out te laten geven.

Een API-sleutel biedt een ruwe authenticatiebarrière. Het is geen volledig auth-systeem, maar het stopt onbedoeld publiek gebruik.

CORS is ook configureerbaar via cors_allow_origin, wat belangrijk is als een browser-gebaseerde UI direct de server aanroept.

Operaties en observabiliteit

Dit deel beantwoordt de echte operator-vraag: “Waar kun je Prometheus-metrics scrapen van een TGI-server”.

OpenAPI-documentatie en interactieve documentatie

TGI exposeert zijn OpenAPI en Swagger UI onder de /docs route, wat handig is als je snel wilt bevestigen wat request- en responsvormen zijn of endpoints wilt testen zonder een client te schrijven.

Prometheus-metrics

TGI exporteert Prometheus-metrics op het /metrics endpoint. Deze metrics dekken wachtrijgrootte, request-latentie, token-aantallen en batch-niveau tijden. Het resultaat is dat je kunt waarnemen of het systeem beperkt wordt door prefill, decode of wachtrij.

End-to-end productiemonitoring—PromQL, Grafana-dashboards, alerts en Docker- of Kubernetes-scrape-layouts voor deze stacks—is gedekt in Monitor LLM Inference in Production (2026): Prometheus & Grafana voor vLLM, TGI, llama.cpp.

Tracing en gestructureerde logs

TGI ondersteunt gedistribueerd tracing via OpenTelemetry. Logs kunnen ook in JSON worden uitgegeven, wat log-pipelines gemakkelijker maakt.

Playbook voor probleemoplossing

TGI-falen neigen zich te clusteren in een paar categorieën, en elke categorie heeft een heel andere oplossing.

De container draait maar er wordt geen GPU gedetecteerd

De meest voorkomende oorzaak is dat de container-runtime niet is geconfigureerd voor GPU-passthrough. Bij Nvidia correleert dit vaak met ontbrekende Nvidia Container Toolkit-ondersteuning, of het draaien op een host-driverstack die niet overeenkomt met verwachtingen.

Model-downlaadfouten en machtigingsfouten

Als de server modelbestanden niet kan downloaden, zijn de gebruikelijke boosdoeners een ontbrekende auth-token voor gated modellen, een token zonder model-leesmachtigingen, of rate-limieten. Het correct instellen van HF_TOKEN lost het geval van gated modellen op.

CUDA out of memory of plotselinge herstarts onder belasting

De meest voorkomende oorzaak is een te permissive token-budget. Als max_total_tokens groot is en clients lange generaties aanvragen, zal de server geheugen reserveren voor worst-case requests. Verminder het budget, verminder de concurrentie, of kies een kwantiseringsmethode die past bij je beperkingen.

Multi-GPU NCCL-fouten, hangs of extreme vertragingen

Bij het sharden over meerdere GPU’s zijn shared memory en NCCL belangrijk. Onvoldoende shared memory binnen containers creëert vaak instabiliteit. Het verhogen van shared memory-toewijzing of het uitschakelen van SHM-sharing via NCCL_SHM_DISABLE kan gedrag veranderen, met een prestatie-afweging.

NCCL-problemen worden ook makkelijker te debuggen wanneer NCCL-debuglogging is ingeschakeld, omdat de foutrapporten explicieter zijn.

Raadselachtige kernel-fouten op niet-A100 hardware

Sommige modellen gebruiken custom kernels die eerst op specifieke hardware zijn getest. Als je onverklaarde kernel-falen ziet, is --disable-custom-kernels vaak de simpelste manier om te bevestigen of custom kernels betrokken zijn.

Poortverwarring en “het draait maar ik kan het niet bereiken”

Een klassieke valkuil is het vermengen van het Docker-poortmapping-model met het lokale standaardpoortmodel. In Docker-voorbeelden serveert de container vaak op 80, terwijl lokale runs standaard op 3000. Als je de verkeerde poort mappt, landen je curl-requests op niets, en het systeem ziet er kapot uit terwijl het eigenlijk gewoon onbereikbaar is.

Afsluitende notitie

TGI voelt als infrastructuur. Dat is het compliment. Het is een systeem ontworpen om tekstgeneratie saa genoeg te maken om te opereren, meetbaar genoeg om te debuggen en flexibel genoeg om te passen in bestaande OpenAI-achtige client-stacks.