> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-ru/yazykovye-modeli/tgi.md).

# TGI (Text Generation Inference)

Запустите HuggingFace Text Generation Inference (TGI) для production-сервинга LLM на GPU Clore.ai

Text Generation Inference (TGI) — это production-класс фреймворк HuggingFace для обслуживания LLM, предназначенный для высокопроизводительного и низколатентного инференса. Он поддерживает Flash Attention 2, непрерывный батчинг, PagedAttention и тензорный параллелизм из коробки — что делает его лучшим решением для развёртывания больших языковых моделей в масштабе на GPU-серверах CLORE.AI.

{% hint style="success" %}
Все примеры можно запускать на GPU-серверах, арендованных через [маркетплейс CLORE.AI](https://clore.ai/marketplace).
{% endhint %}

## Требования к серверу

| Параметр | Минимум                                    | Рекомендуется        |
| -------- | ------------------------------------------ | -------------------- |
| ОЗУ      | 16 ГБ                                      | 32 ГБ+               |
| VRAM     | 8 ГБ                                       | 24 ГБ+               |
| Диск     | 50 ГБ                                      | 200 ГБ+              |
| GPU      | Любая NVIDIA (Ampere+ для Flash Attention) | A100, H100, RTX 4090 |

{% hint style="info" %}
Flash Attention 2 требует архитектуру Ampere или новее (RTX 3000+, A100, H100). Для более старых GPU TGI автоматически переключится на стандартное внимание.
{% endhint %}

## Быстрое развертывание на CLORE.AI

**Docker-образ:** `ghcr.io/huggingface/text-generation-inference:latest`

**Порты:** `22/tcp`, `8080/http`

**Переменные среды:**

| Переменная         | Пример                               | Описание                                   |
| ------------------ | ------------------------------------ | ------------------------------------------ |
| `MODEL_ID`         | `mistralai/Mistral-7B-Instruct-v0.3` | ID модели HuggingFace                      |
| `HF_TOKEN`         | `hf_xxx...`                          | Токен HuggingFace (для gated-моделей)      |
| `NUM_SHARD`        | `2`                                  | Количество GPU для тензорного параллелизма |
| `MAX_INPUT_LENGTH` | `4096`                               | Максимум входных токенов                   |
| `MAX_TOTAL_TOKENS` | `8192`                               | Максимум входных + выходных токенов        |
| `QUANTIZE`         | `bitsandbytes-nf4`                   | Метод квантизации                          |

## Пошаговая настройка

### 1. Арендуйте GPU-сервер на CLORE.AI

Перейдите на [маркетплейс CLORE.AI](https://clore.ai/marketplace) и фильтруйте серверы по:

* VRAM ≥ 24 ГБ для моделей 7B (полная точность)
* VRAM ≥ 12 ГБ для моделей 7B (4-битная квантизация)
* VRAM ≥ 80 ГБ для моделей 70B (полная точность, один GPU)

### 2. Подключитесь по SSH

После подтверждения заказа подключитесь к серверу, используя данные SSH из панели управления CLORE.AI:

```bash
ssh -p <PORT> root@<SERVER_IP>
```

Или используйте Web Terminal из панели заказа CLORE.AI.

### 3. Скачайте Docker-образ TGI

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

### 4. Запустите TGI с моделью

**Базовый запуск (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
```

**С токеном HuggingFace (для gated-моделей, таких как 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_your_token_here \
  ghcr.io/huggingface/text-generation-inference:latest \",
  --model-id meta-llama/Meta-Llama-3-8B-Instruct \
  --max-input-length 8192 \
  --max-total-tokens 16384
```

**С 4-битной квантизацией (для меньшего объёма 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
```

**Тензорный параллелизм на нескольких GPU (для моделей 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. Проверьте, что сервер запущен

```bash
# Проверьте логи
docker logs -f tgi

# Дождитесь сообщения "Connected", затем проверьте:
curl http://localhost:8080/health
```

Ожидаемый ответ: `{"status":"ok"}`

### 6. Доступ через HTTP-прокси CLORE.AI

В панели заказа CLORE.AI вы увидите свой `http_pub` URL для порта 8080. Это позволяет получать доступ через браузер/API без SSH-туннелирования:

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

***

## Примеры использования

### Пример 1: Базовая генерация текста

```bash
curl http://localhost:8080/generate \
  -X POST \\
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": "What is the capital of France?",
    "parameters": {
      "max_new_tokens": 100,
      "temperature": 0.7
    }
  }'
```

### Пример 2: Chat Completions (совместимо с OpenAI)

TGI поддерживает формат API OpenAI для chat completions:

```bash
curl http://localhost:8080/v1/chat/completions \\
  -X POST \\
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "Вы — полезный помощник."},
      {"role": "user", "content": "Объясни квантовую запутанность простыми словами."}
    ],
    "max_tokens": 512,
    "temperature": 0.8,
    "stream": false
  }'
```

### Пример 3: Потоковый ответ

```bash
curl http://localhost:8080/generate_stream \
  -X POST \\
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": "Write a Python function to calculate Fibonacci numbers:",
    "parameters": {
      "max_new_tokens": 300,
      "temperature": 0.2
    }
  }' \
  --no-buffer
```

### Пример 4: Python-клиент

```python
from huggingface_hub import InferenceClient

# Замените на ваш URL CLORE.AI http_pub
client = InferenceClient(model="http://localhost:8080")

# Простая генерация
response = client.text_generation(
    "Переведи на французский: Hello, how are you?",
    max_new_tokens=100,
    temperature=0.7,
)
print(response)

