Microduck RL – 小型双足机器人的仿真到现实训练

它是什么 – 一组 MuJoCo-Warp 环境和训练脚本，教导一个 800 克、25 厘米高的双足机器人（Microduck）行走、站立、翻滚、滑冰、踢球等。策略通过 PPO 学习，导出为 ONNX，然后由配套的微鸭运行时在物理机器人上运行。

为什么重要

完整的仿真到现实流水线 – 使用 BAM 致动器模型（电压控制的 Dynamixel XL330），具有真实的摩擦、齿隙和域随机化。这种保真度是这种小型伺服驱动机器人仿真与现实差距的最大来源。
可热插拔的策略 – 所有策略共享一个 61 维观测向量，因此机器人可以在不重新启动守护进程的情况下切换行走、恢复、技巧等。
开源可复现 – 从 MJCF 机器人文件（从 Onshape 生成）到训练命令、导出脚本和发布工作流，一切都已提供。

工作原理（高层流程）

环境定义 – src/mjlab_microduck/tasks/*_env_cfg.py 描述每个任务（例如，Mjlab-Velocity-Flat-MicroDuck）。它们设置地形、奖励函数和随机化标志。
训练 – 运行 uv run train <task> --env.scene.num-envs 4096。PPO 通过 MuJoCo Warp 在 GPU 上运行；典型的步态在 1-2 小时内完成。
检查 – uv run play … 在 MuJoCo 查看器中可视化检查点；您也可以录制视频。
导出 – scripts/export.py 将检查点转换为已经包含观测归一化器的 ONNX 图。
发布 – uv run publish … 将 ONNX 文件和清单上传到 Hugging Face Hub，使其可安装在任何 Microduck 机器人上。
部署 – 在机器人上，robotctl policy add … 和 robotctl policy load walk … 加载策略；守护进程在运行时将其切换。

关键组件

组件	作用
BAM 致动器模型	模拟电压控制、反电动势、库仑和斯特里贝克摩擦，以及可选的 ±1° 齿轮间隙（齿隙）。
MJCF 机器人文件	从 Onshape 导出；多个变体（`robot_walk.xml`、`robot_groundcontact.xml`、`robot_groundcontact_rollers.xml`，以及齿隙版本）。
任务注册表 (`src/mjlab_microduck/tasks/__init__.py`)	注册每个环境，包括自动生成的齿隙孪生环境。
训练 CLI (`train_cli.py`)	围绕 mjlab 训练框架的轻量包装器；与上游 mjlab CLI 相同。
导出/推理脚本	`scripts/export.py` 生成 ONNX；`scripts/infer_policy.py` 在 CPU MuJoCo 中运行策略以进行快速测试。
发布工具	打包 ONNX + `manifest.json` + README 并推送到 Hugging Face，处理验证（形状、NaN、归一化器）。
测试	小的 pytest 套件检查奖励符号约定、关节索引一致性和 NaN 防护。

快速入门（快速步骤）

# 克隆并进入
git clone https://github.com/pollen-robotics/microduck_rl && cd microduck_rl

# 训练行走步态（需要 GPU）
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
uv run scripts/export.py Mjlab-Velocity-Flat-MicroDuck --wandb-run-path <...>

# 可选：发布到 Hugging Face
uv run publish --onnx output.onnx --repo <user>/microduck-walk --kind perpetual --slot walk

没有 GPU？ 添加 --hf-jobs 将训练卸载到 Hugging Face Jobs。

典型用例

研究 – 在现实世界的双足机器人上实验域随机化、致动器建模或新的奖励设计。
教育/演示 – 用几行代码展示小型机器人执行技巧（翻滚、轮滑）。
社区共享 – 将自定义步态或技巧发布到 Hugging Face Hub；任何拥有 Microduck 的人都可以立即安装。

许可证与归属

代码：Apache 2.0。
3D 网格：CC-BY-NC-SA 4.0（参见 LICENSE-MODELS.md）。

Microduck RL 是现代仿真到现实强化学习在物理机器人上的具体端到端示例，包括真实的致动器物理、域随机化和精简的发布工作流。

pollen-robotics/microduck_rl