TGI (Text Generation Inference)

Ejecuta HuggingFace Text Generation Inference (TGI) para servir LLMs en producción en las GPU de Clore.ai

Text Generation Inference (TGI) es el framework de HuggingFace para servir LLM en producción, diseñado para inferencia de alto rendimiento y baja latencia. Admite Flash Attention 2, agrupamiento continuo, PagedAttention y paralelismo tensorial de forma nativa, lo que lo convierte en la solución ideal para desplegar modelos de lenguaje grandes a escala en servidores GPU de CLORE.AI.

Todos los ejemplos se pueden ejecutar en servidores GPU alquilados a través de CLORE.AI Marketplace.

Requisitos del servidor

Parámetro	Mínimo	Recomendado
RAM	16 GB	32 GB+
VRAM	8 GB	24 GB+
Disco	50 GB	200 GB+
GPU	Cualquier NVIDIA (Ampere+ para Flash Attention)	A100, H100, RTX 4090

Flash Attention 2 requiere arquitectura Ampere o más reciente (RTX 3000+, A100, H100). Para GPUs más antiguas, TGI volverá automáticamente a la atención estándar.

Despliegue rápido en CLORE.AI

Imagen Docker: ghcr.io/huggingface/text-generation-inference:latest

Puertos: 22/tcp, 8080/http

Variables de entorno:

Variable	Ejemplo	Descripción
MODEL_ID	mistralai/Mistral-7B-Instruct-v0.3	ID de modelo en HuggingFace
HF_TOKEN	hf_xxx...	Token de HuggingFace (para modelos con acceso restringido)
NUM_SHARD	2	Número de GPUs para paralelismo tensorial
MAX_INPUT_LENGTH	4096	Máximo de tokens de entrada
MAX_TOTAL_TOKENS	8192	Máximo de tokens de entrada + salida
QUANTIZE	bitsandbytes-nf4	Método de cuantización

Configuración paso a paso

1. Alquila un servidor GPU en CLORE.AI

Ve a CLORE.AI Marketplace y filtrar servidores por:

• VRAM ≥ 24 GB para modelos 7B (precisión completa)

• VRAM ≥ 12 GB para modelos 7B (cuantización a 4 bits)

• VRAM ≥ 80 GB para modelos 70B (precisión completa, GPU única)

2. Conéctate vía SSH

Después de que tu pedido sea confirmado, conéctate a tu servidor usando los detalles SSH del panel de CLORE.AI:

ssh -p <PORT> root@<SERVER_IP>

O usa la Terminal Web desde el panel de tu pedido en CLORE.AI.

3. Descarga la imagen Docker de TGI

docker pull ghcr.io/huggingface/text-generation-inference:latest

4. Lanza TGI con un modelo

Lanzamiento básico (Mistral 7B):

docker run -d \
  --name tgi \
  --gpus all \
  --shm-size 1g \
  -p 8080:80 \
  -v /root/models:/data \
  -e MODEL_ID=mistralai/Mistral-7B-Instruct-v0.3 \
  ghcr.io/huggingface/text-generation-inference:latest \
  --model-id mistralai/Mistral-7B-Instruct-v0.3 \
  --max-input-length 4096 \
  --max-total-tokens 8192

Con token de HuggingFace (para modelos con acceso restringido como Llama 3):

docker run -d \
  --name tgi \
  --gpus all \
  --shm-size 1g \
  -p 8080:80 \
  -v /root/models:/data \
  -e HUGGING_FACE_HUB_TOKEN=hf_tu_token_aqui \
  ghcr.io/huggingface/text-generation-inference:latest \
  --model-id meta-llama/Meta-Llama-3-8B-Instruct \
  --max-input-length 8192 \
  --max-total-tokens 16384

Con cuantización a 4 bits (para menor VRAM):

docker run -d \
  --name tgi \
  --gpus all \
  --shm-size 1g \
  -p 8080:80 \
  -v /root/models:/data \
  ghcr.io/huggingface/text-generation-inference:latest \
  --model-id mistralai/Mixtral-8x7B-Instruct-v0.1 \
  --quantize bitsandbytes-nf4 \
  --max-input-length 4096 \
  --max-total-tokens 8192

