TGI — Text Generation Inference: установка, настройка и устранение неполадок

Text Generation Inference (TGI) обладает очень специфической энергетикой. Это не самый новый проект на улице инференса, но это тот, который уже научился, как происходит работа в продакшене, —

— и внедрил эти уроки в настройки по умолчанию. Если ваша цель — «развернуть LLM за HTTP и поддерживать его работу», TGI — это прагматичный инструмент.

Если вы всё ещё взвешиваете варианты размещения моделей, это сравнение хостинга LLM в 2026 году объединяет локальные, самодостаточные и облачные решения, чтобы вы могли увидеть TGI в контексте.

Сначала проверка реальности. По состоянию на 2026 год TGI находится в режиме обслуживания, а репозиторий upstream архивирован с правами только на чтение. Это звучит как плохая новость, пока вы не посмотрите на это с точки зрения эксплуатации. Стабильный движок может стать преимуществом, особенно когда основные изменения происходят в моделях, промптах и требованиях продукта.

Это руководство сосредоточено на четырёх вещах, которые важны в первый день и через тридцать дней: пути установки, работающий быстрый старт, конфигурация, реально меняющая поведение, и mindset устранения неполадок, который экономит время.

Почему TGI всё ещё важен в 2026 году

Легко рассматривать серверы инференса как взаимозаменяемые. Для обзора распространённых локальных стеков начните с Ollama vs vLLM vs LM Studio: Лучший способ запуска LLM локально в 2026?.

На практике существуют только три вопроса, которые имеют значение.

Во-первых, как система ведёт себя под нагрузкой. TGI построен вокруг непрерывного батчинга и потоковой передачи токенов, поэтому он может приоритизировать пропускную способность, сохраняя при этом для пользователей иллюзию отзывчивости.

Во-вторых, может ли он говорить на том диалекте, на котором говорит ваше окружение. TGI поддерживает свой собственный «кастомный API», а также Messages API, совместимый со схемой OpenAI Chat Completions. Это означает, что инструменты, ожидающие эндпоинт в стиле OpenAI, часто можно направить на TGI с минимальными изменениями.

В-третьих, можно ли наблюдать за ним без догадок. TGI экспонирует метрики Prometheus и поддерживает распределённую трассировку через OpenTelemetry, что является разницей между «я думаю, что это медленно» и «prefill насыщен, время очереди растёт, а бюджет токенов для батча слишком высок».

Пути установки и предварительные требования

TGI можно использовать через Docker или через локальную установку из исходного кода. Путь через Docker — это то, что большинство людей имеют в виду, когда говорят «установить TGI», потому что он упаковывает маршрутизатор, сервер модели и ядра в образ, который можно запустить одной командой.

Под капотом TGI — это система с различными компонентами: маршрутизатор, принимающий HTTP и выполняющий батчинг, лаунчер, оркестрирующий один или несколько процессов сервера модели, и сам сервер модели, который загружает модель и выполняет инференс. Это разделение объясняет многое из «почему» за флагами конфигурации и распространёнными режимами отказа.

Два практических предварительных требования возникают снова и снова: доступ к GPU из контейнеров и разумная стратегия кэширования весов модели. Доступ к GPU для Nvidia обычно означает установку Nvidia Container Toolkit, а кэширование означает мапирование тома хоста в контейнер, чтобы веса модели не скачивались каждый раз заново.

Локальная установка из исходного кода

Установка из исходного кода существует, но она ориентирована на разработчиков и создателей ядер. Она ожидает наличия Rust, Python 3.9+ и средств сборки, и обычно это более медленный первый шаг, чем запуск контейнера. Полезно, когда вам нужно изменить внутренности, проверить патчи или интегрироваться с очень специфической средой.

Быстрый старт с Docker

Канонический быстрый старт короток, что и является его сутью. Выберите ID модели, подключите том кэша, откройте порт и запустите контейнер.

Быстрый старт для GPU Nvidia

Это минимальный паттерн, который хорошо работает для первого запуска.

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

Эта одна команда неявно отвечает на частый вопрос FAQ: «Как запустить TGI с Docker на GPU Nvidia», показывая три неотъемлемых элемента: --gpus all, маппинг порта и ID модели.

Мелкая, но важная деталь касается маппинга портов. Контейнер обычно настроен на обслуживание HTTP на порту 80, поэтому вы маппите порт хоста 8080 на порт контейнера 80. Если вы запускаете TGI вне Docker, порт лаунчера по умолчанию часто составляет 3000, что делает путаницу с портами такой распространённой ошибкой первого дня.

Первый запрос с использованием кастомного API

TGI предоставляет простой JSON API в стиле «generate». Потоковый запрос выглядит так.

