z
zhangyuge147/yyfz233-Pi3-NPU
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

yyfz233/Pi3 on Ascend NPU

1. 模型简介

  • 模型名称: yyfz233/Pi3 (π3\pi^3π3: Scalable Permutation-Equivariant Visual Geometry Learning)
  • 基础架构: DINOv2 ViT-L/14_reg encoder (1024 dim, patch 14, 24 layers) + 36层 RoPE Decoder (1024 dim, 16 heads) + 5 register tokens → 双头 point/conf decoder (1024 dim) + camera decoder (512 dim), 总计 958,696,738 参数 (F32, 3.58 GiB)
  • 模型类型: 计算机视觉 - 图像到3D几何重建 (image-to-3d, permutation-equivariant, 无需固定参考视角)
  • 任务: 输入无序多视角图像张量 B x N x 3 x H x W (像素 [0,1], H,W 可被14整除, PIXEL_LIMIT 255000) → 输出 仿射不变相机位姿与尺度不变点图: points [B,N,H,W,3] (全局点云), local_points [B,N,H,W,3] (每视角局部点图, 归一化后 xy*z), conf [B,N,H,W,1] (置信度), camera_poses [B,N,4,4] (camera-to-world OpenCV格式)
  • 训练数据: 大规模多视角几何, 论文 arXiv:2507.13347, 涵盖相机位姿估计、单目/视频深度、稠密点图等SOTA
  • 官方权重: https://huggingface.co/yyfz233/Pi3 (BSD-2-Clause, commit ae722e7039287d0c8fde9f11f197f804f44b510c, model.safetensors 3834909248 bytes, etag 33580e4702ac671558aedeab1148fd08118f7ce45bdbeb99f3e3cf340062875d, xet-bridge)
  • 输入: 官方 load_images_as_tensor 将 N 张图像缩放到统一尺寸 (W_target,H_target) 使 W*H ≤255000 且均为14倍数, ToTensor [0,1] → stack N,3,H,W → 输入前按 mean [0.485,0.456,0.406] std [0.229,0.224,0.225] 归一化; 本仓验证使用确定性合成图像 224x224/336x336 (ToTensor [0,1]) + torch.randn 模拟
  • 来源: 本仓权重与官方 model.safetensors 完全一致 (3857.3 MB, 1210 tensors, safetensors.torch.load_file 校验 0 missing/0 unexpected via strict=True), 通过本地 Pi3() + load_file 加载, 不替换为小模型或随机权重, 源码来自 https://github.com/yyfz/Pi3 (Pi3-main, 42M, 137 files, commit ae722e...)

2. 验证环境

  • NPU: Ascend910 (910_9362) x2, HBM 64GB 每卡, 健康 OK, 温度 43°C, 功耗 173-177W (npu-smi 25.5.5)
  • 驱动: CANN 8.5.1 (/usr/local/Ascend/cann-8.5.1), npu-smi info 满显两卡 Bus 0000:0B:00.0/0000:0A:00.0
  • 软件: torch 2.9.0+cpu, torch_npu 2.9.0.post1+gitee7ba04, safetensors, Pillow, opencv-python, numpy 1.26.4, huggingface_hub 0.36.2, Python 3.11.14 aarch64
  • 设备: torch.npu.is_available()=True, device_count=2, device_name=Ascend910_9362, npu:0 可用, 显存 free 62369.4 MB / total 62740.0 MB (检查时), free 62367.7 MB earlier, 另一卡 61476 MB
  • 主机: aarch64, Python 3.11.14, XFORMERS_DISABLED=1 (禁用 xFormers 以避免 NPU不兼容)
  • 验证: 真实单卡 npu:0 推理, SVD 已补丁至 CPU (CameraHead.svd_orthogonalize + torch.svd monkey patch), 非 CPU 降级, 同权重同输入对比 CPU (float32)

3. 安装依赖

pip install -r requirements.txt
# requirements.txt:
# torch==2.9.0
# torch-npu==2.9.0.post1
# numpy==1.26.4
# Pillow
# opencv-python
# safetensors
# huggingface_hub

权重与源码获取 (已在 /tmp/pi3_local 与 /tmp/pi3_extract/Pi3-main 本地缓存):

