Полное руководство по Hunyuan3D 2.0: нативная поддержка ComfyUI и ComfyUI-Hunyuan3DWrapper

Hunyuan3D-2 — это серия открытых моделей для генерации 3D, разработанная компанией Tencent. На март 2025 года последняя версия — 2.0, она поддерживает создание высококачественных 3D-моделей с текстурами высокого разрешения на основе текста, изображения или эскиза.

Технические особенности

Система использует раздельный процесс генерации геометрии и синтеза текстур:

• Генерация геометрии (Hunyuan3D-DiT): основана на диффузионной модели, генерирует 3D-модели без текстур, содержит 2,6 млрд параметров, способна точно извлекать геометрическую информацию из изображений или текста.
• Синтез текстур (Hunyuan3D-Paint): добавляет текстуры высокого разрешения (4K) к геометрическим моделям, содержит 1,3 млрд параметров, поддерживает многовидовую генерацию для реалистичных текстур и согласованного освещения.

Разделение этапов формы и текстуры снижает сложность и повышает качество генерации.

Оптимизация производительности и эффективности

• Быстрая генерация: создание модели возможно за 30 секунд, ускоренная версия (Hunyuan3D-DiT-v2-0-Fast) сокращает время вывода на 50% благодаря технике дистилляции.
• Мультимодальный ввод: поддерживаются различные способы ввода — текст, изображения, эскизы, совместимость с плагинами Blender и приложениями Gradio, что снижает порог входа.

Экосистема открытых моделей Проект открыто предоставляет 6 моделей (включая облегчённые версии), подходящих для разных задач:

• Hunyuan3D-2mv: многовидовая модель генерации формы, подходит для сложных сцен.
• Hunyuan3D-Delight-v2-0: модель для обработки изображений, создаёт текстуры, не зависящие от освещения. Также доступны облегчённые версии (2mini), высокоточные модели геометрии (DiT-v2-0) и др.

Ниже приведены онлайн-платформы и реализации, которые позволяют опробовать Hunyuan3D 2.0 без ComfyUI:

• Онлайн-демо Hunyuan3D-2mv
• Онлайн-демо Hunyuan3D-2
• Главная страница Hunyuan3D
• Hunyuan3D-2-WinPortable

Далее рассмотрим способы генерации моделей Hunyuan3D 2.0 в ComfyUI.

Способы реализации Hunyuan3D 2.0 в ComfyUI

В этом руководстве будут рассмотрены основные подходы. Для каждого способа приведены полные рабочие процессы (workflow) и пошаговые инструкции.

ComfyUI-Hunyuan3DWrapper

Разработан Kijai, на данный момент обеспечивает наиболее полную поддержку и функциональность в ComfyUI, позволяет получать полный результат — от модели до текстуры. Однако для генерации текстур требуется отдельная сборка компонента, что подразумевает базовые знания о виртуальных средах Python и командах pip.

Нативная поддержка ComfyUI

ComfyUI теперь официально поддерживает модели Hunyuan3D 2.0 и 2mv, позволяя визуализировать 3D-модели. Однако поддержка текстур пока отсутствует — выводятся воксельные модели, которые тоже могут быть интересны. Для использования достаточно обновить ComfyUI до последней версии, что делает процесс простым и доступным.

ComfyUI 3D Pack

Главная проблема этого плагина — несовместимость зависимостей с последними версиями ComfyUI, из-за чего установка сильно затруднена. После многочисленных попыток мне не удалось его установить, поэтому в статье приведено только краткое описание и ссылки на ресурсы.

Входные изображения

Поскольку в примерах используются разные рабочие процессы, мы предоставляем соответствующие входные изображения. Все материалы взяты из примеров официальной документации ComfyUI, но вы можете использовать и свои изображения.