Paralelismo tensorial multi-GPU (para modelos 70B):

docker run -d \
  --name tgi \
  --gpus all \
  --shm-size 2g \
  -p 8080:80 \
  -v /root/models:/data \
  ghcr.io/huggingface/text-generation-inference:latest \
  --model-id meta-llama/Meta-Llama-3-70B-Instruct \
  --num-shard 2 \
  --max-input-length 8192 \
  --max-total-tokens 16384

5. Verifica que el servidor esté en ejecución

# Revisar logs
docker logs -f tgi

# Espera el mensaje "Connected", luego prueba:
curl http://localhost:8080/health

Respuesta esperada: {"status":"ok"}

6. Acceso vía proxy HTTP de CLORE.AI

En el panel de tu pedido en CLORE.AI verás tu http_pub URL para el puerto 8080. Esto permite acceso desde navegador/API sin túnel SSH:

https://<order-id>.clore.ai/

---

Ejemplos de uso

Ejemplo 1: Generación de texto básica

curl http://localhost:8080/generate \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": "¿Cuál es la capital de Francia?",
    "parameters": {
      "max_new_tokens": 100,
      "temperature": 0.7
    }
  }'

Ejemplo 2: Completions de chat (compatible con OpenAI)

TGI admite el formato de la API de completions de chat de OpenAI:

curl http://localhost:8080/v1/chat/completions \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "Eres un asistente útil."},
      {"role": "user", "content": "Explica el entrelazamiento cuántico en términos sencillos."}
    ],
    "max_tokens": 512,
    "temperature": 0.8,
    "stream": false
  }'

Ejemplo 3: Respuesta en streaming

curl http://localhost:8080/generate_stream \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": "Escribe una función en Python para calcular números de Fibonacci:",
    "parameters": {
      "max_new_tokens": 300,
      "temperature": 0.2
    }
  }' \
  --no-buffer

Ejemplo 4: Cliente en Python

from huggingface_hub import InferenceClient

# Reemplaza con tu URL http_pub de CLORE.AI
client = InferenceClient(model="http://localhost:8080")

# Generación simple
response = client.text_generation(
    "Traduce al francés: Hola, ¿cómo estás?",
    max_new_tokens=100,
    temperature=0.7,
)
print(response)

# Chat
for token in client.chat_completion(
    messages=[{"role": "user", "content": "¿Qué es el aprendizaje automático?"}],
    max_tokens=200,
    stream=True,
):
    print(token.choices[0].delta.content, end="", flush=True)

Ejemplo 5: Solicitudes por lotes

import requests

BASE_URL = "http://localhost:8080"  # o tu URL http_pub de CLORE.AI

prompts = [
    "Resume la Revolución Francesa en 3 frases.",
    "Escribe un haiku sobre computación con GPU.",
    "¿Cuáles son los principales beneficios de Rust sobre C++?",
]

results = []
for prompt in prompts:
    response = requests.post(
        f"{BASE_URL}/generate",
        json={"inputs": prompt, "parameters": {"max_new_tokens": 150}},
    )
    results.append(response.json()["generated_text"])

for prompt, result in zip(prompts, results):
    print(f"Prompt: {prompt}\nAnswer: {result}\n{'-'*50}")

---

Configuración

Parámetros clave de la CLI

Parámetro	Por defecto	Descripción
--model-id	requerido	ID de modelo de HuggingFace o ruta local
--num-shard	1	Número de particiones GPU (paralelismo tensorial)
--max-concurrent-requests	128	Máximo de solicitudes simultáneas
--max-input-length	1024	Longitud máxima de tokens de entrada
--max-total-tokens	2048	Máximo de tokens de entrada + salida
--max-batch-total-tokens	auto	Máximo de tokens por lote
--quantize	ninguna	Cuantización: bitsandbytes-nf4, gptq, awq
--dtype	auto	float16, bfloat16
--trust-remote-code	false	Permitir código de modelo personalizado
--port	80	Puerto del servidor

