第 19 课 · ONNX 合同:部署件的形状与校验
这一课解决什么问题:策略文件从训练机到真机要过好几道手,任何一手出错,你装上鸭子的都可能是一个"没练成"或"没导对"的文件。这一课给你一套校验清单,保证上板的文件真的没问题。
1. ONNX 是什么:模型的通用交付格式
ONNX 是一种模型的通用交付格式:不管用什么框架训练,最后都导出成一个 .onnx 文件,任何支持它的运行时都能加载执行。
类比:训练框架各有各的存法;交付时统一转成 PDF——格式锁死,谁打开都一样。鸭子这边,官方 Rust 运行时就是那个 PDF 阅读器。
回扣第 01 课:浏览器 Sandbox 和真机跑的是同一种文件。
2. 合同条款:61 → 14,一个数都不能动
这份文件签了死合同:obs[1,61] → actions[1,14] @ 50Hz。61 维观测的布局在 microduck-replica/docs/训练参数调整与新动作开发指南.md 第 4 节写得清清楚楚:
| 索引 | 内容 |
|---|---|
| 0–2 / 3–5 | 躯干角速度 / 投影重力(身体歪了多少) |
| 6–19 / 20–33 | 关节角 / 关节速度(各 14,嘴巴除外) |
| 34–47 | 上一次策略原始动作 |
| 48–50 | 速度指令 vx, vy, yaw_rate |
| 51–54 / 55–60 | 头颈 4 关节 / 身体姿态命令槽 |
输出的 14 个动作顺序也是死的:0–4 左腿、5–8 颈头、9–13 右腿。真机 15 只舵机,第 15 个(嘴)不归策略管。
为什么叫合同:改观测顺序、归一化或关节顺序,文件照样能加载——但权重读到的数全对不上号,鸭子当场表演"大脑健全、四肢错乱"。所以新技能用不到的命令槽要保留并填零,不能删——否则无法与现有运行时热切换。
3. 为什么不能手写 torch.onnx.export
torch.onnx.export 是 PyTorch 自带的导出函数。但进阶文档 2.2 节反复强调:必须用官方脚本 scripts/export.py。
原因在"归一化":61 个观测不是直接喂网络的,先过一层归一化(把差几十倍量纲的数拉到统一尺度,网络才学得动)。官方脚本会把这层归一化烘进 ONNX 图里;手工只转网络,仿真回放可能一切正常,真机收到的却是未归一化输入——权重再对也白搭。
一句话:手工转 checkpoint ≠ 官方部署件。
4. 先分清:「训练没成」还是「导出没成」
鸭子动得不对,先定位问题在哪一环。用 uv run play <TASK_ID> --wandb-run-path <...> 回放 checkpoint:
- 回放也走不好 → 训练没成,回第 06 课看曲线;
- 回放走得好、导出后不行 → 导出没成,九成是归一化层或观测顺序被动过。
进阶文档 2.4 节共列五条常见错误,其中三条:手工转忘了归一化层、悄悄改观测顺序、部署加了训练没验证的滤波。
5. 部署前校验清单
装上真机前,按顺序过四道门:
- 文件可追溯:文件名写清出自哪个 run,别用
output.onnx这种转眼不认识的名字; - 形状核对:61 进 14 出。
robotd(板子上的控制守护进程)会拒绝一切形状不对的 ONNX——这是安全网,不是障碍; - 先跑要部署的那个文件:
uv run scripts/infer_policy.py --walking <你的文件.onnx>——必须是"真正要上板的那一个"。它用 50Hz 控制 + BAM 执行器复演部署路径; - 真机加载有仪式:scp 上板后
sudo robotctl policy load walk /home/microduck/walk.onnx——先回 HOME 姿态、再加载、继续驱动;policy list看 7 个槽位,policy reset walk恢复官方策略。
上了真机也别撒手:按指南 13.6 节测试金字塔一级一级来,从单舵机台架、悬空低增益,到软垫站立、低速直行(第 20 课细讲)。
6. 动手练习(10 分钟)
- 对官方
alpha_walking.onnx跑一遍infer_policy.py,记录"加载成功、会走"的输出; - 给文件改个名再跑,确认好坏看的是内容不是文件名;
- 合上资料,默写 61 维观测前三段各是什么。
自查清单
- [ ] 我能用 PDF 类比讲清 ONNX 是什么
- [ ] 我能背出合同 61 → 14 @ 50Hz,并说出至少四段观测的内容
- [ ] 我能解释手工 torch.onnx.export 为什么会造出"看着能用"的坏文件
- [ ] 我能说出部署前的四道校验门
下一课预告
文件验好了,该让它进身体了。第 20 课进车间:装配顺序、热熔螺母、第一次上电的安全清单。
延伸资源
- 契约与质量门出处:
microduck-replica/docs/训练参数调整与新动作开发指南.md第 4、13 节 - 可复现训练与 ONNX 导出:
open-microduck/docs/zh-CN/simulation/reproducible-training-and-export.md - 进阶文档第 0、2 节(两条铁律):
docs/进阶学习文档-训练仿真与部署.md - ONNX 官网:onnx.ai