Плагин ComfyUI-Hunyuan3DWrapper использует узлы плагина ComfyUI-essentials для автоматического удаления фона, а нативный workflow ComfyUI такой функции не имеет, поэтому предоставленные здесь изображения уже обработаны. Если вы хотите использовать свои изображения, обратитесь к разделу удаления фона в инструкции по ComfyUI-Hunyuan3DWrapper.

Рабочий процесс ComfyUI-Hunyuan3DWrapper для Hunyuan3D 2.0

В этом разделе мы рассмотрим использование плагина ComfyUI-Hunyuan3DWrapper для генерации моделей Hunyuan3D 2.0. Я структурировал рабочие процессы и добавил ссылки на скачивание моделей в файлы workflow.

1. Установка необходимых плагинов

Для работы workflow Kijai требуются два плагина:

• ComfyUI-Hunyuan3DWrapper
• ComfyUI_essentials

Вы можете установить их через ComfyUI Manager.

1.1 Установка основных зависимостей плагинов

Этот этап знаком тем, кто уже устанавливал плагины для ComfyUI. Если вы используете ComfyUI Manager, зависимости установятся автоматически.

Если вы устанавливали плагины вручную или через git, необходимо выполнить команды установки зависимостей в соответствующей виртуальной среде ComfyUI.

Пожалуйста, обратитесь к разделу установки зависимостей в конце руководства по установке плагинов ComfyUI.

1.2 Установка компонента генерации текстур

После установки основных зависимостей ComfyUI-Hunyuan3DWrapper необходимо скомпилировать и установить компонент для генерации текстур. Автор предоставил готовые wheel-файлы для определённых сред.

Эти файлы размещены в соответствующей директории, а инструкция по их использованию приведена в Readme плагина. Для удобства русскоязычных пользователей я перевёл и структурировал этот раздел.

1.2.1 Установка готовых wheel-файлов

Ниже приведены инструкции по установке готовых wheel-файлов для разных сред. Если подходящей версии нет, обратитесь к разделу самостоятельной сборки.

pip install wheels\custom_rasterizer-0.1-cp312-cp312-win_amd64.whl

python_embeded\python.exe -m pip install ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\wheels\custom_rasterizer-0.1-cp312-cp312-win_amd64.whl

python_embeded\python.exe -m pip install ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\wheels\custom_rasterizer-0.1.0+torch260.cuda126-cp312-cp312-win_amd64.whl

Для десктопной версии ComfyUI вы можете выполнить следующие шаги для установки в соответствующей среде:

После запуска десктопной версии необходимо открыть терминал, как показано на изображении ниже. Python-среда уже активирована, поэтому вы можете сразу выполнять команды установки в этом терминале.

1. После запуска десктопной версии нажмите на кнопку-переключатель в правом верхнем углу, чтобы открыть панель логов внизу
2. В нижней панели выберите вкладку terminal, чтобы открыть терминал
3. Выполните команду установки в терминале:

pip install ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\wheels\custom_rasterizer-0.1-cp312-cp312-win_amd64.whl

Некоторые пользователи сообщают о проблемах с поиском файла этим методом, поэтому вы также можете использовать команду cd для перехода в соответствующую папку:

cd custom_nodes\ComfyUI-Hunyuan3DWrapper\wheels

4. Используйте ls для вывода списка файлов в папке wheels
5. Используйте pip install для установки соответствующего wheel-файла, например:

pip install custom_rasterizer-0.1-cp312-cp312-win_amd64.whl

Выберите подходящую версию в зависимости от вашей системы.

1.2.2 Установка через самостоятельную компиляцию (если предварительно собранные файлы не подходят для вашей системы)

Если предварительно собранные wheel-файлы не работают на вашей системе, вам потребуется скомпилировать их самостоятельно:

Компиляция и установка Rasterizer:

cd custom_nodes/ComfyUI-Hunyuan3DWrapper/hy3dgen/texgen/custom_rasterizer
python setup.py install

cd hy3dgen/texgen/custom_rasterizer
python setup.py install

python setup.py bdist_wheel

