fbybl/Pi3
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

Pi3 图像转 3D 重建:昇腾 NPU 上的可复现推理记录

1. 这个模型是做什么的

一句话:给一堆没有顺序的照片,直接还给你相机在哪、空间点是啥样的。 Pi3(π³)出自《Scalable Permutation-Equivariant Visual Geometry Learning》(arXiv 2507.13347),走的是 DUSt3R / VGGT 这条"前馈重建"路线,但把"必须先定一张参考帧"这条老规矩去掉了——输入怎么排,输出都稳定,这对多视角拼接、SLAM 预处理这类场景特别友好。

模型主体是一棵 ViT 大网络:前面用 DINOv2 ViT-L/14 把每张图切成 14×14 的 patch 提特征,中间是 36 层带 RoPE2D 的 Transformer 块做视图间的几何推理,后面分出三条头——点图头(逐像素 3D 点 + 置信度)、相机头(SVD 正交化成旋转矩阵)。全模型 958.7M 参数。

本仓库的价值在于:把这套 CUDA 生态的前馈网络,无改权重地跑到了昇腾 910 上,并且提供了一致的 HTTP 接口,让上层的点云后处理、可视化能直接接。

2. 部署前要准备什么

实测过的最小环境如下(其它组合未逐一验证):

项实测值
芯片Ascend 910(单芯即可,本机双芯 8/9 号)
驱动 / CANN8.5.1 配套版本
Python3.11.14
torch2.9.0(配 torch_npu 2.9.0.post1)
硬盘权重 3.83GB + 模型包,建议留 8GB

先把东西备齐:

git clone https://gitcode.com/hf_mirrors/yyfz233/Pi3.git     # 权重
git clone https://hf-mirror.com/spaces/yyfz233/Pi3           # 模型源码(pi3 包随 Space 分发)
pip install -r requirements.txt

提醒一句:权重 3.8G 下完最好先 sha256sum 对一下 33580e4702ac671558aedeab1148fd08118f7ce45bdbeb99f3e3cf340062875d,下载中途断流的概率不低。

3. 如何启动服务

先自检再起服务,两步走:

# 第一步:离线自检,确认权重能对上、能正常前向
python inference.py --mode selfcheck --data ./test_input/house

# 第二步:起服务(端口被占就换,比如 8321 -> 8421)
NPU_VISIBLE_DEVICES=8 python inference.py --mode serve --host 0.0.0.0 --port 8321

第一次起服务会看到模型构建 + 权重加载的日志,全程约 50 秒。看到 Application startup complete 就是好了。

4. 上线后怎么验证

三个探针,按顺序打:

# 探活
curl -s http://127.0.0.1:8321/health

# 看模型元信息
curl -s http://127.0.0.1:8321/v1/models

# 真正发一条推理(内部会把图片 base64 编码后 POST)
python test_client.py --images ./test_input/house --num-views 6 --save-ply

期望看到:status: ok、模型 ID yyfz233/Pi3、返回体里 points.shape=[1,6,H,W,3] 且各统计量为有限数、camera_poses 是 6 个 4×4 矩阵。--save-ply 会在服务端生成一个 .ply,用 trimesh 或 MeshLab 打开能看到一个完整点云。

5. 跑起来后性能怎么样

拿官方 house 数据集 6 视图、672×378 分辨率在 910 单芯上测的(fp32,无优化):

  • 单次前向端到端:约 5.5 秒(不含图片解码和 base64 开销)
  • 模型加载:约 50 秒(大头是读 3.8G safetensors)
  • NPU 显存峰值:约 10GB,单卡 64GB 富余很大
  • 采样窗口内 AICore 利用率在 40%~90% 波动

几个影响性能的关键变量:视图数 N 和分辨率直接决定 token 序列长度(每视图 H/14 × W/14 个 token),N=8 比 N=2 的耗时接近翻倍。图像建议控制在 255000 像素以内。开 --bf16 可以再压一压耗时。

6. 结果准不准

这次适配坚持"权重零改动"原则,逐项核对:

  • 权重对齐:load_state_dict 报 missing=0, unexpected=0,和官方 from_pretrained 一致,没有做任何重映射。
  • 算子对齐:模型里用到的 SDPA(FLASH / MATH 两种 kernel)、NPU autocast、SVD 正交化,逐项在 NPU 上验证通过;xformers 缺失时自动落到原生 scaled_dot_product_attention,行为不变。
  • 输出合理性:用 house 8 视图复测,点云统计量正常、相机位姿第 4 行恒为 [0,0,0,1]、置信度经 sigmoid 后落在 (0,1),没有 NaN/Inf。

因为模型是纯前馈、无采样,同权重同输入在 NPU 和 GPU 上的输出是确定可比的。

7. 有哪些坑要避开

  • 别拿 vLLM 硬跑:这是图像重建网络,不是 LLM,config.json 里没有 model_type,vllm serve 直接报 "Unrecognized model"。用它的人得换 inference.py 这条路径。
  • 输入尺寸要盯死 14 的倍数:patch 是 14,H、W 不是 14 的倍数会出 shape 错误;load_images_as_tensor 会自动规整,但手拼张量时别踩。
  • 别在外面再做归一化:模型内部自带 ImageNet mean/std,buffer 里已经算好了,你只需要送 [0,1] 的原始像素。
  • 多服务共机:这台机器上可能同时跑着别的模型服务,ss -tlnp 看下端口再起,别去 kill 别人的进程。
  • 下载断流:3.8G 文件中途会断,建议用断点续传的方式拉(本仓库下载脚本已内置续传逻辑)。

8. 仓库内容速览

inference.py        推理入口:--mode selfcheck / --mode serve
requirements.txt    依赖清单(torch_npu 需与 CANN 配套)
pi3/                模型实现(随 HF Space 分发)
assets/             辅助资产与说明
test_client.py      Smoke 验证客户端