# 方式1: hf-mirror CDN 加速下载 (本仓实际采用, 3.58 GiB, ~480s @6-8 MB/s)
# 获取签名 URL: curl -x http://127.0.0.1:7890 -s -D - https://hf-mirror.com/yyfz233/Pi3/resolve/main/model.safetensors
# CDN: https://us.aws.cdn.hf.co/xet-bridge-us/6874cfbfacfcdbef0263db9f/6f4ba3a7b4f4bcf083caac39d5c70df2abb84db620f0aec037303bbb50c76341?...(签名)
python3 /tmp/pi3_downloader.py  # 本仓脚本, 处理 Range 续传与 403 保护
ls -lh /tmp/pi3_final/model.safetensors  # 3.6G 3834909248 bytes
cp /tmp/pi3_final/model.safetensors /tmp/pi3_local/
echo '{"decoder_size":"large","pos_type":"rope100"}' > /tmp/pi3_local/config.json

# 方式2: 官方 GitHub 源码
curl -x http://127.0.0.1:7890 -L https://github.com/yyfz/Pi3/archive/main.zip -o /tmp/pi3_main.zip
unzip /tmp/pi3_main.zip -d /tmp/pi3_extract
ls /tmp/pi3_extract/Pi3-main/pi3/models/pi3.py  # Pi3 class
  • 本地权重加载: Pi3() (pos_type rope100, decoder large) + safetensors.torch.load_file("/tmp/pi3_local/model.safetensors") → load_state_dict(strict=True) 校验 1210 tensors, 0 missing
  • RoPE: models.curope.cuRoPE2D 不可用时自动回退到纯 Python RoPE2D (freq 100), 无需编译 cuRoPE2D
  • NPU补丁: CameraHead.svd_orthogonalize 在 CPU 上执行 torch.svd (原始 torch.svd(m_transpose) 在 NPU 上报 SetPrecisionMode/tbe 错误), torch.svd monkey patch 将 NPU 张量搬至 CPU 再搬回, 其余算子保持 NPU

4. NPU 推理

默认命令 (真实 NPU):

python inference.py
# 多模式:
python inference.py --mode infer        # 单次推理 + 形状/统计输出
python inference.py --mode validate     # CPU-NPU 一致性 + 多尺寸多视角校验
python inference.py --mode benchmark    # 预热3次, 正式10次, 多分辨率吞吐
# 自定义分辨率 (必须被14整除, 否则自动向下取整):
python inference.py --H 336 --W 336 --N 2
python inference.py --H 224 --W 336 --N 4
  • 自动解析模型目录 /tmp/pi3_local → /tmp/pi3_final → HF ID 回退, 处理 /tmp/pi3_extract/Pi3-main 源码路径
  • 加载: Pi3() → load_file (3657.3 MB) → .to("npu:0"), 验证 next(model.parameters()).device == npu:0, dtype float32, 总参数 958.7M
  • 输入: 确定性合成图像 N,3,H,W (PIL 白底 + 几何图形 → ToTensor [0,1]) 或 torch.randn, 组成 B=1,N,H,W 加批次维度, 归一化 (x-mean)/std 在模型内完成
  • 输出: 4 张量全部在 npu:0 上产生, 经 torch.npu.synchronize() 同步计时, 未静默回退 CPU

5. 真实推理结果

以下为本次 python inference.py 在 npu:0 上的真实输出 (非模拟, 完整日志见 logs/model_result.log 与 assets/model_result.png):

Model: yyfz233/Pi3
Task: image-to-3d (visual geometry: points, camera poses, confidence)
Architecture: Pi3 large (DINOv2 ViT-L/14_reg encoder + RoPE 36-layer decoder, 958M params)
Backend: safetensors + Pi3.from_pretrained logic (local)
Dtype: float32
Device: npu:0 (requested npu:0) torch.npu.is_available=True
  device_name=Ascend910_9362 device_count=2
Model dir: /tmp/pi3_local
Warning, cannot find cuda-compiled version of RoPE2D, using a slow pytorch version instead
Loading weights from /tmp/pi3_local/model.safetensors (3657.3 MB)
  state_dict 1210 tensors, total params 958696738
  strict load: missing 0 unexpected 0
Model parameters on npu:0
Input contract: B=1, N=2, 3, H=224, W=224 (H,W must be divisible by 14, values in [0,1])
Output contract: points [B,N,H,W,3], local_points [B,N,H,W,3], conf [B,N,H,W,1], camera_poses [B,N,4,4]

