乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > VERL 源码精读 06:Single Controller、WorkerGroup 与 Ray 调度

VERL 源码精读 06:Single Controller、WorkerGroup 与 Ray 调度

当前时间： 2026-08-23 19:03:43 分类：办公文件 评论(0)
VERL 源码精读 06:Single Controller、WorkerGroup 与 Ray 调度

学习主题：VERL 源码精读 06 

理解 controller 如何通过 WorkerGroup 调用远程 Ray workers，以及 dispatch/collect 装饰器如何隐藏分布式细节。

 阅读目标：建立可复述、可定位、可调试的源码理解，不停留在 API 名称层面。

1. 本篇学习范围

理解 controller 如何通过 WorkerGroup 调用远程 Ray workers，以及 dispatch/collect 装饰器如何隐藏分布式细节。

这一篇关注的不是“怎么把命令跑起来”，而是读清楚源码中每个对象为什么存在、它和前后模块如何传递数据，以及出问题时应该从哪里开始定位。

2. 源码入口文件

本篇建议按下面顺序阅读：

verl/single_controller/base/worker_group.pyverl/single_controller/base/decorator.pyverl/single_controller/base/worker.pyverl/single_controller/ray/base.pytests/single_controller

这些文件覆盖了本篇主题的主路径。阅读时不需要一开始就把所有分支展开，先抓主干，再回头看特殊配置、后端差异和异常处理。

3. 核心调用链

本篇主调用链可以压缩为：

worker 方法用 `@register(dispatch_mode=...)` 声明如何被远程调用。`WorkerGroup._bind_worker_method()` 扫描这些方法并绑定到 WorkerGroup 对象。controller 调用 WorkerGroup 方法时，输入先经过 dispatch_fn 切分。RayWorkerGroup 将切分后的数据发送给各个 Ray actor。各 worker 执行完成后，collect_fn 将结果收集并合并成统一返回值。

这条链路是读源码时的地图。后续遇到新的类、函数或配置字段，都可以先判断它属于链路中的哪一段。

4. 核心概念

  • Single controller 意味着算法主循环集中在一个控制进程中，worker 只执行被调度的计算。
  • Dispatch 描述数据怎么发，Collect 描述结果怎么收，Execute 描述调用哪些 worker。
  • 这种模式让 trainer 代码避免直接写大量 ray.get 和 remote()。
  • WorkerGroup 是理解 VERL 分布式抽象的关键层。

这些概念共同决定了本篇源码的设计方式。VERL 的一个重要特点是，很多类名看起来像普通工程封装，但背后实际是在解决大模型 RL 的分布式执行问题。

5. 数据在这一层如何流动

在 VERL 中，几乎所有训练阶段都可以用同一套数据流语言描述：

输入 batch-> 按并行度或任务类型拆分-> 分发到本地函数或远程 worker-> 执行高成本计算或轻量控制逻辑-> 收集结果-> 写回 DataProto / TensorDict / TransferQueue-> 进入下一阶段

本篇主题对应的数据流重点是：

  1. worker 方法用 @register(dispatch_mode=...) 声明如何被远程调用。
    仅仅给原始函数func贴 3 个属性：dispatch_mode、execute_mode、blocking。没有修改函数逻辑。@register = 贴标签。后面WorkerGroup会扫描这个标签，识别 “这是一个可以远程调用的 worker 方法”。
    这是一个贴@register的示例。
  2. WorkerGroup._bind_worker_method()
     扫描这些方法并绑定到 WorkerGroup 对象。
    遍历worker_cls所有成员方法；
    判断：if hasattr(method, "_is_worker_method") → 识别被@register标记过的函数；
    读取该方法上的元信息：dispatch_mode、execute_mode；
    动态生成一个包装函数 wrapper
    绑定到 WorkerGroup 实例上，名字和原始 worker 方法一模一样。
  3. controller 调用 WorkerGroup 方法时，输入先经过 dispatch_fn 切分。
  4. RayWorkerGroup 将切分后的数据发送给各个 Ray actor。
  5. 各 worker 执行完成后，collect_fn 将结果收集并合并成统一返回值。

读代码时要始终跟踪字段而不是只跟踪函数名。典型字段包括：

