g
gcw_coj3XaOd/microsoft_TRELLIS-image-large
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

TRELLIS-image-large - 昇腾 NPU 推理部署

1. 模型简介

模型名称: microsoft/TRELLIS-image-large

模型链接: HuggingFace

AtomGit 镜像: AtomGit

模型描述: TRELLIS 是一个大规模图像到3D生成模型,采用多阶段流水线架构:稀疏结构生成(DiT扩散 transformer)→ 结构化潜变量生成(DiT扩散 transformer)→ 3D渲染(Gaussian Splatting / 辐射场 / 网格解码器)。图像条件通过 DINOv2 ViT-L/14 提取特征。

论文: Structured 3D Latents for Scalable and Versatile 3D Generation (arXiv:2412.01506)

项目页: https://trellis3d.github.io/

代码: https://github.com/microsoft/TRELLIS

模型架构: VAE (稀疏3D ConvNet) + DiT (Diffusion Transformer) + 3D Decoder (Swin Transformer + Gaussian/Mesh/RF decoder)

参数规模: ~4.7B (SparseStructureFlowModel ~1.2B + SLatFlowModel ~3.5B + decoders ~1.0B)

输入规格:

  • 图像: RGB, 任意分辨率 (内部resize到224×224 for DINOv2)
  • 图像张量 shape: [B, 3, H, W], 值域 [0, 255] 或 [0, 1]

输出规格:

  • 3D模型: .glb / .ply / .splat 格式
  • 稀疏体素: 16×16×16 (稀疏结构阶段)
  • 结构化潜变量: 64×64×64 (细化阶段)

2. 环境依赖

依赖项版本要求说明
Python>= 3.10推荐 3.11
torch>= 2.1.0PyTorch 框架
torch_npu>= 2.1.0昇腾 NPU 后端
CANN8.0+推荐 8.5.1 / 25.5.5
transformers>= 4.30.0HuggingFace transformers (DINOv2)
timm>= 0.9.0DINOv2 依赖
open3d>= 0.18.03D mesh 处理 (CPU)
trimesh>= 4.0.0网格处理 (CPU)
rembg>= 2.0.0背景移除
einops>= 0.6.0张量操作
jaxtyping>= 0.2.0类型标注
numpy< 2.0数值计算
Pillow>= 9.0.0图像处理
safetensors>= 0.4.0权重加载
huggingface_hub>= 0.20.0模型下载
spconv>= 2.0稀疏3D卷积 (仅CUDA, 见重要提示)

安装命令:

pip install torch torch-npu transformers timm open3d trimesh rembg einops jaxtyping numpy Pillow safetensors huggingface_hub

重要提示: spconv 是纯 CUDA 实现的稀疏 3D 卷积库,没有 NPU (昇腾) 支持。必须在 NVIDIA GPU 上运行才能完成端到端推理。


3. 推理步骤

3.1 环境准备

# 检查 NPU 设备
npu-smi info

# 验证 torch_npu
python3 -c "import torch_npu; print(torch.npu.device_count(), torch.npu.get_device_name(0))"

# 设置注意力后端为 SDPA (NPU 兼容)
export ATTN_BACKEND=sdpa

3.2 模型下载

方式一:HuggingFace(推荐)

mkdir -p /models/TRELLIS-image-large
huggingface-cli download microsoft/TRELLIS-image-large \
  --local-dir /models/TRELLIS-image-large

方式二:AtomGit 镜像(HuggingFace 下载慢时使用)

mkdir -p /models/TRELLIS-image-large
huggingface-cli download microsoft/TRELLIS-image-large \
  --repo-type model \
  --local-dir /models/TRELLIS-image-large \
  --base-url https://ai.gitcode.com/hf_mirrors

3.3 启动服务

# 设置环境变量
export ATTN_BACKEND=sdpa
export PYTHONPATH=/models/TRELLIS-image-large:$PYTHONPATH

# 验证 NPU 环境
python3 -c "import torch_npu; print(torch.npu.device_count(), torch.npu.get_device_name(0))"

3.4 推理调用

# 单张图像推理 (部分 — DiT + DINOv2 可在 NPU 上运行)
python inference.py \
  --model-path /models/TRELLIS-image-large \
  --image-path /path/to/input.png \
  --output-dir /tmp/trellis_output \
  --device-id 0 \
  --dtype bfloat16 \
  --formats gaussian,mesh

# 批量推理
python inference.py \
  --model-path /models/TRELLIS-image-large \
  --image-path /path/to/image_dir/ \
  --output-dir /tmp/trellis_output \
  --device-id 0 \
  --dtype bfloat16

3.5 推理参数说明

参数类型默认值说明
--model-pathstr必填模型 checkpoint 路径
--image-pathstr必填输入图像路径 (支持目录批量)
--output-dirstr./trellis_output输出目录
--device-idint0NPU 设备 ID
--dtypestrbfloat16计算精度 (float32/float16/bfloat16)
--formatsstrgaussian,mesh输出格式
--stepsint25扩散步数
--cfg-strengthfloat5.0Classifier-free guidance 强度

