Hunyuan3D-2 详细部署教程

1. 部署前必读：硬件需求与版本选择

Hunyuan3D-2 是腾讯混元团队开源的大规模 3D 资产生成系统，采用双阶段架构：先生成无纹理的几何模型（Hunyuan3D-DiT），再合成高分辨率纹理贴图（Hunyuan3D-Paint）。这种设计将形状和纹理生成的难度解耦，同时提供了灵活性。

1.1 硬件需求（关键）

模型版本 形状生成显存 纹理生成显存 适用场景
Hunyuan3D-2mini ~3-5 GB 需额外显存 低显存消费级 GPU
Hunyuan3D-2mv ~6 GB 需额外显存 多视图输入
Hunyuan3D-2 标准版 ~6 GB 总计 16 GB 高质量完整流程

📌 官方说明：形状生成需 6 GB VRAM，形状 + 纹理生成总共需 16 GB VRAM。测试显示，RTX 4070（12GB）运行 Mini 模型仅占用约 4 GB 显存，单次生成约 11.5 秒。

1.2 软件环境要求

组件 最低版本 推荐版本
操作系统 Windows 10 / macOS / Linux Windows 11
Python 3.10.0 3.10.9
CUDA 11.3 11.7 / 12.1
Visual Studio 2019 2022
GPU NVIDIA 6GB VRAM NVIDIA 12GB+ VRAM

⚠️ CUDA 兼容性说明：CUDA 版本限制来自 PyTorch 构建，与 NVIDIA 无关。

1.3 部署方式选择

方式 适用平台 难度 推荐度
Windows 整合包 Windows ⭐ ⭐⭐⭐⭐⭐
源码安装 全平台 ⭐⭐⭐⭐ ⭐⭐⭐
ComfyUI 集成 全平台 ⭐⭐ ⭐⭐⭐⭐

💡 重要提醒：Hunyuan3D-2 的源码安装涉及 C++ 扩展编译（custom_rasterizer 和 differentiable_renderer），这是最容易出错的环节，Linux 和 Windows 都有已知的编译兼容性问题。

2. Windows 整合包部署（最省心方案）

对于 Windows 用户，强烈建议使用社区整合包，它集成了显存优化（mmgp），避免了繁琐的编译过程。

2.1 方案一：YanWenKun 整合包（支持 2.0/2.1）

基本需求：

  • NVIDIA GPU，驱动版本 ≥576.57（2025 年 6 月后）
  • 生成几何：≥ 3 GB 显存
  • 生成纹理：≥ 6 GB 显存
  • 系统内存：≥ 24 GB

安装步骤：

  1. 根据 GPU 架构下载对应版本（CUDA 12.9 或 CUDA 12.6）
  2. 将两个分卷压缩包（.7z.001 和 .7z.002）放在同一目录
  3. 解压 .001 文件即可（.002 会自动处理）
  4. 解压路径要求：
    • 纯英文/数字，无空格
    • 路径尽量浅（如 C:\AI\HY3D2），避免 MAX_PATH 260 超长报错

启动：双击 启动.bat

📌 可选纹理支持：如需纹理生成，需安装 Visual Studio Build Tools 2022，安装时选择”桌面 C++ 开发”。

2.2 方案二：MackinationsAi 整合包

最低需求：

  • Windows 10/11
  • NVIDIA GPU，≥ 6GB VRAM
  • CUDA Toolkit 12.8（纹理生成用）
  • Visual Studio Build Tools 2022

推荐配置：8GB+ VRAM，24GB+ RAM

安装步骤：

  1. 下载 HY3D_v2_WinPortable_v0.1.3.7z 并解压
  2. 运行 run_build.bat（下载模型并完成安装）
  3. 根据显存选择启动脚本：
    • 高显存（24GB）：boot_HY3D_v2.bat
    • 低显存（4-6GB）：boot_low_vram_HY3D_v2.bat

访问：浏览器打开 http://127.0.0.1:7860

3. 源码安装（全平台）

3.1 安装 PyTorch

先安装 PyTorch，访问 pytorch.org 选择对应 CUDA 版本的命令。例如：

1
2
# CUDA 12.4 示例
pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124

3.2 克隆仓库并安装基础依赖

1
2
3
4
git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2
cd Hunyuan3D-2
pip install -r requirements.txt
pip install -e .

3.3 编译纹理生成依赖（关键步骤）

这是最容易出错的环节，需编译两个 C++ 扩展：

1
2
3
4
5
6
7
8
9
# 编译 custom_rasterizer
cd hy3dgen/texgen/custom_rasterizer
python3 setup.py install
cd ../../..

