microduck_rl：双足机器人强化学习训练环境

项目摘要

项目名称：microduck_rl

平台：github

GitHub Stars：1,061

抓取时间：2026-08-31 22:38

首次公开时间：2025-12-06

License：Apache-2.0

官方仓库：https://github.com/pollen-robotics/microduck_rl

1. 核心功能

根据项目 README，microduck_rl 的核心功能涵盖以下几个维度。

训练环境集合：仓库提供多种训练任务，覆盖速度行走、站立恢复、起立、坐站切换、地面拾取、踢球、翻滚和轮滑等多个运动技能。每种任务还提供 Flat（平坦地形）和 Rough（崎岖地形）两种变体，用户可通过 uv run list-envs 查看完整的任务注册表。

sim2real 配方：所有任务均采用 BAM M6 执行器模型，该模型针对 Dynamixel XL330 舵机建模，包含电压控制律、反电动势、库仑/Stribeck/负载相关摩擦等物理细节。域随机化覆盖电池电压、电压跌落、命令延迟和摩擦幅度等多个维度，帮助策略学习对真实环境变化不敏感的鲁棒行为。

齿隙（Backlash）仿真：每个主要任务都有带 ±1° 齿隙（总计 2°）的 Backlash 版本，用于模拟真实舵机齿轮间隙。齿隙版本的观测和动作维度与标准版本保持一致，因此 ONNX 导出和运行时无需任何修改，用户可以无缝切换训练。

ONNX 导出与部署：训练完成的策略通过 scripts/export.py 导出为 ONNX 格式。根据 README，导出器会将观测归一化器烘焙进 ONNX 图中，这意味着部署时无需额外处理输入数据的标准化。导出的策略可在 CPU MuJoCo 环境中运行验证，也可直接部署到真实机器人。

断点续训：训练脚本支持从检查点继续训练，用户通过 --agent.load-checkpoint 和 --agent.resume 参数恢复中断的训练任务。

云端训练支持：对于没有本地 GPU 的用户，项目支持通过 Hugging Face Jobs 提交训练任务，只需在任何训练命令后添加 --hf-jobs 参数即可。

2. 技术或工作流程

环境建模

microduck_rl 的关键设计决策之一是观测空间的一致性。根据 README 的功能描述，所有策略共享相同的 61 维 actor 观测布局，未驱动关节统一命名为 passive_*（包括滚轮、齿隙轴等），域随机化开关以 ENABLE_* 布尔值形式放在每个环境顶部。

关节布局方面，Microduck 共有 14 个舵机，其中 0 至 4 号控制左腿（hip_yaw、hip_roll、hip_pitch、knee、ankle），其余关节控制右腿和身体其他部分。统一的观测和动作空间设计，使得不同任务之间的策略迁移和代码复用更加便捷。

训练流程

训练流程基于 mjlab 框架（MuJoCo Warp 加速）和 PPO 算法。MuJoCo Warp 在 GPU 上并行仿真大量环境，PPO 利用这些并行环境高效更新策略。README 给出的训练示例使用 4096 个并行环境，在 GPU 上训练一个可用的行走策略大约需要 1 至 2 小时。

完整工作流

以下流程基于 README 公开命令整理，展示从训练到部署的链路：

工作流步骤

训练：使用 uv run train 启动训练，指定任务名称和并行环境数量。
回放：使用 uv run play 在查看器中观察已训练策略的表现。
导出：使用 scripts/export.py 将策略导出为 ONNX。
验证：使用 scripts/infer_policy.py 在 CPU MuJoCo 中运行导出策略。
部署：由 microduck 仓库中的运行时加载 ONNX 模型，在真实机器人上执行。

3. 适用场景与落地建议

根据项目公开材料，microduck_rl 的适用场景可以从目标用户和技术方向两个维度来划分。

场景 1：双足机器人运动控制研究

适合对象：机器人学与强化学习交叉领域的研究者、高校实验室

接入与使用方式：克隆仓库后，通过 `uv run train` 在 GPU 上训练行走、站立恢复、起立等基本运动技能，并使用 `uv run play` 观察策略行为。研究者可以基于现有任务模板扩展新的奖励函数、观测空间或地形变体

能解决的问题：为双足运动控制研究提供一个开箱即用的基线系统，省去从零搭建 MuJoCo 仿真和 PPO 训练流程的工程成本。统一的观测空间设计和任务注册表让实验对比更加规范

使用限制与注意点：训练需要 CUDA GPU，MuJoCo Warp 对显卡型号和驱动版本有一定要求。搜索奖励函数和域随机化参数需要具备强化学习背景知识

场景 2：Sim2Real 迁移工程实践

适合对象：机器人产品团队、希望在真实机器人上部署 RL 策略的工程师

接入与使用方式：直接使用仓库中预设的 BAM 执行器模型与齿隙变体任务进行训练，将训练好的策略导出为 ONNX，再通过 pollen-robotics/microduck 中的运行时部署到 Microduck 真机

能解决的问题：项目中编码的 sim2real 配方（BAM 执行器物理、域随机化、齿隙模拟、奖励设计）是仿真到真实迁移中最容易踩坑的环节。使用这套工作流可以显著缩短从仿真到真机的时间

使用限制与注意点：该工作流是针对 Microduck 机器人验证的，如果要在其他机器人上复用，需要重新建模执行器、关节布局和动力学参数。齿隙版本的 ±1° 是针对 Microduck 舵机的特性设置，其他机型需根据实际舵机参数调整

场景 3：强化学习教学与实验

