HybridFlow 架构详解

5.1 HybridFlow 想解决的问题

之前的 RLHF 框架（DeepSpeed-Chat、OpenRLHF）有两个共同痛点：

1. 算法和系统耦合。算法工程师改 PPO loss，往往要懂 Ray Actor / DeepSpeed engine 才能改；
2. 计算与采样切换时显存浪费。训练时 actor 用 fp32 master、采样时 actor 转 fp16 + KV cache，两套权重并存。

HybridFlow 给出的两件武器：

5.2 Hybrid Controller：算法和系统解耦

这是 verl 区别于 OpenRLHF 的最大设计差异：

实际看 verl/trainer/ppo/ray_trainer.py · RayPPOTrainer.fit()，PPO 主循环就是一个 for 循环 + 几个 RPC 调用。这就是 hybrid controller 的承诺。

5.3 3D-HybridEngine：actor / rollout 同卡共存

普通 RLHF 框架：

$$ \text{actor 占显存} = P_\text{train}\ (\text{含 fp32 master, m, v}) \qquad \text{rollout 占显存} = P_\text{infer}\ (\text{含 fp16 + KV cache}) $$

如果 actor 和 rollout 各占一片卡，总显存 = $P_\text{train} + P_\text{infer}$。verl 选择把它们放在同一片卡上分时复用：

关键技术挑战："训练的 actor 权重布局" ≠ "vLLM 推理的权重布局"，必须做权重 resharding。

5.4 权重 resharding 的"3D"

所谓 3D：

每次训练 → rollout 切换，必须做三维布局变换，把分片的训练权重凑成 vLLM 期望的格式。verl 的 verl/workers/sharding_manager/ 就在干这件事。

5.5 完整数据流（GRPO 单步）

整套流程对应 RayPPOTrainer.fit() 里的一个 for 循环。这就是 HybridFlow 的"看起来像单机"的代码体验。

5.6 ResourcePool 的放置策略

verl 支持三种放置：

在 YAML 里通过 ResourcePool 配置实现：

actor_rollout_ref:
  hybrid_engine: true        # colocated
# 或
actor_rollout_ref:
  hybrid_engine: false       # disaggregated
  rollout:
    n_gpus_per_node: 4
  actor:
    n_gpus_per_node: 4

5.7 异步采样（fully_async）

同步路径：rollout 完后才能训。verl/experimental/fully_async_policy/ 实验性支持异步——rollout 持续跑、actor 间断更新，吞吐显著提升但要容忍 stale data。

开启方式：

actor_rollout_ref.rollout.mode=async

新手不用碰，了解概念即可。

5.8 HybridFlow 与 OpenRLHF 的具体性能差异

在同样硬件上，verl 通常显存使用更少，但单步训练 wall time 不一定更短（resharding 有成本）。

5.9 学术贡献与生态

5.10 update_weights()：训推权重同步真路径

5.3 那张时序图里的 "★ Resharding ★" 在源码里对应 ActorRolloutRefWorker.update_weights()（verl/workers/engine_workers.py:659 起）。它是 hybrid engine 的核心，每次 rollout 前都会被 controller 调一次。

方法签名（简化）：

@register(dispatch_mode=Dispatch.ONE_TO_ALL, blocking=False)
def update_weights(self, global_steps: int):
    if self.config.weight_sync.mode == "naive":
        self._update_weights_naive(global_steps)
    else:
        self._update_weights_via_checkpoint_engine(global_steps)

两种 mode 的差异：

naive 模式的 5 步流程（engine_workers.py:689–734）：

1. rollout.resume(tags=["weights"])（line 699）—— 让 vLLM/SGLang server 从 sleep 醒回来，给"weights"留位置；
2. actor.engine.get_per_tensor_param()（line 703–704）—— 一个生成器，逐张量 yield (name, tensor)。FSDP 这里做 DTensor all-gather，Megatron 做 PP broadcast；
3. rollout.update_weights(per_tensor_param, peft_config=..., global_steps=...)（line 721）—— 流式推给 server adapter；
4. （可选）actor.engine offload 到 CPU 释放 GPU（param_offload=True 时）；
5. rollout.resume(tags=["kv_cache"])（line 734）—— 让 server 再申请 KV cache 准备 generate。

