第 05 课 · 第一次训练:5 次迭代冒烟测试
这一课解决什么问题:完整走一遍 训练 → 回放 → 导出 → 验证 四步,并用 5 次迭代的"冒烟测试"确认你的训练链路是通的。先说清楚:5 次迭代出不了可用步态,它验证的是管线,不是质量。
前置:第 04 课,以及第 03 课装好的环境。
1. 训练的完整四步
# ① 训练(GPU;官方参考:4096 并行环境的 walking 任务约 1–2 小时出可用步态)
uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 4096
# ② 回放训练结果(先分清"训练没成"还是"导出没成")
uv run play Mjlab-Velocity-Flat-MicroDuck --wandb-run-path <entity/project/run_id>
# ③ 导出 ONNX —— 必须用官方脚本!
# 它会把 observation 归一化层写进 ONNX 图;手工转 checkpoint ≠ 官方部署件
uv run scripts/export.py Mjlab-Velocity-Flat-MicroDuck --wandb-run-path <...>
# ④ 用第 03 课的方法验证"真正要部署的那个文件"
uv run scripts/infer_policy.py --walking output.onnx
类比:①是上课做千万道题,②是翻开错题本检查学得怎么样,③是把成绩单办成通行证(ONNX),④是拿通行证过安检。四步缺一不可,且②必须在③前面:先确认"练成了没有",再谈"部署"。
今天只要求你在自己电脑上把这条管线用最小规模跑通,即冒烟测试。
2. Mac 无 GPU 的两个坑(真实事故)
本项目的构建日志里,2026-09-06 第一天就栽了这两跤,原文照录:
坑一:训练一启动就崩 IndexError: list index out of range(崩在 mjlab 的 select_gpus)。原因:训练器默认 gpu_ids=[0],无 CUDA 的机器上 GPU 列表为空,按索引取值直接越界。解法是把环境变量设成空,显式声明"我要用 CPU":
CUDA_VISIBLE_DEVICES="" uv run train ...
坑二:默认日志器是 wandb,没配 API key 直接报错。解法:加 --agent.logger tensorboard,改用本地方案(与官方冒烟参数一致)。
于是 Mac 上的标准冒烟命令(出自 microduck-replica/docs/训练参数调整与新动作开发指南.md 第 5 节):
CUDA_VISIBLE_DEVICES="" uv run train Mjlab-Velocity-Flat-MicroDuck \
--env.scene.num-envs 64 \
--agent.max_iterations 5
3. 5 次迭代到底在测什么
看本项目 2026-09-05 的真实记录(experiment-log.csv 的 lesson-01 行):8 个并行环境 × 每环境 24 步 × 5 次迭代 = 960 次采样,每个环境只经历约 2.4 秒仿真时间。
结果:mean_reward 从 -0.0614 升到 0.0950(网络确实在被更新);但摔倒终止率仍接近 1.0,yaw 转向误差反而从 0.1374 涨到 0.1716——鸭子还在每集必摔。所以那天的结论写的是两句,一句都不能合并:
训练和导出流程通过;步态学习尚未开始到可以评价的程度。
日志状态栏写的是 passed,备注是 pipeline smoke test; not a usable walking policy。
4. 所以,冒烟测试的意义是什么
**验证链路通,不是验证质量。**类比:新车下线先点火看仪表盘——转速表能动、没有故障灯,这叫冒烟;至于百公里加速几秒,点火这一步不回答。reward 从负变正极易造成"它学会走路了"的错觉,请把第 3 节那两句结论背下来。真正的质量判断要看曲线——第 06 课的内容。
5. 验收:阶段一的清单
指南第 5 节的原始验收标准,逐条过:
uv run list-envs | rg MicroDuck能看到Mjlab-Velocity-Flat-MicroDuck;- 5 次迭代没有维度、配置、NaN 错误;
- 回放能看到鸭子、能改变速度命令:
CUDA_VISIBLE_DEVICES="" uv run play Mjlab-Velocity-Flat-MicroDuck --checkpoint-file <model_xxx.pt> --viewer viser --num-envs 1(Mac 上用--viewer viser,浏览器打开); - 知道新日志写到
logs/rsl_rl/<experiment_name>/下面。
动手练习(30 分钟)
跑完冒烟测试,照 experiment-log.csv 的表头(id/date/task/device/num_envs/iterations/status/notes)给自己建一行 lesson-01。status 写 passed/failed,notes 必须写清"这是链路测试,不是步态评价"。
自查清单
- [ ] 我能默写 训练 → 回放 → 导出 → 验证 四步,并说清每步干什么
- [ ] 我知道 Mac 无 GPU 的两个坑和各自解法
- [ ] 我能解释"冒烟测试通过"和"训练成功"为什么是两句话
- [ ] 我的实验表里已经有了自己的 lesson-01 行
全部打勾,进入第 06 课:看懂训练曲线。
下一课预告
第 06 课读曲线:优先看哪几个指标、reward 涨为什么可能是在骗你、expD 那次"站稳了但没走成"的完整复盘。
延伸资源
- 进阶学习文档第 2 节(训练四步的出处):
docs/进阶学习文档-训练仿真与部署.md - 同题材长文《5 次迭代,能证明强化学习环境可用吗?》:
docs/microduck-30day/articles/day-01-5-iteration-smoke-test.md - 实验总表(你的表应该长得像它):
docs/microduck-30day/experiments/experiment-log.csv