TGI – Text Generation Inference – Installation, konfiguration och felsökning

Text Generation Inference (TGI) har en mycket specifik energi. Det är inte den nyaste killen på inferensgatan, men det är den som redan har lärt sig hur produktion bryts –

och sedan bakat in dessa lärdomar i standardinställningarna. Om ditt mål är “att servera en LLM bakom HTTP och hålla den igång”, är TGI en pragmatisk verktygslåda.

Om du fortfarande väger var du ska köra modeller, drar den här jämförelsen av LLM-hosting 2026 in lokala, självhysta och molnbaserade lösningar så att du kan placera TGI i sitt sammanhang.

En verklighetscheck först. Per 2026 är TGI i underhållsläge och upstream-repositoriet har arkiverats som skrivskyddat. Det låter som dåliga nyheter tills man ser det från en operationsperspektiv. En stabil motor kan vara en funktion, särskilt när den verkliga omsättningen ligger i modeller, prompts och produktkrav.

Denna guide fokuserar på fyra saker som betyder något på dag noll och dag tretti: installationsvägar, en quickstart som faktiskt fungerar, konfiguration som förändrar faktiskt beteende, och en felsökningsinställning som sparar tid.

Varför TGI fortfarande betyder något 2026

Det är lätt att behandla inferensservrar som utbytbara. För en verktygsvisa undersökning av vanliga lokala stackar, börja med Ollama vs vLLM vs LM Studio: Bäst sätt att köra LLMs lokalt 2026?.

I praktiken finns det bara tre frågor som betyder något.

Först, hur beter den sig under belastning. TGI är byggt kring kontinuerlig batching och token-strömning, så den kan prioritera genomströmning samtidigt som den ger användare illusionen av responsivitet.

För det andra, kan den tala dialekten som din verktygskedja redan talar. TGI stöder sitt eget “custom API” och även ett Messages API som är kompatibelt med OpenAI Chat Completions-schema. Det betyder att verktyg som förväntar sig en OpenAI-formad endpoint ofta kan riktas mot TGI med minimal förändring.

För det tredje, kan du observera den utan att gissa. TGI exponerar Prometheus-mätningar och stöder distribuerad tracing via OpenTelemetry, vilket är skillnaden mellan “jag tror att det är långsamt” och “prefill är mättad, kötid växer, och batch-token-budgeten är för hög”.

Installationsvägar och förutsättningar

TGI kan närmas via Docker eller via en lokal install från källkod. Docker-vägen är den väg de flesta menar när de säger “installera TGI”, eftersom den packar routern, modelservern och kärnorna i en bild som kan köras med ett enda kommando.

Under huven är TGI ett system med distinkta komponenter: en router som accepterar HTTP och utför batching, en launcher som orkestrerar en eller flera modelserverprocesser, och modelservern som laddar modellen och utför inferens. Denna separation förklarar mycket av “varför” bakom konfigurationsflaggor och vanliga felmoder.

Två praktiska förutsättningar dyker upp gång på gång: GPU-tillgång från container, och en vettig cachestrategi för modellvikt. GPU-tillgång för Nvidia innebär vanligtvis att Nvidia Container Toolkit är installerat, och cachestrategi innebär att man mappar en värdvolym till containern så att modellvikt inte laddas ner varje gång.

Lokal install från källkod

En källkodinstall finns, men den är åsiktsstyrd mot utvecklare och kärnbyggare. Den förväntar sig Rust, Python 3.9+, och byggverktyg, och det är oftast ett långsammare första steg än att köra containern. Användbart när du behöver modifiera inre delar, testa patches, eller integrera med en mycket specifik miljö.

Quickstart med Docker

Den kanoniska quickstarten är kort, vilket är precis poängen. Välj ett model-ID, mapp ett cachevolume, exponera en port, och kör containern.

Nvidia GPU quickstart

Detta är ett minimalt mönster som fungerar väl för första start.

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

Detta enda kommando svarar implicit på en vanlig FAQ-fråga, “Hur kör du TGI med Docker på en Nvidia GPU” genom att visa de tre icke-förhandlingsbara delarna: --gpus all, en portmappning, och ett model-ID.

En subtil men viktig punkt är portmappningen. Containern är vanligtvis konfigurerad att servera HTTP på port 80, så du mappar värdens 8080 till containerns 80. Om du kör TGI utanför Docker är standardporten för launchern ofta 3000, vilket är varför portförvirring är så vanlig första dagen.

Första förfrågan med hjälp av det custom API:t

TGI exponerar ett enkelt JSON-“generera”-stils API. En strömande förfrågan ser ut så här.

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

