# HunyuanImage 3.0

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

**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 Community (бесплатно для исследований и коммерческого использования при менее 100M MAU)

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

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

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

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

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

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

**Рекомендуемая настройка Clore.ai:**

* **Лучшее соотношение цены и качества:** 1× A100 80GB (\~$2–4/день) — комфортно запускает полную модель без выгрузки
* **Бюджетный вариант:** 1× RTX 4090 (\~$0.5–2/день) — работает с выгрузкой на CPU (медленнее, но функционирует)
* **Быстрый продакшен:** 2× A100 80GB (\~$4–8/день) — для пакетной генерации и модели 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/cu121

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

### Текст-в-изображение с Transformers

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

# Загрузите модель (требуется ~80GB 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   | Diffusion Transformer  | Diffusion Transformer |
| Редактирование изображений         | ✅ Нативно              | ❌ Требуется ControlNet | ❌ Требуется img2img   |
| Объединение нескольких изображений | ✅ Нативно              | ❌                      | ❌                     |
| Перенос стиля                      | ✅ Нативно              | ❌ Требуется LoRA       | ❌ Требуется LoRA      |
| Мин. VRAM                          | \~24GB (с выгрузкой)   | 16GB                   | 8GB                   |
| Скорость (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. **A100 80GB — оптимальный выбор** — Один A100 80GB (\~$2–4/день на Clore.ai) запускает модель Instruct без трюков с выгрузкой. Это значительно быстрее, чем RTX 4090 с выгрузкой на CPU.
3. **Предварительно скачивайте модели** — Полная контрольная точка Instruct занимает \~160GB. Скачайте её один раз на постоянный том Clore.ai, чтобы не загружать заново при каждом запуске новой инстанции.
4. **Используйте SSH-туннелирование для Gradio** — Не выставляйте порт 7860 публично. Используйте `ssh -L 7860:localhost:7860` чтобы безопасно получить доступ к веб-интерфейсу из вашего браузера.
5. **Попробуйте бэкенд vLLM для пакетной работы** — Если вы генерируете много изображений, путь вывода vLLM (в папке `vllm_infer/` ) обеспечивает значительно лучшую пропускную способность.

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

| Проблема                                         | Решение                                                                                                                            |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `CUDA — недостаточно памяти` на RTX 4090         | Используйте `device_map="auto"` чтобы включить выгрузку на CPU или переключиться на модель Distil                                  |
| Загрузка не удаётся / очень медленно             | Установите `HF_TOKEN` переменную окружения; используйте `huggingface-cli download` с `--resume-download`                           |
| Не удаётся загрузить модель по HF ID             | Из-за точки в имени сначала клонируйте локально: `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) — Пользовательский узел Community ComfyUI