blocking=False 这一点很关键：controller 发起 update_weights 后立刻拿到 future，可以并行做别的（比如启动数据 prefetch、统计 timer），等到真正调 generate_sequences() 时再 await。

5.11 sleep_level 与 resume(tags) 的语义

读 rollout 配置时经常碰到 sleep_level: 1 / sleep_level: 2，意思常被误解：

resume(tags=...) 是带标签的——只 wake up 指定 tag。所以才会看到 resume(tags=["weights"]) + 后面 resume(tags=["kv_cache"]) 这种分两步唤醒的写法：第一步先腾出权重位置准备接 update，第二步再申请 KV 准备 generate。两步之间，旧 KV 已经被释放，让 update_weights 拷贝有最大可用空间。

对应源码：vLLM 这边是 ServerAdapter._execute_method("wake_up", tags=[...])（vllm_rollout.py:150–162）；SGLang 这边是 HTTP 调 /release_memory_occupation 与 /resume_memory_occupation（sglang_rollout.py:270 起）。

5.12 get_per_tensor_param()：训练侧的权重提取

这是 hybrid engine "魔法" 的真实施工方。verl/workers/engine/base.py:150 的 BaseEngine 定义：

def get_per_tensor_param(self) -> Generator[Tuple[str, Tensor], None, None]:
    """yield (name, tensor) one by one; 各后端各自实现 all-gather / broadcast"""

FSDP 实现要点：

• 对每个 FSDP-wrapped 参数调 summon_full_params() context 让 DTensor 在 rank 0 拼齐；
• 结合"layered summon"——大模型不能一次性 gather 全部参数，按 layer 分组，每组 yield 完之后释放；
• base_sync_done flag 跟踪"base 权重是否已经同步过"——LoRA 路径下，base 同步一次后续只增量推 adapter。

Megatron 实现要点：

• 每个 PP stage 只持有自己的 layer 参数；先 PP broadcast 让所有 PP rank 都拿到本 stage 之外的权重；
• broadcast 完后 rollout 拓扑只需要 DP，TP 部分由 vLLM/SGLang 自己重切；
• 用完立刻释放非本 stage 的参数，避免显存翻倍。

5.13 实验性：fully_async_policy

5.7 已经提到 fully_async，这里展开它的真实数据流（verl/experimental/fully_async_policy/）：

三条与默认 hybrid 路径的关键差异：

1. rollout 和 train 不共卡——分两套 ResourcePool；
2. trajectory 流式产出——rollout 持续往 TransferQueue 推，train 持续从 ReplayBuffer 拉；
3. 权重同步走 NCCL 直接 broadcast 到 rollout 进程——不经过 checkpoint engine，延迟比 disaggregated 模式低；
4. 可设 staleness_threshold 控制 train 用多旧的 rollout 数据。

README 公布的 benchmark：128 卡 Qwen2.5-7B DAPO，相对 colocate sync 提速 2.35×（FSDP）/ 2.67×（Megatron）。代价是 rollout 数据有 1-2 步延迟，对收敛影响很小但调参更难。

5.14 实验性：one_step_off_policy

fully_async 太激进时还有个温和版：verl/experimental/one_step_off_policy/。它把训练和 rollout 的并行度限制为一步——train 用上一步的 rollout，rollout 跑下一步的，永不会更落后。

实战推荐顺序：colocate sync → one_step_off_policy → fully_async。前者最稳，后者最快但需要更细的资源分配能力。

5.15 verl-omni / vexact 概要

2026 上半年 verl 衍生出几个独立仓，本书不展开但需要知道存在：

vexact 的核心 idea：训练侧 forward 和 rollout 侧 forward 数值上差异（即"训练 logits ≠ rollout logits"）是 PPO 不收敛的常见根因——vexact 用同一份 HF transformer 实现两侧 forward，逐 token logits 完全一致，让 importance ratio 永远 ≈ 1。代价是吞吐不如 vLLM/SGLang。建议把它当作"金标"，怀疑训推不一致时切过去对比一次。

5.16 这章给你留下什么

• 理解 HybridFlow 的"hybrid" 双关：hybrid controller + hybrid engine；
• 知道为什么 verl 显存更省（actor / rollout 共置）；
• 知道权重 resharding 是什么、为什么需要；
• 知道 colocated / disaggregated / hybrid 三种放置如何选；
• 读 RayPPOTrainer.fit() 时不会迷失方向。