OpenWAM 训练系统完整指南:train.yaml、Hydra 与 DeepSpeed ZeRO 协同的 8 大调优开关
OpenWAM 训练系统完整指南:train.yaml、Hydra 与 DeepSpeed ZeRO 协同的 8 大调优开关
OpenWAM 是一个面向 World-Action Model(WAM,世界-动作模型) 的开源训练栈。它的训练系统以一份 configs/train.yaml 为核心,通过 Hydra 组合模型与数据加载配置,再由 scripts/train.sh 拉起 torchrun + DeepSpeed ZeRO 分布式训练——全文带你快速看懂这条链路,并掌握 8 个最常用的调优开关。
一、先认识 OpenWAM 的训练架构
OpenWAM 把"训练一个视频-动作联合模型"拆成了清晰的模块:configs/ 放 Hydra 配置、openwam/train/ 放训练器、openwam/model/ 放三种架构(dual_system / single_system / tri_system)、openwam/dataloader/ 放各基准数据集的读取器。
一次训练的最小链路是:
scripts/train.sh自动探测 GPU 数量,调用torchrun启动 scripts/train.py;train.py作为 Hydra 入口,加载configs/train.yaml及其组合的配置组;- 从
cfg.training构建 HuggingFace Accelerate 的DeepSpeedPlugin(ZeRO 阶段、梯度累积、梯度裁剪、优化器 offload 都来自这里); OpenWAMTrainer(openwam/train/openwam_trainer.py)完成建模、冻结、优化器构建与训练循环,并把解析后的完整配置随每个 checkpoint 一起保存,保证可复现。
💡 推荐硬件:官方建议 8 张 80GB 显存 GPU 即可支持 Wan2.2-5B 及更小视频骨干的全部架构训练。
二、train.yaml 的结构:Hydra 如何"拼"出一套完整配置
configs/train.yaml 顶部只有三行 defaults,就完成了"模型 + 数据"的选择:
defaults:
- model: dual_system # dual_system / single_system / tri_system
- dataloader: robotwin # robotwin / ebench / libero / vlabench ...
- _self_
model组:指向 configs/model/ 下的架构文件,再级联选出视频骨干(model/video_backbone=wan22_ti2v_5b)、动作骨干、VLM 骨干等子组;dataloader组:指向 configs/dataloader/ 下的数据集配置,内置 7 个基准:robotwin、robodojo、robocasa_gr1、ebench、libero、robocasa365、vlabench;training段:所有运行时调优参数都收在这里(下文 8 大开关)。
Hydra 的精髓在于命令行覆盖:不改文件即可切换配置组或覆写单个值,例如
# 换数据集 + 调学习率(CLI 覆盖优先于 yaml 文件)
bash scripts/train.sh dataloader=libero training.learning_rate=5e-5
# 完整选型的调试跑
bash scripts/train.sh \
dataloader=libero \
model=dual_system \
model/video_backbone=wan22_ti2v_5b \
model.architecture.variant=joint_self_attn \
model.architecture.attention_mask_mode=mutual \
training.debug=true
多机训练则通过环境变量交给 scripts/train.sh 处理:
NNODES=2 NODE_RANK=0 MASTER_ADDR=192.0.2.1 bash scripts/train.sh
三、8 大调优开关详解 🎛️
以下 8 组开关全部位于 configs/train.yaml 的 training 段,均可在 CLI 直接覆盖。
1. training.debug:20 步快速冒烟测试
默认 false。设为 true 后自动改写为 max_steps=20、第 10/20 步存 checkpoint、学习率恒定——适合新机器上先验证"环境 + 数据 + 模型选型"能跑通,再切回 false 正式训练。
bash scripts/train.sh training.debug=true
2. 优化器五件套:learning_rate / adam_betas / weight_decay / max_grad_norm / gradient_accumulation_steps
默认 1e-4 的 AdamW(β=[0.9, 0.95])、weight decay 0.01、梯度裁剪 1.0。显存紧张或想放大有效 batch 时,把 gradient_accumulation_steps 调大即可——累积 N 个微批次才做一次优化器更新,等效 batch 扩大 N 倍而显存几乎不变:
bash scripts/train.sh training.batch_size=1 training.gradient_accumulation_steps=8
3. 学习率调度:lr_scheduler / warmup_ratio / action_lr / video_lr
lr_scheduler: cosine(带线性 warmup,warmup_ratio: 0.05 控制预热比例)是默认策略;设为 null 则退化为恒定学习率。更细的玩法是 per-module 学习率:action_lr 与 video_lr 可以为动作头和视频骨干单独指定学习率(见 openwam/train/utils/optimizer_groups.py 的分组建组逻辑),微调预训练视频骨干时尤其有用:
bash scripts/train.sh training.action_lr=1e-4 training.video_lr=1e-5
4. mixed_precision:bf16 混合精度
取值 bf16 / fp16 / no。默认 bf16——它同时决定训练与部署的计算精度,数值稳定且无需 loss scaling,是 A100/H 系卡的首选。
5. zero_stage:DeepSpeed ZeRO 核心开关
取值 1 或 2(默认 2):
| 阶段 | 分片内容 | 效果 |
|---|---|---|
| ZeRO-1 | 优化器状态 | 显存显著下降 |
| ZeRO-2 | 优化器状态 + 梯度 | 显存进一步下降,默认选择 |
它在 scripts/train.py 中被读入 DeepSpeedPlugin,无需 accelerate launch 即可激活:
# 显存非常紧张时退回 ZeRO-1
bash scripts/train.sh training.zero_stage=1
6. 显存优化三兄弟:use_gradient_checkpointing 系列
| 开关 | 默认 | 作用 |
|---|---|---|
use_gradient_checkpointing |
true |
反向传播时重算激活值而非全部保存,省显存、代价约一次额外前向 |
use_gradient_checkpointing_offload |
false |
把 checkpointed 激活 offload 到 CPU,更省显存、更慢 |
initialize_model_on_cpu |
false |
模型在 CPU 构建,交由 DeepSpeed prepare() 搬上 GPU,缓解多卡同时初始化的内存峰值 |
7. offload_optimizer_device:优化器状态 CPU offload
取值 none / cpu(默认 none)。当 ZeRO 分片后优化器状态仍放不下时,把它整体 offload 到 CPU 内存——吞吐会下降,但能救回即将 OOM 的大模型训练。
8. 损失权重与断点:lambda_video / lambda_action / save_steps / finetune_ckpt_path / resume_ckpt_path
lambda_video与lambda_action(默认各 1.0)控制视频 flow-matching 损失与动作 flow-matching 损失的相对权重;save_steps(默认 2000)+keep_last_k_ckpts(默认 1,滚动窗口只留最近 K 个)管理磁盘;finetune_ckpt_path与resume_ckpt_path互斥(二者同设会直接报错):前者从已有权重"热启动"一个 step 从 0 开始的新 run;后者恢复优化器/调度器/RNG 全状态,在原 run 目录续训(需先开save_full_states_for_resume: true)。
# 微调 OpenWAM-α 基座:
bash scripts/train.sh dataloader=libero \
training.finetune_ckpt_path=<foundation_ckpt_dir>
四、新手调参速查表
| 我想…… | 怎么开 |
|---|---|
| 验证环境能不能跑通 | training.debug=true |
| 显存不够,先降精度分片 | training.zero_stage=1 + training.gradient_accumulation_steps=4 |
| 还 OOM | 追加 training.offload_optimizer_device=cpu |
| 微调预训练基座,保护视频骨干 | training.video_lr=1e-5 training.action_lr=1e-4 |
| 训练中断后续跑 | 提前开 save_full_states_for_resume=true,再设 training.resume_ckpt_path=<ckpt_dir> |
| 多机扩展 | NNODES=2 NODE_RANK=0 MASTER_ADDR=<ip> bash scripts/train.sh |
五、相关资源
- 训练与部署完整文档:assets/openwam_usage_docs/train-and-deploy.md
- 训练器主循环:openwam/train/openwam_trainer.py
- Hydra 入口与 DeepSpeed 组装:scripts/train.py
- 架构扩展指南:assets/openwam_usage_docs/architecture-extension.md
- 基准评测客户端:benchmarks/(RoboTwin、LIBERO、EBench 等 8 个)
掌握这份 train.yaml 与上述 8 大开关,你就能在单卡调试到多机多卡之间自由切换,快速上手 OpenWAM 的 WAM 预训练与微调。