# Чат
for token in client.chat_completion(
    messages=[{"role": "user", "content": "Что такое машинное обучение?"}],
    max_tokens=200,
    stream=True,
):
    print(token.choices[0].delta.content, end="", flush=True)
```

### Пример 5: Пакетные запросы

```python
import requests

BASE_URL = "http://localhost:8080"  # или ваш URL CLORE.AI http_pub

prompts = [
    "Кратко изложите Французскую революцию в 3 предложениях.",
    "Напишите хайку о GPU-вычислениях.",
    "Каковы основные преимущества Rust по сравнению с 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}\nОтвет: {result}\n{'-'*50}")
```

***

## Конфигурация

### Ключевые параметры CLI

| Параметр                    | По умолчанию | Описание                                       |
| --------------------------- | ------------ | ---------------------------------------------- |
| `--model-id`                | обязательный | ID модели HuggingFace или локальный путь       |
| `--num-shard`               | 1            | Количество GPU-шардов (тензорный параллелизм)  |
| `--max-concurrent-requests` | 128          | Максимум одновременных запросов                |
| `--max-input-length`        | 1024         | Максимальная длина входных токенов             |
| `--max-total-tokens`        | 2048         | Максимум входных + выходных токенов            |
| `--max-batch-total-tokens`  | auto         | Максимум токенов на батч                       |
| `--quantize`                | none         | Квантизация: `bitsandbytes-nf4`, `gptq`, `awq` |
| `--dtype`                   | auto         | `float16`, `bfloat16`                          |
| `--trust-remote-code`       | false        | Разрешить пользовательский код модели          |
| `--port`                    | 80           | Порт сервера                                   |

### Использование локальной модели

Если у вас есть модель, загруженная локально:

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

### Квантизация AWQ (быстрее, чем 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
```

***

## Советы по производительности

### 1. Включите Flash Attention 2

Flash Attention 2 автоматически включается на GPU архитектуры Ampere+ (RTX 3000+, A100, H100). Дополнительная настройка не требуется.

### 2. Настройте максимальный размер батча

Для сценариев с высокой пропускной способностью увеличьте размер батча:

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

### 3. Используйте bfloat16 на GPU Ampere+

```bash
--dtype bfloat16
```

Это более численно стабильно, чем float16, и работает идентично на современных GPU.

### 4. Предзагружайте модели в постоянное хранилище

```bash
# На сервере выполните предзагрузку перед запуском 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')
"
```

Затем подключите локальный путь, чтобы избежать повторной загрузки при перезапуске.

### 5. Управление памятью GPU

Для RTX 3090/4090 (24 ГБ VRAM):

```bash
# Модель 7B в float16 помещается идеально
--max-total-tokens 8192

# Модели 13B требуется квантизация
--quantize bitsandbytes-nf4
--max-total-tokens 4096
```

### 6. Спекулятивное декодирование

Для более быстрой генерации используйте меньшие модели в качестве черновика:

```bash
--speculate 4  # Количество спекулятивных токенов
```

***

## Устранение неполадок

### Проблема: "CUDA out of memory"

```
Ошибка: CUDA out of memory. Tried to allocate X GiB
```

**Решение:** Уменьшите `--max-total-tokens` или включите квантизацию:

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

### Проблема: Медленная загрузка модели

**Решение:** Используйте зеркало HuggingFace или предварительную загрузку:

```bash
# Установите зеркало
-e HF_ENDPOINT=https://hf-mirror.com
```

### Проблема: сервер недоступен через http\_pub

**Решение:** Убедитесь, что порт 8080 сопоставлен правильно. TGI внутренне слушает порт 80, но снаружи вы сопоставляете его с 8080:

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

### Проблема: требуется "trust\_remote\_code"

Некоторые модели (например, Falcon, Phi) требуют пользовательского кода:

```bash
--trust-remote-code
```

### Проблема: медленный первый ответ

Первый запрос запускает загрузку модели в VRAM. Это нормально. Последующие запросы будут быстрыми.

```bash
# Проверьте ход загрузки
docker logs -f tgi | grep -E "Connected|Error|Loading"
```

### Проблема: контейнер сразу завершается

```bash
# Проверьте наличие ошибок
docker logs tgi

# Частое решение: увеличьте общую память
--shm-size 2g
```

***

## Ссылки

* [GitHub](https://github.com/huggingface/text-generation-inference)
* [Документация](https://huggingface.co/docs/text-generation-inference)
* [Docker Hub / GHCR](https://github.com/huggingface/text-generation-inference/pkgs/container/text-generation-inference)
* [Поддерживаемые модели](https://huggingface.co/docs/text-generation-inference/supported_models)
* [маркетплейс CLORE.AI](https://clore.ai/marketplace)

***

## Рекомендации по GPU для Clore.ai

| Сценарий использования  | Рекомендуемый GPU | Оценочная стоимость на Clore.ai |
| ----------------------- | ----------------- | ------------------------------- |
| Разработка/тестирование | RTX 3090 (24 ГБ)  | $0.07–0.21/гпу/ч                |
| Production (7B–13B)     | RTX 4090 (24 ГБ)  | $0.14–0.42/гпу/ч                |
| Крупные модели (70B+)   | A100 80GB / H100  | \~$1.04/gpu/hr                  |

> 💡 Все примеры в этом руководстве можно развернуть на [Clore.ai](https://clore.ai/marketplace) GPU-серверах. Просматривайте доступные GPU и арендуйте по часам — без обязательств, с полным root-доступом.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-ru/yazykovye-modeli/tgi.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.