一句话:给一堆没有顺序的照片,直接还给你相机在哪、空间点是啥样的。 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 接口,让上层的点云后处理、可视化能直接接。
实测过的最小环境如下(其它组合未逐一验证):
| 项 | 实测值 |
|---|---|
| 芯片 | Ascend 910(单芯即可,本机双芯 8/9 号) |
| 驱动 / CANN | 8.5.1 配套版本 |
| Python | 3.11.14 |
| torch | 2.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,下载中途断流的概率不低。
先自检再起服务,两步走:
# 第一步:离线自检,确认权重能对上、能正常前向
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 就是好了。
三个探针,按顺序打:
# 探活
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 打开能看到一个完整点云。
拿官方 house 数据集 6 视图、672×378 分辨率在 910 单芯上测的(fp32,无优化):
几个影响性能的关键变量:视图数 N 和分辨率直接决定 token 序列长度(每视图 H/14 × W/14 个 token),N=8 比 N=2 的耗时接近翻倍。图像建议控制在 255000 像素以内。开 --bf16 可以再压一压耗时。
这次适配坚持"权重零改动"原则,逐项核对:
load_state_dict 报 missing=0, unexpected=0,和官方 from_pretrained 一致,没有做任何重映射。scaled_dot_product_attention,行为不变。因为模型是纯前馈、无采样,同权重同输入在 NPU 和 GPU 上的输出是确定可比的。
config.json 里没有 model_type,vllm serve 直接报 "Unrecognized model"。用它的人得换 inference.py 这条路径。load_images_as_tensor 会自动规整,但手拼张量时别踩。ss -tlnp 看下端口再起,别去 kill 别人的进程。inference.py 推理入口:--mode selfcheck / --mode serve
requirements.txt 依赖清单(torch_npu 需与 CANN 配套)
pi3/ 模型实现(随 HF Space 分发)
assets/ 辅助资产与说明
test_client.py Smoke 验证客户端