verl 架构精通指导面向已跑通 PPO/GRPO、需要改算法、换并行策略、做异步训练、扩展后端或压吞吐的工程师与研究员。阅读建议先读同目录《verl 架构入门指导》再按本文「问题驱动」深入。1. 精通目标你要能回答的问题为什么 HybridFlow 在 LLM-RL 上优于「纯多 Controller」与「纯单 Controller」权衡点在哪register/ Dispatch / Collect / n-d mesh 如何把 SPMD Worker 伪装成单机 APIActorRolloutRefWorkerTrainingWorkerBaseEngine Rollout 的职责边界与扩展点训练并行度DP/TP/PP/EP与生成并行度不一致时权重如何 reshard内存为何能接近「零冗余」如何用同一套 Worker 能力拼出 Online DPO / GRPO / 自定义算法而不复制后端代码Colocated vs Disaggregated、同步 vs One-step-off async 各自适用什么规模与延迟模型若以上都能画图并落到配置/代码路径即可视为「精通 verl 架构」。2. HybridFlow 设计精读2.1 两层 Dataflow 与软件复用论文与官方指南的关键洞察NN 训练图节点是算子边是 tensor。RL 图节点是高层算子rollout / logprob / update边是跨角色数据移动。LLM 把「节点内部」变成多进程后若把控制流也多进程化并对齐绑定维度统一多 Controller分离verl固定算法 固定后端的峰值效率往往更高略有 Driver 通信税换 FSDP↔Megatron / vLLM↔SGLang难控制与计算耦合易控制流不动写新算法GRPO、Online DPO…多进程协调成本高Driver 上改几段调用动态/异构放置难ResourcePool 映射即可verl 明确选择用少量通信换算法与后端的组合爆炸复用。论文报告相对基线约1.5×–20×吞吐提升来源不仅是编程模型还有3D-HybridEngine等系统优化。2.2 执行模型Driver 视角main_task (Ray remote, 建议非 head) └── RayPPOTrainer.fit() ├── RLHFDataset / DataLoader → 全局 batch在 Driver ├── ResourcePool colocated WorkerGroup └── loop: dispatch DataProto → Workers Workers 内部Engine / Rollout SPMD collect → union → 轻量 advantageDriver update metrics ckpt精通要点Driver 应保持「薄」——只做编排、轻量统计与 advantage重计算、集体通信、优化器状态必须在 Worker/Engine 内。3. 现行组件分层2025–2026 主线旧fsdp_workers/megatron_workers/ 独立 Actor·Critic·ShardingManager 已收敛。精通应以engine_workers为准。3.1 分层图┌──────────────────────────────────────────────────────────┐ │ Trainer 层main_ppo / RayPPOTrainer / Hydra config │ │ - 算法循环、KL、advantage、校验、日志、ckpt 调度 │ └────────────────────────────┬─────────────────────────────┘ │ RayWorkerGroup DataProto ┌────────────────────────────▼─────────────────────────────┐ │ Worker 层engine_workers │ │ ActorRolloutRefWorker ─┬─ TrainingWorker (actor/ref) │ │ ├─ BaseRollout (vLLM/SGLang/HF) │ │ └─ checkpoint_engine (权重同步) │ │ TrainingWorker独立── Critic / RM / SFT / DPO │ └────────────────────────────┬─────────────────────────────┘ │ EngineRegistry ┌────────────────────────────▼─────────────────────────────┐ │ Engine 层BaseEngine 实现 │ │ FSDP/FSDP2 | Megatron | Automodel | VeOmni | TorchTitan │ │ ( NPU MindSpeed 等) │ │ forward_step / train_batch / infer_batch / ckpt / export│ └──────────────────────────────────────────────────────────┘3.2 ActorRolloutRefWorker角色组合表role构建内容典型场景actorTrainingWorker checkpoint engine纯训练角色rolloutBaseRollout独立推理池refforward-only TrainingWorker独立参考策略actor_rolloutactor rollout ckpt最常见 colocated PPOactor_rollout_ref三者全开单池最大复用LoRA PPO 友好为何 colo actorrollout权重同步可走 NCCL/本地避免跨机全量拷贝成为瓶颈。为何 colo actorrefLoRAref 即 baseadapter 开关即可省一整份大模型。3.3 TrainingWorker统一「引擎外壳」职责持有一个BaseEngine optimizer profilerset_loss_fn注入 PPO / distillation / 自定义 losstrain_mini_batch按 PPO epoch × mini-batch 循环每 mini-batch 一步优化infer_batchlogprob / value / reward / teacher支持no_lora_adapterto(cpu|device)手动 offload和生成阶段抢显存时关键Critic、RM、独立 Ref 都是同一套 TrainingWorker 不同 engine configlm_head vs value_head。3.4 EngineRegistry后端真正插拔点运行时由actor.strategy/engine.strategy解析例如model_typebackendEnginelanguage_modelfsdp / fsdp2FSDPEngineWithLMHeadlanguage_modelmegatronMegatronEngineWithLMHeadvalue_modelfsdp2 / megatron*EngineWithValueHead…automodel / veomni / torchtitan / mindspeed对应实现扩展新后端的标准路径实现BaseEngine子类forward_step、并行、ckpt、get_per_tensor_param等EngineRegistry.register(model_type..., backend...)配置strategy: your_backendWorker 层无需改已 engine-agnostic4. 单 Controller 编程模型深潜4.1 没有语法糖时的真实成本chunksdata.chunk(dp_size)futs[wg._workers[i].generate_sequences.remote(chunks[i])foriinrange(dp_size)]outtorch.cat(ray.get(futs),dim0)每个 RPC 都重复切分 → 分发 → 收集。算法一长可读性与正确性双崩。4.2register的契约register(dispatch_modeDispatch.DP_COMPUTE_PROTO)defgenerate_sequences(self,data:DataProto)-DataProto:...含义输入/输出遵循DataProto或现行 TensorDict 路径以源码为准Dispatcher 按并行拓扑切 batch各 rank SPMD 执行Collector 拼接/归约回 Driver预置模式历史与现行Dispatch.ONE_TO_ALL如init_model、update_weightsDispatch.DP_COMPUTE_PROTO纯 DP 切分make_nd_compute_dataproto_dispatch_fn(mesh_name...)从 Engine 实际 mesh 推导Megatron 的 PP 可对 Driver投影为额外 DP 维从而避免为每个后端手写MEGATRON_PP_AS_DP_PROTO精通时请直接读verl/single_controller/base/decorator.py与 Worker 上每个register。4.3 DataProto / batch 代数主循环大量使用pop抽出生成所需字段union把 logprob / values / rewards 并回同一 batchmeta_info携带 metrics、全局步数等设计纪律凡跨 Worker 的数据字段名、dtype、sequence 维、mask 约定必须稳定算法扩展优先「加字段 union」而不是另起平行数据结构。5. 权重同步与 3D-HybridEngine5.1 问题本质Actor训练并行布局大 TP/PP/EP、FSDP shard与推理布局vLLM/SGLang 的 TP、可能不同 PP几乎总不一致。朴素做法训练一份权重 推理一份权重 →约 2× 显存 昂贵 broadcast。5.2 3D-HybridEngine 思想论文精心选择生成阶段的 TP/PP 分组与 micro-DP使各卡上的训练分片与生成分片最大化重叠过渡期用并发 all-gather在 micro-DP 内完成布局变换目标近零权重冗余 显著降低 reshard 通信实践中在 verl 里体现为colocatedcheckpoint_engine.backend naive→engine.get_per_tensor_param→rollout.update_weightsdisaggregated / asyncnccl全量广播或delta只同步相对上轮变化的参数见 One Step Off Policy 配方LoRAmodel.lora.mergeTrue时可先 merge 再推给 rollout5.3update_weights时序典型同步 PPOupdate_actor → (可选 offload optimizer) → update_weights → generate_sequences → ...异步 / one-step-off边生成边训练rollout 用 θ_tactor 更新 θ_{t1}再通过 checkpoint_engine 推送精通者必须能根据集群拓扑选择模式优点代价 / 风险Colocated sync实现简单权重一致调试友好生成与训练串行GPU 利用率波形明显Disaggregated训练池与推理池异构扩缩需要稳定的权重传输与版本协议One-step-off async掩盖气泡吞吐更高轻微 off-policy要控 KL / 学习率 / sync 频率6. Ray Trainer初始化与放置策略6.1 ResourcePool 与 colocateRayResourcePool(process_on_nodes[n_gpus_per_node]*nnodes,use_gpuTrue,max_colocate_count1,# FSDP 常荐 1多角色进同一进程)FSDPmax_colocate_count1create_colocated_worker_cls合并角色减少 CUDA/分布式上下文。Megatron历史上更常1或分池若强行同进程合并各角色共享同一 3D 并行度——若要 actor/critic 不同 TP/PP应分 ResourcePool、不要 colocate。6.2 初始化顺序文档硬建议critic / ref / rm 先init_modelactor_rollout 最后 init让 vLLM 在剩余显存上规划 KV cache这是大规模训练「能不能稳跑」的关键运维知识不是风格问题。6.3 并行配置思维模型全局 batch在 Drivermicro batch在 Engine 防 OOM。改吞吐优先rollout 并行与 KV、生成长度、n每 prompt 采样数。改收敛优先ppo_mini_batch_size、ppo_epochs、clip_ratio、KL 机制、adv_estimator。切勿把 micro_batch 当成算法超参去扫在实现正确时不应改变收敛语义。7. 算法扩展范式从 PPO 到任意 RLHF官方原则一句话Single process drives multi-process computation and data communication.7.1 三步法务必内化列出 SPMD 计算 API例generate_sequences/compute_log_prob/update_policy/infer为每种分布式拓扑实现 dispatch/collect或复用内置在 Driver 用这些 API 编排控制流7.2 Online DPO 映射示例算法步骤Worker API每 prompt 生成 N 条SampleGenerator.generate_sequences打分排序成 pairDriver 或 RM Workerref logprobReferencePolicy.inferDPO 更新DPOActor.update同一 ResourcePool 可挂多组 WorkerGroup也可 colocate。多数情况下应复用 PPO 已验证的 Engine/Rollout而不是重写分布式。7.3 GRPO / 无 Critic 算法配置层algorithm.adv_estimatorgrpo等架构层可关掉 critic WorkerDriver 用组内相对奖励估优势精通点理解advantage 估计是算法可插拔点与 Engine 无关7.4 KL 控制的两条管路Reward 内 KLalgorithm.use_kl_in_rewardkl_ctrlfixed / adaptiveActor KL lossactor.use_kl_losskl_loss_coefkl_loss_typek1/k2/k3/full 及直通变体二者语义不同调参时不要混为同一个旋钮。Dual-clipclip_ratio_c则是对负优势过大 ratio 的下界保护。8. 性能与正确性精通级排查清单8.1 吞吐火焰图逻辑阶段阶段常见瓶颈方向timing/genKV、采样长度、rollout TP、调度气泡升推理引擎、拆推理池、异步weight sync全量广播、冗余两份权重HybridEngine / delta sync / coloupdate_actor并行度、重计算、通信FSDP2、Megatron 3D、activation ckptDriver 侧过大 batch 集中在 Driver、频繁 ray.get减 meta、避免大结果落地 CPU数据变长 padding 浪费seqlen balancing、pack8.2 正确性雷区Dispatch mesh 与真实并行不一致→ 静默错分数据比 OOM 更可怕。生成用 θ_new、logprob 用 θ_old 未对齐→ PPO ratio 语义损坏。token-level score 与 response mask 不对齐→ advantage 泄漏到 prompt。ref 与 actor tokenizer/chat template 不一致→ KL 失真。异步训练未限制离策略程度→ 短期吞吐升、长期不收敛。8.3 FSDP2 / Megatron 选择直觉中小模型、快速迭代FSDP2官方推荐方向更好内存与 composability可torch.compile。超大模型 / MoE / 极致 3DMegatron EP与 vLLM/SGLang 组合冲击数百 B 级。多轮 / 工具 / Agent优先评估 SGLang multiturn 与 sandbox 配方。9. 配置与代码的「控制平面」精通者应能从一份 Hydra 覆盖还原运行时拓扑actor_rollout_ref:model:path:...actor:strategy:fsdp2ppo_mini_batch_size:...ppo_micro_batch_size:...clip_ratio:0.2use_kl_loss:falserollout:name:vllm# 或 sglangn:1tensor_model_parallel_size:...ref:...critic:strategy:fsdp2algorithm:adv_estimator:gaeuse_kl_in_reward:falsegamma:...lam:...trainer:nnodes:...n_gpus_per_node:...阅读配置的顺序资源 → 角色是否 colocate → 训练 strategy → 推理引擎 → batch 三维global/mini/micro→ 算法adv/KL/clip→ 日志与 ckpt。10. 源码阅读地图建议顺序顺序路径读什么1verl/trainer/main_ppo.py入口、RewardManager、Worker 装配2verl/trainer/ppo/ray_trainer.pyfit真源placementvalidate3verl/single_controller/**WorkerGroup、decorator、ResourcePool4verl/workers/engine_workers.pyRPC 面与 role 组合5verl/workers/engine/**你使用的 Backend 实现6verl/workers/rollout/**生成与 update_weights7verl/trainer/ppo/core_algos.py或等价loss、KL、advantage8examples/tests/special_e2e/可运行契约与回归论文 HTMLhttps://arxiv.org/html/2409.19256 —— 精读Hybrid controller API与3D-HybridEngine 分组两节。11. 精通实践课题建议亲手做最小改动换算法在 Driver 把 PPO 换成「生成 N 条 → 组内归一化优势 → 无 Critic 更新」对照 GRPO 实现。自定义 Reward规则 RM 融合断言 token-level 形状。拆池ActorRollout 与 Critic 分 ResourcePool测量利用率与通信。新 Backend 骨架一个 dummyBaseEngine注册进 Registry跑通init_model 空train_batch。异步配方按官方 one-step-off 文档打开 delta sync画 θ 版本时间线。故障注入故意错误dispatch mesh观察现象并写排查笔记。12. 架构决策备忘录决策推荐默认何时偏离控制/计算分离保持极致定制内核且算法冻结时可考虑更紧耦合FSDP2中小到中大模型默认上 Megatron 当 3D/MoE 刚需Actor↔Rollout colo默认同步 PPO推理池要弹性扩缩时 disaggregateAdvantage 在 Driver轻量估计估计本身很重时下沉 Worker奖励在 Driver 组合规则多、逻辑活RM 很大时独立 RM Worker先正确后异步sync 收敛基线基线稳定后再 one-step-off13. 小结精通 verl不是背更多类名而是掌握四条杠杆控制流单进程—— 算法创新的主战场WorkerGroup Dispatch—— 把 SPMD 藏起来的边界Engine / Rollout 双后端—— 训练与生成各自 SOTAHybridEngine / checkpoint_engine—— 消除 RLHF 最贵的「两份权重 布局切换」税抓住这四条就能在 verl 上稳定扩展算法、模型规模与集群拓扑。参考链接HybridFlow 论文https://arxiv.org/abs/2409.19256Programming Guidehttps://verl.readthedocs.io/en/latest/hybrid_flow.htmlPPO Ray Trainerhttps://verl.readthedocs.io/en/latest/workers/ray_trainer.htmlEngine Workershttps://verl.readthedocs.io/en/latest/workers/engine_workers.html算法扩展https://verl.readthedocs.io/en/latest/advance/dpo_extension.htmlPPO / GRPOhttps://verl.readthedocs.io/en/latest/algo/ppo.html代码仓库https://github.com/verl-project/verl verl 架构精通指导
verl 架构精通指导面向已跑通 PPO/GRPO、需要改算法、换并行策略、做异步训练、扩展后端或压吞吐的工程师与研究员。阅读建议先读同目录《verl 架构入门指导》再按本文「问题驱动」深入。1. 精通目标你要能回答的问题为什么 HybridFlow 在 LLM-RL 上优于「纯多 Controller」与「纯单 Controller」权衡点在哪register/ Dispatch / Collect / n-d mesh 如何把 SPMD Worker 伪装成单机 APIActorRolloutRefWorkerTrainingWorkerBaseEngine Rollout 的职责边界与扩展点训练并行度DP/TP/PP/EP与生成并行度不一致时权重如何 reshard内存为何能接近「零冗余」如何用同一套 Worker 能力拼出 Online DPO / GRPO / 自定义算法而不复制后端代码Colocated vs Disaggregated、同步 vs One-step-off async 各自适用什么规模与延迟模型若以上都能画图并落到配置/代码路径即可视为「精通 verl 架构」。2. HybridFlow 设计精读2.1 两层 Dataflow 与软件复用论文与官方指南的关键洞察NN 训练图节点是算子边是 tensor。RL 图节点是高层算子rollout / logprob / update边是跨角色数据移动。LLM 把「节点内部」变成多进程后若把控制流也多进程化并对齐绑定维度统一多 Controller分离verl固定算法 固定后端的峰值效率往往更高略有 Driver 通信税换 FSDP↔Megatron / vLLM↔SGLang难控制与计算耦合易控制流不动写新算法GRPO、Online DPO…多进程协调成本高Driver 上改几段调用动态/异构放置难ResourcePool 映射即可verl 明确选择用少量通信换算法与后端的组合爆炸复用。论文报告相对基线约1.5×–20×吞吐提升来源不仅是编程模型还有3D-HybridEngine等系统优化。2.2 执行模型Driver 视角main_task (Ray remote, 建议非 head) └── RayPPOTrainer.fit() ├── RLHFDataset / DataLoader → 全局 batch在 Driver ├── ResourcePool colocated WorkerGroup └── loop: dispatch DataProto → Workers Workers 内部Engine / Rollout SPMD collect → union → 轻量 advantageDriver update metrics ckpt精通要点Driver 应保持「薄」——只做编排、轻量统计与 advantage重计算、集体通信、优化器状态必须在 Worker/Engine 内。3. 现行组件分层2025–2026 主线旧fsdp_workers/megatron_workers/ 独立 Actor·Critic·ShardingManager 已收敛。精通应以engine_workers为准。3.1 分层图┌──────────────────────────────────────────────────────────┐ │ Trainer 层main_ppo / RayPPOTrainer / Hydra config │ │ - 算法循环、KL、advantage、校验、日志、ckpt 调度 │ └────────────────────────────┬─────────────────────────────┘ │ RayWorkerGroup DataProto ┌────────────────────────────▼─────────────────────────────┐ │ Worker 层engine_workers │ │ ActorRolloutRefWorker ─┬─ TrainingWorker (actor/ref) │ │ ├─ BaseRollout (vLLM/SGLang/HF) │ │ └─ checkpoint_engine (权重同步) │ │ TrainingWorker独立── Critic / RM / SFT / DPO │ └────────────────────────────┬─────────────────────────────┘ │ EngineRegistry ┌────────────────────────────▼─────────────────────────────┐ │ Engine 层BaseEngine 实现 │ │ FSDP/FSDP2 | Megatron | Automodel | VeOmni | TorchTitan │ │ ( NPU MindSpeed 等) │ │ forward_step / train_batch / infer_batch / ckpt / export│ └──────────────────────────────────────────────────────────┘3.2 ActorRolloutRefWorker角色组合表role构建内容典型场景actorTrainingWorker checkpoint engine纯训练角色rolloutBaseRollout独立推理池refforward-only TrainingWorker独立参考策略actor_rolloutactor rollout ckpt最常见 colocated PPOactor_rollout_ref三者全开单池最大复用LoRA PPO 友好为何 colo actorrollout权重同步可走 NCCL/本地避免跨机全量拷贝成为瓶颈。为何 colo actorrefLoRAref 即 baseadapter 开关即可省一整份大模型。3.3 TrainingWorker统一「引擎外壳」职责持有一个BaseEngine optimizer profilerset_loss_fn注入 PPO / distillation / 自定义 losstrain_mini_batch按 PPO epoch × mini-batch 循环每 mini-batch 一步优化infer_batchlogprob / value / reward / teacher支持no_lora_adapterto(cpu|device)手动 offload和生成阶段抢显存时关键Critic、RM、独立 Ref 都是同一套 TrainingWorker 不同 engine configlm_head vs value_head。3.4 EngineRegistry后端真正插拔点运行时由actor.strategy/engine.strategy解析例如model_typebackendEnginelanguage_modelfsdp / fsdp2FSDPEngineWithLMHeadlanguage_modelmegatronMegatronEngineWithLMHeadvalue_modelfsdp2 / megatron*EngineWithValueHead…automodel / veomni / torchtitan / mindspeed对应实现扩展新后端的标准路径实现BaseEngine子类forward_step、并行、ckpt、get_per_tensor_param等EngineRegistry.register(model_type..., backend...)配置strategy: your_backendWorker 层无需改已 engine-agnostic4. 单 Controller 编程模型深潜4.1 没有语法糖时的真实成本chunksdata.chunk(dp_size)futs[wg._workers[i].generate_sequences.remote(chunks[i])foriinrange(dp_size)]outtorch.cat(ray.get(futs),dim0)每个 RPC 都重复切分 → 分发 → 收集。算法一长可读性与正确性双崩。4.2register的契约register(dispatch_modeDispatch.DP_COMPUTE_PROTO)defgenerate_sequences(self,data:DataProto)-DataProto:...含义输入/输出遵循DataProto或现行 TensorDict 路径以源码为准Dispatcher 按并行拓扑切 batch各 rank SPMD 执行Collector 拼接/归约回 Driver预置模式历史与现行Dispatch.ONE_TO_ALL如init_model、update_weightsDispatch.DP_COMPUTE_PROTO纯 DP 切分make_nd_compute_dataproto_dispatch_fn(mesh_name...)从 Engine 实际 mesh 推导Megatron 的 PP 可对 Driver投影为额外 DP 维从而避免为每个后端手写MEGATRON_PP_AS_DP_PROTO精通时请直接读verl/single_controller/base/decorator.py与 Worker 上每个register。4.3 DataProto / batch 代数主循环大量使用pop抽出生成所需字段union把 logprob / values / rewards 并回同一 batchmeta_info携带 metrics、全局步数等设计纪律凡跨 Worker 的数据字段名、dtype、sequence 维、mask 约定必须稳定算法扩展优先「加字段 union」而不是另起平行数据结构。5. 权重同步与 3D-HybridEngine5.1 问题本质Actor训练并行布局大 TP/PP/EP、FSDP shard与推理布局vLLM/SGLang 的 TP、可能不同 PP几乎总不一致。朴素做法训练一份权重 推理一份权重 →约 2× 显存 昂贵 broadcast。5.2 3D-HybridEngine 思想论文精心选择生成阶段的 TP/PP 分组与 micro-DP使各卡上的训练分片与生成分片最大化重叠过渡期用并发 all-gather在 micro-DP 内完成布局变换目标近零权重冗余 显著降低 reshard 通信实践中在 verl 里体现为colocatedcheckpoint_engine.backend naive→engine.get_per_tensor_param→rollout.update_weightsdisaggregated / asyncnccl全量广播或delta只同步相对上轮变化的参数见 One Step Off Policy 配方LoRAmodel.lora.mergeTrue时可先 merge 再推给 rollout5.3update_weights时序典型同步 PPOupdate_actor → (可选 offload optimizer) → update_weights → generate_sequences → ...异步 / one-step-off边生成边训练rollout 用 θ_tactor 更新 θ_{t1}再通过 checkpoint_engine 推送精通者必须能根据集群拓扑选择模式优点代价 / 风险Colocated sync实现简单权重一致调试友好生成与训练串行GPU 利用率波形明显Disaggregated训练池与推理池异构扩缩需要稳定的权重传输与版本协议One-step-off async掩盖气泡吞吐更高轻微 off-policy要控 KL / 学习率 / sync 频率6. Ray Trainer初始化与放置策略6.1 ResourcePool 与 colocateRayResourcePool(process_on_nodes[n_gpus_per_node]*nnodes,use_gpuTrue,max_colocate_count1,# FSDP 常荐 1多角色进同一进程)FSDPmax_colocate_count1create_colocated_worker_cls合并角色减少 CUDA/分布式上下文。Megatron历史上更常1或分池若强行同进程合并各角色共享同一 3D 并行度——若要 actor/critic 不同 TP/PP应分 ResourcePool、不要 colocate。6.2 初始化顺序文档硬建议critic / ref / rm 先init_modelactor_rollout 最后 init让 vLLM 在剩余显存上规划 KV cache这是大规模训练「能不能稳跑」的关键运维知识不是风格问题。6.3 并行配置思维模型全局 batch在 Drivermicro batch在 Engine 防 OOM。改吞吐优先rollout 并行与 KV、生成长度、n每 prompt 采样数。改收敛优先ppo_mini_batch_size、ppo_epochs、clip_ratio、KL 机制、adv_estimator。切勿把 micro_batch 当成算法超参去扫在实现正确时不应改变收敛语义。7. 算法扩展范式从 PPO 到任意 RLHF官方原则一句话Single process drives multi-process computation and data communication.7.1 三步法务必内化列出 SPMD 计算 API例generate_sequences/compute_log_prob/update_policy/infer为每种分布式拓扑实现 dispatch/collect或复用内置在 Driver 用这些 API 编排控制流7.2 Online DPO 映射示例算法步骤Worker API每 prompt 生成 N 条SampleGenerator.generate_sequences打分排序成 pairDriver 或 RM Workerref logprobReferencePolicy.inferDPO 更新DPOActor.update同一 ResourcePool 可挂多组 WorkerGroup也可 colocate。多数情况下应复用 PPO 已验证的 Engine/Rollout而不是重写分布式。7.3 GRPO / 无 Critic 算法配置层algorithm.adv_estimatorgrpo等架构层可关掉 critic WorkerDriver 用组内相对奖励估优势精通点理解advantage 估计是算法可插拔点与 Engine 无关7.4 KL 控制的两条管路Reward 内 KLalgorithm.use_kl_in_rewardkl_ctrlfixed / adaptiveActor KL lossactor.use_kl_losskl_loss_coefkl_loss_typek1/k2/k3/full 及直通变体二者语义不同调参时不要混为同一个旋钮。Dual-clipclip_ratio_c则是对负优势过大 ratio 的下界保护。8. 性能与正确性精通级排查清单8.1 吞吐火焰图逻辑阶段阶段常见瓶颈方向timing/genKV、采样长度、rollout TP、调度气泡升推理引擎、拆推理池、异步weight sync全量广播、冗余两份权重HybridEngine / delta sync / coloupdate_actor并行度、重计算、通信FSDP2、Megatron 3D、activation ckptDriver 侧过大 batch 集中在 Driver、频繁 ray.get减 meta、避免大结果落地 CPU数据变长 padding 浪费seqlen balancing、pack8.2 正确性雷区Dispatch mesh 与真实并行不一致→ 静默错分数据比 OOM 更可怕。生成用 θ_new、logprob 用 θ_old 未对齐→ PPO ratio 语义损坏。token-level score 与 response mask 不对齐→ advantage 泄漏到 prompt。ref 与 actor tokenizer/chat template 不一致→ KL 失真。异步训练未限制离策略程度→ 短期吞吐升、长期不收敛。8.3 FSDP2 / Megatron 选择直觉中小模型、快速迭代FSDP2官方推荐方向更好内存与 composability可torch.compile。超大模型 / MoE / 极致 3DMegatron EP与 vLLM/SGLang 组合冲击数百 B 级。多轮 / 工具 / Agent优先评估 SGLang multiturn 与 sandbox 配方。9. 配置与代码的「控制平面」精通者应能从一份 Hydra 覆盖还原运行时拓扑actor_rollout_ref:model:path:...actor:strategy:fsdp2ppo_mini_batch_size:...ppo_micro_batch_size:...clip_ratio:0.2use_kl_loss:falserollout:name:vllm# 或 sglangn:1tensor_model_parallel_size:...ref:...critic:strategy:fsdp2algorithm:adv_estimator:gaeuse_kl_in_reward:falsegamma:...lam:...trainer:nnodes:...n_gpus_per_node:...阅读配置的顺序资源 → 角色是否 colocate → 训练 strategy → 推理引擎 → batch 三维global/mini/micro→ 算法adv/KL/clip→ 日志与 ckpt。10. 源码阅读地图建议顺序顺序路径读什么1verl/trainer/main_ppo.py入口、RewardManager、Worker 装配2verl/trainer/ppo/ray_trainer.pyfit真源placementvalidate3verl/single_controller/**WorkerGroup、decorator、ResourcePool4verl/workers/engine_workers.pyRPC 面与 role 组合5verl/workers/engine/**你使用的 Backend 实现6verl/workers/rollout/**生成与 update_weights7verl/trainer/ppo/core_algos.py或等价loss、KL、advantage8examples/tests/special_e2e/可运行契约与回归论文 HTMLhttps://arxiv.org/html/2409.19256 —— 精读Hybrid controller API与3D-HybridEngine 分组两节。11. 精通实践课题建议亲手做最小改动换算法在 Driver 把 PPO 换成「生成 N 条 → 组内归一化优势 → 无 Critic 更新」对照 GRPO 实现。自定义 Reward规则 RM 融合断言 token-level 形状。拆池ActorRollout 与 Critic 分 ResourcePool测量利用率与通信。新 Backend 骨架一个 dummyBaseEngine注册进 Registry跑通init_model 空train_batch。异步配方按官方 one-step-off 文档打开 delta sync画 θ 版本时间线。故障注入故意错误dispatch mesh观察现象并写排查笔记。12. 架构决策备忘录决策推荐默认何时偏离控制/计算分离保持极致定制内核且算法冻结时可考虑更紧耦合FSDP2中小到中大模型默认上 Megatron 当 3D/MoE 刚需Actor↔Rollout colo默认同步 PPO推理池要弹性扩缩时 disaggregateAdvantage 在 Driver轻量估计估计本身很重时下沉 Worker奖励在 Driver 组合规则多、逻辑活RM 很大时独立 RM Worker先正确后异步sync 收敛基线基线稳定后再 one-step-off13. 小结精通 verl不是背更多类名而是掌握四条杠杆控制流单进程—— 算法创新的主战场WorkerGroup Dispatch—— 把 SPMD 藏起来的边界Engine / Rollout 双后端—— 训练与生成各自 SOTAHybridEngine / checkpoint_engine—— 消除 RLHF 最贵的「两份权重 布局切换」税抓住这四条就能在 verl 上稳定扩展算法、模型规模与集群拓扑。参考链接HybridFlow 论文https://arxiv.org/abs/2409.19256Programming Guidehttps://verl.readthedocs.io/en/latest/hybrid_flow.htmlPPO Ray Trainerhttps://verl.readthedocs.io/en/latest/workers/ray_trainer.htmlEngine Workershttps://verl.readthedocs.io/en/latest/workers/engine_workers.html算法扩展https://verl.readthedocs.io/en/latest/advance/dpo_extension.htmlPPO / GRPOhttps://verl.readthedocs.io/en/latest/algo/ppo.html代码仓库https://github.com/verl-project/verl