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(批量)接口,同时输出确定性动作与采样动作该模型为非自回归生成式模型,无 tokenizer、无文本模态,不适用 vLLM 的 token 化生成管线(详见注意事项)。
本次适配在以下环境中完成全部验证:
| 组件 | 版本 |
|---|---|
| 操作系统 | Linux (aarch64) |
| NPU 硬件 | Ascend 910(双芯,64GB HBM/芯) |
| CANN | 8.5.1 |
| Python | 3.11.14 |
| torch / torch_npu | 2.9.0 / 2.9.0.post1 |
| numpy | 1.24+ |
| FastAPI / uvicorn | 0.123.10 / 0.46.0 |
| vllm / vllm_ascend | 0.18.0(本模型不依赖,见注意事项) |
权重为 ONNX 文件,可从原始 Hugging Face 仓库或镜像下载:
# 本仓库仅含推理代码,权重需单独下载(约 2.3MB)
curl -L -o Huggy.onnx \
https://hf-mirror.com/PaulVialard/ppo-Huggy/resolve/main/Huggy.onnxpip install -r requirements.txtpython inference.py --mode selfcheck --device npu:0自检会加载权重,对中性/轻度偏离/随机扰动三组观测逐组推理,输出确定性动作、采样动作、动作均值与标准差。
# 指定 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 端口。
# 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.pySmoke 通过标准: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 最大差 |
|---|---|
| 动作均值 mu | 1.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,验证正确。
vllm serve 无法承载。请使用本仓库 inference.py。Huggy.onnx 不在本仓库内,需从 HF 镜像单独下载(约 2.3MB),下载后可用 sha256 校验完整性,避免截断损坏。/predict 接口的 sample=true 分支使用可复现 seed 的高斯噪声(默认固定 seed),如需真实随机采样可传入不同 seed。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 # 资产说明