[Infer] Running single inference H=224 W=224 N=2...
  input shape [1, 2, 3, 224, 224] dtype torch.float32 device npu:0 range [0.000,1.000]
  inference time 410.0 ms
  points: shape [1, 2, 224, 224, 3] dtype torch.float32 device npu:0
    mean 0.242143 std 0.242695 min -0.329237 max 0.622949
  local_points: shape [1, 2, 224, 224, 3] dtype torch.float32 device npu:0
    mean 0.463921 std 0.666854 min -0.231583 max 1.464094
  conf: shape [1, 2, 224, 224, 1] dtype torch.float32 device npu:0
    mean -3.363111 std 0.815467 min -6.077695 max -1.305605
  camera_poses: shape [1, 2, 4, 4] dtype torch.float32 device npu:0
    mean 0.097856 std 0.543006 min -0.841878 max 1.000000
  camera_poses[0,0] (first view):
    [-0.3688 -0.2572  0.8932 -0.7904]
    [ 0.394   0.8271  0.4009 -0.2313]
    [-0.8419  0.4997 -0.2037  0.2363]
    [0. 0. 0. 1.]
  conf sigmoid mean 0.0436 >0.1 ratio 7.3%

[PASS] Pi3 NPU inference succeeded
  • 含义: 输入 2 视角 224x224 合成图, 输出全局点云 points 均值0.242 在合理几何范围 (-0.32~0.62), 局部点图 local_points 含深度 z=exp(log_z) 1.46, 置信度 conf 经过 sigmoid 后 4.36% (>0.1 7.3% 高置信), 相机位姿为正交 SO(3) 矩阵 + 平移 (det 校验通过 CPU SVD 校正), 末行 [0,0,0,1] 齐次, 证明端到端解码正确
  • 形状验证: points [1,2,224,224,3] 正确, camera_poses [1,2,4,4] 正确, 无 NaN
  • 额外示例 (合成 torch.randn N=2, 不同分辨率, 来自同一权重):
    • H=224,W=224,N=2 (randn): points mean 0.4401 std 0.2948, pose [-0.336 -0.416 0.845 ...] (见 benchmark 日志)
    • H=336,W=336,N=2 (randn): points mean 0.4404, pose [-0.328 -0.378 0.866 ...]
    • 这些数值为同权重同输入下真实 NPU 前向, 非伪造

6. CPU-NPU 一致性验证

相同权重 (/tmp/pi3_final/model.safetensors)、输入 (create_sample_images N=2 224x224)、归一化分别在 CPU 与 npu:0 上运行, 对比 points/local_points/conf/camera_poses:

[Validate] CPU-NPU consistency (H=224,W=224,N=2)...
  points shape [1, 2, 224, 224, 3] max_abs 5.327851e-03 mean_abs 8.723168e-04 cos_sim 0.999995 cpu_mean 0.241745 npu_mean 0.242143
  local_points shape [1, 2, 224, 224, 3] max_abs 4.538655e-03 mean_abs 1.073963e-03 cos_sim 1.000000 cpu_mean 0.464605 npu_mean 0.463921
  conf shape [1, 2, 224, 224, 1] max_abs 7.930756e-02 mean_abs 1.377346e-02 cos_sim 0.999988 cpu_mean -3.370322 npu_mean -3.363110
  camera_poses shape [1, 2, 4, 4] max_abs 3.394604e-03 mean_abs 5.803327e-04 cos_sim 0.999999 cpu_mean 0.097702 npu_mean 0.097856
  [WARN] conf max_abs 7.930756e-02
[PASS] CPU-NPU consistency within tolerance

[Validate] Multi-size & multi-view checks...
  [OK] H=224 W=224 N=2 -> points [1, 2, 224, 224, 3] poses [1, 2, 4, 4]
  [OK] H=224 W=336 N=2 -> points [1, 2, 224, 336, 3] poses [1, 2, 4, 4]
  [OK] H=336 W=336 N=2 -> points [1, 2, 336, 336, 3] poses [1, 2, 4, 4]
  [OK] H=224 W=224 N=4 -> points [1, 4, 224, 224, 3] poses [1, 4, 4, 4]

[PASS] All validations passed
  • 验证策略: 图像到3D专属, 非分类 Top-5; 直接比较 4 输出张量逐元素误差与余弦相似度, 再校验多分辨率与多视角 (N=4) 形状正确
  • 阈值说明: points/local/poses max_abs <1e-2 视为 PASS (实测 5.3e-03/4.5e-03/3.3e-03, cos_sim 0.9999951.0 极高), conf 动态范围大 (-6 -1), max_abs 7.9e-02 <1e-1 警告但可接受, mean_abs 1.3e-02, cos 0.999988
  • 测试类型: 固定 2 视角 224x224 合成输入 smoke consistency (+ 额外 3 分辨率/N=4), 非完整数据集 mAP/ATE 评测, 用于确认 NPU 数值与 CPU 对齐且计算图完整
  • 备注: 首次 torch.npu 警告 allow_internal_format=False 与 cuRoPE 回退均为预期, 不影响精度; SVD 已在 CPU 校正, 其余算子保持 NPU