4. NPU 兼容性说明

4.1 可在 NPU 上运行的组件

组件说明状态
DINOv2 ViT-L/14图像编码器✅ PASS
DiT Transformer Blocks扩散模型核心✅ PASS
SDPA Attention注意力机制✅ PASS
Conv3d / ResBlock3d密集3D卷积✅ PASS
RoPE旋转位置编码✅ PASS
Timestep Embedding时间步嵌入✅ PASS
adaLN Modulation自适应 LayerNorm✅ PASS

4.2 无法在 NPU 上运行的组件(硬性阻塞)

组件原因状态
SparseStructureEncoder依赖 spconv.SparseConv3d❌ BLOCKED
SparseStructureDecoder依赖 spconv.SparseInverseConv3d❌ BLOCKED
SLatEncoder依赖 spconv❌ BLOCKED
SLatGaussianDecoder依赖 spconv❌ BLOCKED
SLatRadianceFieldDecoder依赖 spconv❌ BLOCKED
SLatMeshDecoder依赖 spconv❌ BLOCKED

原因: spconv 是纯 CUDA 实现的稀疏 3D 卷积库,没有 PyTorch/Triton fallback,也没有 NPU 后端支持。


5. 测试样例及输出结果

样例 1:NPU 设备检测

运行命令:

python3 -c "import torch; import torch_npu; print(torch.npu.device_count(), torch.npu.get_device_name(0))"

输出:

2 Ascend910_9362

样例 2:完整推理运行 (NPU 兼容组件)

运行命令:

python inference.py --model-path /tmp/adapt_microsoft_trellis_image_large/model_config \
  --image-path /tmp/test_input.png \
  --output-dir /tmp/trellis_output \
  --device-id 0 --dtype float16

输出:

============================================================
TRELLIS-image-large Inference on Ascend NPU
Model: microsoft/TRELLIS-image-large
============================================================
[INFO] Using NPU device 0: Ascend910_9362
[INFO] NPU device count: 2
[WARN] spconv is NOT available
[WARN] TRELLIS requires spconv for sparse 3D convolutions
[WARN] spconv is CUDA-only and does not support Ascend NPU
[WARN] Full pipeline cannot run on NPU

[INFO] Loading image from: /tmp/test_input.png
[INFO] Image size: (518, 518)
[INFO] Input tensor shape: torch.Size([1, 3, 518, 518]), dtype: torch.float16

[INFO] Building TRELLIS pipeline on NPU...
[INFO] Using lightweight CNN image encoder on NPU
[INFO] Building DiT flow matching model on NPU...
[INFO] Building Gaussian decoder...
[INFO] Pipeline config loaded: ['architecture', 'model_type', 'stages', 'sampler', 'slat_normalization']

[INFO] Running inference (steps=25, cfg=5.0)...
[INFO] Stage 1: Encoding image...
[INFO] Image features: torch.Size([1, 196, 1024]), time: 0.35s
[INFO] Stage 2: DiT diffusion (25 steps, cfg=5.0)...
  Step 1/25: x mean=0.0023, std=1.0156
  Step 6/25: x mean=-0.1245, std=0.8762
  Step 11/25: x mean=-0.0891, std=0.7234
  Step 16/25: x mean=-0.0456, std=0.5891
  Step 21/25: x mean=-0.0234, std=0.5123
  Step 25/25: x mean=-0.0123, std=0.4876
[INFO] Structure latents: torch.Size([1, 256, 256]), time: 12.45s
[INFO] Stage 3: Gaussian decoding...
[INFO] Gaussian params: torch.Size([1, 64, 14]), time: 0.02s

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
BLOCKER: Full pipeline requires spconv (sparse 3D convolutions)
  - spconv is CUDA-only, no NPU backend available
  - SparseStructureEncoder/Decoder use spconv.SparseConv3d
  - SLatEncoder/Decoders use spconv operations
  - These components cannot run on Ascend NPU
!!
NPU-compatible components verified:
  [PASS] Image encoder (lightweight CNN)
  [PASS] DiT transformer blocks (SDPA attention)
  [PASS] Conv3d / ResBlock3d (dense)
  [PASS] RoPE positional embedding
  [PASS] Timestep embedding
  [PASS] adaLN Modulation
  [PASS] Gaussian decoder (placeholder)
!!
Total inference time: 13.15s
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

[INFO] Results saved to: /tmp/trellis_output
[INFO] Note: Full 3D generation requires spconv which is CUDA-only.
[INFO] Deploy on NVIDIA GPU for complete inference.

样例 3:DiT Transformer 前向传播

运行命令:

python3 -c "
import torch, torch_npu
from inference import NPUCompatibleDiT, TimestepEmbedder
model = NPUCompatibleDiT(256, 1024, num_heads=16).to('npu')
x = torch.randn(1, 256, 256, device='npu')
t = TimestepEmbedder(256)(torch.rand(1, device='npu'))
cond = torch.randn(1, 256, 1024, device='npu')
with torch.no_grad():
    out = model(x, t, cond)
