如何快速上手GalaxeaVLA配置系统:5分钟看懂Hydra四层组合与任务继承机制的完整指南
如何快速上手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,由任务层显式指定。
上图展示的是任务层会引用的 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/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 展开:
任务继承机制: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 层,任务文件只写真正变化的字段。
这种「继承 + 覆盖」带来三个好处:
- 改一处生效全局:调整默认学习率只需改 configs/model/g05.yaml,8 个任务同步受益;
- 任务隔离:libero 的改动不会影响 r1pro 的 tokenizer 配置;
- 新增任务成本极低:复制最接近的 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/ |
model.learning_rate / model.batch_size |
| 预训练权重 | task 层 | model.pretrained_ckpt |
| 数据集路径 | configs/data/ |
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。

