c
zyzoe/trellis2-4b
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

TRELLIS.2-4B 昇腾 NPU 部署

模型简介

TRELLIS.2-4B(microsoft/TRELLIS.2-4B)是微软新一代 image-to-3D 生成模型(~4B 参数,MIT 许可)。输入单张 RGB 图像,三阶段生成 O-Voxel(Flexible Dual Grid + 体素化 PBR 属性)3D 表征:

  1. Sparse Structure 阶段:DINOv3-ViT-L/16 图像编码器 + 16³ 稠密 latent 上的流匹配 DiT(1.3B,30 层,1536 通道),解码 64³ 稀疏占据结构;
  2. Shape SLat 阶段:稀疏流匹配 DiT(1.3B)生成 32 通道结构化隐变量,FlexiDualGrid VAE 解码器还原 mesh 几何(QEF 对偶网格);
  3. Texture SLat 阶段:第二个 1.3B 流匹配 DiT 以 shape 隐变量为条件生成 PBR 体素属性(base color / metallic / roughness / alpha)。

本工程将其适配到华为昇腾 NPU,真实跑通 pipeline_type='512' 完整推理(NPU 型号 Ascend910_9362 / Atlas 800I A2,torch_npu 2.9.0,CANN 8.5.1)。

CUDA 依赖替换(全部纯 torch 实现)

原依赖替换实现说明
spconv(SubMConv3d 稀疏 3D 卷积)vendor/shims/spconv:hash 索引 + 27 偏移 gather + matmul + index_addTRELLIS.2 全部 SparseConv3d 均为 stride=1/padding=None(上/下采样走 Channel2Spatial/Spatial2Channel),SubM 路径全覆盖;与 nn.Conv3d 稠密化对齐已在 TRELLIS-image-large 移植中验证(max err < 4e-6)
flash-attn(varlen / windowed)vendor/shims/flash_attn:分段 pad + F.scaled_dot_product_attention(CANN 融合算子);稠密注意力走 ATTN_BACKEND=sdpa等价语义(非因果、无 dropout)
o_voxel _C C++ hashmap(hashmap_insert/lookup_3d)vendor/o_voxel/convert/_C.py:排序键数组 + searchsorted,miss 返回 0xFFFFFFFF 语义一致flexible_dual_grid_to_mesh 仅用这两个 kernel
cumesh fill_holes / flex_gemm grid_sample_3d可选依赖:导入失败时降级(fill_holes 为外观性后处理,no-op)不影响几何/属性生成
DINOv3 条件编码器(facebook/dinov3-vitl16-pretrain-lvd1689m,HF gated)transformers DINOv3ViTModel + ModelScope 权重镜像,本地 TRELLIS2_DINO_DIR 加载,设备感知(去掉 .cuda() 硬编码)加载门禁 0 missing / 0 unexpected / 0 mismatched
rembg(BiRefNet)可选:输入图自带 alpha 通道时 pipeline 直接使用 alpha 掩码—

其他 NPU 适配点:aclnnMaxDim 不支持 int32 的三处 coords max 改 .long()(modules/sparse/basic.py);run() 中 torch.cuda.empty_cache() 改 torch.npu;low_vram=False 常驻 64GB HBM。

验证环境

  • NPU:Ascend910_9362(Atlas 800I A2),npu-smi 25.5.5,CANN 8.5.1
  • torch 2.9.0+cpu / torch_npu 2.9.0.post1 / transformers 4.57.6
  • Python 3.11.14

环境依赖

见 requirements.txt:torch、torch-npu、transformers、safetensors、pillow、numpy、tqdm。

推理操作流程

# 权重(HF 镜像 / ModelScope 下载到本地后)
export TRELLIS2_MODEL_DIR=/path/to/TRELLIS.2-4B   # 含 pipeline.json + ckpts/
export TRELLIS2_DINO_DIR=/path/to/dinov3-vitl16   # facebook/dinov3-vitl16-pretrain-lvd1689m

python3 inference.py --device npu            # 完整推理 + 三道加载门禁 + 结果 JSON
python3 inference.py --device npu --perf     # 性能测试(预热 5 + 正式 20 次)

输入:assets/test_image.png(RGBA,含 alpha 通道);输出:/tmp/trellis2_4b_output.obj(mesh 几何)+ /tmp/trellis2-4b_npu_results.json(含 O-Voxel 坐标/PBR 属性统计)。

测试用例与真实输出(昇腾 NPU)

输入图:512×512 RGBA(圆 + 三角 + 圆组合的合成物体,带 alpha 通道),seed=42,pipeline_type='512'(12+12+12 步流匹配采样):

[env] torch=2.9.0+cpu device=npu:0 NPU=Ascend910_9362
[gate1][dinov3] missing=0 unexpected=0 mismatched=0
[gate2][dinov3] config keys not landed: ['torch_dtype']
[load] pipeline loaded in 131.0s models=['sparse_structure_decoder', 'sparse_structure_flow_model',
       'shape_slat_decoder', 'shape_slat_flow_model_512', 'tex_slat_decoder', 'tex_slat_flow_model_512']
[load] total parameters (pipeline + conditioner): 5.20B
[gate1] 6 ckpt 全部 0 missing / 0 unexpected(rope_phases 为 __init__ 重计算的 RoPE 表,白名单)
[result] NPU inference time (pipeline_type=512): 19.1s
[result] mesh: vertices=347634 faces=692776
[result] vertex bounds: min=[-0.3611, -0.3180, -0.4912] max=[0.3596, 0.3179, 0.5001]
[result] o-voxel: coords=(347634, 3) attrs=(347634, 6)
[result] base_color mean=[0.5353, 0.1731, 0.0355] metallic=0.0002 roughness=0.9501
[result] exported /tmp/trellis2_4b_output.obj (25.9 MB)
[gate3] real-cond: verts=347634 faces=692776 spatial_std=0.1539 bc_mean=0.2479
[gate3] rand-cond: degenerate(随机初始化条件下降为 0 活跃 voxel,无法生成 mesh)
[gate3] PASS=True(真实条件决定性改变生成结果)

输出解读:单次端到端 19.1s 生成 34.8 万顶点 / 69.3 万三角面的 mesh + 34.8 万 O-Voxel 体素(含 6 维 PBR 属性),两次独立运行统计完全一致(seed=42 决定性);base_color 均值偏橙红,与输入图的彩色几何物体相符;metallic≈0 / roughness≈0.95 为非金属粗糙表面先验。

NPU 性能

预热 5 次 + 正式 20 次(flock /tmp/npu_card0_perf.lock 独占整卡,pipeline_type='512',12+12+12 步):

指标数值
avg17.82 s
min17.58 s
p5017.80 s
p9018.10 s
p9518.25 s
max18.25 s
峰值 HBM12.83 GB / 64 GB

p95/p50 = 1.03,无双峰污染;单次端到端(含三阶段流匹配采样 + mesh/O-Voxel 解码)约 18s。

截图

  • assets/agent_workflow.png:模型上卡日志(设备初始化 → 权重解析 → 上 npu:0,含参数量)
  • assets/npu_device_call.png:npu-smi 实时占用 + torch_npu 设备断言
  • assets/model_result.png:真机 NPU 推理输出

#NPU