Hunyuan3D 2.1

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

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

Все примеры работают на GPU-серверах, арендованных через маркетплейс CLORE.AI.

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

• 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. Клонируйте и установите

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

python gradio_app.py --port 7860 --share

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

• Поле ввода текста для генерации 3D по тексту

• Загрузка изображения для генерации 3D по изображению

• Ползунки для шагов инференса, guidance scale и seed

• Предпросмотр 3D-модели с орбитальным управлением

• Кнопки загрузки для GLB/OBJ/PLY

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

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)

# Этап 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 по изображению

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")

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

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]}")

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

# 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

• Модель на HuggingFace

• маркетплейс CLORE.AI