verl 框架代码教程¶
面向零基础研究生的 verl 强化学习框架逐文件代码讲解
欢迎¶
本教程对 verl（字节跳动 Seed 团队开发的大语言模型强化学习训练框架）的 全部源代码 进行了逐文件讲解，共计 411 篇文档，覆盖 397 个 Python 源文件。
即使你完全不懂强化学习和分布式训练，也可以通过本教程从零开始理解整个框架。
框架架构总览¶
┌─────────────────────────────────────────────────────────────────────┐
│ verl 框架架构 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Single Controller (Driver 进程) │ │
│ │ │ │
│ │ Python 编写 RL 训练逻辑 (PPO / GRPO / DAPO ...) │ │
│ │ 控制各 Worker 的执行顺序和数据传递 (DataProto) │ │
│ └─────┬──────────┬──────────┬──────────┬────────────────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌──────────┐┌──────────┐┌──────────┐┌──────────────┐ │
│ │ Actor ││ Critic ││ Reward ││ Reference │ │
│ │ Worker ││ Worker ││ Worker ││ Worker │ │
│ │ (策略模型) ││ (价值模型) ││ (奖励模型) ││ (参考模型) │ │
│ └────┬─────┘└────┬─────┘└────┬─────┘└──────┬───────┘ │
│ │ │ │ │ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 计算后端 (可灵活选择) │ │
│ │ │ │
│ │ 训练: FSDP / FSDP2 / Megatron-LM │ │
│ │ 推理: vLLM / SGLang / HF Transformers │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ 3D-HybridEngine │ │ │
│ │ │ 训练模式 ◄──参数重分片(Resharding)──► 推理模式 │ │ │
│ │ │ (FSDP/Megatron) (vLLM) │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ GPU 资源 │ │
│ │ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │ │
│ │ │GPU 0 │ │GPU 1 │ │GPU 2 │ │GPU 3 │ │ ... │ │ │
│ │ └───────┘ └───────┘ └───────┘ └───────┘ └───────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
PPO 训练主流程¶
每一轮 PPO 训练迭代按以下顺序执行：
Prompts (一批训练提示)
│
▼
┌────────────────┐
│ ① Rollout 阶段 │ Actor 模型生成回复 (调用 vLLM/SGLang 推理引擎)
│ Actor.generate│
└───────┬────────┘
│ responses
▼
┌────────────────┐
│ ② 打分阶段 │ Reward Model 对回复质量打分
│ RM.score │ Reference Model 计算参考 log_probs (用于 KL 惩罚)
└───────┬────────┘
│ rewards + ref_log_probs
▼
┌────────────────┐
│ ③ 估值阶段 │ Critic 模型估计每个 token 的价值 V(s)
│ Critic.value │
└───────┬────────┘
│ values
▼
┌────────────────┐
│ ④ 计算优势 │ GAE 算法计算优势函数 A(s,a)
│ GAE │ advantage = reward + γV(s') - V(s) (累积折扣)
└───────┬────────┘
│ advantages
▼
┌────────────────┐
│ ⑤ PPO 更新 │ 用 Clip 目标函数更新 Actor 参数
│ Actor.update │ 用价值损失更新 Critic 参数
│ Critic.update │ KL 散度惩罚防止偏离参考模型
└────────────────┘
│
▼
回到 ① 开始下一轮
代码与流程的对应关系¶
| 训练步骤 | 对应代码 | 教程文档 |
|---|---|---|
| 训练主循环 | trainer/main_ppo.py |
训练入口 |
| Ray 分布式调度 | trainer/ppo/ray_trainer.py |
Ray PPO 训练器 |
| PPO/GAE 核心算法 | trainer/ppo/core_algos.py |
核心算法 |
| Actor 生成 & 训练 | workers/actor/ |
Actor Worker |
| Critic 估值 & 训练 | workers/critic/ |
Critic Worker |
| Rollout 推理引擎 | workers/rollout/ |
Rollout Worker |
| 数据协议 DataProto | protocol.py |
数据协议 |
| Worker 编排 | single_controller/ |
单控制器 |
从哪里开始？¶
快速入门（约 2 小时）¶
- 背景知识 — RL、RLHF、PPO、分布式训练基础
- 核心模块 - protocol.py — 框架的数据传输协议
- 训练器 - ray_trainer.py — PPO 训练主循环
- 训练器 - core_algos.py — PPO/GRPO 算法实现
完整学习路线¶
请阅读 阅读指南，其中包含三条不同深度的学习路线和完整文档目录。
模块总览¶
| 模块 | 文档数 | 说明 |
|---|---|---|
| 核心模块 | 4 | DataProto 数据协议、配置基类 |
| 训练器 | 19 | PPO 训练入口、核心算法、SFT |
| Workers | 74 | Actor、Critic、Rollout、Engine |
| 单控制器 | 8 | Ray 分布式 Worker 编排 |
| 模型 | 58 | LLaMA、Qwen2、Megatron 并行 |
| 检查点引擎 | 8 | 分布式模型权重传输 |
| 工具库 | 108 | 数据集、Checkpoint、Profiler 等 |
| 工具 | 16 | Tool Use 工具框架 |
| 交互 | 7 | 多轮对话交互循环 |
| 模型合并 | 6 | 分布式 Checkpoint 合并 |
| 实验性功能 | 92 | 异步训练、VLA、Agent Loop |
| 第三方集成 | 6 | PyTorch/vLLM 补丁 |
背景知识¶
如果你对以下概念不熟悉，建议先阅读 背景知识文档：
- 强化学习（RL）基本概念
- RLHF（人类反馈强化学习）
- PPO（近端策略优化）算法
- 分布式训练（DP、TP、PP、FSDP）