TGI - Text Generation Inference - Installazione, Configurazione e Risoluzione dei Problemi

Text Generation Inference (TGI) ha un’energia molto specifica. Non è il più nuovo arrivato nella strada dell’inferenza, ma è quello che ha già imparato come la produzione si rompe -

e poi ha incorporato quelle lezioni nei valori predefiniti. Se il tuo obiettivo è “eseguire un LLM dietro HTTP e mantenerlo in esecuzione”, TGI è un pezzo pragmatico di attrezzatura.

Se stai ancora valutando dove eseguire i modelli, questo confronto sull’hosting LLM nel 2026 unisce le configurazioni locali, self-hosted e cloud in modo da poter inserire TGI nel contesto.

Un controllo della realtà per prima. Nel 2026, TGI è in modalità manutenzione e il repository upstream è stato archiviato in sola lettura. Sembra una cattiva notizia finché non lo si guarda da una prospettiva operativa. Un motore stabile può essere una caratteristica, specialmente quando il vero cambiamento riguarda i modelli, i prompt e i requisiti del prodotto.

Questa guida si concentra su quattro cose che contano al giorno zero e al giorno trenta: percorsi di installazione, un’avvio rapido che funziona davvero, una configurazione che cambia il comportamento reale e una mentalità di risoluzione dei problemi che fa risparmiare tempo.

Perché TGI è ancora rilevante nel 2026

È facile trattare i server di inferenza come intercambiabili. Per una panoramica strumento per strumento degli stack locali comuni, inizia da Ollama vs vLLM vs LM Studio: Il modo migliore per eseguire LLM localmente nel 2026?.

In pratica, ci sono solo tre domande che contano.

Prima, come si comporta sotto carico. TGI è costruito attorno al batching continuo e allo streaming dei token, quindi può dare priorità al throughput mantenendo l’illusione della reattività per gli utenti.

Secondo, può parlare il dialetto che il tuo strumento già usa. TGI supporta il suo “custom API” e anche un Messages API compatibile con lo schema Chat Completions di OpenAI. Questo significa che gli strumenti che si aspettano un endpoint con forma OpenAI possono spesso essere puntati a TGI con minimi cambiamenti.

Terzo, puoi osservarlo senza indovinare. TGI espone metriche Prometheus e supporta il tracciamento distribuito tramite OpenTelemetry, che è la differenza tra “penso che sia lento” e “il prefill è saturo, il tempo di coda sta crescendo e il budget dei token del batch è troppo alto”.

Percorsi di installazione e prerequisiti

TGI può essere affrontato tramite Docker o tramite un’installazione locale dal sorgente. Il percorso Docker è quello a cui la maggior parte delle persone si riferisce quando dice “installa TGI”, perché impacchetta il router, il server del modello e i kernel in un’immagine che può essere eseguita con un singolo comando.

Sotto il cofano, TGI è un sistema con componenti distinti: un router che accetta HTTP ed esegue il batching, un launcher che orchestra uno o più processi del server del modello e il server del modello che carica il modello ed esegue l’inferenza. Questa separazione spiega gran parte del “perché” dietro le bandiere di configurazione e i comuni modi di fallimento.

Due prerequisiti pratici si presentano di nuovo e di nuovo: l’accesso GPU dai container e una strategia di cache sana per i pesi del modello. L’accesso GPU per Nvidia tipicamente significa che il Nvidia Container Toolkit è installato, e la caching significa mappare un volume host sul container in modo che i pesi del modello non vengano scaricati ogni volta.

Installazione locale dal sorgente

Un’installazione dal sorgente esiste, ma è opinata verso gli sviluppatori e i costruttori di kernel. Si aspetta Rust, Python 3.9+ e strumenti di build, ed è solitamente un primo passo più lento rispetto all’esecuzione del container. Utile quando hai bisogno di modificare gli interni, testare patch o integrare con un ambiente molto specifico.

Avvio rapido con Docker

L’avvio rapido canonico è breve, che è esattamente il punto. Scegli un ID del modello, monta un volume di cache, espone una porta ed esegui il container.

Avvio rapido per GPU Nvidia

Questo è uno schema minimale che funziona bene per il primo avvio.

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

Quel comando singolo risponde implicitamente a una frequente domanda FAQ, “Come si esegue TGI con Docker su una GPU Nvidia” mostrando i tre elementi non negoziabili: --gpus all, una mappatura della porta e un ID del modello.

Un punto sottile ma importante è la mappatura della porta. Il container è tipicamente configurato per servire HTTP sulla porta 80, quindi mappi la porta host 8080 alla porta container 80. Se esegui TGI fuori Docker, la porta predefinita per il launcher è spesso 3000, motivo per cui la confusione delle porte è un bug così comune del primo giorno.

Prima richiesta usando l’API custom