cd C:\ComfyUI_windows_portable\ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\hy3dgen\texgen\custom_rasterizer
C:\ComfyUI_windows_portable\python_embeded\python.exe -m pip install .

После успешной установки в папке site-packages вашей среды Python должны появиться файлы custom_rasterizer_kernel*.pyd и папка custom_rasterizer.

Компиляция расширения mesh_processor:

cd custom_nodes/ComfyUI-Hunyuan3DWrapper/hy3dgen/texgen/differentiable_renderer
python setup.py build_ext --inplace

cd hy3dgen/texgen/differentiable_renderer
python setup.py build_ext --inplace

cd hy3dgen/texgen/differentiable_renderer
python_embeded\python.exe setup.py build_ext --inplace

Этот файл должен находиться в этой папке. Он используется только для исправления вершин; если этот файл не существует, будет использоваться резервный вариант на CPU, что будет намного медленнее. Исправление вершин находится в отдельном узле, поэтому в худшем случае его можно обойти, но при этом будет хуже заполнение текстур.

1.3 Необязательная установка: BPT (Boundary Preserving Transform)

Этот компонент полностью является необязательным, но имеет высокие требования к установке:

cd custom_nodes/ComfyUI-Hunyuan3DWrapper/hy3dgen/shapegen/bpt
pip install -r requirements.txt

cd ComfyUI-Hunyuan3DWrapper\hy3dgen\shapegen\bpt
pip install -r requirements.txt

python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\hy3dgen\shapegen\bpt\requirements.txt

Скачайте файл весов: bpt-8-16-500m.pt

Скопируйте bpt-8-16-500m.pt в директорию ComfyUI-Hunyuan3DWrapper-main\hy3dgen\shapegen\bpt.

1.4 Обновление Xatlas для исправления проблем с UV-отображением для моделей с высоким полигональным числом

Для исправления проблем с UV-отображением для моделей с высоким полигональным числом вы можете обновить Xatlas:

python_embeded\python.exe -m pip uninstall xatlas

git clone --recursive https://github.com/mworchel/xatlas-python.git
cd .\xatlas-python\extern

git clone --recursive https://github.com/jpcy/xatlas

.\python_embeded\python.exe -m pip install .\xatlas-python\

2. Рабочий процесс Hunyuan3D 2.0 для одного вида

Модели Hunyuan3D 2.0 не являются многовидовыми, поэтому при использовании ComfyUI-Hunyuan3DWrapper вам необходимо использовать модели серии Hunyuan3D-DiT-v2-0, а не серии Hunyuan3D-DiT-v2-mv. Этот плагин не только поддерживает генерацию геометрии модели, но и генерацию текстур, позволяя создавать полные 3D-модели.

2.1 Файл рабочего процесса

Скачайте файл рабочего процесса ниже и перетащите его в ComfyUI, который автоматически предложит завершить загрузку соответствующих моделей.

2.2 Ручная установка модели

Когда Hunyuan3D 2.0 был впервые выпущен, он не предоставлял модели в формате safetensors, поэтому Kijai предоставил конвертированные версии. Однако Hunyuan3D 2.0 теперь предлагает модели в формате safetensors. Вы можете скачать любую из моделей ниже и сохранить их в директорию ComfyUI/models/diffusion_models/.

• Kijai: hunyuan3d-dit-v2-0-fp16.safetensors
• Tencent: hunyuan3d-dit-v2-0/model.fp16.safetensors Download and rename to hunyuan3d-dit-v2-0.safetensors

2.3 Запуск рабочего процесса с изображениями

1. Убедитесь, что hunyuan3d-dit-v2-0.safetensors загружен в узле Hy3DModelLoader
2. Загрузите соответствующее входное изображение в узле Load Image для генерации модели
3. Нажмите кнопку Run или используйте сочетание клавиш Ctrl(cmd) + Enter для запуска рабочего процесса

3. Рабочий процесс Hunyuan3D 2.0 для нескольких видов

