源码导读：Trainer / Strategy / Engine 三层抽象

本章给你一张"哪个文件做什么"的源码地图，把 OpenRLHF 的整套架构剥开。 目标是让你在给 OpenRLHF 提 PR 时知道改哪里。

13.1顶层目录地图

OpenRLHF/
├── openrlhf/                       ★ 主代码
│   ├── cli/                        命令行入口（5 个）
│   │   ├── train_sft.py            SFT 训练
│   │   ├── train_rm.py             Reward Model 训练
│   │   ├── train_dpo.py            DPO / IPO / SimPO 等
│   │   ├── train_ppo_ray.py        ★ PPO / GRPO / RLOO 等 RL 训练
│   │   ├── serve_rm.py             把 RM 起成 HTTP service
│   │   └── lora_combiner.py        merge LoRA 权重
│   ├── trainer/                    训练逻辑
│   │   ├── sft_trainer.py          SFT loop
│   │   ├── rm_trainer.py           RM loop
│   │   ├── dpo_trainer.py          DPO loop
│   │   ├── ppo_trainer.py          ★ PPO loop（单进程版，被 RayActor 调用）
│   │   ├── ppo_trainer_async.py    异步版本（multi-turn agent 用）
│   │   ├── ppo_utils/              experience / KL / replay buffer 等
│   │   └── ray/                    ★ Ray actor 封装
│   │       ├── launcher.py         RayActorGroup / BaseDistributedActor
│   │       ├── ppo_actor.py        actor 端 Ray actor 实现
│   │       ├── ppo_critic.py       critic 端 Ray actor 实现
│   │       ├── vllm_engine.py      ★ vLLM rollout 的 Ray actor
│   │       └── vllm_worker_wrap.py vLLM worker 内部 patch
│   ├── models/                      模型实现
│   │   ├── actor.py                Actor 类（包 HF 模型）
│   │   ├── model.py                get_llm_for_sequence_regression（RM / Critic 用）
│   │   ├── loss.py                  ★ PolicyLoss / ValueLoss / DPOLoss
│   │   ├── ring_attn_utils.py       Ring Attention 实现
│   │   └── utils.py
│   ├── datasets/                    数据加载
│   │   ├── prompts_dataset.py       PPO 用的 prompt dataset
│   │   ├── reward_dataset.py        RM 训练用的 preference dataset
│   │   ├── sft_dataset.py           SFT 用
│   │   └── utils.py
│   └── utils/                       工具
│       ├── deepspeed/               DeepspeedStrategy + offload
│       ├── distributed_util.py      stateless NCCL group
│       ├── logging_utils.py
│       └── ...
├── examples/
│   ├── scripts/                     20+ 个生产级启动脚本
│   └── python/                      自定义 reward / agent 范例
├── tests/                            单元测试
├── docs/
├── dockerfile
├── requirements.txt
├── pyproject.toml
└── setup.py

13.2五条主线代码

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

13.4cli/train_ppo_ray.py：入口

这是所有 RL 训练命令的真正入口。它做几件事：

1. 解析数百个 --xxx flag；
2. 初始化 Ray；
3. 按用户配置创建 RayActorGroup（一个 group 对应一个角色）；
4. 创建 vLLM engines；
5. 调 trainer.fit() 开始主循环。

# 简化版
def train(args):
    ray.init()

    # 按 args 起 4 个角色（按 colocate 配置决定是否合并 PG）
    actor_group  = RayActorGroup(args.actor.num_nodes, args.actor.num_gpus_per_node, PPOActor)
    ref_group    = RayActorGroup(args.ref.num_nodes, args.ref.num_gpus_per_node, ReferenceActor)
    critic_group = RayActorGroup(args.critic.num_nodes, args.critic.num_gpus_per_node, CriticActor)
    reward_group = RayActorGroup(args.reward.num_nodes, args.reward.num_gpus_per_node, RewardActor)

    # 起 vLLM
    vllm_engines = [LLMRayActor.remote(...) for _ in range(args.vllm.num_engines)]

    # 初始化模型（每个 group 各自加载）
    refs = []
    refs.extend(actor_group.async_init_model_from_pretrained(args))
    refs.extend(ref_group.async_init_model_from_pretrained(args))
    refs.extend(critic_group.async_init_model_from_pretrained(args))
    refs.extend(reward_group.async_init_model_from_pretrained(args))
    ray.get(refs)

    # 建 actor ↔ vllm 的 NCCL group
    setup_weight_sync(actor_group, vllm_engines)

    # 跑主循环
    experience_maker = RemoteExperienceMaker(actor_group, critic_group, reward_group, ref_group, ...)
    for episode in range(args.train.num_episodes):
        for step in range(args.train.steps_per_episode):
            experience = experience_maker.make_experience(prompts)
            actor_group.async_run_method("training_step", experience)
            critic_group.async_run_method("training_step", experience)
            if step % args.ckpt.save_steps == 0:
                save_checkpoint(...)

