如何快速上手GalaxeaVLA配置系统:5分钟看懂Hydra四层组合与任务继承机制的完整指南

原创2026-10-26 22:50:181,639 阅读

如何快速上手GalaxeaVLA配置系统:5分钟看懂Hydra四层组合与任务继承机制的完整指南

GalaxeaVLA 是 Galaxea 开源的 VLA(视觉-语言-动作)模型仓库,其配置系统基于 Hydra 构建,采用「train 顶层入口 → task 任务层 → model / tokenizer / data 三个子层」的四层组合结构。本文带你用 5 分钟搞懂这套 Hydra 配置的组合顺序、任务继承机制,以及如何用一条命令验证最终生效的配置,从此改参数不再靠猜。

配置全景:四层结构一图看懂

GalaxeaVLA 的 configs/ 目录按职责拆分为四个部分,组合关系如下:

层级 文件位置 职责
第 1 层:顶层入口 configs/train.yaml 全局默认值、logger、checkpoint、输出目录
第 2 层:任务层 configs/task/ 下的 bridge、droid、libero、r1lite、r1pro、r1pro_wbc、robotwin、so100 选择 model / tokenizer / data,并覆盖任务差异项
第 3 层:模型层 configs/model/g05.yaml 唯一的模型结构入口(G0.5 基于 Qwen3.5-2B)
第 4 层:数据层 configs/data/ 下与任务同名的 yaml 自包含的 dataset、processor、归一化与 parts schema

此外还有唯一的动作分词器入口 configs/tokenizer/actioncodec.yaml,由任务层显式指定。

GalaxeaVLA Hydra配置四层组合结构示意图:train入口继承task任务层,再组合model模型层、tokenizer分词器层与data数据层

上图展示的是任务层会引用的 ActionCodec 动作分词器架构:双臂动作分块后经 Action Encoder 与残差向量量化器(Residual VQ)输出结构化 action token。

逐层拆解:每层负责什么

第 1 层:train.yaml 顶层入口

configs/train.yaml 是整个 Hydra 的顶层配置,其中的 defaults 决定了各子配置的加载顺序——顺序即覆盖顺序:

defaults:
  - _self_
  - data:
  - model:
  - tokenizer: null
  - task:

它同时维护全局通用项:随机种子 seed、logger(支持 wandb / swanlab)、eval_steps、输出目录等。注意文件末尾有个巧妙的桥接——模型代码通过 cfg.model.tokenizer 访问分词器配置,而实际来源是任务层覆盖后的根级 tokenizer: 键:

model:
  tokenizer: ${tokenizer}

这种「插值引用」(${tokenizer})是 Hydra 的招牌能力,让跨层引用无需重复粘贴。

第 2 层:task 任务层(继承机制的核心)

每个机器人/仿真环境对应一个任务文件,例如 configs/task/libero.yaml 的开头:

defaults:
- override /model: g05
- override /tokenizer: actioncodec
- override /data: libero
- _self_

这里 override 的含义是:用本文件的选择覆盖 train.yaml 里的默认组(train 中 tokenizer: null 表示默认不加载分词器,由任务层决定用哪个)。_self_ 放在最后,意味着「本文件自身的键值拥有最高优先级」。

第 3 层:model 模型层

configs/model/g05.yaml 保存模型架构与训练超参的默认值:batch_size: 16、learning_rate: 8.0e-05、model_arch 下的词表大小、action_dim: 20、VLM 层数与注意力头数等。它还大量使用插值与数据层联动,例如:

horizon_steps: ${data.action_size}
cond_steps: ${obs_image_steps:${data.obs_size}}

也就是说:动作时域由数据配置里的 action_size 自动决定,改数据长度时无需手动同步模型层。

第 4 层:data 数据层与 parts_meta

每个 configs/data/.yaml 都是自包含的数据入口,包含 MixtureLerobotDataset 参数(action_size、obs_size)、embodiment_datasets(数据集路径与 shape_meta)和 processors(transform、归一化、过滤、action_state_merger)。

