p
pnflly/ppo-Huggy
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

ppo-Huggy 昇腾 NPU 强化学习策略服务化适配

一、简介

PaulVialard/ppo-Huggy 是开源强化学习教程 Hugging Face Deep RL Course 中训练出的 Huggy 游戏智能体策略。Huggy 是 Unity 引擎中一只通过跳跃收集爱心的小怪兽,本模型即控制 Huggy 完成跳跃收集动作的深度强化学习策略,使用 PPO(Proximal Policy Optimization)算法在 ML-Agents 环境上训练得到。

官方权重以 ONNX 格式发布(Huggy.onnx,2.27MB),核心为一个 多层感知机(MLP)策略网络:

项值
输入obs_0,59 维连续观测(Huggy 位姿、速度、与目标相对位置等)
网络输入归一化 → 3 层 SiLU 全连接(59→512→512→512)→ 动作均值头(512→21)
输出deterministic_continuous_actions(21 维确定性动作)、continuous_actions(21 维高斯采样动作)
参数量0.57M(566,805)
动作缩放动作均值 / 3.0

本仓库将该策略网络适配到 昇腾 910 NPU,实现服务化推理:

  • 权重零改动:直接解析官方 Huggy.onnx 中的 initializer 构建等价 PyTorch 网络,数值与原 ONNX 完全一致(numpy 参照前向对比 max diff ~1e-4,float32 精度内)
  • 服务化接口:torch_npu + FastAPI,提供 /predict(单条)与 /v1/actions(批量)接口,同时输出确定性动作与采样动作
  • 适用场景:将训练好的 RL 策略部署到 NPU 上进行实时动作决策,可作为游戏 AI、仿真控制等场景的推理后端

该模型为非自回归生成式模型,无 tokenizer、无文本模态,不适用 vLLM 的 token 化生成管线(详见注意事项)。

二、验证环境

本次适配在以下环境中完成全部验证:

组件版本
操作系统Linux (aarch64)
NPU 硬件Ascend 910(双芯,64GB HBM/芯)
CANN8.5.1
Python3.11.14
torch / torch_npu2.9.0 / 2.9.0.post1
numpy1.24+
FastAPI / uvicorn0.123.10 / 0.46.0
vllm / vllm_ascend0.18.0(本模型不依赖,见注意事项)

三、服务启动

3.1 拉取权重与代码

权重为 ONNX 文件,可从原始 Hugging Face 仓库或镜像下载:

# 本仓库仅含推理代码,权重需单独下载(约 2.3MB)
curl -L -o Huggy.onnx \
  https://hf-mirror.com/PaulVialard/ppo-Huggy/resolve/main/Huggy.onnx

3.2 安装依赖

pip install -r requirements.txt

3.3 离线自检(可选)

python inference.py --mode selfcheck --device npu:0

自检会加载权重,对中性/轻度偏离/随机扰动三组观测逐组推理,输出确定性动作、采样动作、动作均值与标准差。

3.4 启动服务化推理

# 指定 NPU 设备(本机 NPU_VISIBLE_DEVICES=8,9,npu:0 对应 8 号芯片)
NPU_VISIBLE_DEVICES=8 python3 inference.py --mode serve \
  --host 0.0.0.0 --port 8580 --device npu:0

服务启动约 1-2 秒(模型加载),就绪后监听 8580 端口。

四、Smoke 验证

# 1. 健康检查
curl http://127.0.0.1:8580/health
# {"status":"ok","model":"PaulVialard/ppo-Huggy","device":"npu:0"}

# 2. 模型列表
curl http://127.0.0.1:8580/v1/models
# 返回 model id、task=reinforcement-learning、obs_dim=59、action_dim=21

# 3. 单条推理(59 维观测 -> 21 维动作)
python3 test_client.py

Smoke 通过标准:HTTP 200、deterministic_actions 与 sampled_actions 均为 21 维有限浮点数、动作均值与标准差符合 PPO 分布预期。

五、性能参考

基于昇腾 910 单芯实测(模型极小,性能裕量极大):

项目数值
模型加载~1.1s(含 ONNX 解析与权重载入)
单条推理延迟(预热后)~0.8ms
批量 4 条推理~1.2ms
压测吞吐(300 请求)373.8 req/s(p50 21.2ms)
压测吞吐(20000 请求)352.4 req/s(p50 44.8ms,p99 58.1ms)
大批量(10000 条观测)611ms/批(单请求)
NPU 前向对比8×59 批量 0.279ms/iter vs CPU 0.897ms/iter(快 ~3.2 倍)
HBM 占用3444MB(含 NPU 上下文),服务进程 ~202MB

说明:该模型参数量仅 0.57M,对 Ascend 910 算力占用可忽略(AICore 观测为 0%),实际瓶颈在 HTTP 传输与 batch 数据处理。单芯 64GB HBM 中余量极大。

六、精度测评

采用权重零改动方案:直接解析官方 Huggy.onnx 的 initializer(14 个权重张量),构建等价 PyTorch HuggyPolicy。为验证权重转换准确性,编写 numpy 参照前向(严格复现 ONNX 图语义:归一化 → 3 层 SiLU → 动作头 → 除 3)进行对比:

指标numpy vs torch 最大差
动作均值 mu1.07e-4
确定性动作3.31e-5
采样动作3.78e-5
动作标准差0.0

以上差异均在 float32 数值精度范围内,证明 torch 模块与官方 ONNX 推理路径行为一致。

自检三组观测的输出均为合法的 21 维有限动作值:中性观测(obs=running_mean)动作均值约 [-1.21, 0.44, ...],确定性动作约 [-0.40, 0.15, ...];观测偏离时动作幅值相应增大,符合策略对状态的敏感性预期。确定性动作与采样动作仅差高斯噪声项,采样动作 = (mu + N(0,1)·std)/3,验证正确。

七、注意事项

  1. vLLM 不适用:该模型是 Unity ML-Agents 强化学习策略(非 LLM/VLM),无 tokenizer、无文本模态、registry 无 ML-Agents 架构,vllm serve 无法承载。请使用本仓库 inference.py。
  2. 权重下载:Huggy.onnx 不在本仓库内,需从 HF 镜像单独下载(约 2.3MB),下载后可用 sha256 校验完整性,避免截断损坏。
  3. 观测维度:输入必须是 59 维连续向量,与训练时观测空间一致;维度不符会直接报错。
  4. 动作缩放:确定性动作 = 动作均值 / 3.0,这是 ONNX 图内定义的 action_scale,不要手动移除该缩放,否则动作幅值会与训练分布不一致。
  5. 采样动作:/predict 接口的 sample=true 分支使用可复现 seed 的高斯噪声(默认固定 seed),如需真实随机采样可传入不同 seed。
  6. 端口冲突:宿主机可能同时运行多个模型服务,若 8580 被占用请换用其他端口(如 8680),不要终止他人进程。
  7. 设备映射:本机 NPU_VISIBLE_DEVICES=8,9,npu:0 对应物理 8 号芯片;使用前请以 npu-smi info 确认芯片空闲情况。

八、文件清单

├── inference.py        # 服务化推理入口(selfcheck / serve 两种模式)
├── test_client.py      # HTTP 推理测试客户端
├── requirements.txt    # 运行依赖
├── README.md           # 本文档
└── assets/             # 辅助资产
    └── README.md       # 资产说明