Y
YYPGD/TRELLIS-image-large
模型介绍
文件和版本
Pull Requests
讨论
分析

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_npu2.1.0+NPU 上需安装 torch_npu
trellis / dinov2 / utils3d官方源码包随 libs 目录分发(inference.py 自动注入 sys.path)
transformers>= 4.40trellis.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_pathstr/home/developer/models/TRELLIS-image-large本地权重目录
--devicestr自动(npu > cuda > cpu)推理设备
--stepsint12流匹配采样步数(官方默认25,实测效率取12)
--cfg_strengthfloat5.0无分类器引导强度
--outputstrassets/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 环境运行。