概览

UniRL 围绕一个 Hydra 驱动的训练循环组织。本页只保留导航层说明； 贴近代码的契约来自 unirl/README.md 和各 package README， 并以页面形式内嵌在各文档分区的侧边栏中。

unirl.train_diffusion | train_vlm | train_pe | train_unified_model
  -> register and validate Hydra config
  -> <Domain>Trainer acquires a Ray DevicePool (placement)
  -> trainer builds the rollout workers and train workers
  -> loop: rollout -> reward -> advantage -> train -> optional weight sync

每个领域都有自己的入口和 trainer，驱动方式一致。训练栈只有一套：早期的 v1 actor-group runtime 已退役，single-controller 的 Remote / placement 层现在是唯一路径。

主要参考

• Code Architecture README：模块地图和 runtime data flow。
• Rollout Package README：rollout mode 和 request/response contract。
• Train Stack README：FSDP backend、train-step 契约和结构注入。
• Algorithms Package README：每 track 的 loss contract 和 reward→advantage 路径。
• SDE Package README：SDE strategy、schedule 和 runtime kernel。
• Weight Sync README：dedicated rollout 同步。

数据流

<Domain>Trainer
  -> build RolloutReq, dispatch to the rollout engine
  -> RolloutResp with tracks[name] (conditions, segments, rewards, media)
  -> RewardService.score_and_attach    -> track.rewards
  -> RolloutTrack.compute_advantages    -> track.advantages
  -> TrainStack.train_track(track)      shards across train workers, runs the mini-batch loop
  -> optional weight sync back to dedicated rollout workers

RolloutReq 和 RolloutResp（位于 unirl/types/）是 rollout 与 training 的关键边界。新的 rollout engine 应把 backend-specific 输出转换成这些 typed contract，而不是把 backend object 泄漏到 training 代码中。

trainer（unirl/trainer/<domain>.py）负责 placement 块、worker 构建，以及 rollout、reward、advantage、train、sync 的阶段顺序。

部署模式和 engine-specific 要求以生成的 Rollout Package README 为准。

每 track 一个算法

训练 loss 是单个 per-track 的 cfg.algorithm——一个 StageAlgorithm，例如 unirl.algorithms.diffusion_grpo.DiffusionGRPO。不存在独立的 driver 侧 "rollout control" 对象：

• reward→advantage 的 z-score 在 RolloutTrack.compute_advantages（unirl/types/rollout_resp.py）；
• SDE-index 选择在 DiffusionSamplingParams.resolve_sde_indices（unirl/types/sampling.py）。

单 track recipe 绑定一个 cfg.algorithm；多 track recipe（如 PE）为每个 track 嵌套一个 algorithm: 节点，并运行兄弟 TrainStack。见 Trainer 与训练栈。

Roadmap 路线图

近期方向围绕 框架 Infra、算法 Algorithm、模型 Model 三条线展开，详见 Roadmap 路线图。