ohhoohho/scaffdiff
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

ScaffDiff — 昇腾 NPU 适配

ScaffDiff 是面向 LiDAR 3D 场景补全的支架主导扩散模型(SemanticKITTI 点云),在 Ascend 910B NPU 上完成推理验证。

模型描述

属性值
架构PointTransformerV3 (PTv3) Encoder + 条件特征提取器 + U-Net 风格 DenoisingNetwork
参数encoder 108M + denoiser ≈ 24M(checkpoint 517MB)
输入部分扫描点云 (coord, color, normal)
输出补全场景点云 (N, 3)
推理方式坐标空间 DDIM 扩散(固定 scaffold 坐标,仅演化特征)
原始论文Zhura et al., RA-L 2026 (under review)

环境要求

组件版本
Ascend NPU910 / 910B / 910C
CANN≥ 8.0(推荐 8.5.1)
Python3.10+
PyTorch2.9.0+cpu
torch_npu2.9.0.post1
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

下载权重

# 从 HuggingFace 镜像(推荐国内)
HF_ENDPOINT=https://hf-mirror.com python3 -c "
from huggingface_hub import snapshot_download
snapshot_download('businesslion/scaffdiff', local_dir='./weights')
"

# 或从 GitCode LFS
git clone https://gitcode.com/hf_mirrors/businesslion/scaffdiff.git weights
# 需要 git-lfs 来拉取 .pth 文件

推理示例

python inference.py \
    --checkpoint ./weights/teacher_v2gt/best_model.pth \
    --num_points 400 \
    --num_steps 10 \
    --start_t 200 \
    --device npu:0 \
    --output completed.txt

输出示例:

[1/3] 构建模型并加载权重: ./weights/teacher_v2gt/best_model.pth
[2/3] 构造 400 点 partial scan 输入
[3/3] DDIM 去噪 (steps=10, t0=200) ...
补全点云: 400 点, 耗时 0.432s (0.0432s/step)
已保存补全点云到 completed.txt

精度验证

在 Ascend 910B 上与 CPU 基线对比(确定性输入,不含采样噪声):

对比项结果
Denoiser 余弦相似度0.9999998
Denoiser 最大绝对误差~0.002
DDIM 完整采样余弦(含噪声差异)0.975

项目结构

scaffdiff/
├── inference.py          # 昇腾 NPU 推理脚本
├── requirements.txt      # 环境依赖
├── README.md             # 本文档
├── scaffdiff/            # vendor 模型包
│   ├── __init__.py
│   └── model.py          # 完整模型定义(PTv3 encoder + denoiser + DDIM 调度器)
└── assets/               # 截图素材(用户自行补充)
    ├── agent_workflow.png
    ├── npu_device_call.png
    └── model_result.png

适配要点

  1. CPE 权重布局:checkpoint 的 Conv3d 权重以 (out, k, k, k, in) 存储,加载时需 permute(0, 4, 1, 2, 3) 转为标准布局。
  2. int64 linspace:NPU 不支持 DT_INT64 的 torch.linspace,下采样索引在 CPU 生成后 .to(device)。
  3. Eager 注意力:不使用 flash attention / sdpa,所有注意力用纯 PyTorch 实现(NPU 兼容)。
  4. 参数共享:condition_extractor 与 encoder 共享同一 SonataEncoder 实例,state_dict 中两条路径均保存权重。
  5. 非 LLM 模型:无需 vLLM-Ascend,直接 torch_npu 加载推理。

许可证

Apache 2.0(原模型 MIT 许可证覆盖的例外部分遵循原协议)