TGI - Inferencia de Generación de Texto - Instalación, Configuración y Solución de Problemas

Text Generation Inference (TGI) tiene una energía muy específica. No es el último en llegar en la calle de la inferencia, pero es el que ya aprendió cómo se rompen las cosas en producción -

y luego incorporó esas lecciones en los valores predeterminados. Si tu objetivo es “servir un LLM detrás de HTTP y mantenerlo funcionando”, TGI es una herramienta pragmática.

Si aún estás sopesando dónde ejecutar modelos, esta comparación de alojamiento de LLM en 2026 recopila configuraciones locales, autoalojadas y en la nube para que puedas situar TGI en contexto.

Primero, una revisión de la realidad. A partir de 2026, TGI está en modo de mantenimiento y el repositorio upstream se ha archivado como solo lectura. Eso suena como una mala noticia hasta que lo analizas desde una perspectiva operativa. Un motor estable puede ser una característica, especialmente cuando los cambios reales ocurren en los modelos, los prompts y los requisitos del producto.

Esta guía se centra en cuatro cosas que importan en el día cero y en el día treinta: rutas de instalación, una guía de inicio rápido que realmente funciona, configuraciones que cambian el comportamiento real y una mentalidad de resolución de problemas que ahorra tiempo.

Por qué TGI sigue importando en 2026

Es fácil tratar a los servidores de inferencia como intercambiables. Para una encuesta herramienta por herramienta de pilas locales comunes, comienza desde Ollama vs vLLM vs LM Studio: La mejor manera de ejecutar LLMs localmente en 2026?.

En la práctica, solo hay tres preguntas que importan.

Primero, ¿cómo se comporta bajo carga? TGI se construye alrededor de la agrupación continua (continuous batching) y el flujo de tokens (token streaming), por lo que puede priorizar el rendimiento mientras sigue dando a los usuarios la ilusión de respuesta inmediata.

Segundo, ¿puede hablar el dialecto que tu herramienta ya habla? TGI soporta su propia “API personalizada” y también una API de Mensajes que es compatible con el esquema de Completas de Chat de OpenAI. Eso significa que las herramientas que esperan un endpoint con forma de OpenAI a menudo pueden apuntar a TGI con cambios mínimos.

Tercero, ¿puedes observarlo sin adivinar? TGI expone métricas de Prometheus y soporta trazabilidad distribuida mediante OpenTelemetry, que es la diferencia entre “creo que es lento” y “la fase de prellenado está saturada, el tiempo de cola está creciendo y el presupuesto de tokens por grupo es demasiado alto”.

Rutas de instalación y requisitos previos

TGI se puede abordar vía Docker o vía una instalación local desde el código fuente. La ruta de Docker es el camino que la mayoría de la gente significa cuando dice “instalar TGI”, porque empaqueta el enrutador, el servidor de modelos y los kernels en una imagen que puede ejecutarse con un solo comando.

Bajo el capó, TGI es un sistema con componentes distintos: un enrutador que acepta HTTP y realiza la agrupación, un lanzador que orquesta uno o más procesos del servidor de modelos, y el servidor de modelos que carga el modelo y realiza la inferencia. Esa separación explica mucho del “por qué” detrás de las banderas de configuración y los modos de fallo comunes.

Dos requisitos previos prácticos aparecen una y otra vez: acceso a GPU desde contenedores y una estrategia de caché sensata para los pesos del modelo. El acceso a GPU para Nvidia típicamente significa que el Nvidia Container Toolkit está instalado, y la caché significa mapear un volumen del anfitrión al contenedor para que los pesos del modelo no se vuelvan a descargar cada vez.

Instalación local desde el código fuente

Existe una instalación desde el código fuente, pero está orientada a desarrolladores y constructores de kernels. Espera Rust, Python 3.9+, y herramientas de compilación, y suele ser un primer paso más lento que ejecutar el contenedor. Es útil cuando necesitas modificar los componentes internos, probar parches o integrarte con un entorno muy específico.

Inicio rápido con Docker

El inicio rápido canónico es corto, que es exactamente el punto. Elige un ID de modelo, monta un volumen de caché, expone un puerto y ejecuta el contenedor.

Inicio rápido para GPU Nvidia

Este es un patrón mínimo que funciona bien para el primer arranque.

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

Ese único comando responde implícitamente a una pregunta frecuente de FAQ, “¿Cómo ejecutas TGI con Docker en una GPU Nvidia?” mostrando los tres elementos no negociables: --gpus all, un mapeo de puertos y un ID de modelo.

Un punto sutil pero importante es el mapeo de puertos. El contenedor típicamente está configurado para servir HTTP en el puerto 80, por lo que mapeas el puerto 8080 del anfitrión al puerto 80 del contenedor. Si ejecutas TGI fuera de Docker, el puerto predeterminado para el lanzador a menudo es 3000, lo cual es por qué la confusión de puertos es un error tan común en el primer día.

Primera solicitud usando la API personalizada

TGI expone una API simple de estilo JSON “generate”. Una solicitud con flujo (streaming) se ve así.

