G1-Factory-GR00T-1.7配置文件完全解读:processor_config.json、statistics.json与embodiment映射机制
G1-Factory-GR00T-1.7配置文件完全解读:processor_config.json、statistics.json与embodiment映射机制
如果你正在部署 G1-Factory-GR00T-1.7——NVIDIA 基于 GR00T N1.7 针对宇树 Unitree G1 人形机器人微调的视觉-语言-动作(VLA)策略模型,一定会被仓库里的 processor_config.json、statistics.json 和 embodiment_id.json 这几个文件绕晕:它们到底谁管输入格式、谁管数值归一化、谁又管机器人身份?本文用一张图和几张表把这些配置讲透,帮你一次搞懂 GR00T N1.7 检查点的 embodiment 映射机制,避开加载失败和成功率骤降的常见坑。
一、先认识 G1-Factory-GR00T-1.7:它是什么
G1-Factory-GR00T-1.7 是一个面向 Unitree G1 人形机器人的具身智能策略模型:输入头相机图像(640×480 RGB)、31 维上半身关节状态和一句英文任务指令,输出一段未来 40 步、每步 35 维的全身动作(双臂、双手、腰部关节目标 + 底盘高度指令 + 导航指令)。它在 G1 Factory 仿真环境的 9 个任务(BoxLift、PushButton 等)上微调而来,九任务平均成功率 69.4%,详见 README.md。
模型本体由 Transformer 权重文件承载,但真正决定"这个检查点怎么被喂数据、怎么还原动作"的,是下面这套配置文件:
| 文件 | 一句话作用 |
|---|---|
| config.json | 模型架构与超参数(Gr00tN1d7,32 层动作 Transformer,4 步去噪) |
| processor_config.json | 数据处理器:每种机器人(embodiment)的输入模态、动作分组定义 |
| statistics.json | 各 embodiment 关节数据的归一化统计量(min/max/q01/q99 等) |
| embodiment_id.json | embodiment 标签 → 数字 ID 的映射表(最多 32 个) |
| experiment_cfg/ | 微调时的训练配置与数据集统计,用于溯源复现 |
| SHA256SUMS | 所有文件的 SHA-256 校验和 |
💡 记住一句话:权重文件决定"大脑",这四个 json 决定"手脚怎么接、数值怎么换算"。它们必须成套使用,缺一不可。
二、processor_config.json:输入输出的"接线图"
打开 processor_config.json(约 1184 行),最顶层声明处理器类为 Gr00tN1d7Processor,核心内容是 processor_kwargs.modality_configs——一个按 embodiment 分组的字典,每个 embodiment 定义了四类模态:video、state、action、language。
本模型真正使用的条目:new_embodiment
微调时使用 embodiment_tag: new_embodiment(见 experiment_cfg/config.yaml 第 80 行),所以推理时必须用这个标签加载。该条目从第 1012 行开始,定义了:
| 模态 | 模态键(modality_keys) | 时间范围(delta_indices) |
|---|---|---|
| video | ego_view(头相机单帧) |
仅当前帧 [0] |
| state | left_arm、right_arm、left_hand、right_hand、waist 共 5 组 |
当前帧 [0] |
| action | 5 个关节组 + base_height_command + navigate_command 共 7 组 |
未来 40 步 [0..39] |
| language | annotation.human.task_description |
当前帧 [0] |
几个容易踩坑的细节:
- 动作全部是绝对量(ABSOLUTE):
action_configs中 7 组均为"rep": "ABSOLUTE"、"type": "NON_EEF",即直接输出关节角度目标,而不是末端执行器的相对位移。 - 图像按原始 640×480 送入:处理器内部先裁剪(
image_crop_size: [230, 230])再缩放到 256×256。README 明确警告——在模型自带处理器之前自行缩放图像会降低成功率,请把原分辨率帧直接交给 processor。 - 文件里还有几十个其他 embodiment 条目(如
real_g1_relative_eef_relative_joints、real_r1_pro_sharpa_*),那是基础模型 GR00T N1.7 预训练时支持的其他机器人配置,对本模型只是"陪跑",不要误用。
三、statistics.json:把关节角度"翻译"成模型语言的钥匙
statistics.json(约 4.3 MB)为每个 embodiment 保存了 state / action / relative_action 三大类下每组模态的 6 个统计量:min、max、mean、std、q01、q99(1% 和 99% 分位数)。
以 new_embodiment 为例,action 侧 7 组数据的关键数值:
| 动作组 | q01 示例 | q99 示例 | 含义 |
|---|---|---|---|
left_arm(7 维) |
-1.243 | 0.225 | 左臂关节角范围 |
right_arm(7 维) |
-1.213 | 0.354 | 右臂关节角范围 |
left_hand / right_hand(各 7 维) |
-0.600 | 0.600 | 手指张合 |
waist(3 维) |
-0.067 | 0.073 | 腰部 |
base_height_command(1 维) |
0.405 | 0.734 | 期望底盘高度(米) |
navigate_command(3 维) |
-0.499 | 0.500 | 导航指令 |
为什么需要它?配合 processor_config.json 中的开关:
"use_percentiles": true、"use_mean_std": false→ 采用分位数(q01/q99)裁剪式归一化,而不是均值/标准差缩放,对遥操作数据里的离群值更稳健;"clip_outliers": true→ 超出分位数范围的数值会被截断。
推理时,processor 会用这些统计量把归一化后的模型输出反变换回真实关节角度。换句话说:模型内部算的是"标准化坐标",statistics.json 是"还原回物理世界的换算表"。这也是 README 强调"成功率的依赖项"之一——统计文件必须与检查点版本严格配套,混用不同版本的 statistics.json 会让动作量级全错。
附带说明:experiment_cfg/ 里的统计文件
experiment_cfg/ 目录还保留了微调时的中间产物:dataset_statistics.json 只含 new_embodiment 一个键(即训练集统计),final_processor_config.json 则是训练结束后"处理器 + 统计量 + embodiment 映射"合并后的完整配置。它们主要供复现和溯源,推理时用的是根目录的三个正式文件。
四、embodiment 映射机制:一个标签串起三处配置
这是 GR00T N1.7 最巧妙的设计:同一个检查点能服务多种机器人,靠的是 embodiment 标签作为"钥匙"。
- 标签 → 数字 ID:embodiment_id.json 维护了 50 多个标签到 0~31 整数的映射,其中:
"new_embodiment": 10
"unitree_g1_full_body_with_waist_height_nav_cmd": 25
本模型微调用的 new_embodiment 对应 ID 10(与预训练条目 robocasa_gr1_tabletop 共享同一 ID)。
-
ID → 网络嵌入:config.json 中
"max_num_embodiments": 32,模型内部用 ID 查一张最多 32 行的 embedding 表,让网络"知道"当前面对的是哪种机器人,从而输出对应动作空间(state/action 上限均为 132 维,见max_state_dim/max_action_dim)。 -
标签 → 数据处理规则:同一个标签再去 processor_config.json 的
modality_configs和 statistics.json 中取对应的模态定义与归一化统计量。
embodiment 标签(如 new_embodiment)
├── embodiment_id.json → ID 10 → 模型 embedding(选对"机器人人格")
├── processor_config.json → 输入/输出模态定义(选对"接线方式")
└── statistics.json → q01/q99 归一化(选对"数值换算表")
⚠️ 最常见的加载错误:用了别的标签(比如
unitree_g1_sonic)。ID 不同 → 动作空间对不上 → 机器人直接"乱动"。请始终以new_embodiment加载本检查点。
五、config.json 速览:模型侧的几个关键参数
| 参数 | 值 | 含义 |
|---|---|---|
architectures |
Gr00tN1d7 |
GR00T N1.7 架构 |
model_name |
nvidia/Cosmos-Reason2-2B |
视觉-语言骨干(加载时需访问该受限模型) |
action_horizon |
40 | 一次预测未来 40 步动作 |
num_inference_timesteps |
4 | 流匹配去噪 4 步生成动作 |
diffusion_model_cfg.num_layers |
32 | 32 层动作 Transformer |
max_action_dim / max_state_dim |
132 | 统一的 state/action 维度上限(不足补零) |
dtype / model_dtype |
bfloat16 |
推理精度 |
tune_llm: false |
— | 微调时语言骨干冻结,只训练视觉、投影器与动作头 |
六、动手前 5 个自检问题
- 三个文件齐了吗? processor_config.json、statistics.json、embodiment_id.json 缺一不可,可用 SHA256SUMS 校验下载完整性;
- embodiment 标签用对了吗? 必须是
new_embodiment; - 图像是否原分辨率输入? 640×480 直接交给 processor,不要预先缩放;
- state 传了 5 组吗?
left_arm/right_arm/left_hand/right_hand/waist,共 31 维float32; - 返回的 35 维动作拆对了吗? 7 个输出组(5 关节组 +
base_height_command+navigate_command),其中后两组交给全身平衡控制器转为腿部动作。
小结
G1-Factory-GR00T-1.7 的配置文件分工非常清晰:processor_config.json 定义"给什么、要什么",statistics.json 负责"数值怎么换算",embodiment_id.json 则用标签到 ID 的映射为模型选定对应的机器人身份。三者以 new_embodiment 标签对齐后,检查点即可在 Isaac-GR00T N1.7 代码栈中正确加载,复现在 G1 Factory 九个任务上 69.4% 的平均成功率。理解了这套映射机制,你也能把同样的方法用到其他 GR00T 微调检查点上。