13.5trainer/ray/launcher.py：RayActorGroup 实现

读这个文件能理解"角色 → placement_group → N 个 Ray actor"是怎么落地的。

13.6trainer/ray/ppo_actor.py：训练 actor 主逻辑

这是 OpenRLHF 中最重要的一个文件。每个 RayActorGroup 里的 actor 都是这个类的实例。它的关键方法：

13.7trainer/ppo_utils/experience_maker.py：主循环

这里是"actor / ref / reward / critic 协同"真正发生的地方。RemoteExperienceMaker.make_experience() 大致：

def make_experience(self, prompts):
    # 1. actor 权重同步到 vllm
    self.actor_model_group.async_run_method("broadcast_to_vllm")

    # 2. vllm rollout
    sequences = []
    for engine in self.vllm_engines:
        result = engine.generate.remote(prompts)
        sequences.append(ray.get(result))
    sequences = concat(sequences)

    # 3. 并行调 ref / reward / critic
    ref_logp_ref = self.initial_model_group.async_run_method("forward", sequences)
    reward_ref   = self.reward_model_group.async_run_method("forward", sequences)
    value_ref    = self.critic_model_group.async_run_method("forward", sequences)
    actor_logp_ref = self.actor_model_group.async_run_method("forward", sequences)

    # 4. 等所有结果
    ref_logp, reward, value, actor_logp = ray.get([ref_logp_ref, reward_ref, value_ref, actor_logp_ref])

    # 5. 算 advantage + KL
    advantages, returns = compute_advantages(
        rewards, values, ref_logp, actor_logp,
        gamma=self.gamma, lam=self.lam,
        adv_estimator=self.adv_estimator,
    )

    return Experience(sequences, ref_logp, actor_logp, reward, value, advantages, returns)

13.8trainer/ray/vllm_engine.py：vLLM 集成

vllm_worker_wrap.py 是注入到 vLLM 内部 worker 的 patch，让它能接收 NCCL broadcast 的权重。

13.9models/loss.py：所有 loss 函数

新增算法（比如 GSPO / ORPO）从这里开始，加一个新的 loss class + 在 dispatch 处加 case。

13.10models/actor.py：模型抽象

OpenRLHF 的 Actor 类是 HuggingFace 模型的一层封装：

• 构造时按 --actor.model_name_or_path 加载 HF 模型；
• forward(input_ids, attention_mask) -> (logits, logp) 是核心方法；
• 支持 packing samples + position_ids 跨样本边界处理；
• 支持 ring_attn / flash_attn / fused kernel。

Reference 和 Actor 用同一个类，区别只是 reference 全程 requires_grad=False。

13.11utils/deepspeed/：训练后端

13.12阅读路线总结

1. 跑通 ch03 单机 demo：建立感觉；
2. 读 cli/train_ppo_ray.py：理解入口；
3. 读 trainer/ray/launcher.py：理解 RayActorGroup；
4. 读 trainer/ppo_utils/experience_maker.py · make_experience()：理解主循环；
5. 读 trainer/ray/ppo_actor.py · training_step()：理解训练实现；
6. 读 trainer/ray/vllm_engine.py：理解 vLLM 集成；
7. 读 models/loss.py：理解 PPO loss 实现；
8. 看 trainer/ppo_utils/kl_controller.py：理解自适应 KL；
9. 动手提一个 PR（哪怕修文档）。

13.132025–2026 新增子模块速查

13.1 给的目录树偏简化。下面是基线 commit 上有但容易忽略的新增子模块：

13.147 个 loss 类的完整对照

ch13.9 提了 4 个核心 loss。openrlhf/models/loss.py 实际共有 7 个 loss 类：

13.15建议阅读升级版（7 天路线）

13.16想给 OpenRLHF 提 PR？从这里入手

13.14延伸阅读