TGI – Text Generation Inference – Instalação, Configuração e Solução de Problemas

A Inferência de Geração de Texto (TGI) tem uma energia muito específica. Não é o mais novo na rua da inferência, mas é aquele que já aprendeu como a produção quebra -

e transformou essas lições em padrões. Se o seu objetivo é “servir um LLM atrás de HTTP e mantê-lo em execução”, o TGI é uma ferramenta pragmática.

Se você ainda está ponderando onde executar modelos, esta comparação de hospedagem de LLM em 2026 reúne setups locais, auto-hospedados e em nuvem para que você possa contextualizar o TGI.

Uma verificação da realidade primeiro. Em 2026, o TGI está em modo de manutenção e o repositório upstream foi arquivado como somente leitura. Isso parece uma má notícia até que você analise do ponto de vista de operações. Um motor estável pode ser um recurso, especialmente quando a verdadeira rotatividade está nos modelos, prompts e requisitos de produto.

Este guia foca em quatro coisas que importam no dia zero e no dia trinta: caminhos de instalação, um quickstart que realmente funciona, configurações que alteram o comportamento real e uma mentalidade de solução de problemas que economiza tempo.

Por que o TGI ainda importa em 2026

É fácil tratar servidores de inferência como intercambiáveis. Para uma pesquisa ferramenta por ferramenta de stacks locais comuns, comece em Ollama vs vLLM vs LM Studio: Melhor forma de rodar LLMs localmente em 2026?.

Na prática, existem apenas três perguntas que importam.

Primeiro, como ele se comporta sob carga. O TGI é construído em torno de batching contínuo e streaming de tokens, então ele pode priorizar a vazão (throughput) enquanto ainda dá aos usuários a ilusão de responsividade.

Segundo, ele pode falar o dialeto que sua ferramenta já fala? O TGI suporta sua própria “API personalizada” e também uma API de Mensagens compatível com o esquema de Completas de Chat da OpenAI. Isso significa que ferramentas que esperam um endpoint com formato OpenAI podem frequentemente ser apontadas para o TGI com mudanças mínimas.

Terceiro, você pode observá-lo sem adivinhar. O TGI expõe métricas Prometheus e suporta rastreamento distribuído via OpenTelemetry, o que é a diferença entre “acho que está lento” e “prefill está saturando, tempo de fila está crescendo e o orçamento de tokens por batch está muito alto”.

Caminhos de instalação e pré-requisitos

O TGI pode ser abordado via Docker ou via instalação local a partir do código-fonte. A rota Docker é o caminho que a maioria das pessoas quer dizer quando diz “instalar TGI”, porque ele empacota o roteador, servidor de modelo e kernels em uma imagem que pode rodar com um único comando.

Por baixo do capô, o TGI é um sistema com componentes distintos: um roteador que aceita HTTP e realiza batching, um lançador (launcher) que orquestra um ou mais processos de servidor de modelo, e o servidor de modelo que carrega o modelo e realiza a inferência. Essa separação explica muito do “porquê” por trás de flags de configuração e modos de falha comuns.

Dois pré-requisitos práticos aparecem repetidamente: acesso a GPU de containers e uma estratégia de cache sensata para pesos de modelos. Acesso a GPU da Nvidia geralmente significa que o Nvidia Container Toolkit está instalado, e cache significa mapear um volume de host para o container para que os pesos do modelo não sejam rebaixados a cada vez.

Instalação local a partir do código-fonte

Uma instalação a partir do código-fonte existe, mas é opinada para desenvolvedores e construtores de kernels. Ela espera Rust, Python 3.9+ e ferramentas de build, e geralmente é um primeiro passo mais lento do que rodar o container. É útil quando você precisa modificar internals, testar patches ou integrar com um ambiente muito específico.

Quickstart com Docker

O quickstart canônico é curto, o que é exatamente o ponto. Escolha um ID de modelo, monte um volume de cache, exponha uma porta e rode o container.

Quickstart com GPU Nvidia

Este é um padrão minimalista que funciona bem para a primeira inicialização.

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

Aquele único comando implicitamente responde a uma pergunta frequente de FAQ, “Como você roda o TGI com Docker em uma GPU Nvidia”, mostrando os três não negociáveis: --gpus all, um mapeamento de porta e um ID de modelo.

Um ponto sutil, mas importante, é o mapeamento de porta. O container é tipicamente configurado para servir HTTP na porta 80, então você mapeia a porta 8080 do host para a porta 80 do container. Se você rodar o TGI fora do Docker, a porta padrão para o lançador é frequentemente 3000, o que é por que a confusão de portas é um bug tão comum no primeiro dia.

Primeiro pedido usando a API personalizada

