80 lines
4.8 KiB
Markdown
80 lines
4.8 KiB
Markdown
# MJRL 机器人平台
|
||
|
||
<!-- tracks: README.md @ sha256:124d41b6e17eb69c -->
|
||
|
||
[English](README.md) · [接入流程](docs/WORKFLOWS.md) · [命令手册](docs/USAGE.zh.md)
|
||
|
||
把机器人模型导入 MuJoCo,验证动力学和控制响应,再打包为原生仿真应用。
|
||
平台可以适配兼容的外部策略,也可以通过同一训练环境在原生 MuJoCo CPU 或
|
||
MuJoCo Warp GPU 上训练运动策略。
|
||
|
||
| 层级 | 起点 | 产物 |
|
||
|---|---|---|
|
||
| 0 | 网格、URDF 或缺少已验证控制的 MJCF | 可编译模型和查看应用 |
|
||
| 1 | 兼容策略与明确的观测、动作和关节元数据 | 适配后的 ONNX、布局及数值一致性结果 |
|
||
| 2 | 完整模型与已知运动学 | 确定性控制器及原生验证报告 |
|
||
| 3 | 站姿已标定且控制意图明确的足式机器人 | 机器人规格及锁定形态模板训练 |
|
||
|
||
## 使用 AI Agent 进行接入与训练(推荐)
|
||
|
||
建议使用 AI Agent(如 Claude Code、Antigravity、Cursor、Codex 等)直接打开本仓库根目录文件夹,并通过自然语言指挥 AI 进行机器人接入、训练与打包。
|
||
|
||
仓库内置了 [AGENTS.md](AGENTS.md)、[CLAUDE.md](CLAUDE.md) 以及位于 `.claude/skills/` 下的专用工作流技能(`setup-env`、`onboard-asset`、`tier1-adapt`、`tier2-control`、`tier3-train`、`new-task`、`train`、`controls`、`deploy`、`bundle-manual`)。在仓库根目录下打开后,AI Agent 会自动读取工作规则与验证门禁——你只需告知 URDF、MJCF 或网格模型路径,即可指挥 AI 自动完成环境配置、模型检查与站姿标定、生成 `tasks/<robot_id>/robot_spec.py`、启动或恢复 PPO 训练、执行量化回放评测以及打包原生 `.app` 应用。
|
||
|
||
## 运行模型查看应用
|
||
|
||
在代码库根目录中使用 Python 3.10–3.13:
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
python -m pip install -e ".[dev]"
|
||
python scripts/onboard.py inspect assets/smoke/smoke_biped.xml
|
||
python scripts/deploy.py --robot viewer_smoke --model assets/smoke/smoke_biped.xml --bundle out/viewer_demo
|
||
python scripts/play.py --app out/viewer_demo/viewer_smoke.app --headless --steps 20
|
||
```
|
||
|
||
选择尚未使用的输出目录。Windows 上使用 `.venv\Scripts\Activate.ps1` 激活。
|
||
该模型用于检验加载与打包。接入自己的机器人时,替换为实际模型并按检查报告的建议继续。
|
||
|
||
## 接入自己的机器人
|
||
|
||
1. 用 `scripts/onboard.py inspect` 检查模型和可用的配置或策略元数据。URDF
|
||
和独立网格可用 `build-mjcf` 转换。
|
||
2. 根据[接入流程](docs/WORKFLOWS.md)选择层级。打包可控制应用前,分别验证
|
||
动力学和命令响应。
|
||
3. 足式机器人先标定站姿,再用 `scaffold-tier3` 生成
|
||
`tasks/<robot_id>/robot_spec.py`。双足、四足、轮足双足和多足模板负责
|
||
观测、奖励、域随机化、课程和 PPO。
|
||
4. 用 `python scripts/train.py --list` 查看注册机器人,用
|
||
`python scripts/train.py --task <robot_id> --dry-run` 检查参数解析。
|
||
|
||
原生 `.app` 包含模型、资产依赖、控制器或策略以及 Python 入口。宿主提供
|
||
Python 和所列依赖。现有 Rust 浏览器与板端走独立的旧版包格式。轮足双足的混合
|
||
动作可导出并在原生运行时回放,旧版 Rust 使用其位置动作布局。
|
||
|
||
四个模板分别在原生 CPU 和 Warp GPU 上用合成模型完成过一次 PPO 更新,
|
||
用于验证执行路径。
|
||
|
||
[Go1 示例](assets/go1_example/README.md)还在 RTX 5080 上完成了 1,000 次 PPO
|
||
更新。选定检查点在 0.400 m/s 前进命令下,18 秒回放平均速度为 0.401 m/s,
|
||
平均绝对误差为 0.022 m/s,无重置。原生检查点与 ONNX 回放通过了前进、后退、
|
||
横移、转向及静止探测。这些是平地仿真结果,不是硬件资格认证,也不代表每个
|
||
机器人都能用相同训练规模学会控制。
|
||
|
||
[轮足双足示例](assets/wheeled_biped_example/README.md)验证了腿部位置与车轮速度
|
||
混合控制。所选策略通过了原生前进、后退、转向和静止探测,并在其声明的
|
||
±0.91 m/s 和 ±0.77 rad/s 范围内完成键盘及手柄测试。
|
||
[G1 双足示例](assets/g1_example/README.md)在完成 7,800 次 Warp 更新后,通过了
|
||
七项独立原生探测和满量程键盘测试。
|
||
[研发记录](docs/REFACTOR_STATUS.md)汇总已验收应用、未通过的试验及实测原因。
|
||
|
||
## 参考
|
||
|
||
- [项目指南](docs/PROJECT_GUIDE.zh.md):导航与支持边界说明。
|
||
- [教程](docs/TUTORIAL.zh.md):验证、训练与量化回放流程。
|
||
- [Colab](docs/COLAB.zh.md):在 GPU 上训练已注册的机器人。
|
||
- [硬件与模型参数](docs/HARDWARE.zh.md):标定要求与执行器输入规范。
|
||
- [部署指南](deploy/README.zh.md)与[部署包格式](deploy/BUNDLE.md):应用结构与运行时契约。
|
||
- [贡献指南](CONTRIBUTING.md):目录结构与仓库检查项。
|