curl 127.0.0.1:8080/generate_stream \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"¿Qué es el Aprendizaje Profundo?","parameters":{"max_new_tokens":40}}'

Si prefieres una respuesta única, usa el endpoint sin flujo.

curl 127.0.0.1:8080/generate \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"Explica la agrupación continua en un párrafo.","parameters":{"max_new_tokens":120}}'

Primera solicitud usando la API de Mensajes

Si tu ecosistema espera solicitudes de chat con estilo OpenAI, usa la API de Mensajes. Esto se relaciona directamente con otra pregunta de FAQ, “¿Cómo puedes usar TGI con clientes de chat compatibles con OpenAI?”.

curl 127.0.0.1:8080/v1/chat/completions \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "Eres un asistente conciso."},
      {"role": "user", "content": "Da una definición de paralelismo de tensores en una oración."}
    ],
    "stream": false,
    "max_tokens": 60
  }'

Servir modelos con acceso restringido o privados

Si alguna vez te has preguntado “¿Cómo sirves modelos de Hugging Face con acceso restringido o privados con TGI?”, la respuesta es aburrida por diseño: proporciona un token de Hub vía 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

El modo de fallo aquí también es aburrido: permisos faltantes, alcances de token inválidos o intentar descargar un modelo que requiere aceptar una licencia.

Inicio rápido para AMD ROCm

TGI también tiene imágenes ROCm y una configuración de dispositivo diferente. Si estás en GPUs AMD, la forma de arranque 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

Ejecuciones solo con CPU

Las ejecuciones solo con CPU existen, pero no es la plataforma para la que TGI fue diseñado para ser brillante. Cuando lo haces de todos modos, deshabilitar los kernels personalizados evita algunos 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

Configuraciones que realmente mueven la aguja

TGI tiene muchas banderas. La mayoría de ellas no valen la pena memorizar. Algunas valen la pena entender, porque responden a la pregunta más buscada en este espacio: “¿Qué ajustes de TGI controlan la memoria de GPU y los límites de solicitud?”.

El presupuesto de memoria es el máximo de tokens totales

El concepto más importante en la configuración de TGI es que el servidor necesita un presupuesto de tokens para planificar la agrupación y evitar explosiones de memoria.

Hay dos límites que definen la forma de la solicitud: max_input_tokens y max_total_tokens.

max_total_tokens actúa como un presupuesto de memoria por solicitud porque limita los tokens de entrada más los tokens generados. Si es demasiado alto, cada solicitud se vuelve costosa, la agrupación se vuelve incómoda y la presión de memoria crece. Si es demasiado bajo, los usuarios alcanzan los límites de longitud temprano, y el servidor rechaza cargas de trabajo que de otro modo serían válidas.

Una configuración que hace que el presupuesto sea explícito se ve así.

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 agrupación que importan

Una vez que los presupuestos de tokens están establecidos, el control de agrupación es el siguiente palanca.

max_batch_prefill_tokens limita el trabajo de prellenado, que a menudo es la fase más pesada en memoria y limitada por cómputo. max_batch_total_tokens establece cuántos tokens el servidor intenta ajustar en un grupo en general. Esto es uno de los controles reales de rendimiento.

El control interesante es waiting_served_ratio. Codifica una decisión de política, no una restricción de hardware. Controla cuándo el servidor pausa el trabajo de decodificación en ejecución para traer solicitudes en espera a un nuevo prellenado para que puedan unirse al grupo de decodificación. Los valores bajos tienden a favorecer las solicitudes existentes, los valores altos tienden a reducir la latencia de cola para las solicitudes recién encoladas, y ambos pueden ser “correctos” dependiendo de la forma del tráfico.

Fragmentación, num shard y por qué aparece NCCL

Si tu modelo no cabe en una GPU, o quieres mayor rendimiento mediante paralelismo de tensores, la fragmentación es el siguiente paso.

El modelo mental es simple: --sharded true habilita la fragmentación, y --num-shard controla el conteo de fragmentos. El servidor puede usar todas las GPUs visibles por defecto, o usar un subconjunto.

Un patrón útil en anfitriones con múltiples GPUs es dividir las GPUs en grupos y ejecutar múltiples réplicas de TGI, cada réplica fragmentada a través de su propio subconjunto de GPU. Eso distribuye la carga mientras mantiene la topología de fragmentación simple.

Aquí es también donde la pregunta de FAQ “¿Por qué TGI falla con errores de NCCL o memoria compartida en múltiples GPUs?” se vuelve relevante. Las configuraciones de múltiples GPUs dependen de la comunicación colectiva, y los contenedores necesitan suficiente memoria compartida para una operación segura cuando se usa la opción de respaldo de SHM.

Elecciones de cuantización y lo que intercambian

La cuantización es la configuración de “hacer que quepa” más mal entendida porque mezcla dos objetivos diferentes: reducción de memoria y velocidad.