promptsresponsesattention_maskposition_idsold_log_probsref_log_probvaluesrm_scorestoken_level_rewardsadvantagesreturnsmetrics

不是每一天都会出现全部字段，但这些字段构成了 VERL PPO/GRPO 训练的共同词汇表。

6. 和前后模块的关系

本篇主题通常不是孤立工作的。它至少会连接三类模块：

上游：  配置、数据、controller 状态、已有 batch 字段。本层：  当前主题负责的调度、计算、转换或封装逻辑。下游：  rollout、reward、advantage、loss、metrics、checkpoint 或异步队列。

因此读源码时要避免只看单个函数。更稳的方式是：

1. 找到谁调用它。2. 找到它读取哪些字段。3. 找到它写出哪些字段。4. 找到这些字段下一步被谁使用。5. 找到配置项如何改变它的分支。

这个五步法适用于 VERL 的大多数文件。

7. 实现细节拆解

本篇源码中最值得关注的细节包括：

  1. worker 方法用 @register(dispatch_mode=...) 声明如何被远程调用。
  2. WorkerGroup._bind_worker_method()
     扫描这些方法并绑定到 WorkerGroup 对象。
  3. controller 调用 WorkerGroup 方法时，输入先经过 dispatch_fn 切分。
  4. RayWorkerGroup 将切分后的数据发送给各个 Ray actor。
  5. 各 worker 执行完成后，collect_fn 将结果收集并合并成统一返回值。

这些步骤背后通常有两类逻辑：

控制逻辑：  判断当前训练需要哪些角色、哪些字段、哪些分支。计算逻辑：  真正执行模型推理、训练、reward、advantage 或 loss。

HybridFlow 的设计要求我们把这两类逻辑区分开。控制逻辑更适合在 trainer 或 manager 中读；计算逻辑更适合在 worker、engine 或 core_algos 中读。

8. 配置如何影响本篇路径

VERL 的同一段源码经常会被配置切到不同路径。阅读本篇时尤其要关注这些配置类型：

algorithm:  决定 PPO、GRPO、KL、advantage、rollout correction 等算法行为。actor_rollout_ref:  决定 actor、rollout、reference policy、model path、训练后端和推理后端。critic:  决定是否启用 value model，以及 critic 的训练后端。reward:  决定使用规则 reward、reward model、remote reward 还是 sandbox reward。trainer:  决定训练步数、资源规模、logger、validation、checkpoint 和 V1/V0 模式。

读源码前最好先打印 resolved config。否则很容易在一个未启用的分支里浪费时间。

9. 常见误区和调试要点

  • 如果 worker 方法没有 @register，controller 侧不会自动拥有这个方法。
  • dispatch 模式必须和输入数据结构匹配，DataProto、TensorDict、普通对象不能混用。
  • 分布式 bug 常常不是算法错，而是 dispatch 后每个 worker 拿到的数据 shape 不一致。

调试 VERL 时，不建议一上来就改源码。更稳的顺序是：

1. 确认命令行 override 是否真的进入 resolved config。2. 确认当前走 V0 还是 V1 trainer。3. 确认 DataProto / TensorDict 里字段是否存在。4. 确认 batch 维、response 长度、mask 是否一致。5. 确认对应 worker 是否真的被创建。6. 确认 Ray worker 日志里的原始异常。7. 最后再判断是不是算法公式或 loss 本身的问题。

这个顺序能避免把配置错误、数据错误、分布式调度错误误判成算法错误。

10. 本篇压缩总结

读懂这一篇后，应该能够回答三个问题：

1. 这一层在 VERL 训练链路中负责什么？2. 它接收哪些字段，又产出哪些字段？3. 它的行为主要由哪些配置项改变？

如果这三个问题能答清楚，就说明不是在背目录，而是在按 VERL 的真实执行路径读源码。

11. 下一步阅读

读完本篇后，建议继续沿着训练链路向后走：

入口与配置-> 数据和 DataProto-> WorkerGroup 和 Ray 调度-> Worker 与模型引擎-> Rollout-> Reward-> Advantage-> Actor/Critic loss-> Metrics、Checkpoint、异步扩展

VERL 源码量很大，但主线并不乱。只要始终围绕“一个 batch 如何从 prompt 变成 actor update”这条线阅读，就能把分散目录组织成一张完整图。