TRELLIS-image-large 昇腾NPU部署文档

1. 模型简介

模型名称： TRELLIS-image-large（microsoft/TRELLIS-image-large）模型链接： https://ai.gitcode.com/hf_mirrors/microsoft/TRELLIS-image-large 模型描述： TRELLIS 是微软提出的统一结构化潜变量（Structured LATent, SLAT）3D生成大模型，支持从单张图像生成高质量 3D 资产（可导出 Gaussian Splatting / Radiance Field / Mesh 三种表示）。其图像到3D流程为：DINOv2 编码输入图像作为条件 → 稀疏结构流模型（Sparse Structure Flow，DiT-L）经流匹配采样生成 64³ 体素占据结构（16³×8 潜变量）→ 结构化潜变量流模型在激活体素上生成外观细节 → 由对应解码器输出目标表示。模型架构：稀疏结构扩散采用 24 层 DiT Transformer（model_channels=1024、16 头、qk RMSNorm、APE 位置编码、AdaLN 调制），配 Conv3D VAE（16³ latent ↔ 64³ 占据场）；图像条件编码器为 DINOv2 ViT-L/14-reg；采样器为 FlowEuler + CFG Interval（cfg_strength=5.0, interval=[0.5,1.0]）。参数规模：稀疏结构流模型约 1.1B（fp16 约 1.13GB），全流程合计约 2.4B 参数（约 3.1GB fp16 权重）

2. 环境依赖

依赖项	版本要求	说明
Python	>= 3.10	推荐 3.11
torch / torch_npu	2.1.0+	NPU 上需安装 torch_npu
trellis / dinov2 / utils3d	官方源码包	随 libs 目录分发（inference.py 自动注入 sys.path）
transformers	>= 4.40	trellis.pipelines 导入所需
rembg / onnxruntime	最新版	trellis 图像预处理模块导入所需
safetensors / easydict / einops	最新版	权重加载与模型组件依赖
scikit-learn / open3d	最新版	aarch64 需预加载 libgomp/libGLdispatch（脚本已内置处理）
Pillow / opencv-python-headless	最新版	示例图与结果可视化
昇腾驱动	CANN 8.0.RC2+	推荐最新版

安装命令：

pip install --target /mnt/workspace/TRELLIS-image-large/libs -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
# trellis/dinov2 官方代码包及 DINOv2 权重已随仓库预置到 /mnt/workspace/TRELLIS-image-large/libs

3. 推理步骤

3.1 环境准备

# 检查 NPU 设备
npu-smi info
# 权重已就位（ckpts/ 下含稀疏结构与 SLAT 全部组件权重）
ls /home/developer/models/TRELLIS-image-large/ckpts/

3.2 运行推理

PYTHONPATH=/mnt/workspace/TRELLIS-image-large/libs python3 inference.py --model_path /home/developer/models/TRELLIS-image-large

3.3 推理参数说明

参数	类型	默认值	说明
--model_path	str	/home/developer/models/TRELLIS-image-large	本地权重目录
--device	str	自动（npu > cuda > cpu）	推理设备
--steps	int	12	流匹配采样步数（官方默认25，实测效率取12）
--cfg_strength	float	5.0	无分类器引导强度
--output	str	assets/model_result.png	稀疏结构三视图结果图保存路径

4. 测试样例及输出结果

样例 1：内置合成球体样例（assets/sample_input.png）

输入：

python3 inference.py --model_path /home/developer/models/TRELLIS-image-large

输出：

[INFO] device = npu
[INFO] 模型加载完成 load_time=45.31s (SS-DiT-L 1.1B参数 + SS-VAE解码器 + DINOv2-ViT-L/14图像条件编码器)
[INFO] 推理完成 耗时/elapsed: 180.52s (steps=12, cfg=5.0, device=npu)
[INFO] 稀疏结构: 体素网格 16^3 latent -> 占据体素数=14624
[RESULT] status=ok device=npu voxels=14624 耗时/elapsed: 180.52s

