CANN/Hunyuan3D昇腾适配

在昇腾训练平台上适配Hunyuan3D 2.0 模型的推理

【免费下载链接】cann-recipes-spatial-intelligence本项目针对空间智能业务中的典型模型、加速算法，提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-spatial-intelligence

Hunyuan3D模型是腾讯混元系列在2025年推出的一款3D资产创作模型，用于生成带有高分辨率纹理贴图的高保真度3D模型，本项目旨在提供Hunyuan3D的NPU适配版本，方便用户能够在昇腾生态上直接使用Hunyuan3D。

此外，本样例基于Hunyuan3D模型在NPU进行了性能优化，目前texgen在2万平面mesh网格输入下，推理时间降至26秒。详细内容可至性能优化章节进行查看。

执行样例

环境准备

1. 本样例采用CANN 8.2.RC1。请从CANN软件包下载地址下载Ascend-cann-toolkit_${version}_linux-${arch}.run与Ascend-cann-kernels-${chip_type}_${version}_linux-${arch}.run软件包，并参考CANN安装文档进行安装。

   conda create -n hunyuan3d python==3.10.18 conda activate hunyuan3d

• 本样例的torch以及torch_npu版本为2.6，请从Ascend Extension for PyTorch插件下载torch与torch_npu安装包，同时指定decorator版本

  pip install torch==2.6.0 pip install torchvision==0.21.0 pip install torch-npu==2.6.0.post3 pip install decorator==5.2.1 pip install ninja

网络模型代码准备

• 本仓库依赖Hunyuan3D的开源仓库代码。

• 进入Hunyuan3D的官方仓库，下载Hunyuan3D模型网络结构代码

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

• 下载本仓库代码

  git clone https://gitcode.com/cann/cann-recipes-spatial-intelligence.git

• 将Hunyuan3D仓库的网络模型文件以非覆盖模式复制到本项目目录下。其中下方命令里的/path/to/Hunyuan3D-2/改为Hunyuan3D-2文件路径。

  cd cann-recipes-spatial-intelligence/models/Hunyuan3D cp -rn /path/to/Hunyuan3D-2/* ./

• 安装Python依赖

  pip install -r requirements.txt

• 编译第三方代码

  cd hy3dgen/texgen/differentiable_renderer python3 setup.py install

• 模型结构修改部分如下所示

  Hunyuan3D +--- hy3dgen +--- texgen +--- custom_rasterizer ==> custom_rasterizer in current depository #替换当前文件 +--- differentiable_renderer +--- mesh_render.py ==> differentiable_renderer/mesh_render.py #替换文件 +--- rasterizer.py #添加新文件 +--- minimal_demo_npu.py #添加新文件

权重模型

NPU环境支持Hunyuan3D模型列表，用户可根据需要下载蒸馏版本：

Hunyuan3D-2mv 系列

Hunyuan3D-2 系列

• 权重安装地址为base_dir+model_path，默认base_dir为~/.cache/hy3dgen/，如需修改base_dir，需将./hy3dgen/shapegen/utils.py中第97行和./hy3dgen/texgen/pipelines.py中第61行进行修改

  class Hunyuan3DPaintPipeline: @classmethod def from_pretrained(cls, model_path, subfolder='hunyuan3d-paint-v2-0-turbo'): original_model_path = model_path if not os.path.exists(model_path): # try local path base_dir = os.environ.get('HY3DGEN_MODELS', '~/.cache/hy3dgen/') model_path = os.path.expanduser(os.path.join(base_dir, model_path))

• 最后模型权重路径为

  base_dir+model_path +--- hunyuan3d-dit-v2-0 #单视角图像DIT模型 +--- hunyuan3d-dit-v2-mv #多视角图像DIT模型 +--- hunyuan3d-delight-v2-0 +--- hunyuan3d-paint-v2-0

执行推理

执行推理

由于本项目依靠 cann-recipes-spatial-intelligence 中的module所带的优化模块进行，因此在开始推理前，需要设置环境变量，执行如下指令

source set_env.sh

即可将module所带的优化模块加入环境变量中，之后执行

python minimal_demo_npu.py

minimal_demo_npu.py采用默认设置执行单图像推理，运行不同配置可参考以下脚本执行：

python minimal_demo_npu.py --model_path tencent/Hunyuan3D-2 --multiview --face_reduce --full_graph --multi_thread (--use_render_npu) --save_render

model_path选择模型路径，multiview设置是否采用多视角推理，face_reduce设置是否减少三角面片，full_graph设置是否采用图模式，multi_thread设置是否采用多线程并行执行光栅化，use_render_npu设置是否采用npu方式执行光栅化（不能与multi_thread共同使用），save_render设置是否复用光栅化结果。

推理步骤介绍

Hunyuan3D源码参考diffusers接口API，用于物体生成，包括Hunyuan3D-DiT和Hunyuan3D-Paint两个部分。

运行Hunyuan3D-DiT方式如下：

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

运行Hunyuan3D-Paint方式如下：

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

Hunyuan3D-DiT执行过程中，我们在NPU环境下提供多视角模型推理，具体方式如下：

from hy3dgen.texgen import Hunyuan3DPaintPipeline from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline from torch_npu.contrib import transfer_to_npu images = { "front": "assets/example_mv_images/1/front.png", "left": "assets/example_mv_images/1/left.png", "back": "assets/example_mv_images/1/back.png" } pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained( 'tencent/Hunyuan3D-2mv', subfolder='hunyuan3d-dit-v2-mv', variant='fp16' ) mesh = pipeline( image=images, num_inference_steps=50, octree_resolution=380, num_chunks=20000, generator=torch.manual_seed(12345), output_type='trimesh' )[0] pipeline = Hunyuan3DPaintPipeline.from_pretrained('tencent/Hunyuan3D-2') mesh = pipeline(mesh, image=list(image.values()))

Citation

@misc{lai2025hunyuan3d25highfidelity3d, title={Hunyuan3D 2.5: Towards High-Fidelity 3D Assets Generation with Ultimate Details}, author={Tencent Hunyuan3D Team}, year={2025}, eprint={2506.16504}, archivePrefix={arXiv}, primaryClass={cs.CV}, url={https://arxiv.org/abs/2506.16504}, } @misc{hunyuan3d22025tencent, title={Hunyuan3D 2.0: Scaling Diffusion Models for High Resolution Textured 3D Assets Generation}, author={Tencent Hunyuan3D Team}, year={2025}, eprint={2501.12202}, archivePrefix={arXiv}, primaryClass={cs.CV} } @misc{yang2024hunyuan3d, title={Hunyuan3D 1.0: A Unified Framework for Text-to-3D and Image-to-3D Generation}, author={Tencent Hunyuan3D Team}, year={2024}, eprint={2411.02293}, archivePrefix={arXiv}, primaryClass={cs.CV} }

【免费下载链接】cann-recipes-spatial-intelligence本项目针对空间智能业务中的典型模型、加速算法，提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-spatial-intelligence