核心问题: mjlab + BAM + ONNX 这套 sim2real 配方能否迁移到你的机器人,还是主要作为 Microduck 级双足的参考?
RepoDaily 采用评分
RepoDaily 将该项目的采用分评为 88/100（强）：分数来自文章来源、安装路径、生产风险、差异化、许可证清晰度以及 AI/Agent 适配度。
包含 4 个来源、覆盖 4 类来源；如有 RepoDaily 独有模块，会进一步提高证据分。
检测到 5 个工作流步骤、4 个下一步动作，以及 2 个命令/安装信号。
趋势热度为 +384 stars；如内容中有 release、issue 或维护信号，会提高维护可信度。
采纳风险标记为 medium，并包含 4 条安全说明与 4 条跳过条件。
3 个机会视角、3 个替代方案，以及 4 个类型化模块支撑差异化判断。
文章中包含许可证来源或许可证表述。
文章正文和元数据中检测到 3 个 AI/Agent 相关信号。
项目概览
microduck_rl 是 Pollen Robotics 双仓库布局中的训练半边:本仓库承载强化学习环境,配套的 pollen-robotics/microduck 仓库承载在实体机器人上执行策略的运行时。机器人本体约 800 克、高约 25 厘米,注册表里的每个任务都围绕这具身体设计:带速度指令与头部姿态指令的行走、从俯卧/仰卧/坐姿起身、前滚翻、踩被动轮滑行,以及让'看不见球'的策略踢动 70 毫米、15 克的球。
技术底座是 mjlab 1.3.0——它通过 Warp(warp-lang 1.12.0)在 CUDA GPU 上运行 MuJoCo,训练算法为 PPO,50 Hz 的控制频率与实机部署一致。让这个仓库区别于普通环境合集的,是 sim2real 配方写得非常明白:BAM 执行器物理(来自 Rhoban better-actuator-models 的 mjlab_frictionloss 分支)、域随机化、齿隙(backlash)仿真,以及蒸馏在 AGENTS.md 里的奖励设计手册。策略导出为 ONNX 后,既可以用 scripts/infer_policy.py 在 CPU 版 MuJoCo 里驱动,也可以交给配套运行时部署到真机。
本周期它以 384 颗星排在趋势榜第 18 位——对一个绑定单一厂商硬件的仓库来说相当显眼。它能跨出 Microduck 用户圈的原因在于:训练循环、执行器建模和导出路径都可以复用,而且没有本地 GPU 时,--hf-jobs 标志能把同一条训练命令提交到 Hugging Face Jobs。
为什么现在变热
- 趋势周期内获得 384 颗星(第 18 名),README 开头就是真机视频:行走、起身、前滚翻、轮滑。
- 完整 sim2real 配方公开:BAM 执行器物理、域随机化、齿隙仿真,以及 AGENTS.md 中的奖励设计手册。
- 13 个任务族共 18 个任务 id,从 Mjlab-Velocity-{Flat,Rough}-MicroDuck 到 Mjlab-Spin-Flat-MicroDuck,`uv run list-envs` 可实时列出。
- 没有本地 GPU 也能试:任意训练命令加上 --hf-jobs 即可改交 Hugging Face Jobs 执行。
- Apache-2.0 许可含专利授权,分叉到其他小型双足项目没有法律顾虑。
解决什么问题
- 双足策略训练通常要手工拼装物理引擎、执行器模型、地形随机化和部署桥接——本仓库把这套拼装作为一个锁版整体交付。
- 理想化执行器会掩盖导致 sim2real 失败的齿轮齿隙;microduck_rl 显式仿真齿隙,而不是指望随机化兜底。
- 训练代码与部署代码常被锁在公司私有仓库里;这里拆分透明:本仓库训练并导出 ONNX,pollen-robotics/microduck 在硬件上运行。
- CUDA 环境的摩擦真实存在:首次 `uv sync` 要下载约 2 GB CUDA wheel,在 ARM 设备(DGX Spark / GB10、Jetson)上 uv 默认 30 秒 HTTP 超时可能让下载中途失败。
工作原理
- mjlab 通过 Warp 在 CUDA GPU 上并行运行数千个 MuJoCo 环境;README 的默认训练命令使用 4096 个环境。
- PPO 以 50 Hz 学习策略——与真机运行时消费动作的频率一致。
- BAM(better-actuator-models,导入名 `bam`)提供含摩擦损失的高保真执行器物理;域随机化与齿隙仿真包裹在机器人模型外层。
- 检查点通过 Weights & Biases 跟踪;`uv run play ... --wandb-run-path <entity/project/run_id>` 可在查看器中回放某次运行。
- `scripts/export.py` 把策略转成 ONNX,之后或由配套仓库的运行时部署到真机,或用 `scripts/infer_policy.py --walking output.onnx` 在 CPU 版 MuJoCo 中以键盘驱动。
架构解读:一个入口点、两个仓库、三处锁版
包名为 mjlab-microduck(版本 0.1.0),通过 `mjlab.tasks` 入口点注册到 `mjlab_microduck.tasks`——与 mjlab 自身使用的插件机制相同,因此这是对框架的扩展而非分叉。`train` 命令行脚本刻意遮蔽了 mjlab 自己的入口点:行为一致,额外提供把任务提交到 Hugging Face Jobs 的 `--hf-jobs` 标志(实现位于 train_cli.py)。
三个版本决定定义了整套栈:mjlab==1.3.0、warp-lang==1.12.0、Python >=3.12,<3.13。Python 上界来自 bam(better-actuator-models)对 requires-python <3.13 的锁定——曾经因为上界浮动,Hugging Face Jobs 选到了 3.13.14。其余依赖包括 onnxruntime>=1.24.4、rustypot>=1.4.2、huggingface_hub>=0.27.0、matplotlib>=3.10.9 与 scipy>=1.16。
命令面:从克隆到 ONNX 的完整 CLI 闭环
- `uv run list-envs`——打印实时任务注册表,不用猜任务 id。
- `uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 4096`——训练主行走任务;4096 环境下约 1–2 小时得到可用步态。
- `uv run play Mjlab-Velocity-Flat-MicroDuck --wandb-run-path <entity/project/run_id>`——在查看器中观看训练好的策略。
- `uv run scripts/export.py Mjlab-Velocity-Flat-MicroDuck --wandb-run-path <...>`——导出部署用 ONNX。
- `uv run scripts/infer_policy.py --walking output.onnx`——在 CPU 版 MuJoCo 中用键盘驱动导出的策略,无需 GPU。
- 断点续训:追加 `--agent.run-name resume --agent.load-checkpoint model_29999.pt --agent.resume True`。
- 任意训练命令可加 `--hf-jobs` 提交到 Hugging Face Jobs,细节见 scripts/hf/README.md。
- ARM 设备首次同步前先导出 `UV_HTTP_TIMEOUT=600`,否则约 2 GB 的 CUDA wheel 下载可能撞上 uv 默认 30 秒超时。
维护风险:四处依赖覆盖说明了问题
- 这里声明 scipy>=1.16,是因为 mjlab 1.3.0 在 terrains/heightfield_terrains.py 里导入 scipy 却未声明——全新 `uv sync` 之后连包都导入不了(2026-07-21 发现)。
- protobuf 被覆盖为 >=4.0,<7.0:bam 把 protobuf 锁在 <4,级联把 onnx 压到 1.17.0——该版本没有 wheel、源码构建会失败。
- PyPI 存根包 `zmq==0.0.0`(bam 的依赖)的预编译 wheel 无效(缺少 .dist-info);由于只用 bam.model/bam.actuator,通过永假标记将其剔除。
- mujoco 绝不能覆盖:mujoco-warp 锁定 mujoco 3.10.x,此前的覆盖曾强制降到 3.4.0,因缺少 mjDSBL_MULTICCD 导致导入崩溃。
- 版本号 0.1.0、修复注释日期 2026-07-21,说明依赖图年轻且仍在调整,锁版集合大概率会继续变动。
上手路径:第一次会话长什么样
在 CUDA 机器上,整条闭环一个下午就能走完:克隆仓库、`uv sync`(DGX Spark / GB10 或 Jetson 先设 `UV_HTTP_TIMEOUT=600`)、以 4096 环境训练速度任务一到两小时、在查看器回放、导出 ONNX,最后用键盘在 CPU 版 MuJoCo 里验证策略——全程不需要硬件。没有 CUDA GPU 时,加 `--hf-jobs` 就能在 Hugging Face Jobs 上跑同一套流程,试跑成本为零,但训练运行会进入你的 Hugging Face 账号。
谁适合关注
适合关注
- Microduck 硬件用户,想要参考训练管线而不只是运行时。
- 要把步态或跌倒恢复策略移植到相近体量(约 800 克、25 厘米)小型双足上的机器人工程师。
- 研究执行器保真度的研究者:BAM 摩擦损失建模对比理想力矩执行器。
- 想先看 mjlab 插件系统(`mjlab.tasks` 入口点)实际样例、再动手自建环境的人。
可以先跳过
- 面向四足、机械臂或无人机的项目——这里每个任务 id 都围绕 Microduck 双足的形态构建。
- 锁在 Python 3.13+ 的环境:bam 强制 requires-python <3.13。
- 不愿引入 Weights & Biases 做运行跟踪或 Hugging Face Jobs 做远程训练的场景——两者都织入默认流程。
- 期待稳定 API 的生产服务:包还在 0.1.0,覆盖注释里记录着上游持续破损。
风险与注意事项
Apache-2.0 且锁版可复现,但依赖图以文档化方式呈现脆弱性,任务集只针对一款机器人。
- Python 被 bam 锁在 3.13 以下,与更新的 CUDA 栈存在冲突风险。
- 需要四条 override-dependencies 才能让 `uv sync` 成功,每条都在修上游破损:mjlab 缺声明 scipy、protobuf/onnx 级联、zmq wheel 无效、mujoco-warp 锁版。
- 部署依赖配套 pollen-robotics/microduck 运行时;本仓库本身只产出 ONNX 文件。
- 包版本 0.1.0、修复日期 2026-07-21,说明锁版集合仍在变动。
- Apache-2.0,含第 3 条专利授权,商业使用与分叉没有歧义。
- 训练默认在本地 GPU 进行;`--hf-jobs` 会把运行送到 Hugging Face Jobs,检查点回放需要 Weights & Biases 的 run path——两条路径都会把数据带到第三方账号。
- 包内不含对外网络服务:本体是训练库加 CLI 脚本。
- 首次安装从 PyPI 镜像下载约 2 GB CUDA wheel;ARM 超时规避(`UV_HTTP_TIMEOUT=600`)已写入 README。
替代方案比较
| 方案 | 适用场景 | 代价 |
|---|---|---|
NVIDIA Isaac Lab | 需要厂商维护、覆盖多种机器人与传感器的 GPU RL 框架,而不只是一款双足。 | 免费、开源 |
legged_gym | 沿用 leggedrobotics/ETH 的四足运动管线,并与近年多数论文的环境写法对齐。 | 免费、开源 |
MuJoCo Playground | 更偏向 Google DeepMind 基于 MJX/JAX 的训练环境,而非基于 Warp 的 mjlab 栈。 | 免费、开源 |
这个趋势说明了什么
不分叉训练器就注册第二款机器人
任务经 `mjlab.tasks` 入口点(`mjlab_microduck.tasks`)插入,另一款小型双足可以通过发布自己的包加入注册表,而不必给本仓库打补丁。
为你的 MJCF 模型复制一份 Mjlab-Velocity-Flat-MicroDuck,确认新 id 出现在 `uv run list-envs` 输出中。
在 Microduck 之外复用 BAM 执行器物理
better-actuator-models 锁定自 Rhoban 的 mjlab_frictionloss 分支,这里只导入 bam.model/bam.actuator——同一套模型可以提升任何 mjlab 环境的执行器保真度。
在裸 mjlab 环境中导入 bam.model,对比单个关节与理想执行器的力矩曲线。
把策略迭代搬到 Hugging Face Jobs
遮蔽版 `train` 入口点上的 `--hf-jobs` 标志能在远端执行相同命令,把笔记本变成 4096 环境 PPO 任务的提交客户端。
用 `--hf-jobs` 提交一个短时 Mjlab-Spin-Flat-MicroDuck 任务,对比本地 GPU 的排队到检查点耗时。
RepoDaily 判断
microduck_rl 不是通用 RL 框架,而是一条针对一台 800 克双足的完整、有主见的 sim2real 管线——它的价值恰恰在这份完整:BAM 执行器物理、域随机化、齿隙仿真、18 个任务 id、ONNX 导出,外加远程算力出口,全部以 Apache-2.0 发布。如果你做小型双足,或想要一份最终落到真机上、最易读的 MuJoCo Warp 训练公开范例,值得采用;同时要把锁版依赖图(Python <3.13、四处覆盖)当作这份易读性的代价,先确认你的目标 Python 与 CUDA 栈能否装进去。