说明：脚本完成"图像条件编码 → 稀疏结构流匹配采样 → VAE 解码占据场"完整链路，输出 64³ 占据体素统计与三视图投影结果图；SLAT 外观生成与网格/Gaussian 导出依赖 spconv/nvdiffrast 等 CUDA 专用算子，暂不在 NPU 上执行。

样例 2：调整采样步数

输入：

python3 inference.py --model_path /home/developer/models/TRELLIS-image-large --steps 25

输出：

[INFO] 推理完成 耗时/elapsed: xxx s (steps=25, cfg=5.0, device=npu)
[RESULT] status=ok device=npu voxels=xxxxx 耗时/elapsed: xxx s

5. Agent适配截图

5.1 Agent适配全过程截图

Agent 适配流程

5.2 NPU设备调用截图

NPU 设备调用

5.3 模型适配结果截图

6. 注意事项

推理脚本通过 torch_npu 调用 NPU，设备自动选择 npu > cuda > cpu；
注意力后端强制 sdpa（环境变量 ATTN_BACKEND=sdpa），NPU 不支持 flash_attn/xformers；计算全程 float32（加载后统一 convert_to_fp32），无 float64 算子；
DINOv2 条件编码器以 source='local' 方式从 libs 本地源码加载，权重读取本地 dinov2_vitl14_reg4_pretrain.pth，全程离线；
kaolin 仅被 flexicubes 测试断言引用，仓库内置 stubs/kaolin 轻量桩替代，避免安装 NVIDIA kaolin 编译包；aarch64 下 sklearn/open3d 的 static TLS 问题通过 ctypes 预加载 libgomp/libGLdispatch 解决（脚本已内置）；
共享环境 torchaudio 与 torch 版本不匹配会导致 transformers 导入失败，已在 libs 内隔离安装匹配版本 torchaudio==2.7.1；
输出为稀疏结构阶段的 64³ 占据体素（数量与包围盒统计）与三视图投影 PNG；如需完整纹理 3D 资产导出请参考官方 TRELLIS 仓库在 GPU 环境运行。

TRELLIS-image-large 昇腾NPU部署文档

1. 模型简介

模型名称： TRELLIS-image-large（microsoft/TRELLIS-image-large）模型链接： https://ai.gitcode.com/hf_mirrors/microsoft/TRELLIS-image-large 模型描述： TRELLIS 是微软提出的统一结构化潜变量（Structured LATent, SLAT）3D生成大模型，支持从单张图像生成高质量 3D 资产（可导出 Gaussian Splatting / Radiance Field / Mesh 三种表示）。其图像到3D流程为：DINOv2 编码输入图像作为条件 → 稀疏结构流模型（Sparse Structure Flow，DiT-L）经流匹配采样生成 64³ 体素占据结构（16³×8 潜变量）→ 结构化潜变量流模型在激活体素上生成外观细节 → 由对应解码器输出目标表示。模型架构：稀疏结构扩散采用 24 层 DiT Transformer（model_channels=1024、16 头、qk RMSNorm、APE 位置编码、AdaLN 调制），配 Conv3D VAE（16³ latent ↔ 64³ 占据场）；图像条件编码器为 DINOv2 ViT-L/14-reg；采样器为 FlowEuler + CFG Interval（cfg_strength=5.0, interval=[0.5,1.0]）。参数规模：稀疏结构流模型约 1.1B（fp16 约 1.13GB），全流程合计约 2.4B 参数（约 3.1GB fp16 权重）

2. 环境依赖

依赖项	版本要求	说明
Python	>= 3.10	推荐 3.11
torch / torch_npu	2.1.0+	NPU 上需安装 torch_npu
trellis / dinov2 / utils3d	官方源码包	随 libs 目录分发（inference.py 自动注入 sys.path）
transformers	>= 4.40	trellis.pipelines 导入所需
rembg / onnxruntime	最新版	trellis 图像预处理模块导入所需
safetensors / easydict / einops	最新版	权重加载与模型组件依赖
scikit-learn / open3d	最新版	aarch64 需预加载 libgomp/libGLdispatch（脚本已内置处理）
Pillow / opencv-python-headless	最新版	示例图与结果可视化
昇腾驱动	CANN 8.0.RC2+	推荐最新版