共享的部件布局放在 configs/data/parts_meta/,通过 OmegaConf 的 oc.load 加载,例如 dual_arm_grouped_0409.yaml 定义了标准双臂的 20 维布局:

left_control(9) | left_gripper(1) | right_control(9) | right_gripper(1)

而 R1Lite / R1Pro 输出 27 维,额外包含 lower_body(7)。

分词器与 token 的对应关系可以参考下图的序列模板:条件段(images、embodiment、command、proprio)+ 生成段(可选 CoT + action_codes),每个动作组按 8 个 VQ code 展开:

GalaxeaVLA ActionCodec分词器动作token模板:条件段加生成段的序列结构与token化输出示例

任务继承机制:task 只写差异项

理解了分层,再看「继承」就一目了然了。以 configs/task/libero.yaml 为例,它没有重复模型结构,只覆盖训练差异项:

model:
  batch_size: 8
  learning_rate: 1.0e-05
  max_steps: 100000
  model_arch:
    action_dim: 20
    fm:
      num_flow_samples: 8

对比 configs/task/r1pro.yaml,除了训练超参不同,它还覆盖了 27 维的 parts_meta 与 dropout_noop_parts: true——这正是官方推荐姿势:通用默认在 model / tokenizer / data 层,任务文件只写真正变化的字段。

这种「继承 + 覆盖」带来三个好处:

  1. 改一处生效全局:调整默认学习率只需改 configs/model/g05.yaml,8 个任务同步受益;
  2. 任务隔离:libero 的改动不会影响 r1pro 的 tokenizer 配置;
  3. 新增任务成本极低:复制最接近的 task + data 两个文件,defaults 指向新数据名即可(完整 Checklist 见 configs/QUICK_START.md 的 "Add Your Own Dataset" 一节)。

实战操作:一条命令验证最终配置

改完配置最怕「到底哪个值生效了」。GalaxeaVLA 自带解析工具 tools/resolve_config.py,它会用 Hydra compose 出完整配置树:

# 查看 libero 任务最终生效的模型架构
python tools/resolve_config.py libero --key model.model_arch

# 对比两个任务的差异,只看不同项
python tools/resolve_config.py libero --diff bridge --only-diff

而启动训练时,scripts/run/finetune.sh 支持直接把 Hydra 覆盖追加在命令末尾,无需改文件:

# 临时把 batch_size 改成 8、eval 频率改成 200 步
bash scripts/run/finetune.sh 1 libero model.batch_size=8 eval_steps=200

它还提供 --dry-run(只打印解析后的配置就退出)和 --test(离线日志的调试模式),非常适合首次跑任务前先验证。

常见配置点速查表

我想改… 去哪里改 关键字段
学习率 / batch size / 步数 configs/task/.yaml model.learning_rate / model.batch_size
预训练权重 task 层 model.pretrained_ckpt
数据集路径 configs/data/.yaml embodiment_datasets.*.dataset_groups.*.dataset_dirs
动作时域 horizon data 层 action_size(模型层自动跟随)
部件 schema / 合并规则 configs/data/parts_meta/ + data 层 action_state_merger
分词器默认参数 configs/tokenizer/actioncodec.yaml vq_config
评测频率 / 输出目录 configs/train.yaml 或命令行 eval_steps / exp_name

小结

GalaxeaVLA 的配置系统本质是一条清晰的继承链:train.yaml 定全局 → task 层用 override 选择三个子配置 → model / tokenizer / data 层提供默认值 → task 层键值最后覆盖。掌握了「顺序即优先级」「插值跨层引用」「只写差异项」这三条原则,配合 resolve_config.py 的验证能力,你就能 confidently 地为任何新任务配置出正确的训练环境。

更多细节可阅读官方架构文档:docs/architecture/config_zh.md、docs/architecture/parts_meta_zh.md 与 docs/architecture/tokenizer_zh.md。

登录后查看全文
GalaxeaVLA