Hydra 配置

UniRL 使用 Hydra。recipe 是 examples/ 下的自包含 YAML 文件，按 diffusion/、 ar/、sft/、pe/、unified_model/、deep_research/ 组织，需要时再增加模型 子目录。用拥有该训练域的入口选择 recipe：

python -m unirl.train_diffusion --config-name=diffusion/sd3/sd3_trainside

组合模型

recipe 用 _target_ 直接实例化每个运行时组件（FSDP backend、train stack、rollout engine、reward service、algorithm、data source 等）。config 类就是定义在使用它的代码旁边的普通 @dataclass——没有 ConfigStore，也没有注册装饰器；recipe 通过把 _target_ 指向该类（并嵌套组件的 config: 块，同样是 _target_）来连接组件。实例化和验证契约以生成的 Config Package README 为准。

参数应该放哪里

recipe 语义放在 examples/ 下所选的 YAML 中。集群本地路径、模型挂载、输出目录和 WandB identity 放在 launcher env var 或 CLI override（recipe 用 ${oc.env:...} 插值）。新增 typed runtime component 时，把 config @dataclass 放在靠近实现的位置；recipe 直接用 _target_ 引用它（无需注册步骤）。

Override 优先级：

CLI Hydra override > launcher env var > YAML default

运行时契约

--cfg job --resolve 只会让 Hydra 组合所选 YAML，并解析 override 与 ${oc.env:...} 等插值。它不会实例化 recipe、检查文件路径、运行 dataclass __post_init__，也不能证明跨组件与 batch geometry 兼容。

组件 config dataclass 的校验要等 owning driver/actor 构造并实例化组件时才会运行。 unirl/config/validation.py 中的 validate_* 跨组件 helper 当前没有 live call site， 因此不能把它们视为 Ray 启动前的校验阶段。trainer 构造函数和 worker 启动路径还有其它 实际生效的检查，但必须进入真实运行时构造路径才会触发。可用 config 类型及预期契约见 生成的 Config Package README。

sync 和 tensor transport 解决不同问题：sync（cfg.sync）把 trainer 权重同步回 dedicated rollout engine，tensor transport（unirl/distributed/tensor/）是把大型 rollout 输出在 worker 间搬运的数据通道。

大作业前先运行以下命令，但只把它视为 Hydra 组合/环境变量解析检查：

python -m unirl.train_diffusion \
  --config-name=diffusion/sd3/sd3_trainside \
  --cfg job --resolve