TGI – Text Generation Inference – instalacja, konfiguracja, rozwiązywanie problemów

Text Generation Inference (TGI) ma bardzo specyficzną energię. Nie jest najmłodszym dzieckiem na ulicy inferencji, ale jest tym, które już nauczyło się, jak produkcja się psuje –

a następnie wpleciło te lekcje w domyślne ustawienia. Jeśli Twoim celem jest „uruchomienie LLM za HTTP i utrzymanie jego działania", TGI jest pragmatycznym zestawem narzędzi.

Jeśli nadal rozważasz, gdzie uruchamiać modele, to porównanie hostowania LLM w 2026 roku zestawia lokalne, self-hosted i chmurowe konfiguracje, dzięki czemu możesz umieścić TGI w odpowiednim kontekście.

Najpierw realistyczna weryfikacja. Stanem na 2026 rok, TGI znajduje się w trybie konserwacji, a repozytorium upstream zostało zarchiwizowane jako tylko do odczytu. To brzmi jak zła wiadomość, dopóki nie spojrzy się na to z perspektywy operacyjnej. Stabilny silnik może być funkcją, zwłaszcza gdy prawdziwe zmiany dotyczą modeli, promptów i wymagań produktu.

Ten przewodnik koncentruje się na czterech rzeczach, które mają znaczenie w dniu zerowym i trzydziestym: ścieżki instalacji, szybki start, który faktycznie działa, konfiguracja, która zmienia rzeczywiste zachowanie, oraz podejście do rozwiązywania problemów, które oszczędza czas.

Dlaczego TGI nadal ma znaczenie w 2026 roku

Łatwo traktować serwery inferencji jako zamienne. Dla przeglądu narzędzi wspólnych lokalnych stosów, zacznij od Ollama vs vLLM vs LM Studio: Najlepszy sposób na uruchamianie LLM lokalnie w 2026 roku?.

W praktyce istnieją tylko trzy pytania, które mają znaczenie.

Po pierwsze, jak zachowuje się pod obciążeniem. TGI został zbudowany wokół ciągłego batchingu i strumieniowania tokenów, dzięki czemu może priorytetyzować przepływność, jednocześnie dając użytkownikom iluzję responsywności.

Po drugie, czy może mówić dialektem, którego używa Twoje narzędzie. TGI obsługuje własne „niestandardowe API" oraz Messages API, które jest kompatybilne ze schematem OpenAI Chat Completions. Oznacza to, że narzędzia oczekujące endpointu w kształcie OpenAI często można skierować do TGI z minimalnymi zmianami.

Po trzecie, czy możesz je obserwować bez zgadywania. TGI udostępnia metryki Prometheus i obsługuje rozproszone śledzenie (tracing) poprzez OpenTelemetry, co jest różnicą między „myślę, że to wolne" a „prefill jest nasycony, czas kolejki rośnie, a budżet tokenów dla batcha jest zbyt wysoki".

Ścieżki instalacji i wymagania wstępne

Do TGI można podejść za pomocą Dockera lub zainstalować lokalnie ze źródeł. Ścieżka Docker to droga, o której większość ludzi myśli, mówiąc „zainstaluj TGI", ponieważ pakuje router, serwer modelu i jądra do obrazu, który można uruchomić pojedynczym poleceniem.

Pod spodem TGI jest systemem z odrębnymi komponentami: routerem, który akceptuje HTTP i wykonuje batchowanie, uruchamiaczem (launcherem), który koordynuje jeden lub więcej procesów serwera modelu, oraz serwerem modelu, który ładuje model i wykonuje inferencję. To rozdzielenie wyjaśnia wiele „dlaczego" za flagami konfiguracyjnymi i częstymi trybami awarii.

Dwa praktyczne wymagania pojawiają się raz po raz: dostęp do GPU z kontenerów oraz rozsądna strategia cache dla wag modelu. Dostęp do GPU dla Nvidia zazwyczaj oznacza zainstalowane Nvidia Container Toolkit, a cache oznacza mapowanie wolumenu hosta do kontenera, aby wagi modelu nie pobierały się ponownie za każdym razem.

Instalacja lokalna ze źródeł

