Files
2026-11-03 19:46:08 +08:00

9.2 KiB
Raw Permalink Blame History

Universal Humanoid

面向 AI 代码智能体的模块化人形机器人强化学习框架。

Universal Humanoid 将代码智能体与可复现的机器人工程流程连接起来,支持任务定义、奖励迭代、策略训练、定量评估、可视化回放和推理策略包导出。框架基于 mjlab、MuJoCo Warp 和 RSL-RL,将机器人专属配置与共享训练工具分离。

“Universal”指的是可扩展的工程架构,而不是一个无需适配就能控制所有机器人的策略。

English · 环境配置 · 训练运维 · 架构设计 · Agent 手册 · 验证记录

工作流程

开发者 / AI Coding Agent
          ↓
任务定义与奖励配置
          ↓
机器人适配 → mjlab → MuJoCo Warp → RSL-RL PPO
          ↓
检查点与实验记录
          ↓
定量评估 + 可视化回放
          ↓
经过校验的 ONNX 研究用策略包

可以直接使用 CLI,也可以让支持文件编辑与命令执行的代码智能体操作相同工具。项目不绑定某个模型厂商,不要求额外部署专用 Agent 服务;智能体使用各自配置的模型和工具。

核心能力

  • 仓库内后端:rl/mjlab、rl/rsl_rl、G1/T1 资产随项目安装,提供带哈希的依赖锁和源码清单。
  • 机器人自动检查:一次检查脚部 site、IMU 参考系、实际接触反馈、PD/限幅、关节顺序及初始姿态。
  • 模块化任务:机器人、环境和训练配置通过统一入口组合。
  • 奖励迭代:严格校验实验 JSON,支持权重、参数和 Python 奖励函数扩展。
  • GPU 强化学习:MuJoCo Warp 批量仿真与 RSL-RL PPO 训练,支持中间检查点及优化器续训。
  • 训练运维:Linux 后台任务、进度查询、安全停止,以及 TensorBoard 曲线读取与 JSON/CSV/SVG 输出。
  • 实验可追溯:保存配置、源码快照、依赖与资产指纹、检查点哈希。
  • 批量评估:多个检查点 × 评估 seed × 站立/前进/横移/转向,汇总均值、样本方差与定义明确的失败指标。
  • 压力评估:各世界分别随机初始化,可叠加观测噪声和随机速度扰动,记录实际扰动次数。
  • 检查点选择:按显式指标排序,支持同协议矩阵的配对比较,不自动批准部署。
  • 可视化回放:MP4、重置前逐步关节/力矩 CSV,集成 mjlab 原生与 Viser 查看器。
  • 策略导出:ONNX、观测/动作契约、关节顺序、推理一致性和完整性校验。
  • Agent 手册体系:setup-env、new-task、train、controls、deploy 及跨阶段 RL 手册;附环境脚本和文档/接口一致性测试。

项目状态

项目处于早期研究阶段。后端源码、适配器和示例模型已纳入仓库;参考锁定环境为 Linux x86-64 + NVIDIA CUDA,不代表支持所有平台、GPU 或任意机器人。

机器人 示例任务 接入状态
Unitree G1,29 自由度 平地速度跟踪 使用 mjlab 已适配模型,已记录短流程验证结果
Booster T1,23 自由度 平地速度跟踪 已包含适配器及 BSD 许可模型/网格,已记录短流程验证结果
其他人形机器人 待扩展 需新增并验证适配器;发现模型文件不等于完成支持

**安装规则:**直接安装本项目,不要再单独安装 mjlab 或 rsl-rl-lib。包括 sim.py、速度命令与 T1 适配在内的修改均已纳入仓库,并在后端来源说明中记录;不再依赖外部未提交的工作区。

实验配置是起点,不是预训练行走策略。初始短训练策略仍会跌倒;G1 和 T1 分别训练,不共享一个通用策略。具体证据与限制见 VALIDATION.md。

快速开始

无仿真依赖地查看任务

在仓库根目录,使用 Python 3.11 或更新版本:

PYTHONPATH=src python -m universal_humanoid list
PYTHONPATH=src python -m universal_humanoid plan --config experiments/g1_smoke.json

配置运行环境

训练需要兼容的 NVIDIA GPU/驱动。G1/T1 无需外部后端或资产路径,按锁文件安装即可:

python3 .agents/skills/setup-env/scripts/detect.py
uv sync --locked --extra dev --python 3.13
./scripts/uh doctor
./scripts/uh verify-vendor
./scripts/uh check-robot --config experiments/g1_smoke.json --output runs/g1-check.json
./scripts/uh smoke --config experiments/g1_smoke.json --steps 16

