verl 框架教程 -- 阅读指南¶
本文档帮助你规划阅读路线，让你用最合理的顺序理解 verl 框架的每一个模块。
一、欢迎¶
欢迎来到 verl 框架教程！
verl 是一个面向大语言模型（LLM）强化学习训练的开源框架，核心实现了 RLHF（基于人类反馈的强化学习）训练流程，包括 PPO 算法、分布式 Worker 调度、多种推理引擎集成等能力。
这套教程为每一个源码文件都编写了对应的讲解文档，总计 200+ 篇，覆盖了 verl 框架的全部代码。无论你是想快速了解整体架构，还是想深入某个具体实现，都能在这里找到对应的讲解。
二、前置知识¶
阅读本教程前，建议你具备以下基础：
| 知识领域 | 最低要求 | 推荐水平 |
|---|---|---|
| Python | 熟悉类、装饰器、上下文管理器 | 熟练使用 dataclass、typing |
| PyTorch | 了解 Tensor、Module、前向传播 | 熟悉分布式训练（DDP/FSDP） |
| 深度学习 | 了解 Transformer、Loss、Optimizer | 了解 LLM 微调流程 |
| 强化学习 | 不需要 -- 教程会从零讲起 | 了解 PPO 会更轻松 |
| 分布式系统 | 不需要 -- 教程会从零讲起 | 了解 Ray 框架会更轻松 |
如果你对强化学习完全陌生，请先阅读 00_background_knowledge.md，它会从零开始讲解 RL、RLHF、PPO 等核心概念。
三、推荐阅读路线图¶
路线 A：快速入门（约 2 小时）¶
目标：理解 verl 的核心架构和 PPO 训练流程，建立全局视角。
阅读顺序（共 8 篇）：
1. 00_background_knowledge.md -- 背景知识，理解 RL/RLHF/PPO 是什么
2. core/index.md -- 核心模块总览
3. core/02_protocol.md -- DataProto：数据如何在模块间流动
4. trainer/index.md -- Trainer 模块总览
5. trainer/main_ppo.py.md -- PPO 训练入口：一切从这里开始
6. trainer/ppo/ray_trainer.py.md -- Ray 分布式 PPO 训练器：核心调度逻辑
7. trainer/ppo/core_algos.py.md -- PPO 核心算法：优势估计与策略损失
8. workers/index.md -- Workers 模块总览：了解 Actor/Critic/Rollout 架构
读完这 8 篇，你就能理解 verl 框架的"骨架"——数据怎么定义、训练怎么发起、PPO 怎么计算、Worker 怎么分工。
路线 B：完整学习路线（按依赖关系排序）¶
目标：系统地从底层到上层读完所有模块。
阶段 1 -- 基础层（先读这些，因为所有上层模块都依赖它们）
├── 00_background_knowledge.md
├── core/（init → base_config → protocol）
└── utils/（device → config → distributed → fsdp_utils → 其他工具）
阶段 2 -- 分布式控制层
└── single_controller/（init → worker → decorator → worker_group → ray/）
阶段 3 -- 模型层
├── models/（registry → transformers/ → mcore/ → llama_megatron/ → qwen2_megatron/）
└── checkpoint_engine/（base → 各后端实现）
阶段 4 -- 执行层（Workers）
├── workers/config/ -- Worker 配置定义
├── workers/actor/ -- Actor（策略网络）
├── workers/critic/ -- Critic（价值网络）
├── workers/rollout/ -- Rollout（推理生成引擎）
├── workers/reward_manager/ -- 奖励计算
├── workers/engine/ -- 训练引擎抽象层
├── workers/sharding_manager/ -- 模型分片管理
└── workers/fsdp_workers + megatron_workers + engine_workers
阶段 5 -- 训练调度层
├── trainer/config/ -- 训练配置
├── trainer/ppo/ -- PPO 算法核心
├── trainer/main_ppo.py -- PPO 入口
├── trainer/sft_trainer.py -- SFT 训练
└── trainer/main_eval.py -- 评估入口
阶段 6 -- 工具与交互层
├── tools/ -- 工具系统（搜索/代码执行/MCP）
└── interactions/ -- 交互系统（多轮对话环境）
阶段 7 -- 辅助模块
├── model_merger/ -- checkpoint 合并
├── third_party/ -- 第三方库补丁
└── utils/ 子模块（dataset, checkpoint, kernel, megatron, profiler, qat 等）
阶段 8 -- 实验性功能
└── experimental/（agent_loop, fully_async_policy, vla, reward_loop 等）
路线 C：按兴趣选读¶
根据你关心的主题，直接跳到对应模块：
| 我想了解... | 去读... |
|---|---|
| PPO 算法是怎么实现的 | trainer/ppo/core_algos.py.md |
| 训练流程是怎么跑起来的 | trainer/main_ppo.py.md → trainer/ppo/ray_trainer.py.md |
| 数据是怎么在模块间传递的 | core/02_protocol.md |
| 多卡分布式是怎么调度的 | single_controller/ 整个目录 |
| vLLM/SGLang 推理集成 | workers/rollout/vllm_rollout/ 或 workers/rollout/sglang_rollout/ |
| 奖励函数怎么写 | workers/reward_manager/ + utils/reward_score/ |
| 模型权重怎么在训练和推理间同步 | checkpoint_engine/ |
| LLM 怎么调用工具 | tools/ + experimental/agent_loop/ |
| FSDP 分布式训练细节 | workers/fsdp_workers.md + utils/07_fsdp_utils.md |
| Megatron 并行训练 | workers/megatron_workers.md + models/mcore/ + utils/megatron/ |
| SFT 监督微调 | trainer/sft_trainer.py.md + trainer/sft_trainer_ray.py.md |
| LoRA/PEFT 微调 | utils/24_megatron_peft_utils.md |
| 全异步训练 | experimental/fully_async_policy/ |
| 视觉语言模型 (VLA) | experimental/vla/ |
四、模块依赖关系与阅读顺序¶
下面的 ASCII 图展示了 verl 各模块的依赖关系。箭头表示"被依赖"方向（A → B 表示 B 依赖 A，所以先读 A）。
verl 模块依赖关系图
┌──────────────────────────────────────────────────────────────────────┐
│ 基础层 (最先阅读) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ core/ │ │ utils/ │ │ single_controller/ │ │
│ │ (数据协议) │ │ (工具集) │ │ (分布式调度) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘ │
│ │ │ │ │
└──────────┼───────────────────┼───────────────────────┼──────────────┘
│ │ │
v v v
┌──────────────────────────────────────────────────────────────────────┐
│ 模型层 (第二层阅读) │
│ │
│ ┌──────────────┐ ┌──────────────────┐ │
│ │ models/ │ │checkpoint_engine/ │ │
│ │ (模型定义与 │ │ (权重同步引擎) │ │
│ │ 并行适配) │ │ │ │
│ └──────┬───────┘ └────────┬─────────┘ │
│ │ │ │
└──────────┼─────────────────────┼────────────────────────────────────┘
│ │
v v
┌──────────────────────────────────────────────────────────────────────┐
│ 执行层 (第三层阅读) │
│ │
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ actor/ │ │ critic/ │ │ rollout/ │ │reward_manager/│ │
│ │(策略网络)│ │(价值网络)│ │(推理引擎) │ │ (奖励计算) │ │
│ └────┬────┘ └────┬────┘ └─────┬────┘ └───────┬───────┘ │
│ │ │ │ │ │
│ └───────────┴────────────┴───────────────┘ │
│ │ │
│ v │
│ ┌──────────────────────────────────────┐ │
│ │ fsdp_workers / megatron_workers / │ │
│ │ engine_workers (整合各 Worker) │ │
│ └──────────────────┬───────────────────┘ │
│ │ │
└───────────────────────────┼─────────────────────────────────────────┘
│
v
┌──────────────────────────────────────────────────────────────────────┐
│ 训练调度层 (第四层阅读) │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ trainer/ppo/ │ │
│ │ (PPO 训练器 -- 框架的顶层调度中心) │ │
│ └──────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────┘
│
v
┌──────────────────────────────────────────────────────────────────────┐
│ 扩展层 (按需阅读) │
│ │
│ ┌────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────────────┐ │
│ │ tools/ │ │interactions/ │ │model_merger/ │ │ experimental/ │ │
│ │(工具) │ │(交互环境) │ │(模型合并) │ │ (实验性功能) │ │
│ └────────┘ └──────────────┘ └─────────────┘ └──────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────┘
五、模块阅读顺序详解¶
以下是推荐的阅读顺序，带编号和理由说明：
第 1 步：背景知识¶
| 序号 | 文档 | 理由 |
|---|---|---|
| 1 | 00_background_knowledge.md | 从零讲解 RL、RLHF、PPO、分布式训练等概念，是所有后续内容的知识基础 |
第 2 步：核心模块 (core/)¶
| 序号 | 文档 | 理由 |
|---|---|---|
| 2 | core/index.md | 核心模块总览，了解三个基础文件的关系 |
| 3 | core/01_init.md | 包入口，了解 verl 对外暴露了什么 |
| 4 | core/03_base_config.md | 配置基类，简短易懂，快速建立信心 |
| 5 | core/02_protocol.md | DataProto 数据协议——最核心的数据结构，所有模块间数据传输都用它 |
第 3 步：工具集 (utils/) -- 核心部分¶
| 序号 | 文档 | 理由 |
|---|---|---|
| 6 | utils/index.md | 工具模块总览 |
| 7 | utils/01_device.md | 设备抽象层，了解 CUDA/NPU 统一接口 |
| 8 | utils/02_config.md | 配置管理，了解 OmegaConf 配置转换 |
| 9 | utils/06_distributed.md | 分布式训练基础工具 |
| 10 | utils/07_fsdp_utils.md | FSDP 工具，后续 Worker 会大量使用 |
第 4 步：分布式控制 (single_controller/)¶
| 序号 | 文档 | 理由 |
|---|---|---|
| 11 | single_controller/index.md | 分布式控制模块总览 |
| 12 | single_controller/init.md | 模块入口 |
| 13 | single_controller/base/worker.md | Worker 基类定义 |
| 14 | single_controller/base/decorator.md | 装饰器——将本地方法变为分布式方法 |
| 15 | single_controller/base/worker_group.md | WorkerGroup——管理一组 Worker |
| 16 | single_controller/ray/base.md | Ray 后端实现 |
第 5 步：模型层 (models/)¶
| 序号 | 文档 | 理由 |
|---|---|---|
| 17 | models/index.md | 模型模块总览 |
| 18 | models/registry.md | 模型注册机制 |
| 19 | models/transformers/monkey_patch.md | 核心的 monkey patch 入口 |
| 20 | models/transformers/dense_common.md | 通用前向传播优化 |
第 6 步：Workers（执行层）¶
| 序号 | 文档 | 理由 |
|---|---|---|
| 21 | workers/index.md | Workers 模块总览——非常重要 |
| 22 | workers/actor/base.md | Actor Worker 基类 |
| 23 | workers/actor/dp_actor.md | FSDP Actor 实现 |
| 24 | workers/critic/base.md | Critic Worker 基类 |
| 25 | workers/critic/dp_critic.md | FSDP Critic 实现 |
| 26 | workers/rollout/base.md | Rollout 基类 |
| 27 | workers/rollout/vllm_rollout/vllm_rollout.md | vLLM 推理引擎集成 |
| 28 | workers/reward_manager/abstract.md | 奖励管理器基类 |
| 29 | workers/reward_manager/naive.md | 最简奖励管理器实现 |
| 30 | workers/fsdp_workers.md | FSDP Workers 整合层 |
第 7 步：训练调度层 (trainer/)¶
| 序号 | 文档 | 理由 |
|---|---|---|
| 31 | trainer/index.md | Trainer 模块总览 |
| 32 | trainer/main_ppo.py.md | PPO 训练入口——一切从这里开始 |
| 33 | trainer/ppo/ray_trainer.py.md | Ray PPO Trainer——核心调度逻辑 |
| 34 | trainer/ppo/core_algos.py.md | PPO 核心算法实现 |
| 35 | trainer/ppo/reward.py.md | 奖励函数加载 |
| 36 | trainer/ppo/metric_utils.py.md | 训练指标计算 |
第 8 步：扩展模块（按需阅读）¶
| 序号 | 文档 | 理由 |
|---|---|---|
| 37 | checkpoint_engine/index.md | 权重同步引擎 |
| 38 | tools/index.md | 工具系统（搜索/代码执行） |
| 39 | interactions/index.md | 交互系统（多轮对话） |
| 40 | model_merger/index.md | checkpoint 合并 |
| 41 | third_party/index.md | 第三方库补丁 |
| 42 | experimental/index.md | 实验性功能 |
六、各模块一句话简介¶
| 模块 | 一句话简介 |
|---|---|
| core/ | 定义 verl 的基本数据结构 DataProto 和配置基类，是整个框架的"语言" |
| utils/ | 提供设备管理、分布式、数据集、checkpoint、性能分析等基础工具，是框架的"底座" |
| single_controller/ | 实现"单控制器"分布式架构，让主进程像调用本地方法一样操控远程 Worker |
| models/ | 模型定义与并行适配层，让 HuggingFace/Megatron 模型能在 PPO 训练中高效运行 |
| checkpoint_engine/ | 训练-推理间的权重同步引擎，支持 NCCL/NIXL/Mooncake 等多种通信后端 |
| workers/ | RLHF 的核心执行层，包含 Actor、Critic、Rollout、Reward 四大 Worker |
| trainer/ | 训练调度中心，实现 PPO/SFT 训练流程的顶层编排逻辑 |
| tools/ | 工具系统，让 LLM 在训练中能调用搜索、代码执行等外部工具 |
| interactions/ | 交互系统，让 LLM 在训练中能与环境进行多轮对话并获取反馈 |
| model_merger/ | 将 FSDP/Megatron 分片 checkpoint 合并为 HuggingFace 格式 |
| third_party/ | 第三方库（PyTorch、vLLM）的补丁代码，修复 bug 和处理版本兼容性 |
| experimental/ | 实验性功能：全异步训练、Agent Loop、VLA、动态数据集等前沿特性 |
七、文档总目录¶
以下是所有教程文档的完整索引，按模块分类。
7.0 背景知识与指南¶
- 00_background_knowledge.md -- 从零理解 RL/RLHF/PPO/分布式训练
- 00_reading_guide.md -- 本文档（阅读指南）
- TODO.md -- 教程编写进度追踪
7.1 core/ -- 核心数据协议¶
- core/index.md -- 模块总览
- core/01_init.md --
verl/__init__.py包入口 - core/02_protocol.md --
verl/protocol.py数据传输协议 (DataProto) - core/03_base_config.md --
verl/base_config.py配置基类
7.2 utils/ -- 工具模块¶
- utils/index.md -- 模块总览
基础工具： - utils/01_device.md -- 设备抽象层 - utils/02_config.md -- 配置管理 - utils/03_import_utils.md -- 动态导入与依赖检查 - utils/04_py_functional.md -- Python 函数式工具 - utils/05_torch_dtypes.md -- Torch 数据类型工具 - utils/06_distributed.md -- 分布式训练工具 - utils/07_fsdp_utils.md -- FSDP 工具 - utils/08_ulysses.md -- Ulysses 序列并行 - utils/09_tokenizer.md -- Tokenizer 工具 - utils/10_chat_template.md -- 聊天模板 - utils/11_tensordict_utils.md -- TensorDict 工具 - utils/12_torch_functional.md -- Torch 函数工具 - utils/13_activation_offload.md -- 激活值卸载 - utils/14_tracking.md -- 实验追踪 - utils/15_seqlen_balancing.md -- 序列长度均衡 - utils/16_memory_utils.md -- 显存管理 - utils/17_init.md -- utils 入口 - utils/18_attention_utils.md -- 注意力计算工具 - utils/19_flops_counter.md -- FLOPS 计算 - utils/20_fs.md -- 文件系统工具 - utils/21_groupwise.md -- 分组统计 - utils/22_hdfs_io.md -- HDFS IO - utils/23_logging_utils.md -- 日志工具 - utils/24_megatron_peft_utils.md -- Megatron PEFT/LoRA - utils/25_megatron_utils.md -- Megatron 模型转换 - utils/26_model.md -- 模型创建工具 - utils/27_net_utils.md -- 网络工具 - utils/28_npu_flash_attn_utils.md -- NPU FlashAttention - utils/29_ray_utils.md -- Ray 工具 - utils/30_rollout_skip.md -- Rollout 跳过策略 - utils/31_rollout_trace.md -- Rollout 追踪 - utils/32_transformers_compat.md -- Transformers 兼容性
子模块：
utils/dataset/ -- 数据集工具： - utils/dataset/index.md -- 数据集模块总览 - utils/dataset/01_init.md -- 入口 - utils/dataset/02_rl_dataset.md -- RL 数据集 - utils/dataset/03_rm_dataset.md -- RM 数据集 - utils/dataset/04_dataset_utils.md -- 数据集工具 - utils/dataset/05_vision_utils.md -- 视觉数据处理 - utils/dataset/06_multiturn_sft_dataset.md -- 多轮 SFT 数据集
utils/checkpoint/ -- Checkpoint 管理： - utils/checkpoint/index.md -- Checkpoint 模块总览 - utils/checkpoint/01_init.md -- 入口 - utils/checkpoint/02_checkpoint_manager.md -- 管理器 - utils/checkpoint/03_checkpoint_handler.md -- 处理器 - utils/checkpoint/04_fsdp_checkpoint_manager.md -- FSDP Checkpoint - utils/checkpoint/05_megatron_checkpoint_manager.md -- Megatron Checkpoint
utils/kernel/ -- 高性能 Kernel： - utils/kernel/index.md -- Kernel 模块总览 - utils/kernel/01_init.md -- 入口 - utils/kernel/02_linear_cross_entropy.md -- 线性交叉熵 - utils/kernel/03_kernels.md -- Triton Kernel - utils/kernel/04_fp8_kernel.md -- FP8 Kernel
utils/megatron/ -- Megatron 并行工具： - utils/megatron/index.md -- Megatron 工具总览 - utils/megatron/01_init.md -- 入口 - utils/megatron/02_optimizer.md -- 优化器 - utils/megatron/03_sequence_parallel.md -- 序列并行 - utils/megatron/04_pipeline_parallel.md -- 流水线并行 - utils/megatron/05_tensor_parallel.md -- 张量并行 - utils/megatron/06_memory.md -- 内存管理 - utils/megatron/07_dist_checkpointing.md -- 分布式 Checkpoint - utils/megatron/08_router_replay_patch.md -- Router Replay 补丁 - utils/megatron/09_router_replay_utils.md -- Router Replay 工具
utils/profiler/ -- 性能分析： - utils/profiler/index.md -- 性能分析总览 - utils/profiler/01_init.md -- 入口 - utils/profiler/02_config.md -- 配置 - utils/profiler/03_profile.md -- Profile 工具 - utils/profiler/04_nvtx_profile.md -- NVTX Profile - utils/profiler/05_mstx_profile.md -- MSTX Profile - utils/profiler/06_torch_profile.md -- Torch Profile - utils/profiler/07_performance.md -- 性能统计 - utils/profiler/08_empty_annotations.md -- 空注解占位
utils/reward_score/ -- 奖励评分函数： - utils/reward_score/init.md -- 入口 - utils/reward_score/gsm8k.md -- GSM8K 数学评分 - utils/reward_score/math_reward.md -- MATH 评分 - utils/reward_score/math_dapo.md -- DAPO 数学评分 - utils/reward_score/math_batch.md -- 批量数学评分 - utils/reward_score/math_verify.md -- 数学验证 - utils/reward_score/geo3k.md -- 几何题评分 - utils/reward_score/search_r1_like_qa_em.md -- 搜索 QA 评分 - utils/reward_score/prime_math/init.md -- PRIME 数学入口 - utils/reward_score/prime_math/grader.md -- PRIME 评分器 - utils/reward_score/prime_math/math_normalize.md -- 数学标准化 - utils/reward_score/prime_code/init.md -- PRIME 代码入口 - utils/reward_score/prime_code/testing_util.md -- 代码测试工具 - utils/reward_score/prime_code/utils.md -- 代码评分工具 - utils/reward_score/sandbox_fusion/init.md -- Sandbox Fusion 入口 - utils/reward_score/sandbox_fusion/utils.md -- Sandbox Fusion 工具
其他 utils 子模块： - utils/debug/init.md -- 调试工具入口 - utils/debug/metrics.md -- 调试指标 - utils/debug/performance.md -- 性能调试 - utils/debug/trajectory_tracker.md -- 轨迹追踪 - utils/experimental/init.md -- 实验工具入口 - utils/experimental/torch_functional.md -- 实验性 Torch 工具 - utils/logger/init.md -- 日志入口 - utils/logger/aggregate_logger.md -- 聚合日志器 - utils/metric/init.md -- 指标入口 - utils/metric/utils.md -- 指标工具 - utils/qat/init.md -- QAT 入口 - utils/qat/core.md -- QAT 核心 - utils/qat/linear.md -- QAT Linear 层 - utils/qat/quantizer.md -- 量化器 - utils/qat/vllm_patch.md -- vLLM QAT 补丁 - utils/rendezvous/init.md -- Rendezvous 入口 - utils/rendezvous/ray_backend.md -- Ray 后端 - utils/sglang/sglang_fp8_utils.md -- SGLang FP8 工具 - utils/vllm/init.md -- vLLM 工具入口 - utils/vllm/patch.md -- vLLM 补丁 - utils/vllm/utils.md -- vLLM 工具 - utils/vllm/vllm_fp8_utils.md -- vLLM FP8 工具
7.3 single_controller/ -- 分布式控制¶
- single_controller/index.md -- 模块总览
- single_controller/init.md -- 模块入口
- single_controller/base/init.md -- base 子模块入口
- single_controller/base/worker.md -- Worker 基类
- single_controller/base/decorator.md -- 分布式装饰器
- single_controller/base/worker_group.md -- WorkerGroup
- single_controller/ray/init.md -- Ray 子模块入口
- single_controller/ray/base.md -- Ray 后端实现
7.4 models/ -- 模型层¶
- models/index.md -- 模块总览
- models/init.md -- 模块入口
- models/registry.md -- 模型注册表
- models/weight_loader_registry.md -- 权重加载注册表
models/transformers/ -- HuggingFace 适配： - models/transformers/init.md -- 入口 - models/transformers/monkey_patch.md -- Monkey Patch 入口 - models/transformers/dense_common.md -- 通用前向传播 - models/transformers/llama.md -- LLaMA 适配 - models/transformers/qwen2.md -- Qwen2 适配 - models/transformers/qwen2_vl.md -- Qwen2-VL 适配 - models/transformers/qwen3_vl.md -- Qwen3-VL 适配 - models/transformers/glm4v.md -- GLM-4V 适配 - models/transformers/kimi_vl.md -- KimiVL 适配 - models/transformers/apertus.md -- Apertus 适配 - models/transformers/tiled_mlp.md -- TiledMLP - models/transformers/npu_patch.md -- NPU 补丁
models/mcore/ -- Megatron-Core 集成： - models/mcore/init.md -- 入口 - models/mcore/registry.md -- 注册表 - models/mcore/bridge.md -- Bridge - models/mcore/mbridge.md -- MBridge - models/mcore/config_converter.md -- 配置转换 - models/mcore/model_initializer.md -- 模型初始化 - models/mcore/model_forward.md -- 前向传播 - models/mcore/model_forward_fused.md -- 融合前向 - models/mcore/model_forward_1f1b_overlap.md -- 1F1B 重叠 - models/mcore/loader.md -- 权重加载 - models/mcore/saver.md -- 权重保存 - models/mcore/weight_converter.md -- 权重转换 - models/mcore/patch.md -- 补丁 - models/mcore/mtp_patch.md -- MTP 补丁 - models/mcore/qwen2_5_vl.md -- Qwen2.5-VL - models/mcore/util.md -- 工具函数
models/llama_megatron/ -- LLaMA Megatron 实现： - models/llama_megatron/init.md -- 入口 - models/llama_megatron/llama_init.md -- 初始化 - models/llama_megatron/modeling_llama_megatron.md -- 模型定义 - models/llama_megatron/layers/init.md -- 层入口 - models/llama_megatron/layers/parallel_attention.md -- 并行注意力 - models/llama_megatron/layers/parallel_decoder.md -- 并行解码器 - models/llama_megatron/layers/parallel_linear.md -- 并行线性层 - models/llama_megatron/layers/parallel_mlp.md -- 并行 MLP - models/llama_megatron/layers/parallel_rmsnorm.md -- 并行 RMSNorm - models/llama_megatron/checkpoint_utils/init.md -- Checkpoint 工具入口 - models/llama_megatron/checkpoint_utils/llama_loader.md -- 权重加载 - models/llama_megatron/checkpoint_utils/llama_loader_depracated.md -- 旧版加载（已弃用） - models/llama_megatron/checkpoint_utils/llama_saver.md -- 权重保存
models/qwen2_megatron/ -- Qwen2 Megatron 实现： - models/qwen2_megatron/init.md -- 入口 - models/qwen2_megatron/qwen2_init.md -- 初始化 - models/qwen2_megatron/modeling_qwen2_megatron.md -- 模型定义 - models/qwen2_megatron/layers/init.md -- 层入口 - models/qwen2_megatron/layers/parallel_attention.md -- 并行注意力 - models/qwen2_megatron/layers/parallel_decoder.md -- 并行解码器 - models/qwen2_megatron/layers/parallel_linear.md -- 并行线性层 - models/qwen2_megatron/layers/parallel_mlp.md -- 并行 MLP - models/qwen2_megatron/layers/parallel_rmsnorm.md -- 并行 RMSNorm - models/qwen2_megatron/checkpoint_utils/init.md -- Checkpoint 工具入口 - models/qwen2_megatron/checkpoint_utils/qwen2_loader.md -- 权重加载 - models/qwen2_megatron/checkpoint_utils/qwen2_loader_depracated.md -- 旧版加载（已弃用） - models/qwen2_megatron/checkpoint_utils/qwen2_saver.md -- 权重保存
7.5 checkpoint_engine/ -- 权重同步引擎¶
- checkpoint_engine/index.md -- 模块总览
- checkpoint_engine/init.md -- 模块入口
- checkpoint_engine/base.md -- 基类与注册表
- checkpoint_engine/nccl_checkpoint_engine.md -- NCCL 后端
- checkpoint_engine/hccl_checkpoint_engine.md -- HCCL 后端（华为）
- checkpoint_engine/nixl_checkpoint_engine.md -- NIXL 后端
- checkpoint_engine/kimi_checkpoint_engine.md -- Kimi 后端
- checkpoint_engine/mooncake_checkpoint_engine.md -- Mooncake 后端
7.6 workers/ -- 执行层¶
- workers/index.md -- 模块总览
- workers/init.md -- 模块入口
- workers/background.md -- 后台 Worker
- workers/fsdp_workers.md -- FSDP Workers 整合
- workers/megatron_workers.md -- Megatron Workers 整合
- workers/engine_workers.md -- 统一引擎 Workers
workers/config/ -- Worker 配置： - workers/config/init.md -- 入口 - workers/config/actor.md -- Actor 配置 - workers/config/critic.md -- Critic 配置 - workers/config/engine.md -- 引擎配置 - workers/config/model.md -- 模型配置 - workers/config/optimizer.md -- 优化器配置 - workers/config/reward.md -- 奖励配置 - workers/config/rollout.md -- Rollout 配置 - workers/config/megatron_peft.md -- Megatron PEFT 配置
workers/actor/ -- Actor Worker： - workers/actor/init.md -- 入口 - workers/actor/base.md -- 基类 - workers/actor/dp_actor.md -- FSDP Actor - workers/actor/megatron_actor.md -- Megatron Actor
workers/critic/ -- Critic Worker： - workers/critic/init.md -- 入口 - workers/critic/base.md -- 基类 - workers/critic/dp_critic.md -- FSDP Critic - workers/critic/megatron_critic.md -- Megatron Critic
workers/rollout/ -- Rollout（推理引擎）： - workers/rollout/init.md -- 入口 - workers/rollout/base.md -- 基类 - workers/rollout/schemas.md -- 数据 Schema - workers/rollout/tokenizer.md -- Tokenizer 工具 - workers/rollout/utils.md -- 工具函数 - workers/rollout/replica.md -- Replica 管理 - workers/rollout/hf_rollout.md -- HuggingFace Rollout - workers/rollout/naive/init.md -- Naive Rollout 入口 - workers/rollout/naive/naive_rollout.md -- Naive Rollout - workers/rollout/vllm_rollout/init.md -- vLLM 入口 - workers/rollout/vllm_rollout/vllm_rollout.md -- vLLM Rollout - workers/rollout/vllm_rollout/vllm_async_server.md -- vLLM 异步服务 - workers/rollout/vllm_rollout/utils.md -- vLLM 工具 - workers/rollout/vllm_rollout/bucketed_weight_transfer.md -- 分桶权重传输 - workers/rollout/sglang_rollout/init.md -- SGLang 入口 - workers/rollout/sglang_rollout/sglang_rollout.md -- SGLang Rollout - workers/rollout/sglang_rollout/async_sglang_server.md -- SGLang 异步服务 - workers/rollout/sglang_rollout/http_server_engine.md -- HTTP 服务引擎 - workers/rollout/sglang_rollout/utils.md -- SGLang 工具 - workers/rollout/trtllm_rollout/trtllm_rollout.md -- TensorRT-LLM Rollout - workers/rollout/trtllm_rollout/trtllm_async_server.md -- TRT-LLM 异步服务
workers/engine/ -- 训练引擎抽象： - workers/engine/init.md -- 入口 - workers/engine/base.md -- 基类 - workers/engine/utils.md -- 工具 - workers/engine/fsdp/init.md -- FSDP 引擎入口 - workers/engine/fsdp/transformer_impl.md -- FSDP Transformer 实现 - workers/engine/fsdp/utils.md -- FSDP 引擎工具 - workers/engine/megatron/init.md -- Megatron 引擎入口 - workers/engine/megatron/transformer_impl.md -- Megatron Transformer 实现 - workers/engine/megatron/utils.md -- Megatron 引擎工具 - workers/engine/mindspeed/init.md -- MindSpeed 引擎入口 - workers/engine/mindspeed/transformer_impl.md -- MindSpeed Transformer 实现 - workers/engine/torchtitan/init.md -- TorchTitan 引擎入口 - workers/engine/torchtitan/transformer_impl.md -- TorchTitan Transformer 实现 - workers/engine/torchtitan/utils.md -- TorchTitan 工具 - workers/engine/veomni/init.md -- VeOmni 引擎入口 - workers/engine/veomni/transformer_impl.md -- VeOmni Transformer 实现 - workers/engine/veomni/utils.md -- VeOmni 工具
workers/reward_manager/ -- 奖励管理： - workers/reward_manager/init.md -- 入口 - workers/reward_manager/registry.md -- 注册表 - workers/reward_manager/abstract.md -- 抽象基类 - workers/reward_manager/naive.md -- Naive 实现 - workers/reward_manager/batch.md -- Batch 实现 - workers/reward_manager/dapo.md -- DAPO 实现 - workers/reward_manager/prime.md -- PRIME 实现
workers/sharding_manager/ -- 分片管理： - workers/sharding_manager/init.md -- 入口 - workers/sharding_manager/base.md -- 基类 - workers/sharding_manager/fsdp_ulysses.md -- FSDP+Ulysses
workers/utils/ -- Worker 工具： - workers/utils/init.md -- 入口 - workers/utils/losses.md -- 损失函数 - workers/utils/padding.md -- Padding 工具
7.7 trainer/ -- 训练调度¶
- trainer/index.md -- 模块总览
- trainer/init.py.md -- 模块入口
- trainer/constants_ppo.py.md -- PPO 常量
- trainer/main_ppo.py.md -- PPO 训练入口
- trainer/main_eval.py.md -- 评估入口
- trainer/main_generation_server.py.md -- 生成服务器入口
- trainer/sft_trainer.py.md -- SFT 单机训练器
- trainer/sft_trainer_ray.py.md -- SFT 分布式训练器
trainer/config/ -- 训练配置： - trainer/config/init.py.md -- 入口 - trainer/config/config.py.md -- 基础配置 - trainer/config/algorithm.py.md -- 算法配置
trainer/ppo/ -- PPO 核心： - trainer/ppo/init.py.md -- 入口 - trainer/ppo/ray_trainer.py.md -- Ray PPO Trainer（最核心） - trainer/ppo/core_algos.py.md -- 核心算法 - trainer/ppo/reward.py.md -- 奖励函数 - trainer/ppo/metric_utils.py.md -- 指标计算 - trainer/ppo/utils.py.md -- 工具函数 - trainer/ppo/prefix_grouper_utils.py.md -- 前缀分组 - trainer/ppo/rollout_corr_helper.py.md -- Rollout 修正
7.8 tools/ -- 工具系统¶
- tools/index.md -- 模块总览
- tools/init.md -- 模块入口
- tools/schemas.md -- 数据 Schema
- tools/base_tool.md -- 工具基类
- tools/mcp_base_tool.md -- MCP 工具基类
- tools/search_tool.md -- 搜索工具
- tools/mcp_search_tool.md -- MCP 搜索工具
- tools/gsm8k_tool.md -- GSM8K 工具
- tools/geo3k_tool.md -- Geo3K 工具
- tools/image_zoom_in_tool.md -- 图片放大工具
- tools/sandbox_fusion_tools.md -- Sandbox Fusion 工具
- tools/utils/init.md -- 工具 utils 入口
- tools/utils/tool_registry.md -- 工具注册表
- tools/utils/search_r1_like_utils.md -- 搜索工具辅助
- tools/utils/mcp_clients/McpClientManager.md -- MCP 客户端管理
- tools/utils/mcp_clients/utils.md -- MCP 客户端工具
7.9 interactions/ -- 交互系统¶
- interactions/index.md -- 模块总览
- interactions/init.md -- 模块入口
- interactions/base.md -- 交互基类
- interactions/gsm8k_interaction.md -- GSM8K 交互
- interactions/weather_interaction.md -- 天气交互
- interactions/utils/init.md -- 工具入口
- interactions/utils/interaction_registry.md -- 交互注册表
7.10 model_merger/ -- 模型合并¶
- model_merger/index.md -- 模块总览
- model_merger/01_init.md -- 入口
- model_merger/02_main.md -- CLI 入口
- model_merger/03_base_model_merger.md -- 基类
- model_merger/04_fsdp_model_merger.md -- FSDP 合并
- model_merger/05_megatron_model_merger.md -- Megatron 合并
7.11 third_party/ -- 第三方补丁¶
- third_party/index.md -- 模块总览
- third_party/01_init.md -- 入口
- third_party/02_vllm_init.md -- vLLM 兼容层
- third_party/03_torch_inits.md -- PyTorch 补丁入口
- third_party/04_state_dict_utils.md -- State Dict 工具
- third_party/05_checkpoint_state_dict.md -- Checkpoint State Dict
7.12 experimental/ -- 实验性功能¶
- experimental/index.md -- 模块总览
- experimental/01_init.md -- 入口
experimental/agent_loop/ -- Agent 循环： - experimental/agent_loop/01_init.md -- 入口 - experimental/agent_loop/02_agent_loop.md -- 核心 Agent Loop - experimental/agent_loop/03_single_turn_agent_loop.md -- 单轮 Agent - experimental/agent_loop/04_tool_agent_loop.md -- 工具 Agent - experimental/agent_loop/05_tool_parser.md -- 工具解析器 - experimental/agent_loop/06_utils.md -- 工具函数 - experimental/agent_loop/07_prometheus_utils.md -- 监控
experimental/dataset/ -- 数据集： - experimental/dataset/01_init.md -- 入口 - experimental/dataset/02_sampler.md -- 采样器
experimental/dynamic_dataset/ -- 动态数据集： - experimental/dynamic_dataset/01_init.md -- 入口 - experimental/dynamic_dataset/02_dynamicgen_dataset.md -- 动态生成
experimental/fully_async_policy/ -- 全异步训练： - experimental/fully_async_policy/01_fully_async_main.md -- 入口 - experimental/fully_async_policy/02_fully_async_rollouter.md -- 异步 Rollout - experimental/fully_async_policy/03_fully_async_trainer.md -- 异步 Trainer - experimental/fully_async_policy/04_message_queue.md -- 消息队列 - experimental/fully_async_policy/05_param_sync.md -- 参数同步 - experimental/fully_async_policy/06_detach_utils.md -- Detach 工具 - experimental/fully_async_policy/07_megatron_utils.md -- Megatron 工具 - experimental/fully_async_policy/08_fsdp2_utils.md -- FSDP2 工具 - experimental/fully_async_policy/agent_loop/01_init.md -- Agent Loop 入口 - experimental/fully_async_policy/agent_loop/02_agent_loop.md -- Agent Loop - experimental/fully_async_policy/agent_loop/03_partial_tool_agent_loop.md -- 部分工具 Agent - experimental/fully_async_policy/agent_loop/04_partial_single_turn_agent_loop.md -- 部分单轮 Agent - experimental/fully_async_policy/sglang_rollout/01_sglang_async_server.md -- SGLang 异步 - experimental/fully_async_policy/sglang_rollout/02_init.md -- SGLang 入口 - experimental/fully_async_policy/vllm_rollout/01_vllm_async_server.md -- vLLM 异步 - experimental/fully_async_policy/vllm_rollout/02_init.md -- vLLM 入口 - experimental/fully_async_policy/unittest/01_simple_streaming_demo.md -- 流式 Demo
experimental/one_step_off_policy/ -- 单步 Off-Policy： - experimental/one_step_off_policy/01_main_ppo.md -- PPO 入口 - experimental/one_step_off_policy/02_ray_trainer.md -- Ray Trainer - experimental/one_step_off_policy/03_utils.md -- 工具 - experimental/one_step_off_policy/04_distributed_utils.md -- 分布式工具 - experimental/one_step_off_policy/agent_loop/01_init.md -- Agent Loop 入口 - experimental/one_step_off_policy/agent_loop/02_agent_loop.md -- Agent Loop
experimental/reward_loop/ -- 奖励循环： - experimental/reward_loop/01_init.md -- 入口 - experimental/reward_loop/02_reward_loop.md -- 奖励循环 - experimental/reward_loop/03_reward_model.md -- 奖励模型 - experimental/reward_loop/04_reward_manager_init.md -- 管理器入口 - experimental/reward_loop/05_reward_manager_registry.md -- 管理器注册表 - experimental/reward_loop/06_reward_manager_base.md -- 管理器基类 - experimental/reward_loop/07_reward_manager_naive.md -- Naive 管理器 - experimental/reward_loop/08_reward_manager_dapo.md -- DAPO 管理器 - experimental/reward_loop/09_reward_manager_limited.md -- Limited 管理器 - experimental/reward_loop/10_reward_manager_remote.md -- Remote 管理器 - experimental/reward_loop/11_router_naive.md -- Naive 路由 - experimental/reward_loop/12_router_sglang.md -- SGLang 路由
experimental/separation/ -- 训练推理分离： - experimental/separation/01_init.md -- 入口 - experimental/separation/02_engine_workers.md -- 引擎 Workers - experimental/separation/03_ray_trainer.md -- Ray Trainer
experimental/vla/ -- 视觉语言动作（VLA）： - experimental/vla/01_main_ppo.md -- PPO 入口 - experimental/vla/02_main_sac.md -- SAC 入口 - experimental/vla/03_rob_ray_trainer.md -- 机器人 Ray Trainer - experimental/vla/04_env_loop.md -- 环境循环 - experimental/vla/05_dp_rob.md -- DP 机器人 - experimental/vla/06_fsdp_workers.md -- FSDP Workers - experimental/vla/07_naive_rollout_rob.md -- Naive Rollout - experimental/vla/08_prepare_libero_dataset.md -- LIBERO 数据准备 - experimental/vla/09_envs_init.md -- 环境入口 - experimental/vla/10_action_utils.md -- 动作工具 - experimental/vla/11_libero_env_init.md -- LIBERO 环境入口 - experimental/vla/12_libero_env.md -- LIBERO 环境 - experimental/vla/13_libero_venv.md -- LIBERO 虚拟环境 - experimental/vla/14_libero_utils.md -- LIBERO 工具 - experimental/vla/15_isaac_env_init.md -- Isaac 环境入口 - experimental/vla/16_isaac_env.md -- Isaac 环境 - experimental/vla/17_models_init.md -- 模型入口 - experimental/vla/18_register_vla_models.md -- VLA 模型注册 - experimental/vla/19_modules_mlp.md -- MLP 模块 - experimental/vla/20_openvla_init.md -- OpenVLA 入口 - experimental/vla/21_openvla_constants.md -- OpenVLA 常量 - experimental/vla/22_openvla_configuration.md -- OpenVLA 配置 - experimental/vla/23_openvla_modeling.md -- OpenVLA 模型 - experimental/vla/24_openvla_train_utils.md -- OpenVLA 训练工具 - experimental/vla/25_openvla_processing.md -- OpenVLA 数据处理 - experimental/vla/26_pi0_torch_init.md -- Pi0 Torch 入口 - experimental/vla/27_pi0_configuration.md -- Pi0 配置 - experimental/vla/28_pi0_modeling.md -- Pi0 模型 - experimental/vla/29_pi0_utils.md -- Pi0 工具 - experimental/vla/30_pi0_model.md -- Pi0 模型定义 - experimental/vla/31_paligemma_with_expert.md -- PaliGemma 专家模型 - experimental/vla/32_pi0_policy_init.md -- Pi0 策略入口 - experimental/vla/33_pi0_policy_base.md -- Pi0 策略基类 - experimental/vla/34_pi0_policy_libero.md -- Pi0 LIBERO 策略 - experimental/vla/35_sac_base.md -- SAC 基类 - experimental/vla/36_sac_actor.md -- SAC Actor - experimental/vla/37_sac_replay_pool.md -- SAC 经验回放 - experimental/vla/38_sac_ray_trainer.md -- SAC Ray Trainer - experimental/vla/39_sac_naive_rollout_pi05.md -- SAC Naive Rollout - experimental/vla/40_env_worker.md -- 环境 Worker - experimental/vla/41_env_manager.md -- 环境管理器 - experimental/vla/42_env_loop_wg_test.md -- 环境循环测试
祝你阅读愉快！如果有任何疑问，建议从 00_background_knowledge.md 开始，然后沿着路线 A 快速建立全局视角。