Здравствуйте друзья! 🌟
Хотите превратить фотографию вазы, игрушечной машинки или эскиза персонажа в полноценную 3D-модель? С Hunyuan3D-2-WinPortable сделать это проще, чем кажется!
Что это за проект?
Hunyuan3D-2-WinPortable — инструмент, который с помощью нейросетей преобразует фотографии в 3D-модели. Сфотографировали керамическую вазу? Программа создаст её 3D-форму (меш), а если добавить снимки с других ракурсов, наложит реалистичные текстуры. Процесс идёт в два этапа: сначала строится геометрия объекта, затем добавляются цвета и детали. ️
Это портативная версия Hunyuan3D 2.0, где всё собрано в одном пакете, чтобы сэкономить ваше время. Благодаря доработкам сообщества (включая модуль mmgp от DeepBeepMeep), проект работает на видеокартах NVIDIA с 6 ГБ памяти, так что ваш ПК или ноутбук, скорее всего, справится. В комплекте идут скрипты (файлы .bat), которые автоматизируют установку и запуск.
Проект поддерживает модели:
- Hunyuan3D-2 🟦: Основная модель для создания высокодетализированных 3D-мешей и текстур. Идеальна для видеокарт с 8 ГБ+ памяти, например, чтобы создать модель автомобиля с чёткими деталями.
- Hunyuan3D-2mini 🟩: Упрощённая версия для слабых систем (6 ГБ видеопамяти). Подходит для простых объектов, таких как игрушки или фигурки.
- Hunyuan3D-2mv 🟨: Версия для нескольких ракурсов (multi-view). Использует до четырёх фотографий — например, спереди и сзади (два ракурса) или спереди, сзади, слева и справа (четыре). Это улучшает точность формы и текстур. Два снимка фигурки персонажа (спереди и сзади) дадут более реалистичный результат, чем одно фото.
Создавайте 3D-объекты для игр, анимации или просто ради эксперимента. Для продвинутых пользователей есть возможность интеграции с ComfyUI 🛠️. Также проект поддерживает генерацию 3D-моделей из текста (text-to-3D) с помощью скрипта run-with-text_to_3d.bat — просто введите описание, например, «керамическая ваза с синим узором», и модель создаст объект. ️
Обзор всех файлов проекта
Проект содержит несколько .bat-скриптов, которые упрощают установку и запуск. Вот их список с описанием:
- 0-initialize.bat 🛠️: Создаёт виртуальное окружение Python и устанавливает основные зависимости (например, transformers, diffusers, FFmpeg).
- 1-compile-install-texture-gen.bat 🎨: Компилирует модули для генерации текстур (используется на шаге 6).
- 2-download-models.bat ⬇️: Скачивает модели с HuggingFace (~19 ГБ).
- 3-start.bat ▶️: Запускает стандартный режим для создания 3D-меша из одного фото (6 ГБ+ видеопамяти).
- 4-start-mv.bat 📸: Запускает режим для нескольких ракурсов с Turbo-оптимизацией.
- 5-start-api-server.bat 🌐: Запускает API-сервер без текстур (для интеграции с другими приложениями).
- 6-start-api-server-with-texture.bat 🌐: API-режим с поддержкой текстур.
- 6-start-api-server-with-texture-dmc.bat 🌐️: Запускает API-сервер с текстурами и оптимизацией DMC (Direct Machining Control). DMC — это технология управления процессом наложения текстур, которая ускоряет и улучшает точность работы, особенно для сложных 3D-моделей. Подходит для интеграции с другими программами и оптимизации ресурсов.
- run-very_low_vram.bat 🐢: Оптимизирован для слабых видеокарт (<8 ГБ, но минимум 6 ГБ).
- run-high_vram.bat 🚀: Для мощных систем (24 ГБ+ видеопамяти).
- run-mv-high_vram.bat 🚀: Для нескольких ракурсов на мощных системах (24 ГБ+).
- run-with-text_to_3d.bat ✍️: Генерирует 3D-модель по текстовому описанию (например, «керамическая ваза»).
- UPDATE.bat 🔄: Обновляет проект и зависимости из репозитория.
Теперь, когда вы знаете, за что отвечает каждый файл, можно приступать к установке!
Что для этого понадобится?️
Видеокарта: NVIDIA с минимум 6 ГБ видеопамяти (4 ГБ возможно, но генерация модели будет очень медленной). Для текстур лучше 8 ГБ+, оптимально — 24 ГБ+. Если у вас RTX 5000-й серии (например, RTX 5090), обратите внимание на инструкцию ниже. 🎮
Драйвер видеокарты: Версия новее марта 2024 года (>550). Проверьте в NVIDIA Control Panel. ️
Оперативная память: Минимум 16 ГБ. 💾
CUDA Toolkit: Версия 12.4, 12.6 или 12.8. Для RTX 5000-й серии используйте CUDA 12.8. ⚙️
Visual Studio Build Tools: Версия 2022 для компиляции текстур. 🔧
Место на диске: Около 20 ГБ (19 ГБ для моделей). 💽
Операционная система: Windows. 🖼️
Для RTX 5000-й серии:
Теоретически проект должен запускаться на видеокартах RTX50XX серии. ✅
Вам нужно установить CUDA 12.8. ⚙️
Затем используйте эти команды для установки (100 процентной гарантии работоспособности дать не могу т.к не являюсь владельцем видеокарты этой серии):
cmd
git clone https://github.com/Tencent/Hunyuan3D-2.git
cd Hunyuan3D-2
git pull
python -m venv venv
call venv\Scripts\activate.bat
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu128
pip install -r requirements.txt
cd hy3dgen/texgen/custom_rasterizer
python setup.py install
cd ../../..
cd hy3dgen/texgen/differentiable_renderer
python setup.py install
cd ../../..
После установки попробуйте запустить интерфейс с помощью этого скрипта или нужного bat-файла в проекте :
cmd
call venv\Scripts\activate.bat
python gradio_app.py --model_path tencent/Hunyuan3D-2 --subfolder hunyuan3d-dit-v2-0-turbo --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode --enable_flashvdm
Проверка CUDA: Введите nvcc --version в PowerShell или CMD. Если установлена версия 12.4, 12.6 или 12.8, новую ставить не нужно. ✅
Путь к папке: Выбирайте папку без пробелов и кириллицы, например, G:\Hunyuan3D2.
Cборка на Boosty — для тех, кто ценит своё время.
Если настройка кажется сложной для вас или вы просто хотите сразу приступить к созданию 3D-моделей, скачайте уже настроенную сборку Hunyuan3D-2-WinPortable на моём Boosty. Всё уже сделано за вас: зависимости установлены, останется скачать только необходимые модели и проект готов к работе. Это идеальный вариант для новичков или тех, кто не хочет разбираться в технических деталях. Всё, что нужно, — 50+ ГБ свободного места на диске для всех моделей и видеокарта NVIDIA.
Скачайте архив со сборкой. ️
Распакуйте его в папку без пробелов и кириллицы, например, G:\Hunyuan3D2.
Запустите 2-download-models.bat, скачаются необходимые модели.
Запустите 3-start.bat или другой в зависимости от вашей потребности и количества видеопамяти вашей видеокарты и откройте в браузере http://localhost:8080. ️
Выполните пункты 2.1 и 2.2 описанные ниже. (установка CUDA Toolkit и Visual Studio Build Tools)
Готово! Если сборка устарела, посмотрите на [GitHub] обновления проекта и обновите проект через файл UPDATE.bat
Для тех, кто хочет настроить проект самостоятельно, чтобы использовать свежую версию или разобраться в процессе, читайте дальше. 🔍
Настройка с нуля — для тех, кто хочет всё контролировать.
Шаг 1: Скачивание проекта 📥
⚠️ Требуется минимум 20 ГБ свободного места и стабильный интернет.
Перейдите на [страницу релизов на GitHub].
Скачайте последний архив, Hunyuan3D2_WinPortable.7z. ️
Распакуйте его с помощью 7-Zip в папку, например, G:\Hunyuan3D2.
Совет: Если у вас есть старая версия проекта, скопируйте папку HuggingFaceHub в новую, чтобы не скачивать все модели заново.
Шаг 2: Установка необходимых программ ️
Для работы нужны CUDA Toolkit и Visual Studio Build Tools. Сначала проверьте, что уже установлено.
2.1. CUDA Toolkit ⚙️
⚠️ В PowerShell или CMD введите nvcc --version. Если отображается версия 12.4, 12.6 или 12.8, пропустите этот шаг.
Если нет. Перейдите на [сайт NVIDIA].
Выберите версию в зависимости от модели вашей видеокарты (12.8 для RTX 40-й серии и новее), Windows, «exe (local)». Если не нашли нужную, смотрите в архиве версий.
Установка: Запустите установочный файл. ▶️
Выберите Custom (Advanced).
Отметьте:
CUDA > Runtime > Libraries — для вычислений. ✅
CUDA > Development > Compilers — для обработки кода. ✅
Снимите галочки с ненужных компонентов (например, Samples).
Установите в папку по умолчанию, обычно это C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v--.-.
Проверка: Введите nvcc --version. Если отображается версия CUDA, всё готово.
2.2. Visual Studio Build Tools 🔧
⚠️ В PowerShell или CMD введите cl. Если отображается информация о компиляторе MSVC, пропустите этот шаг.
Скачивание: Перейдите на [страницу Visual Studio Build Tools 2022].
Выберите «Build Tools for Visual Studio 2022».
Установка: Запустите установочный файл. ️
Выберите Desktop development with C++.
Убедитесь, что включены:
- MSVC v143 - VS 2022 C++ x64/x86 build tools — компилятор. ✅
- Windows 10 SDK — для совместимости. ✅
- C++ CMake tools for Windows — для сборки. ✅
Отключите ненужные компоненты.
Установите в папку по умолчанию.
Введите cl. Если отображается информация о компиляторе, всё готово. ✅
2.3. ⚠️ Закройте все терминалы, файловые менеджеры и программы, которые могут использовать файлы проекта.
Шаг 3: ⚠️ Требуется стабильный интернет для загрузки моделей (~19 ГБ). Если процесс прервётся, перезапустите скрипты.
Откройте папку проекта, например, G:\Hunyuan3D2.
Запустите 0-initialize.bat. Этот скрипт: Создаёт виртуальное окружение Python и создает необходимые для работы файлы. ️
Устанавливает библиотеки, такие как transformers, diffusers, FFmpeg (для обработки данных).
Запустите один раз после распаковки. ️
Запустите 2-download-models.bat. Он скачивает модели (минимально ~19 ГБ) с HuggingFace и сохраняет их в папку HuggingFaceHub в проекте. ️
Если появляются ошибки, такие как Error: no file named diffusion_pytorch_model.safetensors found, это означает, что файл модели загрузился с ошибкой. Повторите загрузку, предварительно удалив всё из папки HuggingFaceHub. Скрипт загрузки моделей работает довольно криво и готовьтесь к тому, что загрузка моделей отнимет у вас прилично времени.
Шаг 4: Ручное скачивание моделей
⚠️ Выполняйте этот шаг, если автоматическая загрузка через 2-download-models.bat не удалась или в терминале появилось сообщение об отсутствии файлов .safetensors или .bin.
Перейдите на страницы моделей на HuggingFace для ручной загрузки:
- [Hunyuan3D-2] (https://huggingface.co/tencent/Hunyuan3D-2) — основная модель. Скачайте папку с файлами .safetensors (например, hunyuan3d-dit-v2-0).
- [Hunyuan3D-2mini] (https://huggingface.co/tencent/Hunyuan3D-2mini) — версия для слабых систем (6 ГБ VRAM). Скачайте папку hunyuan3d-dit-v2-mini.
- [Hunyuan3D-2mv] (https://huggingface.co/tencent/Hunyuan3D-2mv) — для работы с несколькими ракурсами. Скачайте папку hunyuan3d-dit-v2-mv.
Или способ проще, установите huggingface-cli, если ещё не установлено:
cmd
pip install huggingface_hub ️
В PowerShell откройте папку проекта (например, G:\Hunyuan3D2) и выполните следующие команды, заменив C:\Users\Ваш_Пользователь на путь к вашей учетной записи:
huggingface-cli download tencent/Hunyuan3D-2 --local-dir C:\Users\Ваш_Пользователь.cache\huggingface\hub\Hunyuan3D-2
huggingface-cli download tencent/Hunyuan3D-2mini --local-dir C:\Users\Ваш_Пользователь.cache\huggingface\hub\Hunyuan3D-2mini
huggingface-cli download tencent/Hunyuan3D-2mv --local-dir C:\Users\Ваш_Пользователь.cache\huggingface\hub\Hunyuan3D-2mv
Куда скачиваются модели по умолчанию?
По умолчанию модели загружаются в папку C:\Users\Ваш_Пользователь.cache\huggingface\hub. Чтобы использовать их в проекте, нужно переместить файлы в папку проекта. Cкопируйте их в папку проекта (например, G:\Hunyuan3D2\HuggingFaceHub) с помощью команд:
xcopy C:\Users\Ваш_Пользователь.cache\huggingface\hub\Hunyuan3D-2* G:\Hunyuan3D2\HuggingFaceHub\Hunyuan3D-2\ /E /H /C /I
xcopy C:\Users\Ваш_Пользователь.cache\huggingface\hub\Hunyuan3D-2mini* G:\Hunyuan3D2\HuggingFaceHub\Hunyuan3D-2mini\ /E /H /C /I
xcopy C:\Users\Ваш_Пользователь.cache\huggingface\hub\Hunyuan3D-2mv* G:\Hunyuan3D2\HuggingFaceHub\Hunyuan3D-2mv\ /E /H /C /I
- Замените G:\Hunyuan3D2 на путь к вашей папке проекта.
- Убедитесь, что папка HuggingFaceHub существует в проекте, иначе создайте её вручную.
- Если путь отличается (например, другой диск), настройте команды соответственно.
Шаг 5: Запуск программы ️
Выберите подходящий скрипт в зависимости от вашей видеокарты:
- 3-start.bat — стандартный режим для создания 3D-меша из одного фото (6 ГБ+ видеопамяти).
- run-very_low_vram.bat — для слабых видеокарт (<8 ГБ, но минимум 6 ГБ).
- run-high_vram.bat — для мощных систем (24 ГБ+).
- 4-start-mv.bat — для нескольких ракурсов с Turbo-оптимизацией.
- run-mv-high_vram.bat — для нескольких ракурсов на мощных системах (24 ГБ+).
Запустите нужный скрипт, например, 3-start.bat для стандартного режима. ️
Дождитесь сообщения: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit).
Ошибки вроде EP Error: Can’t load TensorRT не критичны — программа переключится на CUDA.
Откройте браузер и перейдите на http://localhost:8080.
Загрузите фотографию объекта, например, вазы или фигурки. 3D-меш сохранится в папке Hunyuan3D-2\gradio_cache в формате .glb или .obj.
Дополнительные режимы:
Для нескольких ракурсов используйте 4-start-mv.bat или run-mv-high_vram.bat и загрузите до четырёх фотографий.
Для работы через API (например, для интеграции с другими приложениями, напр: Blender):
- 5-start-api-server.bat — API без текстур. 🌐
- 6-start-api-server-with-texture.bat — API с текстурами. 🌐
- 6-start-api-server-with-texture-dmc.bat — API с текстурами и оптимизацией DMC (для специфических сценариев). 🌐️
Для генерации из текста используйте run-with-text_to_3d.bat и введите описание, например, «керамическая ваза». ️
Шаг 6: Создание текстурированной модели
Требуется видеокарта с 8 ГБ+ памяти и Build Tools (Шаг 2.2). Пропустите, если вам достаточно MESH.
Закройте программу (CTRL+C в терминале).
Запустите 1-compile-install-texture-gen.bat. Этот скрипт компилирует модули для создания текстур. ️
Запустите 3-start.bat (или 4-start-mv.bat для нескольких ракурсов) и перейдите на http://localhost:8080. ️
Загрузите до четырёх фотографий (например, спереди и сзади для вазы). Текстурированная модель сохранится в Hunyuan3D-2\gradio_cache.
Шаг 7: Дополнительные возможности
Генерация из текста: Запустите run-with-text_to_3d.bat, чтобы создать 3D-модель по текстовому описанию, например, «керамическая ваза с синим узором». В этом режиме не стоит писать большой и сложный промпт, ограничьтесь простым описанием. ️
Обновление проекта: Используйте UPDATE.bat, чтобы скачать последние изменения из репозитория и обновить зависимости.
Возможные проблемы и решения ️
Отсутствуют файлы .safetensors или .bin: Вернитесь к Шагу 4. ❗
Ошибки “Type mismatch” (например, для UNet): Проверьте файлы в HuggingFaceHub и перезагрузите модели.
Программа тормозит: Обновите драйверы видеокарты (>550) или используйте run-very_low_vram.bat.
Советы
Используйте чёткие снимки с хорошим освещением. Для Hunyuan3D-2mv добавьте два или четыре ракурса, например, спереди и сзади для фигурки.
Логи в папке Hunyuan3D-2 помогут найти причину либо обратитесь за помощью в [сообщество на GitHub].
ComfyUI: Для продвинутых пользователей в [репозитории] есть инструкции по интеграции. ️
Выбор скрипта запуска: run-very_low_vram.bat для слабых систем, run-high_vram.bat для мощных, 4-start-mv.bat для нескольких ракурсов.
Теперь вы можете создавать 3D-модели из фотографий! Самый быстрый способ начать — скачать сборку с моего [Boosty]. Если же вы настроили проект вручную, попробуйте создать модель вазы, машинки или персонажа, а затем доработайте её в Blender или 3DS Max. Hunyuan3D-2-WinPortable открывает мир 3D-моделирования с помощью нейросетей. Если что-то не получается, загляните на [GitHub] за помощью и обновлениями проекта. Успехов в творчестве! И ждем версию 2.5!
Ну и конечно же, если вам понравилась эта статья, буду рад вашим подпискам, комментариям и лайкам. Недавно я запустил Discord-канал и постараюсь поддерживать его насколько возможно, там вы сможете не только следить за новостями, но и общаться, делиться опытом и приобретать новые знания о нейросетях. Чтобы всегда быть в курсе моих новых материалов, подписывайтесь на мой Boosty, Telegram-канал и страницу "ВКонтакте". Пока что нас немного, но я надеюсь, что с течением времени сообщество станет больше. Это станет отличной мотивацией для меня активно работать и над другими социальными сетями.