curl 127.0.0.1:8080/generate_stream \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"Что такое глубокое обучение?","parameters":{"max_new_tokens":40}}'

Если вы предпочитаете единый ответ, используйте непотоковый эндпоинт.

curl 127.0.0.1:8080/generate \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"Объясните непрерывный батчинг в одном абзаце.","parameters":{"max_new_tokens":120}}'

Первый запрос с использованием API Messages

Если ваша экосистема ожидает запросы чата в стиле OpenAI, используйте API Messages. Это напрямую связано с другим вопросом FAQ: «Как использовать TGI с клиентами чата, совместимыми с OpenAI».

curl 127.0.0.1:8080/v1/chat/completions \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "Вы — лаконичный помощник."},
      {"role": "user", "content": "Дайте однострочное определение тензорного параллелизма."}
    ],
    "stream": false,
    "max_tokens": 60
  }'

Развертывание закрытых или приватных моделей

Если вы когда-нибудь спрашивали: «Как развернуть закрытые или приватные модели Hugging Face с помощью TGI», ответ скучен по замыслу: предоставьте токен Hub через 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

Режим отказа здесь тоже скучен: отсутствие прав доступа, неверные области действия токена или попытка получить модель, требующую принятия лицензии.

Быстрый старт для AMD ROCm

TGI также имеет образы ROCm и другой настройкой устройств. Если вы используете GPU AMD, форма запуска меняется.

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

Запуски на CPU существуют, но это не платформа, для которой TGI был спроектирован, чтобы сиять. Когда вы делаете это всё же, отключение кастомных ядер избегает некоторых специфичных для оборудования проблем.

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

Конфигурация, которая действительно двигает дело

В TGI много флагов. Большинство из них не стоит запоминать. Несколько стоит понять, потому что они отвечают на самый часто запрашиваемый вопрос в этой области: «Какие настройки TGI управляют памятью GPU и лимитами запросов».

Бюджет памяти — это max_total_tokens

Единственная самая важная концепция в конфигурации TGI заключается в том, что серверу нужен бюджет токенов для планирования батчинга и предотвращения переполнения памяти.

Существуют два лимита, определяющих форму запроса: max_input_tokens и max_total_tokens.

max_total_tokens действует как бюджет памяти на каждый запрос, потому что он ограничивает входные токены плюс сгенерированные токены. Если он слишком высок, каждый запрос становится дорогим, батчинг становится неуклюжим, а давление на память растёт. Если он слишком низок, пользователи рано сталкиваются с ограничениями длины, и сервер отклоняет в остальном валидные нагрузки.

Конфигурация, делающая бюджет явным, выглядит так.

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

Регулировочные ручки батчинга, которые имеют значение

После установки бюджетов токенов, управление батчингом — это следующая рычаг.

max_batch_prefill_tokens ограничивает работу prefill, которая часто является наиболее требовательной к памяти и вычислительным ресурсам фазой. max_batch_total_tokens устанавливает, сколько токенов сервер пытается уместить в батч в целом. Это один из реальных контроллеров пропускной способности.

Интересная ручка — waiting_served_ratio. Она кодирует политическое решение, а не ограничение оборудования. Она контролирует, когда сервер приостанавливает выполнение работы декодирования, чтобы внести ожидающие запросы в новый prefill, чтобы они могли присоединиться к группе декодирования. Низкие значения склоняются в пользу существующих запросов, высокие значения склоняются к уменьшению хвостовой задержки для новых запросов в очереди, и оба могут быть «правильными» в зависимости от формы трафика.

Шардинг, num shard и почему появляется NCCL

Если ваша модель не помещается на одном GPU, или вы хотите более высокую пропускную способность через тензорный параллелизм, шардинг — это следующий шаг.

Ментальная модель проста: --sharded true включает шардинг, а --num-shard контролирует количество шардов. Сервер по умолчанию может использовать все видимые GPU или их подмножество.

Полезный паттерн на хостах с несколькими GPU — разделение GPU на группы и запуск нескольких реплик TGI, каждая из которых шардирована по своему подмножеству GPU. Это распределяет нагрузку, сохраняя топологию шардинга простой.

Именно здесь вопрос FAQ «Почему TGI падает с ошибками NCCL или общей памяти на нескольких GPU» становится актуальным. Настройки с несколькими GPU полагаются на коллективную коммуникацию, и контейнерам требуется достаточно общей памяти для безопасной работы, когда используется отказоустойчивый механизм SHM.

Выбор квантования и какие компромиссы они несут

Квантование — это наиболее неправильно понимаемая настройка «заставить это влезть», потому что она смешивает две разные цели: снижение потребления памяти и скорость.