3.1 Файл рабочего процесса

Скачайте файл рабочего процесса ниже и перетащите его в ComfyUI, который автоматически предложит завершить загрузку соответствующих моделей.

3.2 Ручная установка модели

Модель Hunyuan3D 2mv для нескольких видов похожа на предыдущую. Kijai также предоставил ранние конвертированные версии, а позже Tencent предоставил версии в формате safetensors. Вы можете скачать любую из моделей ниже и сохранить их в директорию ComfyUI/models/diffusion_models/.

• Kijai: hunyuan3d-dit-v2-0-fp16.safetensors
• Tencent: hunyuan3d-dit-v2-mv/model.fp16.safetensors Download and rename to hunyuan3d-dit-v2-mv-fp16.safetensors

3.3 Запуск рабочего процесса с изображениями

1. Убедитесь, что hunyuan3d-dit-v2-mv-fp16.safetensors загружен в узле Hy3DModelLoader
2. Загрузите входные изображения различных углов в узлах Load Image. Если у вас нет изображений для определенных углов, щелкните правой кнопкой мыши соответствующий узел и установите его режим на Never
3. Нажмите кнопку Run или используйте сочетание клавиш Ctrl(cmd) + Enter для запуска рабочего процесса

Рабочий процесс Hunyuan3D 2.0 для ComfyUI

ComfyUI теперь поддерживает модели серии Hunyuan3D-2mv, позволяя непосредственно генерировать 3D-геометрические модели (в настоящее время без материалов текстур). Вам просто нужно обновить ComfyUI до последней версии, чтобы испытать это. Поскольку ComfyUI Wiki начал сотрудничать с Comfy officials для поддержки Comfy Official Documentation, этот раздел был подробно описан в Comfy Official Documentation. Однако официальная документация в настоящее время поддерживает только китайский и английский языки. Для удобства читателей ComfyUI Wiki ComfyUI Wiki переработал и отредактировал содержимое, которое изначально было опубликовано на docs.comfy.org на нашем сайте.

ComfyUI в настоящее время предлагает три встроенных рабочих процесса, в основном поддерживающих модели серии Hunyuan3D 2.0 и Hunyuan3D-2mv:

• Рабочий процесс Hunyuan3D-2mv для нескольких видов
• Ускоренный рабочий процесс Hunyuan3D-2mv для нескольких видов
• Рабочий процесс Hunyuan3D-2 для одного вида

Эти рабочие процессы были добавлены в последнюю версию шаблонов рабочих процессов ComfyUI. Вы можете найти их в меню workflow -> workflow templates -> 3d.

1. Использование рабочего процесса Hunyuan3D-2mv для нескольких видов

1.1 Пример рабочего процесса

Скачайте изображение ниже и перетащите его в ComfyUI, который автоматически предложит завершить загрузку соответствующих моделей.

1.2 Ручная установка модели

Скачайте hunyuan3d-dit-v2-mv.safetensors и сохраните его в директории ComfyUI/models/checkpoints/, переименовав его в hunyuan3d-dit-v2-mv.safetensors.

1.3 Пошаговый запуск рабочего процесса

1. Убедитесь, что в узле Image Only Checkpoint Loader(img2vid model) загружена модель hunyuan3d-dit-v2-mv.safetensors
2. Загрузите изображения с соответствующих ракурсов в каждый узел Load Image
3. Запустите рабочий процесс (workflow) для генерации 3D-модели

2. Использование ускоренного рабочего процесса Hunyuan3D-2mv-turbo

Hunyuan3D-2mv-turbo — это облегчённая версия Hunyuan3D-2mv, которая работает быстрее.

2.1 Пример рабочего процесса

Скачайте изображение ниже и перетащите его в ComfyUI — система автоматически предложит загрузить необходимые модели.

2.2 Ручная установка модели