安装命令：

pip install --target /mnt/workspace/TRELLIS-image-large/libs -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
# trellis/dinov2 官方代码包及 DINOv2 权重已随仓库预置到 /mnt/workspace/TRELLIS-image-large/libs

3. 推理步骤

3.1 环境准备

# 检查 NPU 设备
npu-smi info
# 权重已就位（ckpts/ 下含稀疏结构与 SLAT 全部组件权重）
ls /home/developer/models/TRELLIS-image-large/ckpts/

3.2 运行推理

PYTHONPATH=/mnt/workspace/TRELLIS-image-large/libs python3 inference.py --model_path /home/developer/models/TRELLIS-image-large

3.3 推理参数说明

参数	类型	默认值	说明
--model_path	str	/home/developer/models/TRELLIS-image-large	本地权重目录
--device	str	自动（npu > cuda > cpu）	推理设备
--steps	int	12	流匹配采样步数（官方默认25，实测效率取12）
--cfg_strength	float	5.0	无分类器引导强度
--output	str	assets/model_result.png	稀疏结构三视图结果图保存路径

4. 测试样例及输出结果

样例 1：内置合成球体样例（assets/sample_input.png）

输入：

python3 inference.py --model_path /home/developer/models/TRELLIS-image-large

输出：

[INFO] device = npu
[INFO] 模型加载完成 load_time=45.31s (SS-DiT-L 1.1B参数 + SS-VAE解码器 + DINOv2-ViT-L/14图像条件编码器)
[INFO] 推理完成 耗时/elapsed: 180.52s (steps=12, cfg=5.0, device=npu)
[INFO] 稀疏结构: 体素网格 16^3 latent -> 占据体素数=14624
[RESULT] status=ok device=npu voxels=14624 耗时/elapsed: 180.52s

说明：脚本完成"图像条件编码 → 稀疏结构流匹配采样 → VAE 解码占据场"完整链路，输出 64³ 占据体素统计与三视图投影结果图；SLAT 外观生成与网格/Gaussian 导出依赖 spconv/nvdiffrast 等 CUDA 专用算子，暂不在 NPU 上执行。

样例 2：调整采样步数

输入：

python3 inference.py --model_path /home/developer/models/TRELLIS-image-large --steps 25

输出：

[INFO] 推理完成 耗时/elapsed: xxx s (steps=25, cfg=5.0, device=npu)
[RESULT] status=ok device=npu voxels=xxxxx 耗时/elapsed: xxx s

5. Agent适配截图

5.1 Agent适配全过程截图

Agent 适配流程

5.2 NPU设备调用截图

NPU 设备调用

5.3 模型适配结果截图

6. 注意事项

推理脚本通过 torch_npu 调用 NPU，设备自动选择 npu > cuda > cpu；
注意力后端强制 sdpa（环境变量 ATTN_BACKEND=sdpa），NPU 不支持 flash_attn/xformers；计算全程 float32（加载后统一 convert_to_fp32），无 float64 算子；
DINOv2 条件编码器以 source='local' 方式从 libs 本地源码加载，权重读取本地 dinov2_vitl14_reg4_pretrain.pth，全程离线；
kaolin 仅被 flexicubes 测试断言引用，仓库内置 stubs/kaolin 轻量桩替代，避免安装 NVIDIA kaolin 编译包；aarch64 下 sklearn/open3d 的 static TLS 问题通过 ctypes 预加载 libgomp/libGLdispatch 解决（脚本已内置）；
共享环境 torchaudio 与 torch 版本不匹配会导致 transformers 导入失败，已在 libs 内隔离安装匹配版本 torchaudio==2.7.1；
输出为稀疏结构阶段的 64³ 占据体素（数量与包围盒统计）与三视图投影 PNG；如需完整纹理 3D 资产导出请参考官方 TRELLIS 仓库在 GPU 环境运行。