Hunyuan3d-2.1推理指导

概述

Hunyuan3D是一个大规模3D生成系统，目标是从单张参考图像（或可选的手工网格）自动生成高保真几何形状和高分辨率纹理的3D模型。shape阶段主要用于生成几何形状模型，Paint阶段用于生成3D网格纹理。

一、准备运行环境

表 1 硬件配套表

配套	版本
cpu架构	x86_64
设备	A2 / A3

表 2 版本配套表

配套	版本	环境准备指导
Python	3.11.10	-
torch	2.1.0	-

1.1 获取CANN&MindIE安装包&环境准备

设备支持 Atlas 800I/800T A2(8*64G)推理设备：支持的卡数最小为1 Atlas 800I/800T A2(8*64G)
环境准备指导

1.2 CANN安装

# 增加软件包可执行权限，{version}表示软件版本号，{arch}表示CPU架构，{soc}表示昇腾AI处理器的版本。
chmod +x ./Ascend-cann-toolkit_{version}_linux-{arch}.run
chmod +x ./Ascend-cann-kernels-{soc}_{version}_linux.run
chmod +x ./Ascend-cann-nnal_{version}_linux-{arch}.run  (若使用稀疏FA)
# 校验软件包安装文件的一致性和完整性
./Ascend-cann-toolkit_{version}_linux-{arch}.run --check
./Ascend-cann-kernels-{soc}_{version}_linux.run --check
./Ascend-cann-nnal{version}_linux-{arch}.run --check  (若使用稀疏FA)
# 安装
./Ascend-cann-toolkit_{version}_linux-{arch}.run --install
./Ascend-cann-kernels-{soc}_{version}_linux.run --install
./Ascend-cann-nnal{version}_linux-{arch}.run --torch_atb --install  (若使用稀疏FA)

# 设置环境变量
source /usr/local/Ascend/ascend-toolkit/set_env.sh
source /usr/local/Ascend/nnal/atb/set_env.sh

1.3 MindIE安装

# 增加软件包可执行权限，{version}表示软件版本号，{arch}表示CPU架构。
chmod +x ./Ascend-mindie_${version}_linux-${arch}.run
./Ascend-mindie_${version}_linux-${arch}.run --check

# 方式一：默认路径安装
./Ascend-mindie_${version}_linux-${arch}.run --install
# 设置环境变量
cd /usr/local/Ascend/mindie && source set_env.sh

# 方式二：指定路径安装
./Ascend-mindie_${version}_linux-${arch}.run --install-path=${AieInstallPath}
# 设置环境变量
cd ${AieInstallPath}/mindie && source set_env.sh

1.4 Torch_npu安装

下载 pytorch_v{pytorchversion}_py{pythonversion}.tar.gz

tar -xzvf pytorch_v{pytorchversion}_py{pythonversion}.tar.gz
# 解压后，会有whl包
pip install torch_npu-{pytorchversion}.xxxx.{arch}.whl

1.5 gcc、g++安装

# 若环境镜像中没有gcc、g++，请用户自行安装
yum install gcc
yum install g++

# 导入头文件路径
export CPLUS_INCLUDE_PATH=/usr/include/c++/12/:/usr/include/c++/12/aarch64-openEuler-linux/:$CPLUS_INCLUDE_PATH

注：若使用openeuler镜像，需要配置gcc、g++环境，否则会导致fatal error: 'stdio.h' file not found

1.6 OpenGL动态链接库安装

yum install libGL
yum install libXrender
yum install libXi
yum install libxkbcommon
yum install libSM

注：若使用openeuler镜像，需要配置OpenGL环境，否则会导致ImportError: xxx.so.1: cannot open shared object file: No such file or directory

二、权重 & 代码下载

2.1 权重及配置文件说明

权重下载

Huggingface

模型	链接
Hunyuan3D-2.1	🤗huggingface

Modelers

模型	链接
Hunyuan3D-2.1	Modelers

   mkdir ckpts
   cd ckpts
   hf download tencent/Hunyuan3D-2.1

2.2 下载本仓库代码 & 安装依赖

   git clone https://modelers.cn/MindIE/Hunyuan3D-2.1.git
   pip3 install -r requirements.txt

2.3 安装渲染依赖 & 其他权重

安装渲染依赖

cd hy3dpaint/custom_rasterizer
pip install -e .
cd ../..
cd hy3dpaint/DifferentiableRenderer
bash compile_mesh_painter.sh
cd ../..

下载RealESRGAN权重

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

下载 dinov2-giant 权重

cd ckpts
hf download facebook/dinov2-giant

2.4 代码修改

修改hunyuan3d-paintpbr-v2-1权重文件/....../tencent/Hunyuan3D-2.1/hunyuan3d-paintpbr-v2-1/unet/attn_processor.py中的AttnCore.process_attention_base函数

