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/libs3. 推理步骤
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-large3.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 s5. Agent适配截图
5.1 Agent适配全过程截图
5.2 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 环境运行。