verl 代码阅读指南¶
本文档帮助你规划 verl 源代码的阅读路径。如果你还没有读过背景知识，请先阅读 00_background_knowledge.md。
推荐阅读顺序¶
verl 的代码量较大（约 400 个 Python 文件），不建议从头到尾线性阅读。以下是按优先级排列的阅读路线图，分为 必读、重要 和 选读 三个层次。
第一阶段：核心基础（必读）¶
理解 verl 的数据流和编程模型，这是后续一切的基础。
| 顺序 | 文档 | 内容 |
|---|---|---|
| 1 | core/01_init.md | 包入口，了解 verl 导出了什么 |
| 2 | core/03_base_config.md | 配置管理基础 |
| 3 | core/02_protocol.md | 最核心 —— DataProto 数据协议 |
读完这三个文件，你就能回答："verl 中数据是怎么表示和传递的？"
第二阶段：单控制器编程模型（必读）¶
理解 verl 的分布式编程范式——如何用简单的 Python 代码控制多 GPU 计算。
| 顺序 | 文档 | 内容 |
|---|---|---|
| 4 | single_controller/index.md | 模块总览 |
| 5 | single_controller/base/decorator.md | @register 装饰器 |
| 6 | single_controller/base/worker.md | Worker 基类 |
| 7 | single_controller/base/worker_group.md | WorkerGroup 管理 |
读完这部分，你就能回答："verl 的分布式任务是怎么调度和执行的？"
第三阶段：PPO 训练流程（必读）¶
理解完整的 RLHF 训练循环。
| 顺序 | 文档 | 内容 |
|---|---|---|
| 8 | trainer/index.md | 训练器模块总览 |
| 9 | trainer/main_ppo.py.md | PPO 训练入口 |
| 10 | trainer/ppo/ray_trainer.py.md | Ray PPO Trainer 核心逻辑 |
| 11 | trainer/ppo/core_algos.py.md | PPO/GRPO 等算法实现 |
读完这部分，你就能回答："一轮 PPO 训练是怎么跑起来的？"
第四阶段：Worker 实现（重要）¶
了解各角色（Actor、Critic、Rollout）的具体实现。
| 顺序 | 文档 | 内容 |
|---|---|---|
| 12 | workers/index.md | Workers 模块总览和架构图 |
| 13 | workers/fsdp_workers.md | FSDP 后端 Worker 实现 |
| 14 | workers/actor/ | Actor Worker 详细实现 |
| 15 | workers/critic/ | Critic Worker 详细实现 |
| 16 | workers/rollout/ | Rollout 推理引擎集成 |
第五阶段：模型和工具（重要）¶
| 顺序 | 文档 | 内容 |
|---|---|---|
| 17 | models/index.md | 模型适配总览 |
| 18 | models/transformers/llama.md | LLaMA 模型序列并行适配 |
| 19 | checkpoint_engine/index.md | 权重同步引擎 |
| 20 | utils/index.md | 工具函数总览 |
第六阶段：高级特性（选读）¶
根据你的兴趣选择性阅读。
| 文档 | 内容 |
|---|---|
| experimental/agent_loop/ | Agent 循环（多轮对话、工具调用） |
| tools/ | 工具系统（搜索、代码执行等） |
| model_merger/ | 分布式 checkpoint 合并工具 |
| experimental/vla/ | 视觉-语言-动作模型（机器人控制） |
| experimental/fully_async_policy/ | 全异步训练 |
阅读技巧¶
- 先看 README：每个模块目录下都有
index.md，先读它了解模块全貌 - 关注数据流：理解数据从哪里来、经过什么处理、到哪里去
- 跟着
DataProto：它是 verl 的数据载体，跟着它的chunk、concat、union就能理解数据流转 - 看注册表模式：verl 大量使用注册表模式（
@register），理解一个就理解了所有 - 回头查背景知识：遇到不懂的概念，回到 背景知识文档 查阅
各模块 README 索引¶
| 模块 | README |
|---|---|
| 核心 | core/index.md |
| 单控制器 | single_controller/index.md |
| 训练器 | trainer/index.md |
| Workers | workers/index.md |
| 模型 | models/index.md |
| 工具函数 | utils/index.md |
| Checkpoint 引擎 | checkpoint_engine/index.md |
| 模型合并 | model_merger/index.md |
| 工具系统 | tools/index.md |
| 交互 | interactions/index.md |
| 实验性功能 | experimental/index.md |
| 第三方 | third_party/index.md |