O TGI expõe uma API JSON simples de estilo “generate”. Um pedido de streaming parece com isso.

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

Se você preferir uma única resposta, use o endpoint não streaming.

curl 127.0.0.1:8080/generate \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"Explique batching contínuo em um parágrafo.","parameters":{"max_new_tokens":120}}'

Primeiro pedido usando a API de Mensagens

Se seu ecossistema espera pedidos de chat no estilo OpenAI, use a API de Mensagens. Isso se relaciona diretamente com outra pergunta de FAQ, “Como você pode usar o TGI com clientes de chat compatíveis com OpenAI”.

curl 127.0.0.1:8080/v1/chat/completions \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "Você é um assistente conciso."},
      {"role": "user", "content": "Dê uma definição de paralelismo de tensor em uma frase."}
    ],
    "stream": false,
    "max_tokens": 60
  }'

Servindo modelos restritos ou privados

Se você já perguntou “Como você serve modelos restritos ou privados do Hugging Face com o TGI”, a resposta é chata por design: forneça um token Hub 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

O modo de falha aqui também é chato: permissões ausentes, escopos de token inválidos ou tentar puxar um modelo que requer aceitação de uma licença.

Quickstart com AMD ROCm

O TGI também tem imagens ROCm e uma configuração de dispositivo diferente. Se você estiver em GPUs AMD, a forma de boot muda.

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

Execuições apenas com CPU

Execuções apenas com CPU existem, mas não é a plataforma para a qual o TGI foi projetado para ser brilhante. Quando você faz isso mesmo assim, desabilitar kernels personalizados evita alguns problemas específicos de hardware.

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

Configuração que realmente move a agulha

O TGI tem muitos flags. A maioria deles não vale a pena memorizar. Alguns valem a pena entender, porque eles respondem à pergunta mais pesquisada neste espaço: “Quais configurações do TGI controlam a memória da GPU e limites de pedidos”.

Orçamento de memória é o máximo total de tokens

O conceito mais importante na configuração do TGI é que o servidor precisa de um orçamento de tokens para planejar o batching e evitar estouradas de memória.

Existem dois limites que definem a forma do pedido: max_input_tokens e max_total_tokens.

max_total_tokens atua como um orçamento de memória por pedido porque limita tokens de entrada mais tokens gerados. Se for muito alto, cada pedido se torna caro, o batching se torna estranho e a pressão de memória cresce. Se for muito baixo, os usuários atingem limites de comprimento cedo, e o servidor rejeita cargas de trabalho que seriam válidas.

Uma configuração que torna o orçamento explícito parece com isso.

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

Controles de batching que importam

Uma vez que os orçamentos de tokens sejam definidos, o controle de batching é a próxima alavanca.

max_batch_prefill_tokens limita o trabalho de prefill, que é frequentemente a fase mais pesada em memória e limitada por computação. max_batch_total_tokens define quantos tokens o servidor tenta encaixar em um batch no geral. Este é um dos controles reais de vazão.

O controle interessante é waiting_served_ratio. Ele codifica uma decisão de política, não uma restrição de hardware. Ele controla quando o servidor pausa o trabalho de decodificação em execução para trazer pedidos em espera para um novo prefill para que eles possam se juntar ao grupo de decodificação. Valores baixos tendem a favorecer pedidos existentes, valores altos tendem a reduzir a latência de cauda para pedidos recém-enfileirados, e ambos podem ser “corretos” dependendo da forma do tráfego.

Sharding, num shard, e por que o NCCL aparece

Se o seu modelo não cabe em uma GPU, ou você quer maior vazão via paralelismo de tensor, sharding é o próximo passo.

O modelo mental é simples: --sharded true habilita sharding, e --num-shard controla a contagem de shards. O servidor pode usar todas as GPUs visíveis por padrão, ou usar um subconjunto.

Um padrão útil em hosts multi-GPU é dividir GPUs em grupos e rodar múltiplas réplicas do TGI, cada réplica sharded através de seu próprio subconjunto de GPU. Isso espalha a carga mantendo a topologia de sharding simples.

É também aqui que a pergunta de FAQ “Por que o TGI falha com erros NCCL ou de memória compartilhada em múltiplas GPUs” se torna relevante. Setups multi-GPU dependem de comunicação coletiva, e containers precisam de memória compartilhada suficiente para operação segura quando a fallback SHM é usada.

Escolhas de quantização e o que elas trocam

Quantização é a configuração “fazer caber” mais mal compreendida porque ela mistura dois objetivos diferentes: redução de memória e velocidade.

O TGI suporta pesos pré-quantizados para esquemas como GPTQ e AWQ, e também quantização em tempo de execução para certos métodos como bitsandbytes e EETQ. Alguns métodos reduzem memória mas são mais lentos que precisão de meia precisão nativa, o que é por que quantização não deve ser tratada como uma atualização de desempenho gratuita.

