# Hunyuan3D 2.1

Hunyuan3D 2.1 от Tencent — двухэтапная модель генерации 3D: сначала она предсказывает геометрию (форму), затем синтезирует PBR-текстуры. Она принимает на вход как текстовые подсказки, так и эталонные изображения и выводит готовые к производству меши в форматах GLB, OBJ или PLY. С более чем 3 миллионами загрузок на HuggingFace, это одна из наиболее широко используемых открытых моделей генерации 3D.

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

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

* **Текст-в-3D и изображение-в-3D** — оба режима ввода в одной модели
* **Двухэтапный конвейер** — сначала генерация формы, затем синтез PBR-текстур
* **Высокое качество вывода** — детализированная геометрия с картами альбедо, нормалей и шероховатости
* **Несколько форматов экспорта** — GLB, OBJ, PLY
* **Веб-интерфейс Gradio** — взаимодействие через браузер, без необходимости программирования
* **16–24 ГБ видеопамяти** — работает на RTX 3090 и RTX 4090
* **3M+ загрузок** на HuggingFace — активное сообщество и постоянные обновления

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

| Компонент | Минимум        | Рекомендуется  |
| --------- | -------------- | -------------- |
| GPU       | RTX 3090 24 ГБ | RTX 4090 24 ГБ |
| VRAM      | 16 ГБ          | 24 ГБ          |
| ОЗУ       | 16 ГБ          | 32 ГБ          |
| Диск      | 50 ГБ          | 100 ГБ         |
| CUDA      | 11.8           | 12.1+          |
| Python    | 3.10           | 3.11           |

**Цены Clore.ai:** RTX 4090 ≈ $0.5–2/день · RTX 3090 ≈ $0.3–1/день

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

### 1. Клонирование и установка

```bash
git clone https://github.com/Tencent/Hunyuan3D-2.git
cd Hunyuan3D-2

# Создать окружение
conda create -n hunyuan3d python=3.10 -y
conda activate hunyuan3d

# Установить PyTorch
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# Установить зависимости
pip install -r requirements.txt

# Скачать веса модели (автозагрузка при первом запуске, ~15 ГБ всего)
python -c "from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline; Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')"
```

### 2. Запустить веб-интерфейс Gradio

```bash
python gradio_app.py --port 7860 --share
```

Интерфейс предоставляет:

* Поле ввода текста для генерации 3D по тексту
* Загрузка изображения для генерации 3D по изображению
* Ползунки для шагов вывода, масштаба направляющей и seed
* Просмотр 3D-модели с орбитальным управлением
* Кнопки загрузки для GLB/OBJ/PLY

### 3. Генерация через Python API

```python
from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
from hy3dgen.texgen import Hunyuan3DPaintPipeline

# Этап 1: Генерация формы
shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="shapegen",
)
shape_pipeline.to("cuda")

# Сгенерировать меш из текста
mesh = shape_pipeline(
    prompt="детализированный средневековый меч с украшенной рукоятью",
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

mesh.export("sword_shape.glb")
```

### 4. Добавить текстуры (Этап 2)

```python
# Этап 2: Синтез текстур
texture_pipeline = Hunyuan3DPaintPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="texgen",
)
texture_pipeline.to("cuda")

textured_mesh = texture_pipeline(
    mesh=mesh,
    prompt="детализированный средневековый меч с украшенной рукоятью",
    num_inference_steps=20,
    seed=42,
)[0]

textured_mesh.export("sword_textured.glb")
```

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

### Генерация из изображения в 3D

```python
from PIL import Image

# Загрузить референсное изображение
image = Image.open("reference_chair.png")

# Сгенерировать форму из изображения
mesh = shape_pipeline(
    image=image,
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

# Применить текстуру
textured = texture_pipeline(
    mesh=mesh,
    image=image,
    num_inference_steps=20,
    seed=42,
)[0]

textured.export("chair.glb")
```

### Пакетная обработка

```python
from pathlib import Path

prompts = [
    "красный спортивный автомобиль, low-poly игровой ассет",
    "деревянный сундук с сокровищами, PBR-материал",
    "киберпанковский шлем с визором, твердая поверхность",
]

output_dir = Path("/workspace/3d-output")
output_dir.mkdir(exist_ok=True)

for i, prompt in enumerate(prompts):
    mesh = shape_pipeline(prompt=prompt, num_inference_steps=30, seed=42)[0]
    textured = texture_pipeline(mesh=mesh, prompt=prompt, num_inference_steps=20, seed=42)[0]
    textured.export(str(output_dir / f"asset_{i:03d}.glb"))
    print(f"Generated: asset_{i:03d}.glb — {prompt[:40]}")
```

### Экспорт в несколько форматов

```python
# GLB (рекомендуется — включает текстуры, универсальный формат)
textured_mesh.export("model.glb")

# OBJ (с файлом материала MTL)
textured_mesh.export("model.obj")

# PLY (цвета вершин, совместим с облаком точек)
textured_mesh.export("model.ply")
```

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

| GPU      | Форма (30 шагов) | Текстура (20 шагов) | Итого    |
| -------- | ---------------- | ------------------- | -------- |
| RTX 4090 | \~20 сек         | \~15 сек            | \~35 сек |
| RTX 3090 | \~30 сек         | ≈25 с               | \~55 сек |
| A100 40G | \~18 сек         | \~12 с              | \~30 сек |

## Советы

* **Удаляйте фоны с изображений** перед преобразованием изображения в 3D — используйте `rembg` для чистой сегментации
* **Текстовые подсказки выигрывают от конкретики** — "low-poly средневековый меч с рукоятью, обернутой кожей" даёт лучшие результаты, чем просто "меч"
* **Уменьшите `num_inference_steps`** до 15–20 для более быстрых предварительных просмотров в процессе итераций
* **Увеличьте `guidance_scale`** (8–12) для более строгого соответствия подсказке ценой уменьшения разнообразия
* **GLB — лучший формат экспорта** — он объединяет геометрию, текстуры и материалы в одном файле
* **Используйте `--share`** при запуске Gradio на Clore.ai для удалённого доступа через браузер
* **Веса модели занимают \~15 ГБ** — убедитесь, что на диске достаточно места перед первым запуском
* **Для игровых ассетов**, генерируйте в высоком качестве, затем уменьшайте полигональность в Blender для уровней LOD

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

| Проблема                               | Решение                                                                                               |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `CUDA — недостаточно памяти`           | Используйте RTX 3090+ (24 ГБ). Уменьшайте размер батча или шаги вывода                                |
| Загрузка модели зависла                | Проверьте место на диске. Используйте `huggingface-cli download tencent/Hunyuan3D-2` вручную          |
| Интерфейс Gradio недоступен            | Передайте `--share` флаг, или пробросьте порт 7860 с панели Clore.ai                                  |
| Плохое качество геометрии              | Увеличьте `num_inference_steps` до 40+, попробуйте разные seed'ы                                      |
| Артефакты в текстурах                  | Убедитесь, что меш формы чист перед этапом текстурирования                                            |
| Ошибки импорта при чистой установке    | Запустите `pip install -r requirements.txt` снова — некоторые зависимости компилируются из исходников |
| Медленная генерация при первом запуске | Ожидаемо — компиляция модели и загрузка весов кэшируются после первого инференса                      |

## Ресурсы

* [Hunyuan3D-2 GitHub](https://github.com/Tencent/Hunyuan3D-2)
* [Модель на HuggingFace](https://huggingface.co/tencent/Hunyuan3D-2)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)