TGI espone una semplice API JSON “generate” style. Una richiesta di streaming appare così.

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

Se preferisci una singola risposta, usa l’endpoint non streaming.

curl 127.0.0.1:8080/generate \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"Spiega il batching continuo in un paragrafo.","parameters":{"max_new_tokens":120}}'

Prima richiesta usando l’API Messages

Se il tuo ecosistema si aspetta richieste di chat stile OpenAI, usa l’API Messages. Questo si relaziona direttamente a un’altra domanda FAQ, “Come si può usare TGI con client di chat compatibili OpenAI”.

curl 127.0.0.1:8080/v1/chat/completions \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "Sei un assistente conciso."},
      {"role": "user", "content": "Dai una definizione in una frase del parallelismo tensoriale."}
    ],
    "stream": false,
    "max_tokens": 60
  }'

Servire modelli gated o privati

Se hai mai chiesto “Come si servono modelli Hugging Face gated o privati con TGI”, la risposta è noiosa per progettazione: fornisci un token Hub tramite 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

Il modo di fallimento qui è anche noioso: permessi mancanti, scope del token non validi o tentativo di estrarre un modello che richiede l’accettazione di una licenza.

Avvio rapido per AMD ROCm

TGI ha anche immagini ROCm e una configurazione del dispositivo diversa. Se sei su GPU AMD, la forma dell’avvio cambia.

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

Esecuzioni solo CPU

Le esecuzioni CPU esistono, ma non sono la piattaforma per cui TGI è stato progettato per essere brillante. Quando lo fai comunque, disabilitare i kernel personalizzati evita alcuni problemi specifici dell’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

Configurazione che muove davvero l’ago

TGI ha molte bandiere. La maggior parte non vale la pena memorizzarle. Poche valgono la pena di essere comprese, perché rispondono alla domanda più cercata in questo spazio: “Quali impostazioni di TGI controllano la memoria GPU e i limiti delle richieste”.

Il budget di memoria è il totale massimo di token

Il singolo concetto più importante nella configurazione di TGI è che il server ha bisogno di un budget di token per pianificare il batching ed evitare esplosioni di memoria.

Ci sono due limiti che definiscono la forma della richiesta: max_input_tokens e max_total_tokens.

max_total_tokens agisce come un budget di memoria per richiesta perché limita i token di input più i token generati. Se è troppo alto, ogni richiesta diventa costosa, il batching diventa goffo e la pressione sulla memoria cresce. Se è troppo basso, gli utenti incontrano limiti di lunghezza presto e il server rifiuta carichi di lavoro altrimenti validi.

Una configurazione che rende il budget esplicito appare così.

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

Le manopole di batching che contano

Una volta impostati i budget dei token, il controllo del batching è la prossima leva.

max_batch_prefill_tokens limita il lavoro di prefill, che è spesso la fase più pesante per la memoria e vincolante per la computazione. max_batch_total_tokens imposta quanti token il server cerca di inserire in un batch complessivamente. Questo è uno dei veri controlli del throughput.

La manopola interessante è waiting_served_ratio. Incapsula una decisione di politica, non un vincolo hardware. Controlla quando il server sospende il lavoro di decoding in esecuzione per portare le richieste in attesa in un nuovo prefill in modo che possano unirsi al gruppo di decoding. Valori bassi tendono a favorire le richieste esistenti, valori alti tendono a ridurre la latenza della coda per le richieste appena accodate e entrambi possono essere “corretti” a seconda della forma del traffico.

Sharding, num shard e perché appare NCCL

Se il tuo modello non entra in una GPU, o vuoi un throughput più alto tramite parallelismo tensoriale, lo sharding è il prossimo passo.

Il modello mentale è semplice: --sharded true abilita lo sharding e --num-shard controlla il conteggio degli shard. Il server può usare tutte le GPU visibili di default, o un sottoinsieme.

Uno schema utile su host multi GPU è dividere le GPU in gruppi ed eseguire più repliche TGI, ciascuna replica sharded attraverso il proprio sottoinsieme di GPU. Questo diffonde il carico mantenendo la topologia di sharding semplice.

Questo è anche dove la domanda FAQ “Perché TGI fallisce con errori NCCL o di memoria condivisa su più GPU” diventa rilevante. Le configurazioni multi GPU si basano sulla comunicazione collettiva e i container hanno bisogno di memoria condivisa sufficiente per un’operazione sicura quando si usa il fallback SHM.

Scelte di quantizzazione e cosa scambiano

La quantizzazione è l’impostazione “fallo entrare” più fraintesa perché mescola due obiettivi diversi: riduzione della memoria e velocità.

TGI supporta pesi pre-quantizzati per schemi come GPTQ e AWQ, e anche quantizzazione in tempo reale per certi metodi come bitsandbytes e EETQ. Alcuni metodi riducono la memoria ma sono più lenti della precisione half nativa, motivo per cui la quantizzazione non dovrebbe essere trattata come un aggiornamento delle prestazioni gratuito.