原本：

# Apply RoPE if provided
if apply_rope_fn is not None:
    query, key = apply_rope_fn(query, key, head_dim, **kwargs)

# Compute attention
hidden_states = F.scaled_dot_product_attention(
    query, key, value, attn_mask=attention_mask, dropout_p=0.0, is_causal=False
)

现在：

# Apply RoPE if provided
if apply_rope_fn is not None:
    query, key = apply_rope_fn(query, key, head_dim, **kwargs)

if value.shape[-1]>key.shape[-1]:
    pad_num = value.shape[-1] - key.shape[-1]
    query = torch.nn.functional.pad(query, (0,pad_num), value=0)
    key = torch.nn.functional.pad(key, (0,pad_num), value=0)

# Compute attention
hidden_states = F.scaled_dot_product_attention(
    query, key, value, attn_mask=attention_mask, dropout_p=0.0, is_causal=False
)

修改hunyuan3d-paintpbr-v2-1权重文件/....../tencent/Hunyuan3D-2.1/hunyuan3d-paintpbr-v2-1/unet/attn_processor.py中SelfAttnProcessor2_0.process_single函数

原本：

# Device management (if needed)
if multiple_devices:
    device = torch.device("cuda:0") if token == "albedo" else torch.device("cuda:1")

现在：

# Device management (if needed)
if multiple_devices:
    device = torch.device("cuda") if token == "albedo" else torch.device("cuda")

修改hunyuan3d-paintpbr-v2-1权重文件/....../tencent/Hunyuan3D-2.1/hunyuan3d-paintpbr-v2-1/unet/attn_processor.py中SelfAttnProcessor2_0.__call__函数

原本：

# Process each PBR setting
results = []
for token, pbr_hs in zip(self.pbr_setting, pbr_hidden_states):
    processed_hs = rearrange(pbr_hs, "b n_pbrs n l c -> (b n_pbrs n) l c").to("cuda:0")
    result = self.process_single(attn, processed_hs, None, attention_mask, temb, token, False)
    results.append(result)

现在：

# Process each PBR setting
results = []
for token, pbr_hs in zip(self.pbr_setting, pbr_hidden_states):
    processed_hs = rearrange(pbr_hs, "b n_pbrs n l c -> (b n_pbrs n) l c").to("cuda")
    result = self.process_single(attn, processed_hs, None, attention_mask, temb, token, False)
    results.append(result)

三、Hunyuan3D-2.1使用

3.1 图生3D几何形状+纹理贴图

export HY3DGEN_MODELS = "/……/ckpts/"
export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True"
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3
torchrun \
  --nproc_per_node=4 \
  --master_port=29400 \
  demo.py \
    --use_attentioncache \
    --use_cfg_parallel \
    --start_step 15\
    --attentioncache_interval 5 \
    --end_step 45

参数说明：

HY3DGEN_MODELS：模型权重路径，此处假设权重路径为：/.../ckpts/tencent/Hunyuan3D-2.1
ASCEND_RT_VISIBLE_DEVICES=0：设备ID。
nproc_per_node=4：4卡推理，可设置其他卡数。
use_attentioncache：启用dit注意力缓存计算
use_cfg_parallel：启用cfg并行
start_step：注意力缓存开始步
attentioncache_interval：注意力缓存间隔步。
end_step：注意力缓存停止步

3.2 图生3D几何形状（shape阶段）

# cd hy3dshape:
export HY3DGEN_MODELS="/.../ckpts/" 
export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True"
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3
torchrun \
  --nproc_per_node=4 \
  --master_port=29400 \
  minimal_demo.py \
    --use_attentioncache \
    --use_cfg_parallel \
    --start_step 15\
    --attentioncache_interval 5 \
    --end_step 45

参数说明：

HY3DGEN_MODELS：模型权重路径，此处假设权重路径为：/.../ckpts/tencent/Hunyuan3D-2.1
ASCEND_RT_VISIBLE_DEVICES=0,1,2,3：设备ID。
use_attentioncache：启用dit注意力缓存计算
use_cfg_parallel：启用cfg并行
start_step：注意力缓存开始步
attentioncache_interval：注意力缓存间隔步。
end_step：注意力缓存停止步

3.3 3D形状生成纹理贴图（paint阶段）

# cd hy3dpaint:
python3 demo.py

四、推理结果参考

800T A3 2卡

模型	阶段	E2E耗时
Hunyuan3D-2.1	shape	9.1s
Hunyuan3D-2.1	paint	73.9s

声明

本代码仓提到的数据集和模型仅作为示例，这些数据集和模型仅供您用于非商业目的，如您使用这些数据集和模型来完成示例，请您特别注意应遵守对应数据集和模型的License，如您因使用数据集或模型而产生侵权纠纷，华为不承担任何责任。
如您在使用本代码仓的过程中，发现任何问题（包括但不限于功能问题、合规问题），请在本代码仓提交issue，我们将及时审视并解答。

