# TGI (Inferencia de generación de texto)

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.

{% hint style="success" %}
Todos los ejemplos se pueden ejecutar en servidores GPU alquilados a través de [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## 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 |

{% hint style="info" %}
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.
{% endhint %}

## 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](https://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:

```bash
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

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

### 4. Lanza TGI con un modelo

**Lanzamiento básico (Mistral 7B):**

```bash
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):**

```bash
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):**

```bash
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):**

```bash
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

```bash
# 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

```bash
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:

```bash
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

```bash
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

```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

```python
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:

```bash
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)

```bash
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:

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

### 3. Usar bfloat16 en GPUs Ampere+

```bash
--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

```bash
# 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):

```bash
# 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:

```bash
--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:

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

### Problema: la descarga del modelo es lenta

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

```bash
# 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:

```bash
-p 8080:80  # host:container
```

### Problema: "trust\_remote\_code is required"

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

```bash
--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.

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

### Problema: el contenedor se cierra inmediatamente

```bash
# Revisar errores
docker logs tgi

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

***

## Enlaces

* [GitHub](https://github.com/huggingface/text-generation-inference)
* [Documentación](https://huggingface.co/docs/text-generation-inference)
* [Docker Hub / GHCR](https://github.com/huggingface/text-generation-inference/pkgs/container/text-generation-inference)
* [Modelos compatibles](https://huggingface.co/docs/text-generation-inference/supported_models)
* [CLORE.AI Marketplace](https://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](https://clore.ai/marketplace) servidores GPU. Navega las GPUs disponibles y alquila por hora — sin compromisos, acceso root completo.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-es/modelos-de-lenguaje/tgi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.