TGI soporta pesos precuantizados para esquemas como GPTQ y AWQ, y también cuantización sobre la marcha para ciertos métodos como bitsandbytes y EETQ. Algunos métodos reducen memoria pero son más lentos que la precisión nativa de media precisión, por lo que la cuantización no debe tratarse como una mejora de rendimiento gratuita.

Un ejemplo simple de cuantización de 8 bits sobre la marcha se ve así.

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

Y una variante de 4 bits se ve así.

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

Formado de API y barreras de seguridad básicas

TGI puede ejecutarse como un servicio interno, o exponerse más ampliamente. Si la exposición es posible, dos banderas importan: max_concurrent_requests y api_key.

max_concurrent_requests proporciona contrapresión. Hace que el servidor rechace solicitudes excesivas en lugar de dejar que todo se encole y se agote el tiempo.

Una clave de API proporciona una barrera de autenticación gruesa. No es un sistema de autenticación completo, pero detiene el uso público accidental.

CORS también es configurable vía cors_allow_origin, lo cual importa si una interfaz de usuario basada en navegador llama al servidor directamente.

Operaciones y observabilidad

Esta sección responde a la pregunta real del operador: “¿Dónde puedes raspar métricas de Prometheus de un servidor TGI?”.

Documentación OpenAPI e interactiva

TGI expone su OpenAPI y Swagger UI bajo la ruta /docs, lo cual es útil cuando quieres confirmar rápidamente las formas de solicitud y respuesta o probar endpoints sin escribir un cliente.

Métricas de Prometheus

TGI exporta métricas de Prometheus en el endpoint /metrics. Estas métricas cubren el tamaño de la cola, latencia de solicitud, conteos de tokens y tiempos a nivel de grupo. El resultado es que puedes observar si el sistema está limitado por el prellenado, la decodificación o el encolamiento.

El monitoreo de producción de extremo a extremo—PromQL, paneles de Grafana, alertas y diseños de raspado de Docker o Kubernetes para estas pilas—se cubre en Monitoreo de Inferencia de LLM en Producción (2026): Prometheus & Grafana para vLLM, TGI, llama.cpp.

Trazabilidad y registros estructurados

TGI soporta trazabilidad distribuida vía OpenTelemetry. Los registros también pueden emitirse en JSON, lo cual hace que las tuberías de registros sean más fáciles.

Manual de resolución de problemas

Los fallos de TGI tienden a agruparse en unos pocos cubos, y cada cubo tiene una corrección muy diferente.

El contenedor se ejecuta pero no se detecta ninguna GPU

La causa más común es que el tiempo de ejecución del contenedor no está configurado para el paso de GPU. En Nvidia, esto a menudo se correlaciona con el soporte faltante del Nvidia Container Toolkit, o ejecutarse en una pila de controladores del anfitrión que no coincide con las expectativas.

Fallos de descarga de modelos y errores de permiso

Si el servidor no puede descargar archivos de modelos, los culpables habituales son un token de autenticación faltante para modelos restringidos, un token sin permisos de lectura de modelos, o límites de tasa. Establecer HF_TOKEN correctamente resuelve el caso de modelos restringidos.

CUDA sin memoria o reinicios repentinos bajo carga

La causa más común son presupuestos de tokens demasiado permisivos. Si max_total_tokens es grande y los clientes solicitan generaciones largas, el servidor reservará memoria para solicitudes de peor caso. Reduce el presupuesto, reduce la concurrencia o elige un método de cuantización que se ajuste a tus restricciones.

Errores NCCL en múltiples GPUs, bloqueos o ralentizaciones extremas

Cuando se fragmenta a través de múltiples GPUs, la memoria compartida y NCCL importan. La memoria compartida insuficiente dentro de los contenedores a menudo crea inestabilidad. Aumentar la asignación de memoria compartida o deshabilitar el intercambio de SHM vía NCCL_SHM_DISABLE puede cambiar el comportamiento, con un intercambio de rendimiento.

Los problemas de NCCL también se vuelven más fáciles de depurar cuando se habilita la depuración de registros de NCCL, porque los informes de error son más explícitos.

Errores extraños de kernel en hardware no A100

Algunos modelos usan kernels personalizados que primero se probaron en hardware específico. Si ves fallos de kernel inexplicables, --disable-custom-kernels es frecuentemente la forma más simple de confirmar si los kernels personalizados están involucrados.

Confusión de puertos y “se ejecuta pero no puedo alcanzarlo”

Una clásica bala de pie es mezclar el modelo de mapeo de puertos de Docker con el modelo de puerto predeterminado local. En los ejemplos de Docker, el contenedor comúnmente sirve en el 80, mientras que las ejecuciones locales por defecto van a 3000. Si mapeas el puerto equivocado, tus solicitudes de curl caen en la nada, y el sistema parece roto cuando en realidad es solo inalcanzable.

Nota final

TGI se siente como infraestructura. Ese es el cumplido. Es un sistema diseñado para hacer que la generación de texto sea lo suficientemente aburrida para operar, medible lo suficiente para depurar y flexible lo suficiente para encajar en pilas de clientes existentes con forma de OpenAI.