Um exemplo simples de quantização de 8 bits em tempo de execução parece com isso.

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

E uma variante de 4 bits parece com isso.

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

Moldagem de API e guard rails básicos

O TGI pode ser rodado como um serviço interno, ou exposto mais amplamente. Se a exposição for possível, dois flags importam: max_concurrent_requests e api_key.

max_concurrent_requests fornece contra-pressão. Ele faz o servidor recusar pedidos excessivos em vez de deixar tudo enfileirar e dar tempo esgotado.

Uma chave de API fornece uma barreira de autenticação grosseira. Não é um sistema de auth completo, mas ele para o uso público acidental.

CORS também é configurável via cors_allow_origin, o que importa se uma UI baseada em navegador chama o servidor diretamente.

Operações e observabilidade

Esta seção responde à pergunta real do operador: “Onde você pode raspar métricas Prometheus de um servidor TGI”.

Docs OpenAPI e docs interativos

O TGI expõe sua OpenAPI e Swagger UI na rota /docs, o que é útil quando você quer confirmar rapidamente formas de pedido e resposta ou testar endpoints sem escrever um cliente.

Métricas Prometheus

O TGI exporta métricas Prometheus no endpoint /metrics. Essas métricas cobrem tamanho de fila, latência de pedidos, contagens de tokens e tempos de nível de batch. O resultado é que você pode observar se o sistema está limitado por prefill, decodificação ou enfileiramento.

Monitoramento de produção de ponta-a-ponta—PromQL, dashboards Grafana, alertas, e layouts de raspagem Docker ou Kubernetes para esses stacks—é coberto em Monitorar Inferência de LLM em Produção (2026): Prometheus & Grafana para vLLM, TGI, llama.cpp.

Rastreamento e logs estruturados

O TGI suporta rastreamento distribuído via OpenTelemetry. Logs também podem ser emitidos em JSON, o que facilita pipelines de log.

Playbook de solução de problemas

Falhas do TGI tendem a se agrupar em alguns baldes, e cada balde tem uma correção muito diferente.

O container roda mas nenhuma GPU é detectada

A causa mais comum é que o runtime do container não está configurado para passthrough de GPU. Na Nvidia, isso frequentemente correlaciona com suporte Nvidia Container Toolkit ausente, ou rodar em um stack de driver de host que não corresponde às expectativas.

Falhas de download de modelo e erros de permissão

Se o servidor não pode baixar arquivos de modelo, os culpados habituais são um token de auth ausente para modelos restritos, um token sem permissões de leitura de modelo, ou limites de taxa. Definir HF_TOKEN corretamente resolve o caso de modelo restrito.

CUDA fora de memória ou reinícios súbitos sob carga

A causa mais comum é orçamentos de tokens excessivamente permissivos. Se max_total_tokens for grande e clientes pedirem gerações longas, o servidor reservará memória para pedidos de pior caso. Reduza o orçamento, reduza a concorrência ou escolha um método de quantização que se ajuste às suas restrições.

Erros NCCL multi-GPU, travamentos ou lentidão extrema

Ao fazer sharding através de múltiplas GPUs, memória compartilhada e NCCL importam. Memória compartilhada insuficiente dentro de containers frequentemente cria instabilidade. Aumentar a alocação de memória compartilhada ou desabilitar compartilhamento SHM via NCCL_SHM_DISABLE pode mudar o comportamento, com uma compensação de desempenho.

Problemas NCCL também se tornam mais fáceis de debugar quando o log de debug NCCL é habilitado, porque os relatórios de erro são mais explícitos.

Erros de kernel estranhos em hardware não A100

Alguns modelos usam kernels personalizados que foram testados em hardware específico primeiro. Se você ver falhas de kernel inexplicáveis, --disable-custom-kernels é frequentemente a maneira mais simples de confirmar se kernels personalizados estão envolvidos.

Confusão de porta e “roda mas eu não consigo alcançá-lo”

Um erro clássico é misturar o modelo de mapeamento de porta Docker com o modelo de porta padrão local. Em exemplos Docker, o container frequentemente serve na porta 80, enquanto execuções locais padrão para 3000. Se você mapear a porta errada, seus pedidos curl caem em nada, e o sistema parece quebrado quando na verdade é apenas inacessível.

Nota de encerramento

O TGI sente-se como infraestrutura. Esse é o elogio. É um sistema projetado para tornar a geração de texto entediante o suficiente para operar, mensurável o suficiente para debugar, e flexível o suficiente para se encaixar em stacks de clientes existentes com formato OpenAI.