Hugging Face TGI: text generation inference tgi llm en Docker y Kubernetes (Guía Homelab 2026)

TL;DR

Text generation inference con TGI sigue siendo hoy una pieza clásica del ecosistema Hugging Face para servir LLM con continuous batching, métricas claras y API tipo OpenAI. Atención: el README oficial declara ya modo mantenimiento y recomienda mirar vLLM / SGLang para evolución futura. En homelab, úsalo para aprender, para stacks ya existentes o cuando necesitas integración directa con el Hub; pin de imagen (3.3.5 en los ejemplos), --shm-size 1g y caché persistente no son opcionales. Tiempo de lectura aproximado: veinte minutos.

Tabla de contenidos

• TL;DR
• Introducción
• Qué aporta TGI al mapa de inferencia LLM
• Requisitos: GPU, drivers y memoria compartida
• Primer arranque con Docker oficial
• Docker Compose reproducible
• Kubernetes: shm, GPU y probes
• Arquitectura interna del servidor TGI
• Variables de entorno y límites operativos
• Reverse proxy, buffering y streams largos
• Tensor parallelism y topología PCIe
• tgi docker gpu: checklist de arranque
• APIs: generate, stream y Messages
• Cuantización y VRAM
• Observabilidad: [Prometheus y OpenTelemetry](#observabilidad-prometheus-y-opentelemetry)
• Integración con [n8n, agentes y LiteLLM](#integración-con-n8n-agentes-y-litellm)
• Seguridad y exposición
• Comparativas: TGI vs vLLM vs Ollama)
• Mejores prácticas de operación
• Modelos gated y cumplimiento
• Plan de migración hacia vLLM o SGLang
• Troubleshooting: text generation, inference y TGI
• 📦 Descargar ejemplos
• Enlaces relacionados
• Preguntas frecuentes
• Conclusión

Introducción

Si buscas text generation inference tgi llm en 2026, normalmente quieres throughput, compatibilidad OpenAI y un camino Docker probado. Este artículo asume que ya controlas contenedores básicos y red en casa; si no, repasa antes Docker Compose de 0 a homelab para no mezclar dos curvas de aprendizaje a la vez. Text Generation Inference (TGI) es el servidor open source de Hugging Face que históricamente alimentó Hugging Chat y endpoints gestionados: Rust + Python + gRPC, con tensor parallelism, Flash/Paged Attention en arquitecturas populares y documentación extensa. La noticia nueva es el maintenance mode: sigue siendo válido aprenderlo y operarlo, pero debes leerlo como herramienta de transición, no como apuesta única a diez años.

Este artículo enlaza con guías ya publicadas en ElDiarioIA (todas verificadas como URLs estables en el momento de redacción): vLLM en producción, cuantización de LLMs, LocalAI OpenAI-compatible, Ollama vs LM Studio y observabilidad con Prometheus + Grafana-observabilidad/).

Qué aporta TGI al mapa de inferencia LLM

TGI concentra lo esencial de text generation inference para LLM: cola de peticiones, continuous batching, streaming SSE y endpoints REST documentados en /docs. La etiqueta tgi en contenedores (ghcr.io/huggingface/text-generation-inference) es el mismo producto que verás en tutoriales antiguos; mantén coherencia de versión en tu wiki interna.

La recomendación oficial de mirar vLLM no borra lo aprendido con TGI: muchos conceptos (batching, parallelismo, cuantización) trasladan casi uno a uno. Si ya leíste nuestra guía de vLLM, usa este artículo como contraste y como plan B cuando necesitas features muy acopladas al ecosistema transformers del Hub. Si quieres la frase completa de posicionamiento SEO, aquí va otra vez de forma honesta: text generation inference tgi llm resume “servidor TGI + modelo causal grande”; no es magia, es ingeniería de colas y memoria.

Requisitos: GPU, drivers y memoria compartida

• NVIDIA: Container Toolkit + drivers recientes (README sugiere CUDA 12.2+). Actualiza el host antes de culpar a TGI por kernel panics esporádicos.
• shm: --shm-size 1g en Docker; en Kubernetes emptyDir Memory en /dev/shm.
• Disco: modelos decenas de GB; volumen persistente para caché del Hub (HUGGINGFACE_HUB_CACHE / bind /data).
• Tokens: modelos gated requieren HF_TOKEN con permisos de lectura.

Primer arranque con Docker oficial

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

Prueba mínima de generación:

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":20}}'

Docker Compose reproducible

Usa el repositorio de ejemplos (pin de versión y variables) en la sección 📦 Descargar ejemplos. Ventaja: mismo despliegue TGI + modelo LLM documentado en Git que en el servidor.

Kubernetes: shm, GPU y probes

