TRELLIS.2-4B(microsoft/TRELLIS.2-4B)是微软新一代 image-to-3D 生成模型(~4B 参数,MIT 许可)。输入单张 RGB 图像,三阶段生成 O-Voxel(Flexible Dual Grid + 体素化 PBR 属性)3D 表征:
本工程将其适配到华为昇腾 NPU,真实跑通 pipeline_type='512' 完整推理(NPU 型号 Ascend910_9362 / Atlas 800I A2,torch_npu 2.9.0,CANN 8.5.1)。
| 原依赖 | 替换实现 | 说明 |
|---|---|---|
| spconv(SubMConv3d 稀疏 3D 卷积) | vendor/shims/spconv:hash 索引 + 27 偏移 gather + matmul + index_add | TRELLIS.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。
见 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 属性统计)。
输入图: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 为非金属粗糙表面先验。
预热 5 次 + 正式 20 次(flock /tmp/npu_card0_perf.lock 独占整卡,pipeline_type='512',12+12+12 步):
| 指标 | 数值 |
|---|---|
| avg | 17.82 s |
| min | 17.58 s |
| p50 | 17.80 s |
| p90 | 18.10 s |
| p95 | 18.25 s |
| max | 18.25 s |
| 峰值 HBM | 12.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