Instalacja ze źródeł istnieje, ale jest skierowana opiniowo do deweloperów i budowniczych jąder. Oczekuje Rusta, Pythona 3.9+ oraz narzędzi budowlanych, i zazwyczaj jest wolniejszym pierwszym krokiem niż uruchamianie kontenera. Przydatne, gdy potrzebujesz zmodyfikować wnętrze, przetestować łaty lub zintegrować się z bardzo specyficznym środowiskiem.

Szybki start z Dockerem

Kanoniczny szybki start jest krótki, co jest dokładnie jego celem. Wybierz ID modelu, zamontuj wolumen cache, wystaw port i uruchom kontener.

Szybki start z GPU Nvidia

To minimalny wzorzec, który działa dobrze przy pierwszym uruchomieniu.

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

To jedno polecenie domyślnie odpowiada na częste pytanie FAQ: „Jak uruchomić TGI z Dockerem na GPU Nvidia", pokazując trzy niepodważalne elementy: --gpus all, mapowanie portu oraz ID modelu.

Subtelnym, ale ważnym punktem jest mapowanie portu. Kontener jest zazwyczaj skonfigurowany do obsługi HTTP na porcie 80, więc mapujesz port hosta 8080 na port kontenera 80. Jeśli uruchamiasz TGI poza Dockerem, domyślny port dla uruchamiacza często wynosi 3000, dlatego pomylenie portów jest tak powszechnym błędem pierwszego dnia.

Pierwsze żądanie przy użyciu niestandardowego API

TGI udostępnia prosty API w stylu JSON „generate". Żądanie strumieniowe wygląda tak.

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

Jeśli wolisz pojedynczą odpowiedź, użyj endpointu bez strumieniowania.

curl 127.0.0.1:8080/generate \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"Explain continuous batching in one paragraph.","parameters":{"max_new_tokens":120}}'

Pierwsze żądanie przy użyciu API Messages

Jeśli Twoje środowisko oczekuje żądań czatu w stylu OpenAI, użyj API Messages. To bezpośrednio dotyczy innego pytania FAQ: „Jak można użyć TGI z klientami czatu kompatybilnymi z OpenAI".

curl 127.0.0.1:8080/v1/chat/completions \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Give a one sentence definition of tensor parallelism."}
    ],
    "stream": false,
    "max_tokens": 60
  }'

Serwisowanie modeli ograniczonych lub prywatnych

Jeśli kiedykolwiek zadałeś pytanie „Jak serwisować ograniczone lub prywatne modele Hugging Face z TGI", odpowiedź jest nudna z założenia: podaj token Huba poprzez 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

Tryb awarii tutaj jest również nudny: brak uprawnień, nieważne zakresy tokenów lub próba pobrania modelu wymagającego akceptacji licencji.

Szybki start z AMD ROCm

TGI posiada również obrazy ROCm i inne ustawienia urządzenia. Jeśli korzystasz z GPU AMD, kształt uruchamiania się zmienia.

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

Uruchamianie tylko na CPU

Uruchamiania tylko na CPU istnieją, ale to nie jest platforma, do której TGI został zaprojektowany, aby był świetny. Kiedy to robisz mimo wszystko, wyłączenie niestandardowych jąder unika niektórych problemów specyficznych dla sprzętu.

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

Konfiguracja, która faktycznie przesuwa igłę

TGI ma wiele flag. Większość z nich nie warto zapamiętywać. Kilka jest warta zrozumienia, ponieważ odpowiadają na najczęściej wyszukiwane pytanie w tej dziedzinie: „Jakie ustawienia TGI kontrolują pamięć GPU i limity żądań".

Budżet pamięci to maksymalna łączna liczba tokenów

Pojedynczym, najważniejszym pojęciem w konfiguracji TGI jest fakt, że serwer potrzebuje budżetu tokenów do planowania batchingu i unikania wybuchów pamięci.

Istnieją dwa limity definiujące kształt żądań: max_input_tokens i max_total_tokens.

max_total_tokens działa jak budżet pamięci dla pojedynczego żądania, ponieważ ogranicza tokeny wejściowe plus wygenerowane tokeny. Jeśli jest zbyt wysoki, każde żądanie staje się kosztowne, batchowanie staje się niezręczne, a presja na pamięć rośnie. Jeśli jest zbyt niski, użytkownicy szybko napotykają limity długości, a serwer odrzuca w przeciwnym razie ważne obciążenia.

