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_decoder | SparseStructureDecoder(ss_dec_conv3d) |
| sparse_structure_flow_model | SparseStructureFlowModel(3B, 64 token) |
| shape_slat_decoder | FlexiDualGridVaeDecoder |
| shape_slat_flow_model_512 / 1024 | SLatFlowModel(3B ×2) |
| tex_slat_decoder | FlexiDualGridVaeDecoder |
| tex_slat_flow_model_512 / 1024 | SLatFlowModel(3B ×2) |
source /usr/local/Ascend/ascend-toolkit/set_env.sh)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.safetensors | microsoft/TRELLIS-image-large ckpts/ | 141M,软链到 ckpts/ |
DINOv3 dinov3-vitl16-pretrain-lvd1689m | GitCode 镜像 | 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 通道可跳过抠图) |
--output | trellis_output.glb | 输出网格文件 |
--device | npu:0 | NPU 优先,自动回退 CPU |
--seed | 42 | 随机种子 |
[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)官方 TRELLIS.2 依赖多个 CUDA 专属编译扩展,本仓库通过以下方式适配昇腾:
conv_none.py(gather-scatter + hash 邻居查找),SPARSE_CONV_BACKEND=nonetorch.nn.functional.scaled_dot_product_attention 分派,SPARSE_ATTN_BACKEND=sdpanpu() 方法;.cuda() 硬编码改 .to(self.model.device)model.model.layer 结构)├── README.md # 模型卡片(本文件)
├── REPRODUCE.md # 完整复现文档(权重/补丁/FAQ)
├── inference.py # NPU 推理脚本
├── pipeline.json # TRELLIS.2 管线配置(ss_dec 指向本地)
├── ckpts/*.json # 子模型配置(权重 LFS 单独拉取)
├── evidence/ # NPU 验证证据
└── assets/ # 适配过程截图