Hunyuan3D-2

环境要求

• Python 环境（README 未指定具体版本）
• PyTorch，需按 PyTorch 官方网站指引安装
• 可正常使用 pip 的终端环境
• 本地项目代码目录（需能访问 assets/demo.png 等示例图片）

安装与启动步骤

1. 1获取项目代码

   从 GitHub 仓库 Tencent-Hunyuan/Hunyuan3D-2 获取源码到本地目录，README 未给出具体克隆命令，请自行在仓库页面下载或克隆。

2. 2安装 PyTorch

   README 要求先通过 PyTorch 官方网站安装 PyTorch，请按官网指引选择与自己 CUDA/系统匹配的版本安装。

3. 3安装项目依赖

   在项目根目录执行，安装 requirements.txt 中列出的其余依赖包。

   pip install -r requirements.txt

   复制

4. 4安装项目本体

   以可编辑模式安装 hy3dgen 包，安装 Python 导入 hy3dgen.shapegen 等模块才不会报错。

   pip install -e .

   复制

5. 5运行形状生成

   用 diffusers 风格的 API 加载 Hunyuan3D-2 权重，输入图片路径生成网格，返回值是 trimesh 对象。

   from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
   
   pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')
   mesh = pipeline(image='assets/demo.png')[0]

   复制

6. 6运行纹理生成

   导入 Hunyuan3D-Paint 纹理合成管线（README 仅给出导入语句），需与形状生成模型配合使用。

   from hy3dgen.texgen import Hunyuan3DPaintPipeline
   from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline

   复制

关键配置

如何确认成功

执行 shapegen 代码无报错并返回 trimesh 对象，即表示形状生成流程可用；该对象可再保存为 glb/obj 等格式。

常见问题

注意事项

• README 仅提供本地 pip 安装方式，未给出 Docker 镜像或一键启动脚本命令，请勿照搬网上的 docker run 参数。
• README 未指定 Python 与 CUDA 版本要求，建议先确认本机 GPU 与 PyTorch 版本兼容后再装依赖。
• 运行示例需准备图片文件，README 示例使用仓库内的 assets/demo.png，换成自己的图片时请写真实路径。
• 模型权重通过 from_pretrained 加载，首次运行需要能访问模型托管地址，网络受限时可能失败。