eardoi/trellis-2-4b-npu
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

TRELLIS.2-4B(昇腾 NPU 适配)

microsoft/TRELLIS.2-4B 图像→3D 资产生成模型在 华为昇腾 NPU 上的适配实现。基于 TRELLIS.2 的 O-Voxel 稀疏结构(O-Voxel Adaptive Dual Grid)与流匹配(Flow Matching)生成管线,单张图像输入即可生成带纹理的高质量 3D 网格。

模型规格

项目值
参数量7483.4M(8 个子模型合计)
输入单张 RGB 图像(自动缩放至 512/1024)
输出3D 网格(GLB),含稀疏结构 + 形状 + 纹理
架构O-Voxel 稀疏结构 Flow + Dual Grid VAE + 4×SLat Flow 级联
视觉编码DINOv3 ViT-L/16(离线本地化)
背景移除rembg(懒加载,带 alpha 输入可跳过)
子模型类型
sparse_structure_decoderSparseStructureDecoder(ss_dec_conv3d)
sparse_structure_flow_modelSparseStructureFlowModel(3B, 64 token)
shape_slat_decoderFlexiDualGridVaeDecoder
shape_slat_flow_model_512 / 1024SLatFlowModel(3B ×2)
tex_slat_decoderFlexiDualGridVaeDecoder
tex_slat_flow_model_512 / 1024SLatFlowModel(3B ×2)

环境要求

  • 硬件:Ascend 910B 系列(≥1 卡,验证基于 910B3 64GB)
  • CANN:≥ 8.0(source /usr/local/Ascend/ascend-toolkit/set_env.sh)
  • Python:3.10–3.11
  • torch / torch_npu:2.9.0 / 2.9.0.post1

环境准备

export PIP_INDEX_URL=https://repo.huaweicloud.com/repository/pypi/simple/
pip install torch==2.9.0 torch_npu==2.9.0.post1 transformers tokenizers \
    einops easydict omegaconf trimesh pillow numpy

模型权重

推理权重不随本仓库分发(需 GitCode LFS 拉取后本地化):

权重来源说明
ckpts/*.safetensors(9 个)https://ai.gitcode.com/hf_mirrors/microsoft/TRELLIS.2-4B~16G
ss_dec_conv3d_16l8_fp16.safetensorsmicrosoft/TRELLIS-image-large ckpts/141M,软链到 ckpts/
DINOv3 dinov3-vitl16-pretrain-lvd1689mGitCode 镜像1.2G,放 HF 缓存离线加载
git clone https://gitcode.com/hf_mirrors/microsoft/TRELLIS.2-4B.git TRELLIS.2-4B
cd TRELLIS.2-4B && git lfs pull

完整获取与本地化步骤见 REPRODUCE.md。

推理

source /usr/local/Ascend/ascend-toolkit/set_env.sh
export SPARSE_CONV_BACKEND=none
export SPARSE_ATTN_BACKEND=sdpa
export ATTN_BACKEND=sdpa
export HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1

python3 inference.py --model_path ./TRELLIS.2-4B --output trellis_output.glb --device npu:0

参数

参数默认说明
--model_path./TRELLIS.2-4B权重目录(含 pipeline.json + ckpts/)
--image合成测试图输入图像路径(建议带 alpha 通道可跳过抠图)
--outputtrellis_output.glb输出网格文件
--devicenpu:0NPU 优先,自动回退 CPU
--seed42随机种子

验证结果(NPU 实测)

[info] device = npu:0
[warn] rembg 模型加载失败, 将跳过背景移除: ...   # RMBG-2.0 gated, 预期跳过
[info] pipeline 加载完成 (369.5s), models: 8
[info] pipeline.npu() 完成
[info] 总参数量: 7483.4M
[info] 使用合成测试图像 (128x128 渐变 RGBA, 带 alpha 跳过 rembg)
  • ✅ 8 个子模型全部离线加载成功
  • ✅ DINOv3 视觉编码器 NPU 前向通过(1×1029×1024,0.3s)
  • ✅ 纯 PyTorch 稀疏卷积(conv_none 后端)与 sdpa 注意力在 NPU 上工作
  • 🔄 端到端 3D 网格采样验证中(sdpa 分支修复后)

适配说明(NPU)

官方 TRELLIS.2 依赖多个 CUDA 专属编译扩展,本仓库通过以下方式适配昇腾:

  1. 稀疏卷积:flex_gemm(CUDA 编译扩展)→ 纯 PyTorch 实现 conv_none.py(gather-scatter + hash 邻居查找),SPARSE_CONV_BACKEND=none
  2. 注意力:flash_attn / xformers(仅 CUDA)→ torch.nn.functional.scaled_dot_product_attention 分派,SPARSE_ATTN_BACKEND=sdpa
  3. CUDA 依赖懒加载:cumesh / flex_gemm.grid_sample 改为懒加载,NPU 上不触发
  4. 设备迁移:pipeline / VarLenTensor 增加 npu() 方法;.cuda() 硬编码改 .to(self.model.device)
  5. 视觉编码器本地化:DINOv3 从 GitCode 镜像下载并离线加载(兼容 transformers 5.x 的 model.model.layer 结构)
  6. 背景移除:rembg 懒加载(RMBG-2.0 为 gated 仓库),输入带 alpha 通道时直接跳过抠图

目录结构

├── README.md                 # 模型卡片(本文件)
├── REPRODUCE.md              # 完整复现文档(权重/补丁/FAQ)
├── inference.py              # NPU 推理脚本
├── pipeline.json             # TRELLIS.2 管线配置(ss_dec 指向本地)
├── ckpts/*.json              # 子模型配置(权重 LFS 单独拉取)
├── evidence/                 # NPU 验证证据
└── assets/                   # 适配过程截图

引用

  • 模型: https://ai.gitcode.com/hf_mirrors/microsoft/TRELLIS.2-4B
  • 官方: https://trellis3d.github.io/ · https://github.com/Microsoft/TRELLIS
  • DINOv3: https://huggingface.co/facebook/dinov3-vitl16-pretrain-lvd1689m