Hunyuan3D-2.1

环境要求

• Python 3.10（README 实测版本）
• PyTorch 2.5.1 + cu124（NVIDIA CUDA 环境）
• 能执行 git clone / wget 的网络环境
• 具备 C++ 编译环境（README 要求编译自定义光栅化与渲染扩展）

安装与启动步骤

1. 1克隆项目代码

   把仓库拉到本地，后续所有相对路径命令都要在仓库根目录执行。

   git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1.git
   cd Hunyuan3D-2.1

   复制

2. 2安装 PyTorch

   按 README 指定的 cu124 源安装 2.5.1 版本的 torch 系列，避免版本不匹配。

   pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124

   复制

3. 3安装项目依赖

   在仓库根目录安装 requirements.txt 中的 Python 依赖，建议先用虚拟环境隔离。

   pip install -r requirements.txt

   复制

4. 4编译自定义光栅化

   进入 hy3dpaint/custom_rasterizer 以可编辑模式安装，完成后回到仓库根目录。

   cd hy3dpaint/custom_rasterizer
   pip install -e .
   cd ../..

   复制

5. 5编译可微渲染器

   执行官方编译脚本 build_mesh_painter.sh，编译失败通常是缺少 C++/CUDA 编译工具。

   cd hy3dpaint/DifferentiableRenderer
   bash compile_mesh_painter.sh
   cd ../..

   复制

6. 6下载超分权重

   下载 Real-ESRGAN 的 x4plus 权重到 hy3dpaint/ckpt 目录，供纹理阶段使用。

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

   复制

7. 7调用 Python API

   README 提供类 diffusers 的接口，需先把两个子目录加入 sys.path 再导入管线类。

   import sys
   sys.path.insert(0, './hy3dshape')
   sys.path.insert(0, './hy3dpaint')
   from textureGenPipeline import Hunyuan3DPaintPipeline, Hunyuan3DPaintConfig
   from hy3dshape.pipelines import Hunyuan3DDiTFlowMatchingPipeline

   复制

如何确认成功

在仓库根目录执行上述 Python 导入语句，无 ModuleNotFoundError 或编译报错即表示环境安装完成。

常见问题

注意事项

• 安装步骤必须在克隆后的仓库根目录执行，因为命令使用相对路径切换子目录。
• 建议在独立虚拟环境中安装，避免与已有 torch 版本冲突。
• 项目同时提供官网 https://3d.hunyuan.tencent.com 与 HuggingFace Demo，可先在线体验再本地部署。