ppo-Pyramids 昇腾 NPU 部署文档

在昇腾 Ascend 910 NPU 上，使用 torch + torch_npu（按仓内官方 Pyramids.onnx 推理图 1:1 重建 actor） 方式部署 Nablaaa/ppo-Pyramids，推理已完整跑通。

1. 模型简介

项目	内容
模型名称	Nablaaa/ppo-Pyramids
模型链接	https://huggingface.co/Nablaaa/ppo-Pyramids
AtomGit 镜像	https://ai.gitcode.com/hf_mirrors/Nablaaa/ppo-Pyramids
模型描述	Pyramids 金字塔探索 PPO 策略（Unity ML-Agents）
结构/规模	Unity ML-Agents PPO 离散策略（353.8K 参数；3x56 路射线观测 + 4 维向量 =172 -> Linear(172,512)+Swish x2 -> 5 离散动作）
部署方式	torch 2.9.0+cpu / torch_npu 2.9.0.post1，device=npu:0（Ascend 910，CANN 8.5.1）
推理脚本	`inference.py`（本仓根目录）

Nablaaa 用 Unity ML-Agents PPO 训练的 Pyramids 环境策略（378 万步，RND intrinsic reward 辅助探索：拾取方块点亮机关、解锁金字塔拿金砖）。inference.py 在 NPU 上加载仓内最终检查点，按仓内官方 onnx 导出图逐键重建 actor 网络（Swish 激活、5 离散动作、动作掩码），做策略推理验证。

2. 环境依赖

类别	软件	版本
硬件	Ascend 910 NPU（本机 Ascend910_9362）	torch.npu.device_count()>=1
驱动	CANN Toolkit	8.5.1
Python	CPython	3.11.14
框架	torch / torch-npu	2.9.0+cpu / 2.9.0.post1
依赖	见 requirements.txt	pip install -r requirements.txt

运行前加载 CANN 环境：source /usr/local/Ascend/ascend-toolkit/set_env.sh

3. 模型权重获取

模型权重已随仓附带。如需从源仓重新获取：

export HF_ENDPOINT="https://hf-mirror.com"
python -c "from huggingface_hub import snapshot_download; \
snapshot_download('Nablaaa/ppo-Pyramids', local_dir='.')"

4. 推理操作步骤

# 1) 环境
pip install -r requirements.txt
# 2) 运行
source /usr/local/Ascend/ascend-toolkit/set_env.sh
python inference.py

5. 测试用例与输出结果

命令：python inference.py（npu:0），完整输出如下（实测）：

================================================================
Nablaaa/ppo-Pyramids · ML-Agents PPO 策略 · 昇腾 NPU 推理
================================================================
[1] 设备: npu:0 -> Ascend910_9362
[2] 策略重建+权重加载完成（353.8K 参数，strict=True 全键命中），耗时 1.0s
[3] CPU vs NPU logits 最大绝对误差: 1.53e-05（float32 一致性验证）
[4] 4096 条观测批量前向: 0.14 ms/次
[5] 确定性 argmax               动作分布: 不动:0.0% 前进:44.4% 后退:0.0% 左转:20.5% 右转:35.1%
[5] 随机 multinomial           动作分布: 不动:0.4% 前进:43.9% 后退:0.0% 左转:20.7% 右转:35.0%
[5] 掩码(禁后退) argmax           动作分布: 不动:0.0% 前进:44.4% 后退:0.0% 左转:20.5% 右转:35.1%
PASS: ppo-Pyramids 策略在 npu:0 上完成推理（前向/采样/掩码全链路）

运行过程中的 NPU 进程占用见 assets/npu_device_call.png（npu-smi info 实录），推理结果输出见 assets/model_result.png，适配工作流见 assets/agent_workflow.png。

6. 已知问题与适配说明

1. 验证口径

Pyramids 运行环境是 Unity 编译的 x86-64 可执行文件（仓内 config.json 的 env_path），本机 aarch64 NPU 服务器无法拉起 Unity 做回合 rollout；按「策略网络推理」口径验证：合成观测前向 + CPU/NPU 数值一致性 + 采样/掩码，权重逐键加载零改动。

2. 结构依据

actor 结构以仓内 Pyramids.onnx（官方导出同策略推理图）为准：obs_0/1/2(各 56)+obs_3(4) concat=172，Swish=Sigmoid*x；normalize=false 无归一化层。

3. 检查点选取

仓内含 89 个训练检查点，仅保留最终 Pyramids-3778906.pt 与官方导出 Pyramids.onnx 随仓。

7. 目录结构

ppo-Pyramids/
├── inference.py        # NPU 推理脚本（本适配新增）
├── README.md           # 本文档
├── requirements.txt    # 依赖清单
├── ORIGINAL.md         # 原仓 README（若有）
├── assets/             # 验收截图
│   ├── agent_workflow.png
│   ├── npu_device_call.png
│   └── model_result.png
└── （其余为原仓权重与元数据文件）

适配说明：除新增 inference.py / README.md / requirements.txt / assets/ 及将原仓 README 更名为 ORIGINAL.md 外，原仓权重与元数据文件零改动；89 个历史训练检查点仅保留最终 Pyramids-3778906.pt（仓内 Pyramids/ 其余检查点与 tfevents 训练日志未随仓，减重 770MB->9.8MB）。