Hunyuan3d-2.1推理指导

概述

一、准备运行环境

表 1 硬件配套表

配套	版本
cpu架构	x86_64
设备	A2 / A3

表 2 版本配套表

配套	版本	环境准备指导
Python	3.11.10	-
torch	2.1.0	-

1.1 获取CANN&MindIE安装包&环境准备

设备支持 Atlas 800I/800T A2(8*64G)推理设备：支持的卡数最小为1 Atlas 800I/800T A2(8*64G)
环境准备指导

1.2 CANN安装

# 增加软件包可执行权限，{version}表示软件版本号，{arch}表示CPU架构，{soc}表示昇腾AI处理器的版本。
chmod +x ./Ascend-cann-toolkit_{version}_linux-{arch}.run
chmod +x ./Ascend-cann-kernels-{soc}_{version}_linux.run
chmod +x ./Ascend-cann-nnal_{version}_linux-{arch}.run  (若使用稀疏FA)
# 校验软件包安装文件的一致性和完整性
./Ascend-cann-toolkit_{version}_linux-{arch}.run --check
./Ascend-cann-kernels-{soc}_{version}_linux.run --check
./Ascend-cann-nnal{version}_linux-{arch}.run --check  (若使用稀疏FA)
# 安装
./Ascend-cann-toolkit_{version}_linux-{arch}.run --install
./Ascend-cann-kernels-{soc}_{version}_linux.run --install
./Ascend-cann-nnal{version}_linux-{arch}.run --torch_atb --install  (若使用稀疏FA)

# 设置环境变量
source /usr/local/Ascend/ascend-toolkit/set_env.sh
source /usr/local/Ascend/nnal/atb/set_env.sh

1.3 MindIE安装

# 增加软件包可执行权限，{version}表示软件版本号，{arch}表示CPU架构。
chmod +x ./Ascend-mindie_${version}_linux-${arch}.run
./Ascend-mindie_${version}_linux-${arch}.run --check

# 方式一：默认路径安装
./Ascend-mindie_${version}_linux-${arch}.run --install
# 设置环境变量
cd /usr/local/Ascend/mindie && source set_env.sh

# 方式二：指定路径安装
./Ascend-mindie_${version}_linux-${arch}.run --install-path=${AieInstallPath}
# 设置环境变量
cd ${AieInstallPath}/mindie && source set_env.sh

1.4 Torch_npu安装

下载 pytorch_v{pytorchversion}_py{pythonversion}.tar.gz

tar -xzvf pytorch_v{pytorchversion}_py{pythonversion}.tar.gz
# 解压后，会有whl包
pip install torch_npu-{pytorchversion}.xxxx.{arch}.whl

1.5 gcc、g++安装

# 若环境镜像中没有gcc、g++，请用户自行安装
yum install gcc
yum install g++

# 导入头文件路径
export CPLUS_INCLUDE_PATH=/usr/include/c++/12/:/usr/include/c++/12/aarch64-openEuler-linux/:$CPLUS_INCLUDE_PATH

注：若使用openeuler镜像，需要配置gcc、g++环境，否则会导致fatal error: 'stdio.h' file not found

1.6 OpenGL动态链接库安装

yum install libGL
yum install libXrender
yum install libXi
yum install libxkbcommon
yum install libSM

注：若使用openeuler镜像，需要配置OpenGL环境，否则会导致ImportError: xxx.so.1: cannot open shared object file: No such file or directory

二、权重 & 代码下载

2.1 权重及配置文件说明

权重下载

Huggingface

模型	链接
Hunyuan3D-2.1	🤗huggingface

Modelers

模型	链接
Hunyuan3D-2.1	Modelers

   mkdir ckpts
   cd ckpts
   hf download tencent/Hunyuan3D-2.1

2.2 下载本仓库代码 & 安装依赖

   git clone https://modelers.cn/MindIE/Hunyuan3D-2.1.git
   pip3 install -r requirements.txt

2.3 安装渲染依赖 & 其他权重

安装渲染依赖

cd hy3dpaint/custom_rasterizer
pip install -e .
cd ../..
cd hy3dpaint/DifferentiableRenderer
bash compile_mesh_painter.sh
cd ../..

下载RealESRGAN权重

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

下载 dinov2-giant 权重

cd ckpts
hf download facebook/dinov2-giant

2.4 代码修改

修改hunyuan3d-paintpbr-v2-1权重文件/....../tencent/Hunyuan3D-2.1/hunyuan3d-paintpbr-v2-1/unet/attn_processor.py中的AttnCore.process_attention_base函数

原本：

# Apply RoPE if provided
if apply_rope_fn is not None:
    query, key = apply_rope_fn(query, key, head_dim, **kwargs)