Un semplice esempio di quantizzazione a 8 bit in tempo reale appare così.

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 una variante a 4 bit appare così.

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

Formattazione API e guardrail di base

TGI può essere eseguito come servizio interno o esposto più ampiamente. Se l’esposizione è possibile, due bandiere contano: max_concurrent_requests e api_key.

max_concurrent_requests fornisce backpressure. Fa sì che il server rifiuti richieste in eccesso piuttosto che lasciare che tutto si metta in coda e scada il timeout.

Un API key fornisce una barriera di autenticazione grezza. Non è un sistema di auth completo, ma ferma l’uso pubblico accidentale.

CORS è anche configurabile tramite cors_allow_origin, che conta se un’UI basata su browser chiama il server direttamente.

Operazioni e osservabilità

Questa sezione risponde alla vera domanda dell’operatore: “Dove si possono estrarre le metriche Prometheus da un server TGI”.

Documenti OpenAPI e documenti interattivi

TGI espone i suoi OpenAPI e Swagger UI sotto la rotta /docs, che è utile quando vuoi confermare rapidamente le forme di richiesta e risposta o testare gli endpoint senza scrivere un client.

Metriche Prometheus

TGI esporta metriche Prometheus sull’endpoint /metrics. Queste metriche coprono la dimensione della coda, la latenza delle richieste, i conteggi dei token e i tempi a livello di batch. Il risultato è che puoi osservare se il sistema è limitato dal prefill, dal decoding o dalla coda.

Il monitoraggio end-to-end in produzione—PromQL, dashboard Grafana, alert e layout di scraping Docker o Kubernetes per questi stack—è coperto in Monitoraggio Inferenza LLM in Produzione (2026): Prometheus & Grafana per vLLM, TGI, llama.cpp.

Tracciamento e log strutturati

TGI supporta il tracciamento distribuito tramite OpenTelemetry. I log possono anche essere emessi in JSON, il che rende le pipeline di log più facili.

Playbook per la risoluzione dei problemi

I fallimenti di TGI tendono a raggrupparsi in pochi bucket, e ogni bucket ha una correzione molto diversa.

Il container si avvia ma non viene rilevata nessuna GPU

La causa più comune è che il runtime del container non è configurato per il passaggio GPU. Su Nvidia, questo spesso si correla con il supporto Nvidia Container Toolkit mancante, o l’esecuzione su un stack di driver host che non corrisponde alle aspettative.

Fallimenti nel download del modello e errori di permesso

Se il server non può scaricare i file del modello, i soliti colpevoli sono un token di auth mancante per i modelli gated, un token senza permessi di lettura del modello o limiti di velocità. Impostare HF_TOKEN correttamente risolve il caso del modello gated.

CUDA out of memory o riavvii improvvisi sotto carico

La causa più comune è budget di token eccessivamente permissivi. Se max_total_tokens è grande e i client richiedono generazioni lunghe, il server riserverà memoria per le richieste nel caso peggiore. Riduci il budget, riduci la concorrenza o scegli un metodo di quantizzazione che si adatti ai tuoi vincoli.

Errori NCCL su multi GPU, blocchi o rallentamenti estremi

Quando si sharding su più GPU, la memoria condivisa e NCCL contano. Memoria condivisa insufficiente all’interno dei container spesso crea instabilità. Aumentare l’allocazione della memoria condivisa o disabilitare la condivisione SHM tramite NCCL_SHM_DISABLE può cambiare il comportamento, con un compromesso prestazionale.

I problemi NCCL diventano anche più facili da debuggare quando il logging di debug NCCL è abilitato, perché i report degli errori sono più espliciti.

Errori di kernel strani su hardware non A100

Alcuni modelli usano kernel personalizzati che sono stati testati prima su hardware specifico. Se vedi fallimenti di kernel inspiegabili, --disable-custom-kernels è frequentemente il modo più semplice per confermare se i kernel personalizzati sono coinvolti.

Confusione delle porte e “si avvia ma non riesco a raggiungerlo”

Una classica insidia è mescolare il modello di mappatura delle porte Docker con il modello di porta predefinito locale. Negli esempi Docker, il container serve comunemente sulla 80, mentre le esecuzioni locali defaultano sulla 3000. Se mappi la porta sbagliata, le tue richieste curl atterrano nel nulla e il sistema sembra rotto quando in realtà è solo irraggiungibile.

Nota di chiusura

TGI sembra infrastruttura. Quel è il complimento. È un sistema progettato per rendere la generazione di testo abbastanza noiosa da operare, misurabile abbastanza da debuggare e flessibile abbastanza da adattarsi agli stack client esistenti con forma OpenAI.