Om du föredrar en enda respons, använd den icke-strömande endpointen.

curl 127.0.0.1:8080/generate \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"Förklara kontinuerlig batching i ett stycke.","parameters":{"max_new_tokens":120}}'

Första förfrågan med hjälp av Messages API

Om din ekosystem förväntar sig OpenAI-stils chattförfrågningar, använd Messages API. Detta relaterar direkt till en annan FAQ-fråga, “Hur kan du använda TGI med OpenAI-kompatibla chattklienter”.

curl 127.0.0.1:8080/v1/chat/completions \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "Du är en koncis assistent."},
      {"role": "user", "content": "Ge en mening som definierar tensorparallelism."}
    ],
    "stream": false,
    "max_tokens": 60
  }'

Servering av gated eller privata modeller

Om du någonsin har frågat “Hur serverar du gated eller privata Hugging Face-modeller med TGI”, är svaret tråkigt av design: tillhandahåll ett 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

Felmoden här är också tråkig: saknade behörigheter, ogiltiga tokenområden, eller att försöka dra ner en modell som kräver godkännande av en licens.

AMD ROCm quickstart

TGI har också ROCm-bilder och en annan enhetskonfiguration. Om du är på AMD-GPU ändras startformen.

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

CPU-endast körningar

CPU-körningar finns, men de är inte plattformen TGI var designad att vara briljant på. När du gör det ändå, att inaktivera custom kernels undviker vissa hårdvaruspecifika problem.

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 som faktiskt rör på nålen

TGI har många flaggor. De flesta är inte värda att memorisera. Några är värda att förstå, eftersom de svarar på den mest sökta frågan inom detta område: “Vilka TGI-inställningar styr GPU-minne och förfråningsgränser”.

Minnesbudget är maximalt totala token

Det enskilt viktigaste konceptet i TGI-konfiguration är att servern behöver en token-budget för att planera batching och undvika minnesblåsor.

Det finns två tak som definierar förfråningsform: max_input_tokens och max_total_tokens.

max_total_tokens fungerar som en minnesbudget per förfrågan eftersom den begränsar inmatningstoken plus genererade token. Om den är för hög blir varje förfrågan dyr, batching blir klumpig, och minnespressen växer. Om den är för låg, når användare längdbegränsningar tidigt, och servern avvisar annars giltiga arbetsbelastningar.

En konfiguration som gör budgeten explicit ser ut så här.

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-knappar som betyder något

När token-budgetar är inställda, är batching-styrning nästa hävstång.

max_batch_prefill_tokens begränsar prefill-arbetet, vilket ofta är den mest minneskrävande och beräkningsbundna fasen. max_batch_total_tokens sätter hur många token servern försöker få in i en batch totalt. Detta är en av de verkliga genomströmningskontrollerna.

Den intressanta knappen är waiting_served_ratio. Den kodar en politisk beslut, inte en hårdvarubegränsning. Den styr när servern pausar att köra decode-arbetet för att ta in väntande förfrågningar i en ny prefill så att de kan gå med i decode-gruppen. Låga värden tenderar att favorisera befintliga förfrågningar, höga värden tenderar att minska svanslatens för nyköade förfrågningar, och båda kan vara “korrekt” beroende på trafikform.

Sharding, num shard, och varför NCCL dyker upp

Om din modell inte får plats på en GPU, eller om du vill ha högre genomströmning via tensorparallelism, är sharding nästa steg.

Den mentala modellen är enkel: --sharded true aktiverar sharding, och --num-shard styr shard-antalet. Servern kan använda alla synliga GPU:n som standard, eller använda en delmängd.

Ett användbart mönster på flergpu-värdar är att dela upp GPU:n i grupper och köra flera TGI-repliker, där varje replik är sharded över sin egen GPU-delmängd. Det sprider belastningen samtidigt som det håller sharding-topologin enkel.

Detta är också där FAQ-frågan “Varför misslyckas TGI med NCCL eller shared memory-fel på flera GPU:n” blir relevant. Fler-GPU-uppställningar är beroende av kollektiv kommunikation, och containrar behöver tillräckligt med shared memory för säker drift när SHM-fallback används.

Kvantiseringval, och vad de avväger

Kvantisering är den mest missförstådda “få det att passa”-inställningen eftersom den blandar två olika mål: minnesreduktion och hastighet.

TGI stöder för-kvantisering av vikter för scheman som GPTQ och AWQ, och också kvantisering på flytande för vissa metoder som bitsandbytes och EETQ. Vissa metoder reducerar minne men är långsammare än native halvprecision, vilket är varför kvantisering inte bör behandlas som en gratis prestandauppdatering.