TGI поддерживает предварительно квантованные веса для схем вроде GPTQ и AWQ, а также квантование на лету для определённых методов, таких как bitsandbytes и EETQ. Некоторые методы снижают потребление памяти, но работают медленнее, чем нативная полуточность, поэтому квантование не следует рассматривать как бесплатное улучшение производительности.

Простой пример квантования на лету с 8 битами выглядит так.

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

А вариант с 4 битами выглядит так.

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 и базовые защитные механизмы

TGI можно запускать как внутренний сервис или экспонировать более широко. Если экспонирование возможно, два флага имеют значение: max_concurrent_requests и api_key.

max_concurrent_requests обеспечивает обратное давление. Он заставляет сервер отказываться от избыточных запросов, а не позволять всему выстроиться в очередь и истечь по времени.

API-ключ обеспечивает грубую барьеру аутентификации. Это не полноценная система аутентификации, но она предотвращает случайное публичное использование.

CORS также можно настроить через cors_allow_origin, что важно, если на основе браузера UI обращается к серверу напрямую.

Эксплуатация и наблюдаемость

Этот раздел отвечает на реальный вопрос оператора: «Откуда можно собирать метрики Prometheus с сервера TGI».

Документация OpenAPI и интерактивная документация

TGI экспонирует свою документацию OpenAPI и Swagger UI по маршруту /docs, что удобно, когда вы хотите быстро подтвердить формы запросов и ответов или протестировать эндпоинты без написания клиента.

Метрики Prometheus

TGI экспортирует метрики Prometheus на эндпоинт /metrics. Эти метрики охватывают размер очереди, задержку запросов, количество токенов и временные метки уровня батча. В результате вы можете наблюдать, ограничивается ли система prefill, декодированием или очередью.

Производственный мониторинг от начала до конца — PromQL, дашборды Grafana, оповещения и макеты сбора для Docker или Kubernetes для этих стеков — покрыты в Мониторинг инференса LLM в продакшене (2026): Prometheus & Grafana для vLLM, TGI, llama.cpp.

Трассировка и структурированные логи

TGI поддерживает распределённую трассировку через OpenTelemetry. Логи также могут выводиться в формате JSON, что упрощает работу с конвейерами логов.

Плейбук устранения неполадок

Отказы TGI склонны группироваться в несколько категорий, и у каждой категории есть очень разные решения.

Контейнер запущен, но GPU не обнаружен

Самая распространённая причина заключается в том, что среда выполнения контейнера не настроена для передачи GPU. На Nvidia это часто коррелирует с отсутствием поддержки Nvidia Container Toolkit или запуском на стеке драйверов хоста, не соответствующем ожиданиям.

Ошибки загрузки модели и ошибки разрешений

Если сервер не может загрузить файлы модели, обычными виновниками являются отсутствующий токен аутентификации для закрытых моделей, токен без прав чтения модели или лимиты частоты запросов. Правильная настройка HF_TOKEN решает проблему с закрытыми моделями.

Ошибки CUDA out of memory или внезапные перезапуски под нагрузкой

Самая распространённая причина — чрезмерно разрешительные бюджеты токенов. Если max_total_tokens велик, а клиенты запрашивают длинные генерации, сервер будет резервировать память для худших сценариев запросов. Уменьшите бюджет, уменьшите параллелизм или выберите метод квантования, который соответствует вашим ограничениям.

Ошибки NCCL на нескольких GPU, зависания или экстремальные замедления

При шардинге между несколькими GPU важны общая память и NCCL. Недостаточная общая память внутри контейнеров часто создаёт нестабильность. Увеличение выделения общей памяти или отключение общего SHM через NCCL_SHM_DISABLE может изменить поведение, с компромиссом в производительности.

Проблемы с NCCL также легче отлаживать, когда включено отладочное логирование NCCL, потому что сообщения об ошибках становятся более явными.

Странные ошибки ядра на оборудовании, отличном от A100

Некоторые модели используют кастомные ядра, которые сначала тестировались на специфичном оборудовании. Если вы видите необъяснимые сбои ядра, --disable-custom-kernels часто является самым простым способом подтвердить, вовлечены ли кастомные ядра.

Путаница с портами и «оно работает, но я не могу достичь его»

Классическая ловушка — смешивание модели маппинга портов Docker с моделью порта по умолчанию при локальном запуске. В примерах Docker контейнер часто обслуживает запросы на порту 80, в то время как локальные запуски по умолчанию используют 3000. Если вы маппите неправильный порт, ваши запросы curl попадают в пустоту, и система выглядит сломанной, хотя на самом деле она просто недоступна.

Заключительное примечание

TGI ощущается как инфраструктура. Это комплимент. Это система, спроектированная так, чтобы сделать генерацию текста достаточно скучной для эксплуатации, достаточно измеримой для отладки и достаточно гибкой, чтобы вписаться в существующие клиентские стеки в стиле OpenAI.