Monta /dev/shm como en la investigación y pide GPUs con device plugin. Define readiness conservador: descargar pesos puede tardar minutos. Anota en el PR el model-id y la revision del Hub para reproducir builds.

volumeMounts:
  - name: shm
    mountPath: /dev/shm
volumes:
  - name: shm
    emptyDir:
      medium: Memory
      sizeLimit: 1Gi

Arquitectura interna del servidor TGI

Entender TGI como pipeline completo de text generation inference —no solo “el modelo en VRAM”— te ahorra horas de debugging. Una petición típica atraviesa: recepción HTTP/gRPC, validación de esquema, tokenización, encolado en el continuous batching, ejecución en kernels CUDA/ROCm y emisión de tokens (o SSE). Si el cuello de botella está en tokenización o serialización, subir GPU no arregla nada: por eso las métricas de cola y latencia por fase son tan importantes como nvidia-smi.

El servidor mezcla componentes Rust (rutas calientes, gestión de memoria) con piezas Python del ecosistema transformers y extensiones de atención. Cuando actualizas la imagen, no estás cambiando “solo un binario”: estás cambiando stack de kernels, versiones de CUDA empaquetadas y compatibilidad con ciertos checkpoints del Hub. Documenta siempre revision del modelo y el digest de la imagen en tu runbook.

En homelab, trata el arranque en frío como evento costoso: descarga de pesos, verificación de checksums, posible compilación JIT de kernels. Por eso los readiness probes agresivos rompen despliegues en Kubernetes aunque el pod “vaya a estar bien” a los diez minutos. Mejor un initialDelaySeconds alto y una alerta explícita “modelo cargando” que reinicios en bucle.

Variables de entorno y límites operativos

Aquí entra la inferencia llm produccion real: límites de tokens, batch máximo, timeouts y rutas de caché. No copies bloques de Stack Overflow sin cruzarlos con la documentación oficial de TGI; los flags cambian entre versiones menores.

Si comparas con tgi docker gpu en foros, verás que la mitad de los fallos son shm pequeño o volumen de caché lento (HDD barato). Un SSD NVMe dedicado al volumen /data suele ser mejor inversión que una GPU un 15 % más rápida mal alimentada en I/O.

Reverse proxy, buffering y streams largos

Cuando expones tu endpoint TGI detrás de Traefik o Caddy, el enemigo invisible es el buffering HTTP que corta Server-Sent Events o entrega los tokens en “sacudidas” enormes. Desactiva compresión intermedia innecesaria para rutas de streaming, sube timeouts de lectura/escritura y evita CDN que cacheen /generate_stream.

En TLS passthrough vs terminación en el proxy, piensa en quién firma certificados y quién ve headers de autorización. Si terminas TLS en el proxy, puedes inyectar rate limits y request ID antes de TGI; si haces passthrough, simplificas cadena criptográfica pero pierdes inspección L7 salvo que dupliques config. Para homelab doméstico, terminación en Caddy con reverse_proxy y tiempos generosos suele ser el mejor compromiso.

Tensor parallelism y topología PCIe

El tensor parallelism divide capas entre GPUs; no es magia gratuita: necesitas ancho de banda entre dispositivos. Dos tarjetas en slots PCIe x16/x8 eléctricamente correctos y drivers saneados suelen ir mejor que tres GPUs mal enlazadas con NCCL quejándose en logs.

Ejemplo conceptual (ajusta IDs y modelo a tu hardware):

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 meta-llama/Meta-Llama-3.1-8B-Instruct \
  --num-shard 2

Si el contenedor cae con errores NCCL, revisa versión de driver, NCCL_DEBUG=INFO en entorno de prueba (no en producción ruidosa) y confirma que todas las GPUs ven el mismo volumen de pesos. La inferencia llm produccion multi-GPU es tan “de red” como “de modelo”.

tgi docker gpu: checklist de arranque

Antes de decir “TGI no funciona”, recorre esta lista; es la misma que usaría un SRE para tgi docker gpu en un piloto interno:

1. nvidia-smi limpio (sin procesos zombie ocupando VRAM).
2. docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi (sanidad del toolkit).
3. --shm-size 1g o volumen shm en Kubernetes ya montado.
4. Volumen /data con decenas de GB libres y filesystem rápido.
5. HF_TOKEN exportado si el modelo es gated.
6. Pin de imagen (3.3.5 u otra probada), nunca latest en un piloto serio.
7. Prueba HTTP mínima contra /health o /docs según versión, luego /generate corto.
8. Script de humo del repo de ejemplos (sección 📦 Descargar ejemplos) en CI o cron semanal.

Si todo lo anterior pasa y aún hay latencia alta con el servicio de inferencia, entonces sí: mira batching, tamaño de contexto y pruebas de carga comparables con vLLM en el mismo hardware; números mentirosos suelen venir de comparar modelos distintos o precisión distinta.