适合对象：高校课程教师、自学强化学习的学生、开源社区爱好者

接入与使用方式：利用 `uv run list-envs` 查看任务注册表，从简单任务开始逐步体验从训练到部署的完整流程。项目代码结构清晰，AGENTS.md 中记录了环境构建工作流和奖励设计经验，可作为教学辅助材料

能解决的问题：提供一个真实的、非玩具性的强化学习实践项目。与经典 Gym 环境相比，microduck_rl 涉及更丰富的 sim2real 细节，能让学生接触到 RL 在实体机器人上落地所面临的真实挑战

使用限制与注意点：项目对硬件有一定要求，本地没有 CUDA GPU 的用户需借助 Hugging Face Jobs 或其他远程 GPU 资源。此外，项目文档假设用户熟悉 Python 和基础强化学习概念

4. 安装与运行要求

根据项目 README，安装与运行分为以下几个步骤。

环境准备：确保系统满足 CUDA GPU 要求，并安装 uv 包管理器。

克隆仓库：

git clone
cd microduck_rl

训练行走策略：

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 <...>

在 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

5. 环境、硬件或依赖

项目对硬件和软件环境的要求可归纳为以下几点。

CUDA GPU 是训练的必要条件：训练过程依赖 MuJoCo Warp，该框架需要 NVIDIA CUDA GPU 支持，无法在纯 CPU 环境下完成训练。但导出的 ONNX 策略可以在 CPU 上运行推理验证。

uv 包管理器：项目使用 uv 管理依赖，所有训练、回放、导出命令均通过 uv run 执行。首次使用时需安装 uv 并同步项目依赖。

Hugging Face Jobs：无 GPU 环境的用户可在训练命令后添加 --hf-jobs 参数，将训练任务提交到 Hugging Face 云端 GPU 上执行。

ARM 设备注意点：根据 README 提示，在 ARM 设备（如 DGX Spark / GB10、Jetson）上首次运行时，uv sync 会拉取约 2 GB 的 CUDA wheels，uv 默认的 30 秒 HTTP 超时可能导致下载中断。建议先执行 export UV_HTTP_TIMEOUT=600 以延长超时时间。

6. 已知限制

需要先说明：官方 README 没有设置独立的“已知限制”章节，以下限制是从 README 的硬件要求、任务设计和命令参数中整理得出的，未经过真机验证的推断会单独标注。

训练依赖 CUDA GPU：MuJoCo Warp 对 GPU 计算能力有硬性要求，用户需自行确认显卡与驱动兼容性。

针对特定机器人建模：项目中的执行器模型、关节布局和齿隙参数均为 Microduck 定制。BAM M6 执行器模型针对 Dynamixel XL330 舵机建模，移植到其他机器人需要重新标定和验证。

行走策略训练时间：README 注明，在 4096 个并行环境的配置下，训练一个可用的行走策略约需 1 至 2 小时。更复杂的任务（如翻滚、轮滑）可能需要更长的训练时间和更多的调参迭代，但 README 未给出具体时长估算。

观测空间固定：所有策略共享 61 维 actor 观测空间。这一设计保证了任务间兼容性，但也意味着如果用户需要增加自定义传感器输入，必须修改基础观测布局并重新设计训练流程。

齿隙参数不可移植：齿隙变体采用统一的 ±1°（总计 2°），这一数值基于 Microduck 舵机的齿轮间隙特性。对于使用不同舵机型号的机器人，需根据实际参数重新设定。

7. 青峰联创分析

本节内容是基于 microduck_rl 项目公开发布的 README 和仓库代码结构进行的分析，属于分析性判断，并非官方承诺或实测结论。

项目成熟度评估：从项目结构和文档质量来看，microduck_rl 展现出较高的工程完成度。统一的观测空间设计、BAM 执行器建模、齿隙模拟、域随机化开关这四者构成了一套完整的 sim2real 工作流，而不是零散功能的堆砌。项目提供 AGENTS.md 作为奖励设计经验的浓缩文档，这通常表明作者在真实机器人上积累了充分的实践经验，才愿意将工程细节沉淀为文档。

技术路线判断：microduck_rl 选择 mjlab（MuJoCo Warp）+ PPO 作为训练基础设施，这是一个相当务实的技术选型。MuJoCo Warp 的大规模并行仿真能力可以显著缩短训练周期；PPO 作为稳定且经过广泛验证的在线 RL 算法，在机器人运动控制领域有大量成功案例。可以说，这一组合是当前小尺寸足式机器人 RL 训练的主流路线之一。

值得关注的设计细节：BAM 执行器模型的引入颇具亮点。很多开源 RL 项目对执行器的处理是简化甚至忽略的，而 microduck_rl 将电压控制律、反电动势、库仑/Stribeck 摩擦等物理细节纳入标准工作流，这直接关系到仿真策略能否在真实舵机上表现一致。该细节可能是项目 sim2real 成功率的决定性因素之一。

风险与边界：从分析视角看，该项目的高质量文档和完整工具链是加分项，但社区规模仍然有限，问题排查更多依赖 GitHub issue 和自主调试。用户在选择采用此项目时，建议结合自身硬件条件和任务需求，先在小规模任务上验证训练和部署流程，再逐步扩展至更复杂的运动技能。

项目采用 Apache-2.0 许可证，使用者自由度较高：可以用于商业项目、自由修改代码，且不需要发布衍生源码（与 GPL 系许可证相比限制更少）。需要留意的是，许可证仅覆盖代码部分，模型权重、训练日志等产物的使用方式需参照项目维护者的后续说明。