也支持标准 pip install -e '.[dev]';环境配置提供带哈希的 pip 锁定安装方式。doctor 检查环境,check-robot 检查适配器和实际接触;setup-env 脚本可统一执行并保存各项日志。旧的 MJLAB_ROOT 外部后端覆盖已被拒绝。

运行一个小规模完整流程

./scripts/uh pipeline --config experiments/g1_smoke.json \
  --output runs/g1-first --eval-steps 250 --eval-envs 4
./scripts/uh verify-bundle runs/g1-first/bundle --inference

每次使用新的输出目录。*_smoke.json 仅训练两轮,用于验证工程流程,不用于行走能力验收。使用已包含的 T1 适配器时,改用 experiments/t1_smoke.json。完整训练、评估、视频和导出命令见 English README。

看训练过程,而不只看耗时

./scripts/uh train --config experiments/g1_flat.json --output runs/g1-long --background
./scripts/uh status runs/g1-long
./scripts/uh curves runs/g1-long --output analysis/g1-curves
./scripts/uh checkpoints runs/g1-long
./scripts/uh stop runs/g1-long

# 从已有的、已提交的检查点再训练 200 轮;始终使用新目录。
./scripts/uh train --resume runs/g1-long/model_0.pt --iterations 200 \
  --output runs/g1-continued --background

这些是生命周期操作示例,不应无等待地全部连跑。先确认检查点已提交;训练与评估共用 GPU 时需预留显存。curves 同时读取跟踪项、动作分布标准差和回合长度,缺失曲线会明确报告。

benchmark 默认的 seed 是评估 seed;如需研究训练种子差异,应分别训练不同 seed 的配置。默认评估采用随机初始状态,--profile stress 额外开启任务观测噪声与随机速度扰动。续训恢复优化器等训练状态,但不是中断轨迹的逐位复现。

完整的矩阵评估、检查点选择、失败率口径与 play --measure 示例见训练运维手册。

让代码智能体参与实验

可向代码智能体提出:

按 AGENTS.md 和 rl-engineer 手册,为 G1 建立 baseline 并提出奖励改进。在约定预算内训练,用相同评估协议比较跟踪误差和失败事件,记录视频并导出研究用策略包,不连接真机。

规范入口:AGENTS.md、RL 工程手册。不同奖励定义下的总奖励不能直接比较;需要结合任务指标、视频、多种随机种子和足够长的评估时间。

项目结构

位置 用途
rl/mjlab/、rl/rsl_rl/ 仓库内固定后端源码与许可证
uv.lock 完整依赖解析与制品哈希
src/universal_humanoid/robot_specs/ 独立声明的机器人检查契约
src/universal_humanoid/registry.py 机器人/任务注册与工厂引用
src/universal_humanoid/tasks.py 配置适配、奖励注入、评估协议
src/universal_humanoid/rewards.py 可扩展的奖励机制
experiments/ 独立实验配方
src/universal_humanoid/runtime.py 训练、评估、视频与交互回放
src/universal_humanoid/deployment.py 策略导出、契约校验与纯推理消费者
docs/ 环境、架构、验证和发布说明
runs/、bundles/ 运行生成的产物,不纳入版本控制

迁移安装、独立环境、机器人门禁、wheel 资源及完整短流程的实测结果见可移植性验证。

新增机器人需要验证模型、传感器、碰撞、控制参数及关节顺序。原始机器人描述不会被自动替换进训练任务;详细扩展方式见架构文档。

边界与安全

当前不包含真机通信、状态估计、安全监督器、急停、ROS/DDS 映射、自动形态转换、复杂地形任务、动作模仿、多 GPU 训练或原生 CPU 强化学习后端。

导出产物是研究/推理用策略包,不是机器人可执行程序。所有包均标记 hardware_approved: false,没有启用电机的命令。仅加载可信检查点;文件哈希不是数字签名或安全沙箱。

致谢与发布

Git、许可证、依赖锁与 CI 的配置和本地检查结果见仓库基线。

工程流程设计参考 Jumper 的模块化任务与操作规范,仿真和学习依托 mjlab、MuJoCo Warp 与 RSL-RL。组件和资产归属见 NOTICE.md。

参考 Jumper,本项目原创代码和文档采用 Apache-2.0;内置依赖和机器人资产保留原许可证,见 NOTICE.md。对外发布前仍需完成发布检查清单中的跨机器验证和来源审核。