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 Marketplace.

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

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

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

python gradio_app.py --port 7860 --share

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

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

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

• Ползунки для шагов вывода, масштаба направляющей и 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 = [
    "красный спортивный автомобиль, 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]}")

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

# 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

• Модель на HuggingFace

• CLORE.AI Marketplace