pollen-robotics/microduck_rl 源码：https://github.com/pollen-robotics/microduck_rl

Microduck RL

Microduck（https://github.com/pollen-robotics/microduck）的强化学习训练环境——一个约800克、约25厘米高的双足机器人——基于mjlab（https://github.com/mujocolab/mjlab）（MuJoCo Warp）构建，使用PPO算法。策略在此以50Hz频率训练，导出为ONNX格式，并通过pollen-robotics/microduck（https://github.com/pollen-robotics/microduck）中的运行时部署到真实机器人上。

https://github.com/user-attachments/assets/50c3d537-8db2-4005-9d9c-3472faeec4d0

该仓库包含了完整的仿真到现实转换方案：BAM（https://github.com/Rhoban/bam）执行器物理模型、域随机化、间隙模拟，以及使其成功工作的奖励设计经验（精炼方案参见AGENTS.md）。

快速开始

需要CUDA GPU（训练通过MuJoCo Warp运行）和uv（https://docs.astral.sh/uv/）。

在ARM设备（DGX Spark / GB10, Jetson）上： uv sync 首次运行时会下载约2GB的CUDA轮子包，uv默认的30秒HTTP超时可能导致下载中断。首次同步时请设置 UV_HTTP_TIMEOUT=600。

git clone https://github.com/pollen-robotics/microduck_rl
cd microduck_rl

# 训练行走策略（使用您的GPU；在4096个环境中训练约1-2小时可获得可用步态）
uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 4096

# 在查看器中观看训练好的策略
uv run play Mjlab-Velocity-Flat-MicroDuck --wandb-run-path

# 导出用于部署的ONNX模型
uv run scripts/export.py Mjlab-Velocity-Flat-MicroDuck --wandb-run-path <...>

# 在CPU MuJoCo中通过键盘驱动导出的策略
uv run scripts/infer_policy.py --walking output.onnx

从检查点恢复：

uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 4096 \
  --agent.run-name resume --agent.load-checkpoint model_29999.pt --agent.resume True

没有GPU？在任何训练命令中添加 --hf-jobs，可在Hugging Face Jobs上运行而非本地执行（参见scripts/hf/README.md）。

任务列表

uv run list-envs 可打印当前注册的所有环境。在指定任务中存在平面/粗糙地形变体。

部署时，运行时通过共享的61维观测契约热切换这些策略（行走/恢复/特技），因此其中任何一个策略都可以随时接管机器人。scripts/infer_policy.py 正是演练这个过程：

uv run scripts/infer_policy.py --walking walk.onnx --standing stand.onnx \
  --sitstand sitstand.onnx --roulade roulade.onnx --new-cmd-obs

键盘控制（速度指令，G 地面拾取，Y 坐/站，R 翻滚，K/L 踢球）；支持 --debug、--save-csv、--record 用于仿真到现实的对比分析。

间隙变体

每个主要任务都有一个间隙变体，在模型中为14个伺服关节中的每一个串联了±1°的齿轮间隙（总共2°）进行训练：在任务ID中的 MicroDuck 前插入 -Backlash，例如 Mjlab-Velocity-Flat-Backlash-MicroDuck。间隙建模专为仿真到现实设计：每个伺服都有一个无驱动的 passive__backlash 铰链，并且由于真实编码器位于间隙的输出端，固件PD仿真（BacklashEncoderBamActuator）和 joint_pos/joint_vel 观测都穿过间隙进行读取（qpos[servo] + qpos[backlash]）。观测和动作维度不变，因此ONNX导出和运行时无需更改。参见 src/mjlab_microduck/tasks/backlash.py。

执行器模型

所有任务都使用BAM（https://github.com/Rhoban/bam）M6执行器模型，适用于Dynamixel XL330（电压控制律、反电动势、库仑/斯特里贝克/负载依赖性摩擦），并在每个环境中对电池电压、负载下的电压降、指令延迟和摩擦力大小（src/mjlab_microduck/actuator/中的FrictionDRBamActuator）进行域随机化。

在如此微小的规模——微型伺服驱动约800克的双足机器人——执行器保真度是仿真到现实差距的主要因素，这就是为什么执行器建模细致到电压控制律，而非理想的PD控制。

机器人模型

MJCF模型位于 src/mjlab_microduck/robot/microduck/，使用onshape-to-robot（https://github.com/Rhoban/onshape-to-robot）从Onshape导出，每个模型对应一个 config_mjcf_*.json 文件：

scene*.xml 文件将机器人与地板和关键帧（STAND/SIT/FOLD）打包，用于快速查看和 infer_policy.py。

项目结构

src/mjlab_microduck/
├── robot/
│   ├── microduck/           # MJCF导出文件、导出配置、场景、add_backlash.py
│   └── microduck_constants.py  # 机器人配置、HOME坐标系、BAM执行器配置
├── actuator/
│   └── friction_dr_bam.py   # BAM + 摩擦域随机化 + 间隙编码器反馈
├── tasks/
│   ├── __init__.py          # 任务注册（基础 + 间隙变体）
│   ├── mdp.py               # 奖励、事件、观测、自定义类
│   ├── backlash.py          # make_backlash_variant() 环境配置包装器
│   └── microduck_*_env_cfg.py  # 每个任务族一个配置模块
├── train_cli.py             # `train` 入口点（+ --hf-jobs）
└── hf_jobs.py               # Hugging Face Jobs 提交

重要约定：

• 观测布局在所有策略间共享（61维执行器观测：48维本体感知 + 指令 [twist(3), head_pose(4), body_pose(6)]），这使得运行时策略热切换成为可能。不使用指令槽位的环境会用零填充而非丢弃。
• 无驱动关节均命名为 passive_*（滚轮轮子、间隙铰链）；执行器、关节观测和姿态奖励通过 ^(?!passive_).* 选择伺服关节。
• 域随机化开关是每个环境配置文件顶部的 ENABLE_* 布尔值。
• 关节布局（14个伺服）：0–4左腿（髋偏航、髋横滚、髋俯仰、膝盖、脚踝），5–8颈/头（颈俯仰、头俯仰、头偏航、头横滚），9–13右腿。
• 导出器将观测归一化器烘焙到ONNX图中——始终部署由 scripts/export.py 生成的ONNX模型，切勿使用手动转换的检查点，否则策略在运行时会接收到未归一化的观测。

AGENTS.md 记录了环境构建工作流和项目中学到的奖励设计规则（也适用于在此仓库工作的AI编码代理）。

测试

uv run --with pytest pytest tests/```

仅CPU的配置不变性和奖励函数回归测试——这些测试锁定了关节索引映射、奖励符号约定和NaN防护。

## 相关项目

- microduck（https://github.com/pollen-robotics/microduck）— Microduck项目主页，包括运行导出策略的机载运行时
- mjlab（https://github.com/mujocolab/mjlab）— 训练框架（MuJoCo Warp + rsl_rl）
- BAM（https://github.com/Rhoban/bam）— 更好的执行器模型，由Rhoban开发

## 许可证

本项目采用Apache 2.0许可证。详情参见[LICENSE](LICENSE)文件。3D模型文件采用知识共享署名-非商业性使用-相同方式共享许可证。