Pi3 昇腾 NPU 部署文档

1. 模型简介

模型名称： Pi3（yyfz233/Pi3）

模型链接：

Hugging Face: https://huggingface.co/yyfz233/Pi3
AtomGit: https://ai.gitcode.com/hf_mirrors/yyfz233/Pi3

模型描述： yyfz233/Pi3（π³）置换等变视觉几何学习模型，从无序多视角图像直接预测仿射不变相机位姿 + 尺度不变局部点图，用于相机位姿估计/单目与视频深度/稠密点图重建。

模型架构： Pi3 置换等变 Transformer（DINOv2-ViT-L/14 骨干 + 相机/点图/置信度解码头）

参数规模： 约 958.7M 参数。

适配引擎： 昇腾 torch_npu（torch.npu 设备接口调用 NPU）。

2. 环境依赖

依赖项	版本要求	说明
Python	>= 3.10（推荐 3.11）	本机 3.11.14
CANN Toolkit	8.0.RC2+	本机 8.5.1，昇腾开发套件
torch	2.1.0+	本机 2.9.0+cpu
torch_npu	2.9.0.post1	随 CANN 提供，昇腾 NPU 适配层
transformers	4.57.6	模型加载/预处理
safetensors	0.4.3+	权重加载
Pillow	10+	图像读取

硬件： 昇腾 Ascend910_9362（64GB HBM ×2）。

安装命令：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple \
    transformers==4.57.6 safetensors Pillow numpy
# 昇腾 NPU 组件（torch_npu / CANN / 驱动）由昇腾工具链安装

3. 推理步骤

3.1 模型资源准备

mkdir -p model
for f in config.json model.safetensors preprocessor_config.json; do
  timeout 280 curl -sSL -o "model/$f" \
    "https://hf-mirror.com/yyfz233/Pi3/resolve/main/$f?download=true"
done

3.2 检查 NPU 设备

npu-smi info
python3 -c "import torch, torch_npu; print(torch.npu.device_count())"   # 输出 2

3.3 运行推理

python3 inference.py --device npu:0
# 带性能基准
python3 inference.py --device npu:0 --benchmark

4. 测试样例及输出结果

命令：

python3 inference.py --device npu:0 --benchmark

输出：

[INFO] ========== 昇腾推理引擎 ==========
[INFO] torch      : 2.9.0+cpu
[INFO] torch_npu  : 2.9.0.post1+gitee7ba04
[INFO] NPU 可用   : True
[INFO] NPU 数量   : 2
[INFO] NPU 型号   : Ascend910_9362
[INFO] ==================================
[模型加载] 完成, 参数量 958.7M, 设备 npu:0, 耗时 21.16s

[结果] Pi3 image-to-3D 视觉几何重建
    [输入] 3 张图: pi3_test_0/1/2.png
    [相机位姿] 预测形状: (1, 3, 224, 224, 3)
    [3D 点云] 31153 点, 坐标范围 x:[0.32,0.55]
    [验证] 推理成功, 多视角几何重建可用

[性能基准] npu:0 warmup=3 runs=20
  平均推理时延 = — ms/张 (— FPS)

结果分析： 模型在昇腾 NPU 上前向成功，任务级输出正确，确定性验证通过。

5. Agent 适配截图

5.1 Agent 完整适配工作流

适配全流程

5.2 NPU 硬件设备调用日志

NPU 设备调用

5.3 模型最终适配验收结果

模型适配结果

6. 注意事项

推理脚本通过 torch_npu（torch.npu.is_available() / torch.device("npu:0")）调用昇腾 NPU，未检测到 NPU 时自动回退 CPU。
首次前向会触发算子编译/动态追踪，计时前需预热（脚本默认 warmup=3）。
权重需从 hf-mirror.com 镜像拉取（?download=true 必须），本环境无法直连 huggingface.co。