多机运行

训练语义放在 examples/<domain>/*.yaml。Shell 脚本只负责准备环境、启动 Ray、设置路径/logging 默认值，并转发 recipe 名和 Hydra overrides。

启动器

单机作业使用 single-node launcher；多机作业使用 role-aware multinode launcher，让 worker 加入 Ray head 后再训练。第一个参数是 bucket 化的 recipe 名（<domain>/<recipe>）；ENTRY 选择非 diffusion 入口（train_vlm、train_pe、train_unified_model）。

bash examples/run_experiment_single_node.sh diffusion/sd3_trainside
bash examples/run_experiment_multinode_taiji.sh diffusion/sd3_sglang_native_colocate
ENTRY=train_vlm bash examples/run_experiment_multinode_taiji.sh vlm/qwen_vl_argrpo_geo3k_mc_sglang_4x8

环境变量 Override

通用启动器会从环境变量设置路径和 logging 值（PRETRAINED_MODEL、DATA_PATH、EVAL_DATA_PATH、OUTPUT_DIR 以及 W&B 相关项）。模型 checkpoint 环境变量通常是 recipe-specific。

集群 Geometry

不同集群形态下，把 recipe 的 placement 和 batch-geometry 字段一起 override，例如设备数和 train-stack 的 mini-batch 形态：

bash examples/run_experiment_multinode_taiji.sh diffusion/sd3_sglang_native_colocate \
  num_devices=16 \
  stack.micro_batch_size=1 \
  stack.num_updates_per_batch=2

recipe 的 validators 会在 Ray work 前报告不一致的 geometry，所以务必先做 compose check。

启动前检查

大作业前先 compose 并 resolve recipe，不启动 Ray work：

python -m unirl.train_diffusion --config-name=<domain>/<recipe> --cfg job --resolve