Konfiguracja, która ujawnia budżet, wygląda tak.

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

Pętle batchingu, które mają znaczenie

Gdy budżety tokenów są ustawione, kontrola batchingu to dźwiga.

max_batch_prefill_tokens ogranicza pracę prefill, która jest często najbardziej wymagającą pod względem pamięci i obliczeń fazą. max_batch_total_tokens ustawia, ile tokenów serwer próbuje zmieścić w batchu ogółem. To jeden z prawdziwych kontrolerów przepływności.

Ciekawą pętlą jest waiting_served_ratio. Koduje decyzję polityczną, a nie ograniczenie sprzętowe. Kontroluje, kiedy serwer zatrzymuje działanie dekodowania, aby wprowadzić czekające żądania do nowego prefillu, aby mogły dołączyć do grupy dekodowania. Niskie wartości cenderung faworyzują istniejące żądania, wysokie wartości tendencyjnie redukują opóźnienie ogona dla nowo kolejowanych żądań, i obie mogą być „poprawne" w zależności od kształtu ruchu.

Sharding, num shard i dlaczego pojawia się NCCL

Jeśli Twój model nie mieści się na jednym GPU, lub chcesz wyższej przepływności poprzez równoległość tensorów, sharding to kolejny krok.

Model mentalny jest prosty: --sharded true włącza sharding, a --num-shard kontroluje liczbę shardów. Serwer może użyć wszystkich widocznych GPU domyślnie lub użyć podzbioru.

Użytecznym wzorcem na hostach z wieloma GPU jest dzielenie GPU na grupy i uruchamianie wielu replik TGI, gdzie każda replika jest sharded na własnym podzbiorze GPU. To rozprasza obciążenie, utrzymując prostą topologię sharding.

To również miejsce, gdzie pytanie FAQ „Dlaczego TGI zawodzi z błędami NCCL lub pamięci współdzielonej na wielu GPU" staje się istotne. Konfiguracje wielo-GPU polegają na komunikacji zbiorowej, a kontenery potrzebują wystarczającej pamięci współdzielonej dla bezpiecznej operacji, gdy używany jest SHM fallback.

Wybory kwantyzacji i co oferują

Kwantyzacja jest najbardziej niezrozumiałym ustawieniem „zrób to, żeby zmieściło się", ponieważ miesza dwa różne cele: redukcję pamięci i prędkość.

TGI obsługuje wagi pre-kwantyzowane dla schematów takich jak GPTQ i AWQ, a także kwantyzację na bieżąco dla niektórych metod, takich jak bitsandbytes i EETQ. Niektóre metody redukują pamięć, ale są wolniejsze niż natywna precyzja połowiczna, dlatego kwantyzacja nie powinna być traktowana jako darmowa ulepszenie wydajności.

Prosty przykład kwantyzacji 8-bitowej na bieżąco wygląda tak.

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

A wariant 4-bitowy wygląda tak.

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

Shaping API i podstawowe barierki

TGI może być uruchamiany jako usługa wewnętrzna lub wystawiany szerszo. Jeśli wystawienie jest możliwe, dwie flagi mają znaczenie: max_concurrent_requests i api_key.

max_concurrent_requests zapewnia przeciwwagę. Zmusza serwer do odrzucania nadmiernych żądań zamiast pozwalać wszystkim kolejkować się i wygasnąć.

Klucz API zapewnia grubą barierę uwierzytelniania. To nie jest pełny system uwierzytelniania, ale zapobiega przypadkowemu użytkowaniu publicznemu.

CORS jest również konfigurowalny poprzez cors_allow_origin, co ma znaczenie, jeśli interfejs użytkownika oparty na przeglądarce wywołuje serwer bezpośrednio.

Operacje i obserwowalność

Ta sekcja odpowiada na prawdziwe pytanie operatora: „Gdzie można pobrać metryki Prometheus z serwera TGI".

Dokumentacja OpenAPI i interaktywna dokumentacja

