GR00T-WholeBodyControl 总览#

1. 这个仓库是什么#

GR00T-WholeBodyControl 是 NVIDIA GEAR 团队的人形机器人全身控制代码库,目标平台是 Unitree G1(29 DoF,带灵巧手时 43 DoF)。它不是一个单一模型,而是三条并列的技术路线外加一套共享的部署/遥操作基础设施:

理解这个仓库的关键是抓住分层:MotionBricks 生成"要做什么运动",SONIC 或 Decoupled WBC 负责"把这个运动执行出来",最上层还可以挂一个 VLA(GR00T N1.7)来决定"该做什么任务"。

2. 两条控制路线的分野#

Decoupled WBC 和 GEAR-SONIC 解决的是同一个问题,但假设完全不同。

2.1 核心差异#

2.2 该选哪个#

• 要把手准确送到某个位姿(装配、抓取、精细遥操作数据采集)→ Decoupled WBC。QP-IK 的末端误差不受 RL 探索噪声污染,腰部权重(waist_pitch/roll posture 权重 10)还会主动抑制身体晃动。
• 要机器人做出某种整体运动(行走、爬行、模仿人类动捕、跟随生成的运动)→ GEAR-SONIC。它天然吃三种运动来源,且能跟踪训练分布之外的运动。
• 要接 VLA → GEAR-SONIC。64 维 token 已经是标准化的动作空间,VLA 只需要以 2.5 Hz 输出 40 步 token chunk,平衡与协调由预训练策略免费提供。

两者不是迭代替换关系,在仓库里是并列维护的。

3. 三个子项目的关键数字速查#

3.1 Decoupled WBC#

3.2 GEAR-SONIC#

3.3 MotionBricks#

4. 共享基础设施#

三条路线共用同一套外围,理解它们能省很多调试时间。

4.1 坐标系与关节序#

这是跨子项目最容易踩的坑:

• 代码里 w_last=False 即 wxyz。
• pose_aa 是轴角,按 MuJoCo body 顺序。
• Isaac Lab 与 MuJoCo 的关节序不同,由 G1_ISAACLAB_TO_MUJOCO_DOF / G1_MUJOCO_TO_ISAACLAB_DOF 映射;运动 PKL 存 MuJoCo 序,order_converter.py 负责转换。
• MotionBricks ↔ MuJoCo:Motion X = MuJoCo Y,Motion Y = MuJoCo Z,Motion Z = MuJoCo X。

详见 docs/source/references/conventions.md。

4.2 MuJoCo qpos 36 维#

贯穿 MotionBricks 输出、SONIC 规划器输入输出的通用格式:

4.3 遥操作栈#

VR(Apple Vision Pro / Pico / CloudXR)→ 头 + 双手 6D 位姿 + 手指 (25, 4, 4)。两条路线的用法不同:

• Decoupled WBC:位姿 → QP-IK → 关节目标 → 插值 → 机器人。
• GEAR-SONIC:位姿 → teleop_mlp 编码器 → token → 策略。

激活流程一致:按 l 或 toggle_activation → 倒计时 → calibrate() 记录基准姿态;按 k 重置。

4.4 数据采集与 VLA 工作流#

产出标准 LeRobot v2.1 数据集:

outputs/<timestamp>-G1-robot01/
├── data/train-00000.parquet
├── videos/observation.images.ego_view/episode_000000.mp4
└── meta/{info,modality,episodes,tasks}.json(l)

官方建议单任务 50–100 条演示。采集时按 x 标记丢弃,采集后必须跑 process_dataset.py 清掉这些 episode 和残留的 SMPL 帧。

VLA 的动作空间是 78 维 = 64 维 SONIC token + 7 维左手 + 7 维右手,推理 2.5 Hz、每次出 40 步,由 SONIC 以 50 Hz 解码 —— 正好填满 20 倍频率差。

4.5 真机部署要点#

5. 仓库结构#

GR00T-WholeBodyControl/
├── decoupled_wbc/          # 路线一:RL 下半身 + IK 上半身
│   ├── control/
│   │   ├── policy/         # 解耦策略、ONNX RL、插值、遥操作
│   │   ├── teleop/         # IK 求解器栈 (pink/pinocchio)
│   │   ├── envs/g1/        # G1Env
│   │   └── main/teleop/    # ROS 控制循环 + 配置
│   └── sim2mujoco/         # MuJoCo 资产与**实际加载的** RL 配置
├── gear_sonic/             # 路线二:训练侧 (Python / Isaac Lab)
│   ├── config/             # Hydra 配置树 (exp / actor_critic / encoder / decoder / algo)
│   ├── trl/modules/        # UniversalTokenModule 等
│   └── scripts/            # 数据采集、评估、推理启动
├── gear_sonic_deploy/      # 路线二:部署侧 (C++ / TensorRT / ONNX)
├── motionbricks/           # 路线三:运动生成
│   ├── motionbricks/       # 模型代码 (vqvae / motion_backbone)
│   ├── out/                # 三个 checkpoint 及其 config.yaml
│   ├── docs/               # 运动表征文档
│   └── scripts/            # 交互式 demo
├── docs/source/            # Sphinx 文档 (references / tutorials / user_guide)
├── external_dependencies/  # 外部依赖
├── install_scripts/        # 环境安装
└── download_from_hf.py     # 从 HuggingFace 拉模型

6. 阅读顺序建议#

如果是第一次看这个仓库:

1. 先读 Decoupled WBC —— 结构最简单、每一层都能对应到具体的物理量,读完就理解了 G1 的观测/动作接口、PD 控制、遥操作 IK 这些共性概念。
2. 再读 GEAR-SONIC —— 带着上一步建立的接口直觉,去看"如果不分治、全部交给一个策略,该怎么设计潜空间"。重点是 §2.4 的辅助损失表(对齐 1.0 vs 重建 0.01)。
3. 最后读 MotionBricks —— 它与控制无关,是纯生成模型;但它的 qpos 输出格式和 SONIC 规划器完全一致,读完能把整条"生成 → 跟踪"链路串起来。

如果目标是接 VLA,可以跳过 Decoupled WBC,直接读 GEAR-SONIC 的 §2.1(token 从哪来)和 §5(与 VLA 的连接)。

7. 与其他 VLA 工作的关系#

许可:代码 Apache 2.0,模型权重 NVIDIA Open Model License。