# Compute attention
hidden_states = F.scaled_dot_product_attention(
    query, key, value, attn_mask=attention_mask, dropout_p=0.0, is_causal=False
)

现在：

# Apply RoPE if provided
if apply_rope_fn is not None:
    query, key = apply_rope_fn(query, key, head_dim, **kwargs)

if value.shape[-1]>key.shape[-1]:
    pad_num = value.shape[-1] - key.shape[-1]
    query = torch.nn.functional.pad(query, (0,pad_num), value=0)
    key = torch.nn.functional.pad(key, (0,pad_num), value=0)

# Compute attention
hidden_states = F.scaled_dot_product_attention(
    query, key, value, attn_mask=attention_mask, dropout_p=0.0, is_causal=False
)

修改hunyuan3d-paintpbr-v2-1权重文件/....../tencent/Hunyuan3D-2.1/hunyuan3d-paintpbr-v2-1/unet/attn_processor.py中SelfAttnProcessor2_0.process_single函数

原本：

# Device management (if needed)
if multiple_devices:
    device = torch.device("cuda:0") if token == "albedo" else torch.device("cuda:1")

现在：

# Device management (if needed)
if multiple_devices:
    device = torch.device("cuda") if token == "albedo" else torch.device("cuda")

修改hunyuan3d-paintpbr-v2-1权重文件/....../tencent/Hunyuan3D-2.1/hunyuan3d-paintpbr-v2-1/unet/attn_processor.py中SelfAttnProcessor2_0.__call__函数

原本：

# Process each PBR setting
results = []
for token, pbr_hs in zip(self.pbr_setting, pbr_hidden_states):
    processed_hs = rearrange(pbr_hs, "b n_pbrs n l c -> (b n_pbrs n) l c").to("cuda:0")
    result = self.process_single(attn, processed_hs, None, attention_mask, temb, token, False)
    results.append(result)

现在：

# Process each PBR setting
results = []
for token, pbr_hs in zip(self.pbr_setting, pbr_hidden_states):
    processed_hs = rearrange(pbr_hs, "b n_pbrs n l c -> (b n_pbrs n) l c").to("cuda")
    result = self.process_single(attn, processed_hs, None, attention_mask, temb, token, False)
    results.append(result)

三、Hunyuan3D-2.1使用

3.1 图生3D几何形状+纹理贴图

export HY3DGEN_MODELS = "/……/ckpts/"
export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True"
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3
torchrun \
  --nproc_per_node=4 \
  --master_port=29400 \
  demo.py \
    --use_attentioncache \
    --use_cfg_parallel \
    --start_step 15\
    --attentioncache_interval 5 \
    --end_step 45

参数说明：

HY3DGEN_MODELS：模型权重路径，此处假设权重路径为：/.../ckpts/tencent/Hunyuan3D-2.1
ASCEND_RT_VISIBLE_DEVICES=0：设备ID。
nproc_per_node=4：4卡推理，可设置其他卡数。
use_attentioncache：启用dit注意力缓存计算
use_cfg_parallel：启用cfg并行
start_step：注意力缓存开始步
attentioncache_interval：注意力缓存间隔步。
end_step：注意力缓存停止步

3.2 图生3D几何形状（shape阶段）

# cd hy3dshape:
export HY3DGEN_MODELS="/.../ckpts/" 
export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True"
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3
torchrun \
  --nproc_per_node=4 \
  --master_port=29400 \
  minimal_demo.py \
    --use_attentioncache \
    --use_cfg_parallel \
    --start_step 15\
    --attentioncache_interval 5 \
    --end_step 45

参数说明：

HY3DGEN_MODELS：模型权重路径，此处假设权重路径为：/.../ckpts/tencent/Hunyuan3D-2.1
ASCEND_RT_VISIBLE_DEVICES=0,1,2,3：设备ID。
use_attentioncache：启用dit注意力缓存计算
use_cfg_parallel：启用cfg并行
start_step：注意力缓存开始步
attentioncache_interval：注意力缓存间隔步。
end_step：注意力缓存停止步

3.3 3D形状生成纹理贴图（paint阶段）

# cd hy3dpaint:
python3 demo.py

四、推理结果参考

800T A3 2卡

模型	阶段	E2E耗时
Hunyuan3D-2.1	shape	9.1s
Hunyuan3D-2.1	paint	73.9s

声明

本代码仓提到的数据集和模型仅作为示例，这些数据集和模型仅供您用于非商业目的，如您使用这些数据集和模型来完成示例，请您特别注意应遵守对应数据集和模型的License，如您因使用数据集或模型而产生侵权纠纷，华为不承担任何责任。
如您在使用本代码仓的过程中，发现任何问题（包括但不限于功能问题、合规问题），请在本代码仓提交issue，我们将及时审视并解答。