TGI udostępnia swoje OpenAPI i Swagger UI pod trasą /docs, co jest przydatne, gdy chcesz szybko potwierdzić kształty żądań i odpowiedzi lub przetestować endpointy bez pisania klienta.

Metryki Prometheus

TGI eksportuje metryki Prometheus na endpoint /metrics. Te metryki obejmują rozmiar kolejki, opóźnienia żądań, liczbę tokenów i czasy na poziomie batcha. Wynik jest taki, że możesz obserwować, czy system jest ograniczony przez prefill, dekodowanie lub kolejkowanie.

Pełne monitorowanie produkcyjne – PromQL, pulpity Grafana, alerty i układy scrapingu dla Docker lub Kubernetes dla tych stosów – jest omówione w Monitorowanie Inferencji LLM w Produkcji (2026): Prometheus & Grafana dla vLLM, TGI, llama.cpp.

Śledzenie i strukturalne logi

TGI obsługuje rozproszone śledzenie (tracing) poprzez OpenTelemetry. Logi mogą również być emitowane w formacie JSON, co ułatwia rury logów.

Playbook rozwiązywania problemów

Awarie TGI mają tendencję do grupowania się w kilka kategorii, a każda kategoria ma bardzo inną naprawę.

Kontener działa, ale nie wykrywa GPU

Najczęstszą przyczyną jest to, że runtime kontenera nie jest skonfigurowany do przepuszczania GPU. Na Nvidia często koreluje to z brakującym wsparciem Nvidia Container Toolkit lub uruchamianiem na stosie sterownika hosta, który nie spełnia oczekiwań.

Błędy pobierania modelu i błędy uprawnień

Jeśli serwer nie może pobrać plików modelu, zwykłymi winowajcami są brak tokena uwierzytelniającego dla modeli ograniczonych, token bez uprawnień do odczytu modelu lub limity stawki. Ustawienie HF_TOKEN poprawnie rozwiązuje przypadek modeli ograniczonych.

Błąd CUDA out of memory lub nagłe restarty pod obciążeniem

Najczęstszą przyczyną są zbyt liberalne budżety tokenów. Jeśli max_total_tokens jest duże, a klienci żądają długich generacji, serwer zarezerwuje pamięć dla żądań w najgorszym scenariuszu. Zmniejsz budżet, zmniejsz konkurencyjność lub wybierz metodę kwantyzacji, która pasuje do Twoich ograniczeń.

Błędy NCCL na wielu GPU, zawieszenia lub skrajne spowolnienia

Podczas sharding na wielu GPU, pamięć współdzielona i NCCL mają znaczenie. Niedostateczna pamięć współdzielona wewnątrz kontenerów często tworzy niestabilność. Zwiększenie alokacji pamięci współdzielonej lub wyłączenie współdzielenia SHM poprzez NCCL_SHM_DISABLE może zmienić zachowanie, z kompromisem wydajności.

Problemy z NCCL stają się również łatwiejsze do debugowania, gdy włączony jest dziennik debugowania NCCL, ponieważ raporty błędów są bardziej explicite.

Dziwne błędy jądra na sprzęcie innym niż A100

Niektóre modele używają niestandardowych jąder, które zostały przetestowane najpierw na konkretnym sprzęcie. Jeśli widzisz niejasne awarie jądra, --disable-custom-kernels jest często najprostszym sposobem na potwierdzenie, czy niestandardowe jądra są zaangażowane.

Pomylenie portów i „działa, ale nie mogę się połączyć"

Klasycznym błędem jest mieszanie modelu mapowania portów Dockera z modeliem domyślnego portu lokalnego. W przykładach Docker kontener często obsługuje na porcie 80, podczas gdy uruchomienia lokalne domyślnie mają 3000. Jeśli zmappujesz niewłaściwy port, Twoje żądania curl lądują na niczym, a system wygląda na uszkodzony, gdy tak naprawdę jest tylko nieosiągalny.

Zakończenie

TGI czuje się jak infrastruktura. To komplement. Jest to system zaprojektowany tak, aby generowanie tekstu było na tyle nudne, aby można było nim operować, na tyle mierzalne, aby można było je debugować, i na tyle elastyczne, aby pasowało do istniejących stosów klientów w kształcie OpenAI.