> 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-3d/hunyuan3d.md).

# Hunyuan3D 2.1

Создавайте 3D-сетки из текста или изображений с Tencent Hunyuan3D 2.1 на Clore.ai

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

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

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

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

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

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

**Цены Clore.ai:** RTX 4090 ≈ $0.14–0.42/ч · RTX 3090 ≈ $0.07–0.21/ч

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

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

# Установить зависимости
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 по изображению
* Ползунки для шагов инференса, guidance scale и 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 = [
    "красный спортивный автомобиль, низкополигональный игровой ассет",
    "деревянный сундук с сокровищами, PBR-материал",
    "космический шлем с визором, hard surface",
]

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"Создано: 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 sec         | \~15 sec            | \~35 сек |
| RTX 3090 | \~30 сек         | \~25 сек            | \~55 сек |
| A100 40G | \~18 sec         | \~12 с              | \~30 сек |

## Советы

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

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

| Проблема                               | Решение                                                                                                 |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `CUDA out of memory`                   | Используйте 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](https://clore.ai/marketplace)


---

# 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-3d/hunyuan3d.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.