# 编译 differentiable_renderer
cd hy3dgen/texgen/differentiable_renderer
python3 setup.py install
cd ../../..

⚠️ Linux 已知问题与修复：在部分 Linux 发行版上，compile_mesh_painter.sh 编译出的 .so 文件命名不符合 Python 导入预期（mesh_processor.cpython-312-x86_64-linux-gnu.so），导致 Gradio 启动时仍报缺失 mesh_processor。修复方法：将生成的文件重命名为 mesh_processor.so。

⚠️ macOS 特别处理：M1/M2 芯片需指定 CMake 路径：

1
2
cd hy3dgen/texgen/custom_rasterizer
python setup.py install --cmake-prefix=$(brew --prefix)

3.4 运行 Gradio App

标准版（完整功能）：

1
python3 gradio_app.py --model_path tencent/Hunyuan3D-2 --subfolder hunyuan3d-dit-v2-0 --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode

Mini 版（低显存）：

1
python3 gradio_app.py --model_path tencent/Hunyuan3D-2mini --subfolder hunyuan3d-dit-v2-mini --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode

Turbo 加速版（推荐，速度更快）：

1
python3 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

3.5 启动 API 服务器

1
python api_server.py --host 0.0.0.0 --port 8080

测试请求：

1
2
3
4
5
img_b64_str=$(base64 -i assets/demo.png)
curl -X POST "http://localhost:8080/generate" \
     -H "Content-Type: application/json" \
     -d '{"image": "'"$img_b64_str"'"}' \
     -o test2.glb

4. ComfyUI 集成（推荐工作流用户）

ComfyUI 已将 Hunyuan3D-2 内置到模板中，无需额外安装 custom_node。

4.1 使用官方内置节点

在 ComfyUI 的 Templates 区域直接找到 Hunyuan3D-2 工作流。

4.2 旧版 custom_node 注意事项

如果使用 ComfyUI-Hunyuan-3D-2 custom_node：

  • 输入图片必须透明背景，否则生成方形面板

  • 如果 git 不支持 submodule，需手动克隆子仓库：

    1
    2
    3
    4
    cd ComfyUI/custom_nodes/ComfyUI-Hunyuan-3D-2/
    rm -rf Hunyuan3D-2 Hunyuan3D-2.1
    git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2
    git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1

  • v2.1 纹理修复：需手动下载 RealESRGAN 权重：

    1
    wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth -P ckpt

5. 模型选择指南

模型系列 模型名 参数量 特点
Hunyuan3D-2.1 DiT-v2-1 3.0B 最新，PBR 材质
Hunyuan3D-2mv DiT-v2-mv-Turbo 1.1B 多视图输入
Hunyuan3D-2mini DiT-v2-mini-Turbo 0.6B 低显存首选
Hunyuan3D-2 DiT-v2-0-Turbo 1.1B 标准版加速

📌 选型建议：显存有限（<8GB）选 Mini-Turbo，追求质量选标准版 Turbo，需要多视图输入选 mv 系列。

6. 常见问题排查

问题 原因 解决方案
No module named 'custom_rasterizer' C++ 扩展未编译或未安装 重新执行 python setup.py install
mesh_processor 缺失（Linux） .so 文件命名不匹配 重命名为 mesh_processor.so
Gradio 启动报 DLL load failed Windows 编译器版本不匹配 使用 VS2022，或改用整合包
纹理生成显存不足 16GB 需求未满足 使用 --low_vram_mode 或改用 Mini 模型
AMD GPU 无法运行 官方仅支持 NVIDIA CUDA 设置 device='cpu'（极慢），或使用 ROCm
pymeshlab 安装失败（Python 3.13） 3.13 版本尚无正式包 使用开发版 wheel，或降级到 3.10

7. 部署方式选择建议

你的情况 推荐方案
Windows 用户，不想折腾编译 YanWenKun 或 MackinationsAi 整合包
ComfyUI 用户 ComfyUI 内置模板（无需安装）
Linux 服务器，追求可控性 源码安装 + 注意 .so 重命名
显存 < 8GB Mini 模型 + 整合包低显存模式
需要多视图输入 Hunyuan3D-2mv 系列
想快速体验，不想本地部署 使用官方 Hunyuan3D Studio 网站

核心要点：Hunyuan3D-2 的最大门槛是 C++ 扩展编译。Windows 用户强烈建议使用整合包，Linux 用户需注意 mesh_processor.so 重命名问题。选择合适的模型版本（Mini / Turbo / 标准）是平衡质量与显存的关键。