源码导读：调用栈与文件地图

13.1 顶层目录地图

verl/
├── trainer/                              训练入口 + Controller 算法主控
│   ├── main_ppo.py                       ★ 默认启动入口（async 风格）
│   ├── main_ppo_sync.py                  ★ 同步 PPO 入口（TransferQueue / agent loop）
│   ├── main_eval.py                      离线评测入口
│   ├── main_generation_server.py         独立 generation server
│   ├── sft_trainer.py / sft_trainer_ray.py  SFT 单进程 / Ray 入口
│   ├── ppo/
│   │   ├── ray_trainer.py                ★ RayPPOTrainer.fit() 主循环（1769 行）
│   │   ├── core_algos.py                 ★ 算法核心（13 个 advantage / 11 个 policy loss）
│   │   ├── metric_utils.py               metrics 计算与聚合
│   │   ├── utils.py                      Role enum / need_reference_policy
│   │   └── ...
│   ├── distillation/                     在线蒸馏 loss
│   ├── config/                           ★ Hydra YAML 层叠（algorithm/actor/critic/ref/rollout/...）
│   ├── constants_ppo.py                  PPO_RAY_RUNTIME_ENV
│   └── runtime_env.yaml                  Ray runtime 默认环境变量
├── single_controller/                    Controller + WorkerGroup 抽象
│   ├── base/                             平台无关基类
│   │   ├── worker.py                     Worker 基类、@register 装饰器
│   │   ├── worker_group.py               WorkerGroup / NaiveWorkerGroup / ResourcePool / ClassWithInitArgs
│   │   └── decorator.py                  Dispatch 枚举（8 种）+ dispatch/collect 函数
│   └── ray/                              Ray 实现（RayResourcePool / RayWorkerGroup / func_generator）
├── workers/                              Worker 实现
│   ├── engine/                           训练引擎抽象（EngineRegistry）
│   │   ├── base.py                       BaseEngine / EngineRegistry
│   │   ├── fsdp/                         FSDPEngine / FSDPEngineWithLMHead
│   │   ├── megatron/                     MegatronEngine{,WithLMHead,WithValueHead}
│   │   ├── torchtitan/                   TorchTitanEngine
│   │   ├── veomni/                       VeOmniEngine
│   │   ├── automodel/                    AutomodelEngine（HF 直跑 / vexact）
│   │   └── mindspeed/                    华为昇腾
│   ├── rollout/                          采样后端
│   │   ├── base.py                       BaseRollout + _ROLLOUT_REGISTRY
│   │   ├── vllm_rollout/                 vLLM ServerAdapter + BucketedWeightSender
│   │   ├── sglang_rollout/               SGLang ServerAdapter + PD 分离
│   │   └── trtllm_rollout/               TensorRT-LLM ServerAdapter
│   ├── reward_manager/                   reward 计算
│   │   ├── abstract.py                   AbstractRewardManager
│   │   ├── registry.py                   REWARD_MANAGER_REGISTRY
│   │   ├── naive.py / batch.py / dapo.py / prime.py
│   ├── engine_workers.py                 ★ TrainingWorker / ActorRolloutRefWorker
│   ├── utils/losses.py                   ppo_loss / value_loss
│   └── config/                           ★ ActorConfig / CriticConfig / RolloutConfig / EngineConfig
├── protocol.py                           ★ DataProto / DataProtoFuture / BatchData
├── base_config.py                        BaseConfig (frozen dataclass)
├── models/                               transformer 模型实现（多模态 / Megatron 包装）
├── checkpoint_engine/                    多后端 checkpoint（nccl / hccl / kimi / mooncake / nixl）
├── model_merger/                         训完导出 HF 格式
├── third_party/                          第三方集成（vLLM patch 等）
├── tools/                                工具框架（BaseTool / tool_registry）
├── utils/                                通用工具 + reward_score + zero_to_fp32 等
├── experimental/                         2024-2026 新特性温床
│   ├── agent_loop/                       多轮工具调用 agent
│   ├── fully_async_policy/               2025-08 全异步训练
│   ├── one_step_off_policy/              一步 off-policy
│   ├── transfer_queue/                   零拷贝零 padding 数据通道
│   ├── reward_loop/                      在线 reward model
│   ├── teacher_loop/                     在线蒸馏 teacher
│   └── separation/                       架构变体
└── recipe/                               子模块：业界 recipe 集合（独立仓 verl-recipe）

13.2 五条主线代码

13.3 从命令行到训练循环的调用栈

13.4 ray_trainer.py：算法主循环

这是 verl 最重要的一个文件。它的 fit() 函数大约 200-300 行，是算法工程师工作的主战场：