Скачайте hunyuan3d-dit-v2-mv-turbo.safetensors, переименуйте файл в hunyuan3d-dit-v2-mv-turbo.safetensors и сохраните его в папку ComfyUI/models/checkpoints/.

2.3 Пошаговый запуск рабочего процесса

1. Убедитесь, что в узле Image Only Checkpoint Loader(img2vid model) загружена модель hunyuan3d-dit-v2-mv-turbo.safetensors
2. Загрузите изображения с соответствующих ракурсов в каждый узел Load Image
3. В этом рабочем процессе обратите внимание, что cfg установлен на 1.0, а также добавлен узел flux guidance для управления генерацией distillation cfg
4. Запустите рабочий процесс (workflow) для генерации 3D-модели

3. Использование рабочего процесса Hunyuan3D-2 для одного ракурса

Модель Hunyuan3D-2 поддерживает генерацию 3D-моделей по одному изображению.

3.1 Пример рабочего процесса

Скачайте изображение ниже и перетащите его в ComfyUI — система автоматически предложит загрузить необходимые модели.

3.2 Пример входного изображения

3.3 Ручная установка модели

Скачайте hunyuan3d-dit-v2.safetensors, переименуйте файл в hunyuan3d-dit-v2.safetensors и сохраните его в папку ComfyUI/models/checkpoints/.

3.4 Пошаговый запуск рабочего процесса

1. Убедитесь, что в узле Image Only Checkpoint Loader(img2vid model) загружена модель hunyuan3d-dit-v2.safetensors
2. Загрузите входное изображение в узел Load Image
3. Обратите внимание, что в этом рабочем процессе используется узел Hunyuan3Dv2Conditioning, а не Hunyuan3Dv2ConditioningMultiView
4. Запустите рабочий процесс (workflow) для генерации 3D-модели

ComfyUI 3D Pack

Основная проблема при установке ComfyUI 3D Pack — это конфликты зависимостей. Требования к окружению этого плагина отличаются от последних версий ComfyUI, особенно по поддержке версий PyTorch и CUDA. Если вы хотите попробовать, ознакомьтесь с инструкцией по установке на странице проекта ComfyUI-3D-Pack. Также пользователи сообщества предоставили интегрированные сборки, которые можно попробовать: Comfy3D-WinPortable | Интегрированный пакет

Дополнительная информация

Как сгенерировать 3D-модель по тексту

В приведённых выше рабочих процессах используются входные изображения. Вы можете добавить рабочий процесс генерации изображения по тексту перед этими рабочими процессами, чтобы получить нужное изображение. Если вам нужны изображения с разных ракурсов, попробуйте плагин ComfyUI-MVAdapter для генерации мультиракурсных изображений персонажа.

Открытые модели серии Hunyuan3D 2.0

Hunyuan3D 2.0 открыла исходный код нескольких моделей, охватывающих полный процесс 3D-генерации. Подробнее можно узнать на странице Hunyuan3D-2.

Серия Hunyuan3D-2mini

Серия Hunyuan3D-2mv

Серия Hunyuan3D-2

Ссылки по теме Hunyuan 3D 2.0

• Главная страница Hunyuan3D: https://3d.hunyuan.tencent.com
• Демо Hunyuan3D-2: https://huggingface.co/spaces/tencent/Hunyuan3D-2
• Модели Hunyuan3D-2: https://huggingface.co/Tencent/Hunyuan3D-2
• Модели Hunyuan3D-2mv: https://huggingface.co/tencent/Hunyuan3D-2mv
• Демо Hunyuan3D-2mv: https://huggingface.co/spaces/tencent/Hunyuan3D-2mv
• GitHub: https://github.com/Tencent/Hunyuan3D-2
• Discord: https://discord.gg/GuaWYwzKbX
• Отчёт: https://github.com/Tencent/Hunyuan3D-2/blob/main/assets/report/Tencent_Hunyuan3D_2_0.pdf
• Официальный сайт: http://3d-models.hunyuan.tencent.com