Usando un modelo local

Si tienes un modelo descargado localmente:

docker run -d \
  --name tgi \
  --gpus all \
  --shm-size 1g \
  -p 8080:80 \
  -v /path/to/your/model:/model \
  ghcr.io/huggingface/text-generation-inference:latest \
  --model-id /model

Cuantización AWQ (más rápida que NF4)

docker run -d \
  --name tgi \
  --gpus all \
  --shm-size 1g \
  -p 8080:80 \
  -v /root/models:/data \
  ghcr.io/huggingface/text-generation-inference:latest \
  --model-id casperhansen/mistral-7b-instruct-v0.2-awq \
  --quantize awq

---

Consejos de rendimiento

1. Habilitar Flash Attention 2

Flash Attention 2 se habilita automáticamente en GPUs Ampere+ (RTX 3000+, A100, H100). No se necesita configuración adicional.

2. Ajustar el tamaño máximo de lote

Para escenarios de alto rendimiento, aumenta el tamaño del lote:

--max-batch-total-tokens 32000 \
--max-waiting-tokens 20

3. Usar bfloat16 en GPUs Ampere+

--dtype bfloat16

Esto es más estable numéricamente que float16 y rinde de forma idéntica en GPUs modernas.

4. Pre-descargar modelos en almacenamiento persistente

# En el servidor, pre-descarga antes de iniciar TGI
pip install huggingface_hub
python -c "
from huggingface_hub import snapshot_download
snapshot_download('mistralai/Mistral-7B-Instruct-v0.3', local_dir='/root/models/mistral-7b')
"

Luego monta la ruta local para evitar volver a descargar en reinicios.

5. Gestión de memoria GPU

Para RTX 3090/4090 (24GB VRAM):

# Un modelo 7B en float16 entra perfectamente
--max-total-tokens 8192

# Un modelo 13B necesita cuantización
--quantize bitsandbytes-nf4
--max-total-tokens 4096

6. Decodificación especulativa

Para generación más rápida usando modelos más pequeños como borrador:

--speculate 4  # Número de tokens especulativos

---

Solución de problemas

Problema: "CUDA out of memory"

Error: CUDA out of memory. Intentó asignar X GiB

Solución: Reducir --max-total-tokens o habilita la cuantización:

--quantize bitsandbytes-nf4
--max-total-tokens 4096

Problema: la descarga del modelo es lenta

Solución: Usa mirror de HuggingFace o pre-descarga:

# Configurar mirror
-e HF_ENDPOINT=https://hf-mirror.com

Problema: el servidor no es accesible vía http_pub

Solución: Asegúrate de que el puerto 8080 esté mapeado correctamente. TGI escucha internamente en el puerto 80, pero lo mapeas al 8080 externamente:

-p 8080:80  # host:container

Problema: "trust_remote_code is required"

Algunos modelos (p. ej., Falcon, Phi) requieren código personalizado:

--trust-remote-code

Problema: respuesta inicial lenta

La primera solicitud desencadena la carga del modelo en la VRAM. Esto es normal. Las solicitudes posteriores serán rápidas.

# Revisar progreso de carga
docker logs -f tgi | grep -E "Connected|Error|Loading"

Problema: el contenedor se cierra inmediatamente

# Revisar errores
docker logs tgi

# Solución común: aumentar la memoria compartida
--shm-size 2g

---

Enlaces

• GitHub

• Documentación

• Docker Hub / GHCR

• Modelos compatibles

• CLORE.AI Marketplace

---

Recomendaciones de GPU en Clore.ai

Caso de uso	GPU recomendada	Coste estimado en Clore.ai
Desarrollo/Pruebas	RTX 3090 (24GB)	~$0.12/gpu/hr
Producción (7B–13B)	RTX 4090 (24GB)	~$0.70/gpu/hr
Modelos grandes (70B+)	A100 80GB / H100	~$1.20/gpu/hr

💡 Todos los ejemplos en esta guía pueden desplegarse en Clore.ai servidores GPU. Navega las GPUs disponibles y alquila por hora — sin compromisos, acceso root completo.