Y
YYPGD/Pi3
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

Pi3 昇腾NPU部署文档

1. 模型简介

模型名称: Pi3(yyfz233/Pi3,pi3\\pi^3pi3: Scalable Permutation-Equivariant Visual Geometry Learning) 模型链接: https://ai.gitcode.com/hf_mirrors/yyfz233/Pi3 模型描述: pi3\\pi^3pi3 是一个前馈式视觉几何重建 Transformer:输入一组无序图像(无需固定参考视图),采用完全置换等变(permutation-equivariant)架构,直接回归仿射不变的相机位姿与尺度不变的局部点图,可同时完成相机位姿估计、单目/视频深度估计和稠密点云重建等任务。 模型架构: DINOv2 ViT-L/14-reg 编码器 + RoPE100 位置编码 + 置换等变全局注意力 Decoder(large: dim=1024, 24 层)+ 相机头(CameraHead)与点回归头(LinearPts3d / ConvHead),输出全局点云、局部点图、置信度与相机外参。 参数规模: 约 959M(model.safetensors 约 3.8GB)

2. 环境依赖

依赖项版本要求说明
Python>= 3.10推荐 3.11
torch / torch_npu2.1.0+NPU 上需安装 torch_npu
pi3官方源码包随 libs 目录分发(inference.py 自动注入 sys.path)
omegaconf / huggingface_hub / safetensors最新版模型加载依赖
opencv-python-headless / pillow / numpy最新版图像处理与可视化
plyfile最新版点云导出(可选)
昇腾驱动CANN 8.0.RC2+推荐最新版

安装命令:

pip install --target /mnt/workspace/Pi3/libs -i https://pypi.tuna.tsinghua.edu.cn/simple opencv-python-headless pillow numpy plyfile huggingface_hub safetensors omegaconf
# 官方代码包已随仓库预置到 libs/pi3

3. 推理步骤

3.1 环境准备

# 检查 NPU 设备
npu-smi info
# 权重已就位
ls /home/developer/models/Pi3/   # config.json model.safetensors README.md

3.2 运行推理

PYTHONPATH=/mnt/workspace/Pi3/libs python3 inference.py --model_path /home/developer/models/Pi3

3.3 推理参数说明

参数类型默认值说明
--model_pathstr/home/developer/models/Pi3本地权重目录
--devicestr自动(npu > cuda > cpu)推理设备
--num_framesint3示例输入帧数
--image_sizeint224示例输入分辨率(14 的倍数)
--outputstrassets/model_result.png结果图保存路径

4. 测试样例及输出结果

样例 1:内置合成多帧样例(纹理平面平移缩放模拟相机运动)

输入:

python3 inference.py --model_path /home/developer/models/Pi3

输出:

[INFO] device = npu
[INFO] 模型加载完成 load_time=xx.xs
[INFO] 输入张量: (1, 3, 3, 224, 224) dtype=torch.float32
[INFO] 推理完成 耗时/elapsed=xx.xs (frames=3, size=224, device=npu)
[INFO] 全局点云形状: (3, 224, 224, 3), 置信度图形状: (3, 224, 224), 相机位姿形状: (3, 4, 4)
[RESULT] status=ok device=npu 耗时/elapsed=xx.xs

样例 2:调整帧数与分辨率

输入:

python3 inference.py --model_path /home/developer/models/Pi3 --num_frames 2 --image_size 154

输出:

[INFO] 输入张量: (1, 2, 3, 154, 154) dtype=torch.float32
[INFO] 推理完成 耗时/elapsed=xx.xs ...
[RESULT] status=ok device=npu 耗时/elapsed=xx.xs

5. Agent适配截图

5.1 Agent适配全过程截图

Agent 适配流程

5.2 NPU设备调用截图

NPU 设备调用

5.3 模型适配结果截图

模型适配结果

6. 注意事项

  • 推理脚本通过 torch_npu 调用 NPU,设备自动选择 npu > cuda > cpu;
  • 官方代码不在 PyPI 上,pi3 以纯 Python 源码包形式随 /mnt/workspace/Pi3/libs 分发,inference.py 开头自动注入 sys.path;
  • 模型加载使用 PyTorchModelHubMixin.from_pretrained(本地路径),权重仅从本地 --model_path 加载,推理全程离线;
  • 输入为 float32 张量 (1,N,3,H,W)、取值 [0,1],H/W 需为 14 的倍数;NPU 计算全程 float32(无 float64 算子);
  • 注意力为官方 FlashAttentionRope 实现,fp32 下自动走 SDPA math/efficient 后端(非 flash_attention_2 外部依赖),NPU 兼容;
  • 官方 bf16 autocast 路径会强制 SDPBackend.FLASH_ATTENTION(CUDA 专属),本脚本改用 fp32 前向以保证 NPU 可跑;
  • 输出 dict 含 points/local_points/conf/camera_poses 四项;结果图左侧为深度伪彩色、右侧为置信度热力图;
  • 如有精度差异请与官方 pipeline(yyfz/Pi3 GitHub)输出对比确认。