APIs: generate, stream y Messages

• Clásico: /generate y /generate_stream.
• OpenAI-like: /v1/chat/completions (Messages API) — encaja con clientes que ya usan el esquema de chat.

Ejemplo corto de chat:

curl localhost:8080/v1/chat/completions -X POST -H 'Content-Type: application/json' \
  -d '{"model":"tgi","messages":[{"role":"user","content":"Resume TGI en dos frases"}],"max_tokens":80}'

Cuantización y VRAM

TGI soporta varias rutas de cuantización (bitsandbytes, AWQ, GPTQ, Marlin, fp8…). Si vienes de GGUF vs GPTQ vs AWQ, traduce mentalmente: aquí el ahorro es para servidor HF, no para el binario de Ollama. Si aún así te quedas corto de VRAM, baja precisión o salta a modelo más pequeño antes de pedir tensor parallel en dos GPUs mal enlazadas.

Observabilidad: Prometheus y OpenTelemetry

Activa scrape de métricas y, si puedes, OTLP con --otlp-endpoint. Correlaciona latencias con colas de text generation inference: muchos incidentes son cola saturada, no “el modelo se volvió tonto”. Reusa patrones de monitoring de LLMs.

Integración con n8n, agentes y LiteLLM

Muchos lectores no quieren un endpoint TGI aislado: quieren text generation inference estable consumida por automatizaciones. En n8n con workflows sobre bases de datos-mysql-mongodb-guia-completa-tutorial-2025/) puedes llamar a https://tgi.casa/v1/chat/completions con un nodo HTTP, cabeceras mínimas y un cuerpo JSON alineado con la Messages API. Cuidado con prompts dinámicos sin límite: un workflow mal filtrado puede vaciar tu cola de inferencia llm produccion más rápido que un ataque externo.

Si ya usas un proxy unificador de modelos, el patrón típico es LiteLLM delante y TGI como backend OpenAI-compatible. Beneficios: fallback entre proveedores, cuotas por clave API y telemetría homogénea. Coste: otra pieza que versionar y otra superficie de configuración. Para homelab, empieza sin proxy hasta que tengas dos backends reales; la complejidad prematura es la principal causa de incidentes “imposibles” que en realidad son headers mal copiados.

En agentes (MCP, stacks tipo Crew/LangGraph en tus propios experimentos), trata TGI como motor de cómputo: baja temperatura en tareas de extracción estructurada, sube límites de tokens solo donde el formato lo exija, y registra request_id de punta a punta. Cuando algo falle, podrás ver si el error vino del orquestador o del runtime TGI en sí.

Seguridad y exposición

Coloca TGI detrás de Traefik o Caddy con TLS y auth; rate-limit agresivo en homelab público. /docs es útil internamente, no regales OpenAPI a Internet sin filtro.

Comparativas: TGI vs vLLM vs Ollama

Mejores prácticas de operación

Documenta siempre el trío modelo + tag TGI + driver NVIDIA cuando midas text generation inference con LLM reales en tu homelab; sin eso tus benchmarks no son comparables semana a semana. Versiona docker-compose.yml en Git y evita “hotfixes” solo en el servidor.

Define SLO internos modestos: p95 de tiempo hasta primer token y tokens/s sostenidos bajo N clientes concurrentes. Si no tienes presupuesto para k6 completo, al menos un script curl en bucle desde otra máquina deja constancia en el ticket.

Para upgrades de imagen, usa entorno staging con el mismo volumen de caché copiado (snapshot ZFS/Btrfs) antes de tocar producción casera. Un salto de versión puede cambiar kernels CUDA empaquetados y romper compatibilidad sutil.

Modelos gated y cumplimiento

Los modelos con acuerdos de licencia en Hugging Face requieren HF_TOKEN y trazabilidad de quién descarga qué. No compartas el token en Slack: usa un secret manager o variable inyectada por tu orquestador. Si el homelab pertenece a una empresa, enlaza con políticas internas de uso de datos genéricos (no guardes prompts sensibles en logs de proxy sin redacción).

Plan de migración hacia vLLM o SGLang

Si hoy dependes de text generation inference con TGI pero quieres alinearte con el roadmap upstream, monta un plan en tres fases: (1) paridad de API (/v1/chat/completions), (2) pruebas de carga comparables, (3) cutover con rollback conservando el volumen de pesos del Hub. La guía vLLM en producción te da el marco mental; TGI y vLLM comparten ideas de PagedAttention en la documentación de ambos proyectos.

Troubleshooting: text generation, inference y TGI

