verl 核心模块总览¶
本目录包含 verl 框架核心基础模块的代码讲解文档。这些模块定义了框架的基本数据结构和配置机制，是理解整个 verl 框架的起点。
阅读顺序¶
建议按以下顺序阅读，由浅入深：
| 顺序 | 文档 | 对应源文件 | 内容概要 |
|---|---|---|---|
| 1 | 01_init.md | verl/__init__.py |
包入口文件，了解 verl 的整体结构和公开 API |
| 2 | 03_base_config.md | verl/base_config.py |
基础配置类，理解 verl 的配置管理方式 |
| 3 | 02_protocol.md | verl/protocol.py |
最核心的数据传输协议，理解数据如何在模块间流动 |
为什么建议先读 base_config 再读 protocol？因为 base_config 很短（87 行），概念简单，可以快速建立信心；而 protocol 是核心中的核心，内容最多，需要集中精力理解。
三个模块的关系¶
verl/__init__.py ← 包入口，暴露公开 API
│
├── 导入 DataProto ←── verl/protocol.py ← 核心数据协议
│ │
│ ├── 定义数据如何封装、传输、分片、合并
│ └── 支持分布式（Ray）和异步执行
│
└── (独立) verl/base_config.py ← 基础配置类
│
└── 定义配置如何创建、访问、保护
__init__.py是入口，将DataProto暴露给用户protocol.py定义了最核心的DataProto数据结构base_config.py定义了配置基类，与前两者独立
核心概念速查¶
DataProto — 数据传输的"快递包裹"¶
verl 中所有模块间的数据传递都通过 DataProto 完成。它包含三层：
batch（TensorDict）：存放 PyTorch tensor，如input_ids、attention_masknon_tensor_batch（dict of numpy arrays）：存放非 tensor 数据，如原始文本meta_info（dict）：存放元信息，如超参数
核心操作：
- chunk(n) — 分成 n 份（用于分发给 n 个 worker）
- concat(list) — 将多个 DataProto 合并（用于收集 worker 结果）
- union(other) — 合并不同字段（用于组合不同模块的输出）
- make_iterator(batch_size, epochs) — 创建 mini-batch 迭代器
BaseConfig — 安全的配置管理¶
继承 BaseConfig 的配置类具有两个特性：
- 字段默认不可变，防止意外修改
- 支持字典式访问，兼容各种框架
背景知识¶
如果你对以下概念不熟悉，建议在阅读文档前了解：