> 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/generaciya-izobrazhenii/hunyuan-image3.md).

# HunyuanImage 3.0

HunyuanImage 3.0 от Tencent — это **крупнейшая в мире модель генерации изображений с открытым исходным кодом** с 80B общих параметров (13B активных во время инференса). Выпущенная 26 января 2026 года, она ломает шаблон, объединяя генерацию изображений, редактирование и понимание в одну авторегрессионную модель — больше никаких отдельных пайплайнов для text-to-image и image-to-image. Она генерирует фотореалистичные изображения, выполняет точное редактирование с сохранением элементов, обрабатывает перенос стиля и даже делает слияние нескольких изображений — всё в одной модели.

**HuggingFace:** [tencent/HunyuanImage-3.0-Instruct](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct) **GitHub:** [Tencent-Hunyuan/HunyuanImage-3.0](https://github.com/Tencent-Hunyuan/HunyuanImage-3.0) **Лицензия:** Лицензия сообщества Tencent Hunyuan (бесплатно для исследований и коммерческого использования при MAU менее 100 млн)

## Ключевые особенности

* **80B всего / 13B активных параметров** — крупнейшая open-source модель изображений MoE; активирует только 13B параметров за один инференс
* **Единая мультимодальная архитектура** — text-to-image, редактирование изображений, перенос стиля и композиция из нескольких изображений в одной модели
* **Редактирование по инструкциям** — опишите на естественном языке, что вы хотите изменить, сохраняя нетронутые элементы
* **Доступен дистиллированный чекпойнт** — `HunyuanImage-3.0-Instruct-Distil` работает всего за 8 шагов сэмплирования для более быстрой генерации
* **Ускорение vLLM** — нативная поддержка vLLM для значительно более быстрого инференса в продакшене
* **Авторегрессионный фреймворк** — в отличие от моделей на базе DiT (FLUX, SD3.5), использует единый AR-подход как для понимания, так и для генерации

## Варианты модели

| Модель                               | Сценарий использования                                 | Шаги  | HuggingFace                                |
| ------------------------------------ | ------------------------------------------------------ | ----- | ------------------------------------------ |
| **HunyuanImage-3.0**                 | Только text-to-image                                   | 30–50 | `tencent/HunyuanImage-3.0`                 |
| **HunyuanImage-3.0-Instruct**        | text-to-image + редактирование + несколько изображений | 30–50 | `tencent/HunyuanImage-3.0-Instruct`        |
| **HunyuanImage-3.0-Instruct-Distil** | Быстрый инференс (8 шагов)                             | 8     | `tencent/HunyuanImage-3.0-Instruct-Distil` |

## Требования

{% hint style="warning" %}
**Многопроцессорные конфигурации с GPU класса 80GB не представлены на маркетплейсе Clore.ai.** Самые крупные доступные сейчас машины — это 4× RTX PRO 6000 Blackwell (по 96GB, всего 380GB) и 8–11× RTX 5090 (по 32GB). Ёмкость A100 / H200 / B200 продаётся как [голое железо](https://clore.ai/bare-metal) по запросу. Проверьте [Цены и доступность GPU](/guides/guides_v2-ru/nachalo-raboty/pricing.md) перед выбором размера развёртывания.
{% endhint %}

| Конфигурация | Один GPU (с выгрузкой)       | Рекомендуется | Продакшен на нескольких GPU |
| ------------ | ---------------------------- | ------------- | --------------------------- |
| GPU          | 1× RTX 4090 24GB             | 1× A100 80GB  | 2–3× A100 80GB              |
| VRAM         | 24GB (с послойной выгрузкой) | 80 ГБ         | 160–240GB                   |
| ОЗУ          | 128 ГБ                       | 128 ГБ        | 256GB                       |
| Диск         | 200GB                        | 200GB         | 200GB                       |
| CUDA         | 12.8+                        | 12.8+         | 12.8+                       |

**Рекомендуемая конфигурация Clore.ai:**

* **Лучшее предложение на рынке:** 1× RTX PRO 6000 Blackwell 96GB ($0.92–1.38/ч) — запускает полную модель без проблем и без выгрузки. A100 80GB — классический выбор, но доступен только как [голое железо](https://clore.ai/bare-metal)
* **Бюджетный вариант:** 1× RTX 4090 ($0.14–0.42/ч) — работает с выгрузкой на CPU (медленнее, но функционально)
* **Быстрая работа в продакшене:** 2× A100 80GB ([голое железо](https://clore.ai/bare-metal)) — для пакетной генерации и модели Instruct

## Быстрый старт

### Установка

```bash
# Клонируйте репозиторий
git clone https://github.com/Tencent-Hunyuan/HunyuanImage-3.0.git
cd HunyuanImage-3.0

# Создайте окружение
pip install -r requirements.txt
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128

# Скачайте веса модели
huggingface-cli download tencent/HunyuanImage-3.0-Instruct --local-dir ./ckpts/HunyuanImage-3-Instruct
```

### Генерация изображений по тексту с Transformers

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

# Загрузите модель (для полной точности требуется около 80 ГБ VRAM)
model_path = "./ckpts/HunyuanImage-3-Instruct"
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    torch_dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True,
)

# Сгенерируйте изображение по тексту
prompt = "Спокойный японский сад осенью, карпы кои плывут в кристально чистом пруду, падают золотые кленовые листья, стиль акварельной живописи"
output = model.generate_image(prompt, num_inference_steps=30)
output.save("japanese_garden.png")
```

### Использование веб-интерфейса Gradio

Самый простой способ опробовать все возможности:

```bash
cd HunyuanImage-3.0

# Установите Gradio
pip install gradio

# Запустите веб-интерфейс
python gradio_demo.py \\
    --model-path ./ckpts/HunyuanImage-3-Instruct \\
    --server-name 0.0.0.0 \\
    --server-port 7860
```

Затем подключитесь через SSH-туннель: `ssh -L 7860:localhost:7860 root@<clore-ip>`

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

### 1. Генерация изображений по тексту (CLI)

```bash
cd HunyuanImage-3.0

python inference.py \\
    --model-path ./ckpts/HunyuanImage-3-Instruct \\
    --prompt "Киберпанковский городской пейзаж ночью, неоновые небоскрёбы отражаются в мокрых от дождя улицах, летающие автомобили, объёмный туман, 8K" \\
    --output-path output.png \\
    --num-inference-steps 30 \\
    --guidance-scale 5.0
```

### 2. Редактирование изображений на естественном языке

Одна из выдающихся возможностей HunyuanImage 3.0 — редактируйте существующие изображения, описывая изменения:

```bash
python inference.py \\
    --model-path ./ckpts/HunyuanImage-3-Instruct \\
    --prompt "Измените сезон на зиму, чтобы деревья были покрыты снегом" \\
    --image-path input_photo.jpg \\
    --output-path edited_winter.png \\
    --num-inference-steps 30
```

### 3. Быстрая генерация с дистиллированной моделью (8 шагов)

```bash
# Скачайте дистиллированный чекпойнт
huggingface-cli download tencent/HunyuanImage-3.0-Instruct-Distil \\
    --local-dir ./ckpts/HunyuanImage-3-Instruct-Distil

# Генерация всего за 8 шагов (в 5–6 раз быстрее)
python inference.py \\
    --model-path ./ckpts/HunyuanImage-3-Instruct-Distil \\
    --prompt "Портрет астронавта, едущего на лошади по Марсу, фотореалистично" \\
    --output-path astronaut.png \\
    --num-inference-steps 8
```

## Сравнение с другими моделями изображений

| Функция                        | HunyuanImage 3.0       | FLUX.2 Klein             | SD 3.5 Large             |
| ------------------------------ | ---------------------- | ------------------------ | ------------------------ |
| Параметры                      | 80B MoE (13B активных) | 32B DiT                  | 8B DiT                   |
| Архитектура                    | Авторегрессионный MoE  | Диффузионный трансформер | Диффузионный трансформер |
| Редактирование изображений     | ✅ Нативная             | ❌ Требуется ControlNet   | ❌ Требуется img2img      |
| Слияние нескольких изображений | ✅ Нативная             | ❌                        | ❌                        |
| Перенос стиля                  | ✅ Нативная             | ❌ Требуется LoRA         | ❌ Требуется LoRA         |
| Мин. VRAM                      | \~24GB (с выгрузкой)   | 16GB                     | 8 ГБ                     |
| Скорость (A100)                | \~15–30 сек            | \~0.3 сек                | \~5 сек                  |
| Лицензия                       | Сообщество Tencent     | Apache 2.0               | Лицензия Stability AI CL |

## Советы для пользователей Clore.ai

1. **Используйте дистиллированную модель для скорости** — `HunyuanImage-3.0-Instruct-Distil` генерирует за 8 шагов вместо 30–50, сокращая время инференса в 4–6 раз. Качество при этом остаётся удивительно близким к полной модели.
2. **Карта на 96 ГБ — оптимальный вариант** — Одна RTX PRO 6000 Blackwell (или A100 80GB через [голое железо](https://clore.ai/bare-metal)) запускает модель Instruct без каких-либо приёмов выгрузки. Это намного быстрее, чем RTX 4090 с выгрузкой на CPU.
3. **Скачайте модели заранее** — Полный чекпойнт Instruct занимает около 160 ГБ. Скачайте его один раз в постоянный том Clore.ai, чтобы не загружать заново каждый раз при запуске нового экземпляра.
4. **Используйте SSH-туннелирование для Gradio** — Не открывайте порт 7860 публично. Используйте `ssh -L 7860:localhost:7860` для безопасного доступа к веб-интерфейсу из браузера.
5. **Попробуйте backend vLLM для пакетной работы** — Если вы генерируете много изображений, путь инференса vLLM (в `vllm_infer/` папке) обеспечивает значительно более высокую пропускную способность.

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

| Проблема                                         | Решение                                                                                                                               |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `CUDA out of memory` на RTX 4090                 | Используйте `device_map="auto"` чтобы включить выгрузку на CPU, или переключитесь на модель Distil                                    |
| Скачивание не удаётся / очень медленное          | Установите `HF_TOKEN` переменную окружения; используйте `huggingface-cli download` с `--resume-download`                              |
| Не удаётся загрузить модель через ID модели HF   | Из-за точки в названии сначала клонируйте локально: `huggingface-cli download tencent/HunyuanImage-3.0-Instruct --local-dir ./ckpts/` |
| Размытые или низкокачественные результаты        | Увеличьте `--num-inference-steps` до 40–50; увеличьте `--guidance-scale` до 7.0                                                       |
| Редактирование изображений игнорирует инструкции | Будьте точны в том, что нужно изменить и что сохранить; используйте короткие, чёткие промпты                                          |
| Интерфейс Gradio не запускается                  | Убедитесь, что `gradio>=4.0` установлен; проверьте, что путь к модели указывает на правильную директорию                              |

## Дополнительное чтение

* [Репозиторий GitHub](https://github.com/Tencent-Hunyuan/HunyuanImage-3.0) — Официальный код, скрипты инференса, демо Gradio
* [HunyuanImage 3.0-Instruct (HuggingFace)](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct) — Полные веса модели
* [Дистиллированный чекпойнт](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct-Distil) — быстрый инференс за 8 шагов
* [Технический отчёт (arXiv)](https://arxiv.org/pdf/2509.23951) — Подробности архитектуры и бенчмарки
* [Интеграция с ComfyUI](https://github.com/bgreene2/ComfyUI-Hunyuan-Image-3) — Пользовательский узел ComfyUI от сообщества


---

# 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/generaciya-izobrazhenii/hunyuan-image3.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.