# 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) --- # Agent Instructions: 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: ``` GET https://docs.clore.ai/guides/guides_v2-ru/3d-generaciya/hunyuan3d.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.