Ett enkelt på-flytande 8-bitars kvantiseringsexempel ser ut så här.

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

Och en 4-bitars variant ser ut så här.

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-formgivning och grundläggande skyddsräcker

TGI kan köras som en intern tjänst, eller exponeras mer brett. Om exponering är möjlig, är två flaggor viktiga: max_concurrent_requests och api_key.

max_concurrent_requests ger backpressure. Det får servern att vägra överskridande förfrågningar snarare än att låta allt köas och timeouta.

En API-nyckel ger en grov autentiseringsbarriär. Det är inte ett fullt auth-system, men det stoppar oavsiktlig offentlig användning.

CORS är också konfigurerbar via cors_allow_origin, vilket betyder något om en webbläsarbaserad UI anropar servern direkt.

Operationer och observabilitet

Detta avsnitt svarar på den verkliga operatörsfrågan: “Var kan du skrapa Prometheus-mätningar från en TGI-server”.

OpenAPI-dokumentation och interaktiva dokument

TGI exponerar sin OpenAPI och Swagger UI under /docs-rutan, vilket är användbart när du vill snabbt bekräfta förfrånings- och responsformer eller testa endpoints utan att skriva en klient.

Prometheus-mätningar

TGI exporterar Prometheus-mätningar på /metrics-endpointen. Dessa mätningar täcker köstorlek, förfråningslatens, tokenantal och batchnivå-tidpunkter. Resultatet är att du kan observera om systemet är begränsat av prefill, decode eller köning.

End-to-end produktionsövervakning—PromQL, Grafana-dashboard, varningar, och Docker eller Kubernetes scrape-layouts för dessa stackar—täcks i Monitor LLM Inference in Production (2026): Prometheus & Grafana for vLLM, TGI, llama.cpp.

Tracing och strukturerade loggar

TGI stöder distribuerad tracing via OpenTelemetry. Loggar kan också emitteras i JSON, vilket gör logg-pipelines enklare.

Felsökningsspelplan

TGI-fel tenderar att klustra i några få kategorier, och varje kategori har en väldigt annan fix.

Containern kör men ingen GPU upptäcks

Den vanligaste orsaken är att container-runtime inte är konfigurerad för GPU-throughput. På Nvidia korrelerar detta ofta med saknat Nvidia Container Toolkit-stöd, eller körning på en värdarstack som inte matchar förväntningarna.

Modellnedladdningsfel och behörighetsfel

Om servern inte kan ladda ner modellfiler, är de vanliga skuldarna ett saknat auth-token för gated-modeller, ett token utan modellläsbehörighet, eller hastighetsbegränsningar. Att sätta HF_TOKEN korrekt löser fallet med gated-modeller.

CUDA out of memory eller plötsliga omstarter under belastning

Den vanligaste orsaken är överdrivet generösa token-budgetar. Om max_total_tokens är stor och klienter begär långa generationer, kommer servern att reservera minne för värsta-fallet-förfrågningar. Minska budgeten, minska konkurrens, eller välj en kvantiseringmetod som passar dina begränsningar.

Multi-GPU NCCL-fel, hängningar eller extrema saktningar

När sharding sker över flera GPU:n, är shared memory och NCCL viktiga. Otillräckligt shared memory inuti container skapar ofta instabilitet. Att öka shared memory-allokering eller inaktivera SHM-delning via NCCL_SHM_DISABLE kan ändra beteende, med en prestanda-avvägning.

NCCL-problem blir också enklare att felsöka när NCCL-debuggloggning är aktiverad, eftersom felrapporterna är mer explicita.

Udda kärnelfel på icke-A100-hårdvara

Vissa modeller använder custom kernels som testades på specifik hårdvara först. Om du ser o förklarade kärnelfel, är --disable-custom-kernels ofta det enklaste sättet att bekräfta om custom kernels är inblandade.

Portförvirring och “det kör men jag kan inte nå det”

En klassisk fotfälla är att blanda Docker-portmappningsmodellen med lokal standardportmodell. I Docker-exempel serverar containern vanligtvis på 80, medan lokala körningar standardiserar på 3000. Om du mappar fel port, landar dina curl-förfrågningar på ingenting, och systemet ser ut att vara trasigt när det faktiskt bara är orättillgängligt.

Avslutande notering

TGI känns som infrastruktur. Det är komplimangen. Det är ett system designat för att göra textgenerering tråkigt nog att operera, mätbart nog att felsöka, och flexibelt nog att passa in i befintliga OpenAI-formade klientstackar.