刚刚快速浏览了一下 microduck_rl，这个代码库非常优雅。我推荐阅读 agent.md，其中包含了许多有趣的奖励建模小技巧，比如头部跟踪——过度收紧会影响行走，因为头部占鸭子体重的 38%，因此会自然产生振荡。为了解决这个问题，他们使用指数移动平均（EMA）对头部跟踪误差进行平滑处理，本质上只惩罚直流偏置。随着深入代码库，还能发现其他一些小技巧，例如他们如何通过在电机串联添加一个无驱动铰链（极小范围）来模拟电机的齿隙。

点赞 @antoinepirrone

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 构建。策略在此处以 50 Hz 训练，导出为 ONNX，并通过 pollen-robotics/microduck（https://github.com/pollen-robotics/microduck）中的运行时部署到真实机器人上。

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

该仓库编码了完整的 sim2real 配方：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 会拉取约 2 GB 的 CUDA 包，uv 默认的 30 秒 HTTP 超时可能导致下载中断。首次同步时请导出环境变量 UV_HTTP_TIMEOUT=600。

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

# 训练行走策略（使用你的 GPU；约 1-2 小时，设置 4096 个环境可产生可用步态）
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 以进行 sim2real 对比。

齿隙变体

每个主要任务都有一个齿隙孪生任务，在一个模型上训练，该模型为 14 个伺服关节中的每一个串联了 ±1° 的齿轮间隙（总共 2°）。在任务 ID 中，将 -Backlash 插入 MicroDuck 之前即可使用，例如 Mjlab-Velocity-Flat-Backlash-MicroDuck。

齿隙的建模是为 sim2real 而正确进行的：每个伺服都有一个无驱动的 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 克的双足机器人——执行器保真度是 sim2real 差距的主要部分，这就是为什么执行器被建模到其电压控制律层面，而非理想的 PD 控制器。

机器人模型

MJCF 模型位于 src/mjlab_microduck/robot/microduck/，由 Onshape 通过 onshape-to-robot（https://github.com/Rhoban/onshape-to-robot）导出，每个模型一个 config_mjcf_*.json：

scene*.xml 文件将机器人与地面 + 关键帧（站姿/坐姿/折叠）包装在一起，用于快速查看和 infer_policy.py。

项目结构

src/mjlab_microduck/
├── robot/
│   ├── microduck/  # MJCF 导出文件、导出配置、场景、add_backlash.py
│   └── microduck_constants.py  # 机器人配置、HOME 坐标系、BAM 执行器配置
├── actuator/friction_dr_bam.py  # BAM + 摩擦力 DR + 齿隙编码器反馈
├── 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维的actor观察：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 文件。 3D 模型文件采用 Creative Commons BY-SA-NC 许可。