# 伪代码（接近真实结构）
def fit(self):
    for epoch in range(total_epochs):
        for batch in self.train_dataloader:
            # 1. rollout：actor 生成 response
            gen_output = self.actor_rollout_wg.generate_sequences(batch)

            # 2. reference logp
            ref_log_prob = self.actor_rollout_wg.compute_ref_log_prob(gen_output)

            # 3. critic value（PPO only）
            if self.use_critic:
                values = self.critic_wg.compute_values(gen_output)

            # 4. reward
            reward_tensor = self.reward_fn(gen_output)

            # 5. advantage（grpo / gae / rloo / ...）
            gen_output = compute_advantage(
                gen_output,
                adv_estimator=self.config.algorithm.adv_estimator,
                ...
            )

            # 6. 训练 actor
            for ppo_epoch in range(ppo_epochs):
                self.actor_rollout_wg.update_actor(gen_output)

            # 7. 训练 critic
            if self.use_critic:
                self.critic_wg.update_critic(gen_output)

            # 8. 保存 / 评测
            if step % save_freq == 0:
                self._save_checkpoint(...)
            if step % test_freq == 0:
                self._evaluate(...)

整个 RLHF 训练循环就这 8 步。改算法 = 改这 8 步中的某一两步。

13.5 single_controller/：RPC 透明化的实现

13.6 workers/actor/dp_actor.py：训练 actor 主循环

FSDP actor 的 update_actor() 大致结构：

def update_actor(self, data: DataProto) -> DataProto:
    self._enter_train_mode()        # weight resharding 回训练布局

    for micro_batch in chunked(data):
        # 前向：算 new logp
        logits = self.model(micro_batch.input_ids)
        log_prob = compute_log_prob(logits, micro_batch.labels)

        # ratio
        ratio = (log_prob - micro_batch.old_log_prob).exp()

        # policy loss（PPO clip）
        policy_loss = -torch.min(
            ratio * micro_batch.advantages,
            ratio.clamp(1-eps, 1+eps) * micro_batch.advantages,
        ).mean()

        # KL loss（可选）
        kl_loss = compute_kl_loss(log_prob, micro_batch.ref_log_prob)

        loss = policy_loss + self.kl_loss_coef * kl_loss

        loss.backward()

    self.optimizer.step()

读懂这个函数 = 读懂 verl 训练核心。

13.7 workers/rollout/vllm_rollout.py：采样后端封装

新接入一个采样后端 = 模仿这个文件写一个新的 SGLangRollout 或 MyRollout。

13.8 workers/sharding_manager/：训推权重对接

遇到新模型架构 rollout 报形状错，多半要在这里加 special case。

13.9 trainer/ppo/core_algos.py：算法核心

新算法 = 在这里加一个 compute_my_advantage + dispatch 一行 case。

13.10 阅读路线总结

1. 跑通 ch03 单机 GRPO 例子：先有手感；
2. 读 trainer/ppo/ray_trainer.py · fit()：理解主循环 8 步；
3. 读 trainer/ppo/core_algos.py：理解算法侧；
4. 读 single_controller/ray/base.py：理解 RPC 透明化；
5. 读 workers/actor/dp_actor.py：理解训练实现；
6. 读 workers/rollout/vllm_rollout.py：理解推理对接；
7. 看一遍 workers/sharding_manager/fsdp_vllm.py：理解 hybrid engine 的"魔法"。

13.11 想给 verl 提 PR？从这些地方入手

13.12 延伸阅读

13.13 RayPPOTrainer.fit() 真实代码地图

fit() 的伪代码 13.4 已经给过，下表是真实 line 锚点。基于 verl/trainer/ppo/ray_trainer.py（commit 9c38b8bb1876）：

13.14 ActorRolloutRefWorker.update_weights() 完整路径

ch05.10 介绍过 update_weights 的两种 mode。源码在 verl/workers/engine_workers.py:659–738，按行号展开 naive 模式 5 步：

对应到 vLLM ServerAdapter（vllm_rollout.py）：

13.15 EngineRegistry 与所有训练后端的"找类"

"我用 strategy: fsdp，最后实例化的到底是哪个类？"答：

EngineRegistry._registry[model_type][backend][device]

常见组合的实际类（来自 verl/workers/engine/__init__.py:14–65）：

13.16 跟着测试读 API

verl 自带丰富 unit tests，是"我想看这个 feature 怎么用最小化"的最快入口。下表是几份高密度的：

跑测试的标准命令：cd repos/verl && pytest tests/test_protocol.py -xv。-x 在第一个失败处停，-v 看每条 test 名字。

13.17 阅读路线（升级版）

整合本书所有锚点，给一个目标导向的 7 天阅读路线：

跑完这 7 天，verl 90% 的代码不再陌生。剩下 10%（多模态 / VLA / verl-omni）是 niche，到需要时再读对应子目录。

13.18 想给 verl 提 PR？升级版索引