verl 架构入门指导面向想快速理解 verl 在做什么、核心组件如何协作、如何跑通第一条 RL 训练链路的读者。依据HybridFlow 论文、verl 官方文档、verl-project/verl 当前主线设计。1. 一句话理解 verlverlVolcano Engine Reinforcement Learning是字节开源的大模型后训练 / RLHF 框架对应论文 HybridFlow。它解决的核心问题是大模型时代的 RL 既要像「写单机算法伪代码」一样灵活改训练流程又要能高效对接 FSDP / Megatron、vLLM / SGLang 等分布式训练与推理引擎。verl 的答案是控制流单进程Driver 计算流多进程Worker二者通过 Ray 与统一数据协议DataProto解耦。2. 为什么需要这套架构2.1 RL 是两层 Dataflow层级含义例子Control Flow控制流算法步骤怎么排PPO先 rollout → 算 advantage → 更新 actor/criticComputation Flow计算流神经网络怎么算模型 forward / backward / optimizervLLM 生成小模型时代可以把计算直接嵌进控制流单进程。LLM 时代训练与生成本身已是多进程程序于是出现两条路统一多 Controller控制流也改成多进程和计算流绑死 → 性能好但换后端/换算法都难。分离verl 选择控制流保持单进程计算流交给 Worker →算法好写、后端可插拔代价是 Driver↔Worker 有数据搬运。2.2 HybridFlow 的直觉图┌─────────────────────────────┐ │ Driver / RayPPOTrainer │ ← 单进程写 PPO/GRPO 主循环 │ (main_task / fit) │ └──────────────┬──────────────┘ │ DataProto register 分发/收集 ┌─────────┼─────────┬──────────────┐ ▼ ▼ ▼ ▼ ActorRollout Critic Reward/Ref ResourcePool(GPU) (训练生成) (价值) (打分/参考) │ ├── TrainingEngine (FSDP2 / Megatron / ...) └── RolloutEngine (vLLM / SGLang / HF)记住三句话即可入门算法写在 Driver 上看起来像单机 for-loop。重活跑在 Worker 上每个 Worker 占 GPU。WorkerGroup 是代理一次调用 自动切分数据 → RPC → 汇总结果。3. 核心概念速查概念是什么入门只需知道Driver / main_taskRay remote 的控制器进程不要跑在 Ray head省内存里面构造 Trainer 并fit()RayPPOTrainerPPO及同类算法训练器负责数据加载、建 WorkerGroup、跑主循环Worker远程 GPU 上的计算单元暴露init_model、generate_sequences、update_actor等 RPCWorkerGroupWorker 列表的代理Driver 调用wg.generate_sequences(data)即可ResourcePoolGPU 资源组决定 Worker 放在哪些节点/卡上DataProto统一数据容器batch tensor meta是分发/收集的标准接口register(dispatch_mode…)把「切分-分发-收集」绑到 Worker 方法上例如Dispatch.DP_COMPUTE_PROTOActorRolloutRefWorker可组合的混合 Worker可只做 actor / rollout / ref或任意组合方便权重同步与 LoRARewardManager奖励组装器可规则奖励 模型奖励最终给出 token-level reward4. 仓库地图先认路verl/ trainer/ main_ppo.py # RL 入口main_task RewardManager ppo/ray_trainer.py # PPO 主循环 config/ # Hydra 配置模板 workers/ protocol.py # DataProto engine_workers.py # ActorRolloutRefWorker / TrainingWorker现行统一入口 engine/ # FSDP / Megatron / TorchTitan / VeOmni ... rollout/ # vLLM / SGLang / HF utils/ dataset/ # RLHFDataset 等 reward_score/ # gsm8k、math 等规则奖励 examples/ # 可直接改的启动脚本说明旧版fsdp_workers/megatron_workers已收敛到engine_workers EngineRegistry入门时直接看现行 API 即可。5. PPO 主循环用「像单机一样」的代码读懂架构Driver 上的逻辑近似如下与文档一致便于建立心智模型forpromptindataloader:outputactor_rollout_ref_wg.generate_sequences(prompt)old_log_probactor_rollout_ref_wg.compute_log_prob(output)ref_log_probactor_rollout_ref_wg.compute_ref_log_prob(output)valuescritic_wg.compute_values(output)rewardsreward_fn(output)# 也可先 rm_wg.compute_rm_scoreadvantagescompute_advantages(...)# 轻量计算可留在 Driveractor_rollout_ref_wg.update_actor(batch)critic_wg.update_critic(batch)读这段时请对照generate_sequences在 Rollout 引擎常为 vLLM上采样。compute_log_probActor 重算旧策略 logπ。compute_ref_log_prob参考策略用于 KL。compute_valuesCritic 估价值。reward_fn/ RM得到 token-level score。compute_advantagesGAE 等常在 Driver 上算。update_*真正的分布式训练步。这就是 HybridFlow 的「可编程性」换算法 改这个 for-loop 的步骤顺序与公式而不必重写 FSDP/vLLM 内部。6. 一次完整训练链路从配置到跑通推荐按这个顺序上手环境按官方 Installation 安装确认 Ray、训练后端、推理后端版本匹配。数据准备 parquetprompt 等字段用RLHFDataset做 chat template、padding、截断、tokenize。奖励在RewardManager/reward_score实现规则奖励或挂 Reward Model。配置从ppo_trainer.yaml/examples脚本起步先改data.train_files/train_batch_sizeactor_rollout_ref.model.pathtrainer.n_gpus_per_node/nnodesactor_rollout_ref.actor.strategy如fsdp2actor_rollout_ref.rollout后端vLLM / SGLang启动python -m verl.trainer.main_ppo或 examples 里的 bash先用小模型如 0.5B 小 batch 验证链路。观察关注timing/gen、timing/update_actor、reward / KL / response length 等指标。6.1 入门必懂的几个 batch 概念配置项含义data.train_batch_size全局 prompt 数轨迹数 ≈ batch ×rollout.nactor.ppo_mini_batch_sizePPO 更新时的全局 mini-batch*.ppo_micro_batch_size单次 forward/backward 上限防 OOM不改算法语义actor.clip_ratioPPO clip默认约 0.2algorithm.adv_estimatorgae/grpo/rloo等7. 角色与放置Placement入门常见 Worker 角色Actor Rollout常 colocated同卡便于 NCCL/本地快速同步权重。Reference可与 Actor 同进程尤其 LoRAref ≈ base。Critic价值网络PPO 需要GRPO 等可不需要。Reward Model可选常与规则奖励组合。入门实践建议FSDP常用max_colocate_count1多角色合并到同一进程减少 CUDA context。先 colocated 再拆分拆到不同 ResourcePool 能换并行度但配置更复杂。最后再 init rollout文档建议 rollout 后建便于 vLLM 更准地估 KV cache 内存。8. 和常见框架的关系心智对齐组件verl 里通常扮演Ray进程编排、RPC、资源池FSDP / FSDP2 / MegatronActor/Critic训练并行vLLM / SGLang**生成rollout**吞吐HuggingFace模型与 tokenizer 生态入口Hydra / OmegaConf配置组合与命令行覆盖verl 不是「又一个 PPO 实现」而是把 RL 控制流做成可组合编排层底下换训练/推理后端。9. 入门学习路径建议 1–2 周阶段目标材料Day 1–2建立 HybridFlow 心智模型本文 §1–5官方 HybridFlow Programming GuideDay 3–4跑通小模型 PPOQuickstart examplesDay 5–6读主循环与配置PPO Ray Trainer、PPODay 7换奖励 / 试 GRPOreward_score、GRPO入门验收标准能画一张 Driver / WorkerGroup / Engine 关系图能解释为什么 Actor 与 Rollout 常放一起能独立改数据、奖励、batch、模型路径并跑通能说明DataProtoregister省掉了哪三段样板代码10. 常见坑入门版main_task 打在 Ray head 上→ head 资源少易内存打爆。micro_batch 设太大→ OOM先降 micro再动全局 batch。训练后端与 vLLM 版本不匹配→ 按官方安装矩阵对齐。把算法逻辑写进 Worker→ 违背解耦算法步骤应留在 Driver。忽略 token-level reward 形状→ advantage / PPO loss 会对不齐。11. 小结verl 入门只需抓住一条主线单进程写 RL 算法 → WorkerGroup 代理分布式计算 → Engine 插拔训练与生成。搞清这条主线后再深入 3D-HybridEngine、异步 off-policy、自定义BaseEngine等请阅读同目录下的《verl 架构精通指导》。参考链接论文https://arxiv.org/abs/2409.19256文档https://verl.readthedocs.io/en/latest/代码https://github.com/verl-project/verlHybridFlow 编程指南https://verl.readthedocs.io/en/latest/hybrid_flow.html