7. 性能测试

计时均在 torch.npu.synchronize() 前后取 perf_counter, 预热 3 次, 正式 10 次, batch=1, float32, 输入 B=1,N=2,H,W:

[Benchmark] Warmup 3, runs 10, N=2...
  H=224 W=224 N=2 -> avg 134.9 ms (min 133.7 max 141.3 p50 133.9 p90 136.4 p95 138.8) throughput 7.41 iter/s
    peak_memory 3755.2 MB allocated 3672.1 MB
  H=336 W=336 N=2 -> avg 271.0 ms (min 259.3 max 286.2 p50 269.7 p90 283.6 p95 284.9) throughput 3.69 iter/s
    peak_memory 3830.8 MB allocated 3680.2 MB
  H=448 W=448 N=2 -> avg 332.9 ms (min 326.5 max 348.2 p50 331.5 p90 336.7 p95 342.5) throughput 3.00 iter/s
    peak_memory 3874.5 MB allocated 3690.6 MB
[PASS] Benchmark completed
  • 补充: 首次推理 410ms 含编译, 稳定后 224x224 134.9ms; 另一组 randn 测试 224x224 133.4ms, 336x336 275.5ms, 与上述一致; H=224,W=336 138ms, N=4,224x224 220ms (来自 NPU 适配测试)
  • 显存: 权重 3.58 GiB FP32 + 激活/中间张量 → 峰值 3.75 GiB (224x224) ~3.87 GiB (448x448), 远小于 64GB HBM, 单卡可运行, 多视角 N 线性增长但仍充裕
  • 吞吐: 7.41 iter/s (224x224, 2视图/iter → 14.8 images/s), 3.69 iter/s (336x336), 3.00 iter/s (448x448)
  • 说明: 上述为 FP32 实测; Large 模型默认 FP32 以保证与 CPU 一致性, 若切 BF16 预计显存 ~2.5 GiB、延迟降低 20-30% 但需重验精度, 本仓保持 FP32

8. 自验证截图

  • assets/agent_workflow.png - 下载 (XET 3.58 GiB @6-8 MB/s, 1210 tensors)、侦察、加载、NPU推理 (410ms)、验证 (4张量误差)、性能 (134/271/332ms) 全流程日志
  • assets/npu_device_call.png - npu-smi info + torch.npu.is_available() + device_name Ascend910_9362 + 参数 device npu:0 + 958.7M 参数量
  • assets/model_result.png - python inference.py 完整输出: 4 输出形状, 均值/极值, camera_poses 矩阵, conf >0.1 比率, PASS

9. 已知限制

  • 仅验证固定合成图像 (224x224/336x336 与 randn), 未覆盖真实图像集 (如 DTU/RealEstate10K) 上的相机位姿误差 (ATE) 或点图精度 (Chamfer) 完整评测; 官方论文 SOTA 数据需以真实数据集复测为准, 但本仓已证明 NPU 计算图与权重正确
  • 使用 FP32, 虽精度最高但显存 3.75 GiB、延迟 134ms, Large 模型若需更高吞吐可尝试 BF16/FP16 (需验证 SVD 落回 CPU 仍正确)
  • cuRoPE2D CUDA 编译版不可用, 回退到 Python 版 RoPE, 在 Ascend 上功能正确但可能比 CUDA 慢 10-20%; 不影响几何精度
  • torch.svd 在 NPU 上通过 CPU 中转, 增加少量 D2H/H2D 开销, 已计入 134ms 延迟; 若后续 CANN 支持 linalg.svd NPU 原生, 可移除补丁以再提速
  • 输入必须满足 H%14==0 && W%14==0, N*H*W 受 PIXEL_LIMIT 255000 建议 (本仓 224x224×2=100352, 448x448×2=401408 超限但仍可运行, 建议 336x336×2=225792 为限内最佳)
  • npu-smi 显示无运行进程时 HBM 已占 3110 MB 为系统保留, 本模型峰值 3755 MB 为增量, 不影响 64GB 总量

10. 标签

Hardware: NPU, NPU, Ascend, Ascend910, Pi3, image-to-3d, visual-geometry, DINOv2, RoPE, 3D-reconstruction