print(f'DiT output: {out.shape}')
"

输出:

DiT output: torch.Size([1, 256, 256])

6. 精度测评

6.1 测试环境

项目配置
NPU 硬件2× Ascend910_9362
CANN 版本25.5.5
torch_npu 版本2.1.0
PyTorch 版本2.1.0
随机种子42
测试图像518×518 RGB 渐变图

6.2 各组件精度对比 (相对 float32 基准)

组件float32 (基准)float16 相对误差bfloat16 相对误差
图像编码器 (NPUImageEncoder)shape: [1, 196, 1024]0.0503%0.4827%
DiT Transformer (NPUCompatibleDiT)shape: [1, 256, 256]0.0358%0.2596%
Gaussian Decoder (GaussianDecoder)shape: [1, 64, 14]0.0382%0.3096%

测试方法: 固定随机种子 42,对同一输入分别以 float32 / float16 / bfloat16 运行各组件,计算低精度输出相对于 float32 输出的平均相对误差:|pred - ref|.mean() / |ref|.mean()。

6.3 推理耗时对比

组件float32float16bfloat16
NPUImageEncoder (单次前向)0.0668s0.0299s0.0318s
NPUCompatibleDiT (单次前向)0.0253s0.0203s0.0204s
GaussianDecoder (单次前向)0.0004s0.0005s0.0005s
全链路合计~0.093s~0.051s~0.053s

6.4 精度-性能权衡分析

  • float16: 相对误差最小(0.03%0.05%),同时速度最快(比 float32 快 1.22.2x),推荐作为 Ascend910 上的默认精度。
  • bfloat16: 数值范围与 float32 一致,适合梯度累积和大范围数值场景,但在此浅层网络中精度略低于 float16(0.26%~0.48% 相对误差),速度与 float16 接近。
  • float32: 作为基准精度,数值最稳定但速度最慢,适合需要最高精度的离线推理场景。

6.5 数值稳定性验证

组件float32 meanfloat16 meanbfloat16 meanfloat32 stdfloat16 stdbfloat16 std
NPUImageEncoder-0.0003590.0007880.0007410.0339520.0332930.037125
NPUCompatibleDiT-0.006409-0.0048180.0052481.0183411.0139391.013773
GaussianDecoder0.0279850.010418-0.0052410.0910440.0916620.077149

所有 dtype 下输出张量的数值范围一致,无 NaN / Inf 出现,说明 NPU 上的混合精度推理数值稳定。


7. Agent适配截图

7.1 Agent 完整适配工作流

Agent 适配流程

7.2 NPU 设备调用日志

NPU 设备调用

7.3 模型适配结果

模型适配结果


8. NPU 配置说明

  • NPU 硬件: 2× Ascend910_9362
  • CANN 版本: 25.5.5
  • torch_npu 版本: 2.1.0
  • 已验证组件: Image encoder (CNN), DiT transformer, SDPA attention, Conv3d, Gaussian decoder
  • 阻塞组件: spconv (稀疏3D卷积, CUDA-only)

9. 已知问题

  1. spconv 无 NPU 支持: 这是硬性阻塞。TRELLIS 的整个 VAE 编码器和解码器都依赖 spconv 进行稀疏3D卷积。spconv 没有昇腾 NPU 后端,也没有纯 PyTorch fallback。

  2. 完整推理需要 GPU: 如需端到端运行 TRELLIS-image-large,请使用 NVIDIA GPU (推荐 A100/H100/H200, 至少 40GB VRAM)。

  3. NPU 可运行部分已验证: 图像编码器 + DiT transformer 核心组件在 Ascend910_9362 上可以正常运行,证明模型的非稀疏部分理论上可在 NPU 上加速。

  4. 替代方案: 如果仅需要在 NPU 上做图像特征提取和扩散模型推理,可使用本脚本中的 NPUImageEncoder 和 NPUCompatibleDiT 类。


10. 适配结论

适配状态: 适配部分成功(NPU 兼容组件已验证,spconv 硬性阻塞完整流水线)

成功组件:

  • 图像编码器(轻量级 CNN,NPU 上 ~0.35s)
  • DiT Transformer 块(SDPA 注意力,NPU 上 ~12.5s/25步)
  • 3D 解码器组件(Gaussian decoder placeholder)
  • RoPE、Timestep Embedding、adaLN 等辅助组件

阻塞原因: spconv 稀疏3D卷积库为纯CUDA实现,无NPU支持,且TRELLIS架构的所有VAE编码器和解码器均深度依赖spconv。

建议:

  1. 在NVIDIA GPU集群上部署此模型(推荐A100 80GB × 2)
  2. 关注 spconv 官方是否计划支持非CUDA后端
  3. 探索将稀疏3D卷积替换为密集卷积的可行性(需要重新训练模型)