企业官网建设流程全解析

Microduck RL 与 microduck 官方仓库如何分工：训练侧与运行时的完整地图

【免费下载链接】microduck_rlRL training environments for Microduck (mjlab)项目地址: https://gitcode.com/GitHub_Trending/mi/microduck_rl

Microduck RL（microduck_rl）是 Microduck 双足机器人项目的强化学习训练侧仓库：基于 mjlab（MuJoCo Warp）+ PPO，为这台约 800 g、25 cm 高、14 个伺服的双足小鸭子训练 50 Hz 的运动策略，再导出 ONNX 部署到真机。它与官方 microduck 运行时仓库形成"训练 → 导出 → 部署"的完整闭环。本文给你一张清晰的分工地图：谁负责什么、数据怎么流动、接口契约是什么。

🗺️ 一句话分工

两边通过一个硬接口解耦：一份 61 维观察 + 14 维动作的policy.onnx，外加 schema 2 的manifest.json。运行时通过策略热切换（walk / stand / trick）接管机器人，任何策略都能在任意时刻"接手"，这正是两边能独立演进的基石。

🏋️ 训练侧：microduck_rl 做了什么

这个仓库是完整的sim2real 配方：

• 机器人模型：src/mjlab_microduck/robot/microduck/ 下是从 Onshape 导出的 MJCF 模型，按用途分版本——robot_walk.xml（走步，碰撞精简）、robot_groundcontact.xml（倒地类任务，精细碰撞集）、robot_groundcontact_rollers.xml（轮滑任务）等
• 执行器保真：src/mjlab_microduck/actuator/friction_dr_bam.py 用 BAM M6 模型把 XL330 伺服建模到电压控制律层面（反电动势、库仑/Stribeck 摩擦），并叠加电池电压、电压跌落、指令延迟、摩擦系数等域随机化——在这个尺寸上，执行器保真就是 sim2real 差距的大头
• 任务环境：src/mjlab_microduck/tasks/ 里每个任务族一个 cfg 文件，注册表在 src/mjlab_microduck/tasks/init.py。涵盖走步（Velocity）、跌倒恢复（VelStand）、翻身（StandUp/Roulade）、轮滑（Rollers/Swizzle/Slope）、捡取（GroundPick）、踢球（BallKick）等，且每个主任务都有-Backlash-变体（±1° 齿轮间隙）
• 奖励工程经验：AGENTS.md 沉淀了整套"血泪教训"：奖励符号约定、防 reward-hacking 的状态门控、潜基形变、课程调度等

常用命令（详见 README.md）：

uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 4096 # 训练 uv run play Mjlab-Velocity-Flat-MicroDuck --wandb-run-path <run_id> # 仿真中观看 uv run scripts/export.py <TASK> --wandb-run-path <run_id> # 导出 ONNX uv run scripts/infer_policy.py --walking out.onnx # CPU 端部署预演 uv run publish --onnx out.onnx --repo <user>/microduck-<name> --kind episodic --duration-s 4.0

没有本地 GPU？给任何 train 命令加--hf-jobs即可提交到 Hugging Face 托管 GPU 上跑（见 scripts/hf/README.md）。

⚙️ 运行时侧：microduck 官方仓库做了什么

官方仓库是机器人的"身体和大脑"：

• 50 Hz 控制回路：ONNX 策略推理、安全逻辑、跌倒检测、里程计、运动学——这些代码与真机完全一致
• 策略管理：守护进程按 policy manifest schema 2 校验策略，拒绝图形状不符（非[1,61] -> [1,14]）、输出含 NaN 的权重
• robotctl命令行：robotctl policy add / load / robot do完成策略的安装、装槽和触发，一条命令安装社区策略，无需等守护进程发版

本仓库刻意不做这些运行时逻辑——src/mjlab_microduck/publish/manifest.py里那句注释说得很直白：本模块写 manifest，守护进程读它，契约文档在官方仓库。

🔗 交汇点：一个 61 维观察契约

这是分工地图的核心，两边必须严格遵守：

1. 61 维 actor 观察= 48 维本体感知 + 13 维指令块[twist(3), head_pose(4), body_pose(6)]，顺序固定。不用的指令槽位零填充而非删除，保证所有策略可以热切换
2. 14 个动作对应 14 个伺服：0–4 左腿、5–8 颈/头、9–13 右腿；非驱动关节统一命名passive_*（轮子、backlash 铰链）
3. normalizer 烘焙进 ONNX：scripts/export.py 把观察归一化器直接烧进 ONNX 图——仿真里 play 看不出来这个 bug，真机上就会让策略看到未归一化的观察，所以永远走 export 导出，不要手转 checkpoint
4. 只发布"恒指令"策略：episodic（跑--duration-s后自己回到站立，如踢球、空翻）和 perpetual（持续运行，如新走姿--slot walk或保持姿态--unwind-s）两类可发布；阶段驱动/姿态旗标类策略（如地面捡取）由守护进程自己驱动，留在官方策略集里

发布前 src/mjlab_microduck/publish/ 会自动做形状门（[1,61] -> [1,14]，51 维旧策略直接拒收）、冒烟输入测试（拒 NaN / 常值输出）、从 git + wandb 填training溯源块（任务、commit、branch、run、checkpoint）。

📦 完整流水线：从训练到真机一步一图

mjlab 训练（GPU，4096 并行环境，PPO） │ checkpoint (model_XXXXX.pt) ▼ scripts/export.py → ONNX（烘焙 normalizer） │ ▼ uv run publish → HF Hub 仓库（policy.onnx + manifest.json + README） │ ▼ 真机：robotctl policy add <name> <user>/microduck-<name> │ ▼ robotctl robot do <name> → 守护进程 50 Hz 运行

上真机之前还有一个重要的"排演"环节：scripts/infer_policy.py 在 CPU MuJoCo 里用与训练相同的 BAM 执行器模拟伺服，键盘下发速度指令和G/Y/R/K等动作键，多策略同时加载模拟热切换——src/mjlab_microduck/sim/body_server.py 更进一步，把整个仿真身体通过 TCP 喂给官方仓库的robotd（robotd --sim 127.0.0.1:7801），让真机侧代码原封不动地跑在仿真身体上。

📂 关键路径速查

❓ 新手常见问题

Q：我拿到真机策略，需要理解 microduck_rl 吗？不需要。运行时只认policy.onnx+ manifest；理解本仓库只对"想训练新策略"的人必要。

Q：为什么观察必须 61 维，不能按任务裁剪？这是热切换的前提。裁剪维度 = 运行时换策略时会错位，等于每次都要改守护进程。

Q：训练环境报错，先看什么？先跑 5 次迭代的 smoke test（64 环境）抓掉 95% 的配置错误，再看 AGENTS.md 的"不变量"一节——那里列的都是破坏后"仿真里好好的、真机上翻车"的坑。

Q：怎么开始？

git clone https://link.gitcode.com/i/59bbd3f227e3b05ab0f4aab47798b694 cd microduck_rl uv run list-envs # 看看都有哪些训练任务 uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 64 --agent.max_iterations 5

一句话总结分工：microduck_rl 造"会走路的大脑"，microduck 官方仓库是"戴大脑的鸭子"——前者管训练与导出，后者管运行与安全，中间的桥梁就是那份 61 维观察契约。

【免费下载链接】microduck_rlRL training environments for Microduck (mjlab)项目地址: https://gitcode.com/GitHub_Trending/mi/microduck_rl