启动阶段
python -m verl.trainer.main_ppo ...启动 Hydra。- Hydra 将根 YAML、组件 YAML 和命令行 override 合成一个配置树。
validate_config检查 batch、并行度、critic/ref 是否需要等约束。ray.init将环境变量(含 determinism、TransferQueue、RL-Insight)、依赖、可选runtime_env.py_executable和 profiling 设置传播到 actors。- 远程
TaskRunnerV1.run强制开启并初始化 TransferQueue,按trainer.v1.trainer_mode选择 Trainer。 - Trainer
init()依次初始化:tokenizer → dataloader → dump executor → ResourcePool → actor/rollout(及可选 critic)WorkerGroup → critic/actor/ref engine → RewardLoopManager → 可选 teacher manager →LLMServerManager(hybrid replicas)→CheckpointEngineManager→ 休眠 replicas → 加载 checkpoint。driver 还会按trainer.checkpoint_callback_class构造 checkpoint callback。 AgentLoopManagerTQ.create接入 rollout client、teacher client 和 reward handles,然后进入fit。
当前默认同步链更精确地说是:初始化 TQ → PPOTrainerSync.init 创建 WorkerGroup、LLM server、RewardLoop 与 CheckpointEngine → AgentLoopManagerTQ.create → fit → 注册并异步提交 prompt → ReplayBuffer.sample 等待足够终态 groups 并返回轻量 KVBatchMeta → Trainer 按 partition/key 驱动 old/ref/value/advantage/critic/actor → step 结束同步新权重。Trainer 的核心控制对象不是一份始终常驻 driver 的完整训练 batch。
三种 mode 共用的 V1 step 骨架是 on_step_begin → prepare_step → N × _step_once → on_step_end。sync/colocate 通常一次采满逻辑 train batch;separate_async 以 PPO mini-batch 粒度流过 controller。启用 hybrid_rollout.enable_switch 后,step 间会先让 hybrid replicas 帮 standalone rollout 生成,达到 sampleable threshold 再执行 remove/abort/sleep 收回训练;step 末若预计借卡收益大于切换成本,再同步权重并把 replicas 加回 load balancer。
初始化顺序为什么重要
actor、critic 等训练 worker 先占据资源并建立进程组;rollout server 通常后初始化,这样 vLLM/SGLang 在决定 KV cache 容量时能看到更准确的可用显存。共置场景还必须明确谁在何时 offload/reshard,不能让训练 optimizer state 与推理 KV cache 无控制地同时占满显存。
同步训练 step 的概念链路
无论 V0/V1,核心依赖关系相同:
V1 的具体实现在 verl/trainer/ppo/v1/trainer_base.py:fit 里每步调用 step();step 按 parameter_sync_step 做多次 _step_once;_step_once 的顺序是:sample →(可选 colocated reward)→ _balance_batch → _compute_old_log_prob → ref log-prob → values → _compute_advantage → update critic → update actor。行号会随 hook 与 metrics 增删漂移,应按符号定位。V0 的线性参考实现位于 verl/trainer/ppo/ray_trainer.py(deprecated)。
1. prompt 与 uid
RLHFDataset 从 Parquet 或 Hugging Face Dataset 读取数据,并用与 rollout 对齐的模板/tokenizer 做长度检查;实际取样主要返回 raw messages 与 reward/tool metadata,最终 chat template 与 token 构造在 AgentLoop 侧完成。Trainer 给每个原始 prompt 一个 uid。当前 AgentLoop 只走 Continuous Token:文本/VL builder 按 tokenizer、processor 和模型族自动选择;未知 model_type 会告警并选通用 text/VL builder,只有已识别族与 processor 不能安全匹配等情况才显式报错。这不是回退到 legacy re-tokenize。
当 rollout.n > 1 时,V1 在同一 prompt uid 下启动多个 session,trajectory key 形如 {uid}_{session_id}_{index}。GRPO/RLOO 仍按 uid 聚合候选;若丢失关联,优势估计会把不同题目的回答混组。
代码入口:verl/utils/dataset/rl_dataset.py(RLHFDataset 类 72 行起,_read_files_and_tokenize 169,__getitem__ 386)。
2. rollout 与多轮 AgentLoop
LLMServerManager 管理 vLLM/SGLang/TRT-LLM 服务副本(都以 async server 模式注册;SPMD sync rollout 已在 v0.7 移除);AgentLoopWorker 接收 prompt,调用 server client,累积 response ids、逐轮 token、mask 和工具结果。单轮任务也是一个最简单的 agent loop。
多轮时不能最后把 messages 重新套一遍 chat template 代替真实 rollout token,因为模板、空格或特殊 token 的差异会使训练时 log-prob 对应的 token 序列不同于采样策略,破坏 on-policy 一致性。这就是官方文档强调的 token-in/token-out 原则。
3. reward
reward 可来自:
- 规则函数:数学答案匹配、代码单测、格式检查、工具任务是否完成。
- reward model:另一个模型对回答评分(判别式 RM 或生成式 GenRM)。
- 多种 score 的组合与 shaping,例如超长惩罚。
RewardManager/RewardLoop 最终把结果整理为 token-shaped score。纯 outcome reward 常写在最后一个有效 response token。GAE、ReMax、REINFORCE++ 通过时间递推或 reward-to-go 传播;GRPO/RLOO 则先汇总序列 reward,再把组相对标量广播到有效 action token,它们不提供细粒度 temporal credit assignment。RewardLoop 可以和 rollout 流式衔接;生成式 RM 还可配置 full_determinism(#7027)保证判分可复现。
4. log-prob 与 value
- rollout log-prob:真实生成轨迹的策略概率(由推理引擎返回)。
- actor old log-prob:固定 PPO 更新的分母。decoupled 模式(默认,
rollout_correction.bypass_mode=false)在训练该 batch 前由 actor 的_compute_old_log_prob重算;bypass 模式直接使用 rollout 值。自 #7188 起separate_async也支持 decoupled,不再强制 bypass。 - reference log-prob:仅在 KL 约束需要时计算。
- values:仅在 GAE/critic 路径需要。
计算前经常按有效序列长度重新平衡 batch(_balance_batch),避免某些 data-parallel rank 被长回答拖慢。
5. reward shaping 与 advantage
若使用 reward-side KL,先从 token score 中扣除 KL penalty。随后根据 algorithm.adv_estimator 进入 estimator。response mask 决定哪些 token 有效;padding 和 EOS 后内容不能进入统计。
V1 对多轨迹 GRPO 还有额外语义:只用每个 {uid, session_id} 的最终输出做组相对计算,再把标量广播到该 session 的其他输出(v1/utils.py 的 compute_advantage_for_multi_trajectories);非 GRPO estimator 走普通公共路径,不能据此类推。
Decoupled 模式下,_compute_advantage 之前还会调用 compute_rollout_correction_and_add_to_batch(见 verl/trainer/ppo/v1/trainer_base.py 的 _compute_old_log_prob 及后续 correction 分支),基于 rollout/old 两套 log-prob 计算 IS/RS 权重与训推偏移指标;bypass 模式跳过这一步,由 bypass_mode policy loss 直接处理。
特别注意 ReMax:公共 estimator 强制需要 reward_baselines,完整 greedy-baseline rollout 与字段写入目前只见 V0 RayPPOTrainer;默认 V1 _compute_advantage 没有准备该字段,因此不能只设置 algorithm.adv_estimator=remax。使用前必须核查 recipe 是否切到 trainer.use_v1=false,或目标版本的 V1 是否已补齐 baseline 数据链路。
6. critic 与 actor 更新
GAE 时先用 returns 更新 critic,再用 advantage 更新 actor。actor 内部按 mini-batch/micro-batch 或 token budget 切分,重新前向得到 current log-prob,计算 ratio、clipped objective、entropy/KL 等,再反向和 optimizer step。
“先 critic 还是先 actor”不是核心算法定义,但会影响显存切换和实现。面试时应强调依赖是 advantage 已确定;critic 与 actor 是不同优化目标。
7. 权重同步与下一轮
actor 更新后,rollout 必须看到新版本权重。V1 统一由 CheckpointEngineManager 协调:
- 共置(sync/colocate_async):基类强制
backend="naive",走进程内 per-tensor 拷贝。ActorRolloutRefWorker.update_weights的顺序是:resume(tags=["weights"])→ 写入新权重(LoRA 可 merge)→ actor 参数可 offload 回 CPU →resume(tags=["kv_cache"])恢复推理。 - 分离(separate_async):断言 backend 非 naive,可选
nccl(HCCL 同名覆盖注册)、nixl、mooncake、kimi_ckpt_engine、delta_sharded等(checkpoint_engine/registry),面向 standalone rollout 做跨节点传输。
当前 NCCL engine 的构造签名默认开启 node-local multi_sender:actor rank 0 同节点的其他 actor rank 作为 relay 参与同一个 broadcast group,利用 NVLink 把根部 fan-out 扩到多块 NIC;它们不是额外权重源。delta_sharded 则只在 FSDP1/FSDP2/TorchTitan → SGLang BF16 的分离场景支持,不能把 roadmap 中的 Megatron 当作已支持。
典型共置生命周期是:休眠/释放 rollout → actor 训练 → 恢复 rollout weights → 同步 → actor 参数可 offload → 恢复 KV cache。
异步模式不必每 step 全部等待,但需要模型版本号、parameter_sync_step(separate_async 默认 4)、replay buffer 的 max_off_policy_threshold(默认 8)和 drop|wait 策略共同控制陈旧度。
三类 mask
| mask | 作用 |
|---|---|
attention_mask | prompt + response 中哪些 token 真实存在 |
response_mask | response 尾段中哪些 token 参与 RL reward/advantage/loss(1=模型生成,0=工具/环境返回或 padding) |
SFT loss_mask | 哪些 assistant token 参与监督损失 |
工具返回、环境 observation 等 token 可以存在于上下文并影响后续生成,但通常应在 response loss mask 中排除,避免模型被训练去”预测环境”。
如何调试一条样本
对同一 uid 打印或落盘以下字段:prompt ids/text、response ids/text、attention/response mask、reward components、old/ref log-prob、value、advantage、model version。先核对 token 与 mask,再看数学指标;很多”算法不收敛”实际是模板、截断、reward 落点或分组问题。