1. Contenedor sale al arrancar: revisa VRAM vs modelo, shm y logs de descarga.
2. 401/403 en Hub: HF_TOKEN o permisos del modelo gated.
3. Latencia alta con poca carga: revisa disco lento o red hacia Hub.
4. Tensor parallel inestable: topología PCIe/NVLink y drivers.
5. Streams que “cortan” a mitad: buffering en reverse proxy; desactiva compresión o sube timeouts en Traefik/Caddy.
6. GPU al 100 % pero pocos tokens/s: revisa precisión, tamaño de batch efectivo y si el modelo está cuantizado como crees.
7. OOM intermitente: prompts largos + KV cache; baja max_new_tokens en clientes o sube cuantización.
8. Healthcheck rojo en Kubernetes pero UI funciona: probe demasiado pronto; separa liveness de readiness.

nvidia-smi
docker logs -f <container>
curl -sf localhost:8080/docs >/dev/null && echo "docs OK"

Si tras el checklist sigues bloqueado, exporta un bundle mínimo para tu propio ticket: versión exacta de imagen, model-id + revision, tramo de logs desde arranque hasta primer 500 de /generate, y resultado de curl contra /metrics si lo tienes habilitado. Esa disciplina es la diferencia entre inferencia llm produccion amateur y operación que escala a otro humano sin perder un día en repros.

📦 Descargar ejemplos

Repo público:

https://github.com/ziruelen/learningaiagents/tree/main/docker/huggingface-tgi-text-generation-inference-2026

Enlaces relacionados

• vLLM en producción
• GPU scheduling en Kubernetes
• WordPress con Docker (instalación) (patrones de Compose/SSL transferibles)
• MCP: Model Context Protocol
• Open WebUI + Ollama
• LangChain vs LlamaIndex (RAG)

Preguntas frecuentes

¿Sigue vivo el proyecto TGI?

Sí, pero en mantenimiento; aceptan parches menores y mejoras de docs. Planifica comparación con vLLM/SGLang.

¿Qué significa text generation inference tgi llm en la práctica?

Servir modelos causal LM con alto throughput y APIs estándar; tgi es el binario/servicio, llm el modelo.

¿Puedo usar solo CPU?

No es el objetivo; el README permite --disable-custom-kernels sin GPU, pero rendimiento pobre.

¿Cómo evito re-descargar pesos?

Volumen persistente en /data y variables HF_HOME/HUGGINGFACE_HUB_CACHE coherentes.

¿Qué versión de imagen uso?

Pin explícito (p. ej. 3.3.5); evita latest en producción casera.

¿Cómo integro clientes OpenAI?

Endpoint /v1/chat/completions con Messages API.

¿Dónde veo OpenAPI?

/docs en la instancia o la UI publicada en documentación HF.

¿Tensor parallel obligatorio?

Solo si el modelo no cabe en una GPU; añade complejidad NCCL.

¿Cómo mido throughput?

Prometheus + pruebas de carga reproducibles; anota modelo y tag.

¿Y si necesito RAG sobre mis PDFs?

Mira AnythingLLM o Flowise; TGI es inferencia, no orquestación documental completa.

¿Cómo comparo con vLLM?

Lee la guía de vLLM en ElDiarioIA y haz tabla de latencia/coste operativo en tu hardware.

¿Qué pasa con AMD?

Imagen -rocm y dispositivos /dev/kfd, /dev/dri según README.

¿Necesito Ingress en Kubernetes?

Sí, con TLS y timeouts adecuados para streams largos.

¿Puedo meter TGI detrás de LiteLLM?

Patrón habitual: unificar rutas y budgets; valida compatibilidad de esquema.

¿Qué monitorizo primero?

VRAM, cola, tokens/s y errores de Hub.

¿Debo documentar el maintenance mode a negocio?

Sí; transparencia evita prometer roadmap que ya no es prioridad upstream.

Conclusión

Text generation inference con TGI y LLM del Hub sigue siendo una combinación potente y muy didáctica: enseña batching, parallelismo y operación real. Con el aviso de mantenimiento, tu homelab gana si usa TGI como referencia o soporte de legado, y vLLM/SGLang como candidatos de largo plazo. Si mantienes TGI, trata el despliegue como producción: métricas, pin de imagen, shm y backups de caché. El siguiente paso natural es comparar números contra vLLM en tu GPU, no en benchmarks de Twitter.

Cierra el círculo con el stack TGI + LLM documentado en Git (Compose, variables y smoke test), enlazado desde este artículo, y con una tabla simple de “antes/después” cuando cambies versión de imagen o precisión. Ese hábito —reproducibilidad + evidencias— es el mismo que pedirías en un equipo de plataforma en empresa, solo que aquí el stakeholder eres tú dentro de seis meses, cuando hayas olvidado qué flags tocaste a las tres de la madrugada.