verl 主线 pipeline 大改：我该关心的三件事

Q1为什么要动主线？目的是什么？

一句话：老 pipeline 的三条隐含假设（同步、定长、单轮）挡住了 Agent 训练。大改就是把这三条拆掉。

换句话说，V1 把老的「大 trainer」拆成了三个各司其职的组件： 生成侧（AgentLoopManager + LLM Server）、 数据桥（TransferQueue）、 训练侧（PPOTrainer + CheckpointEngine）。这也解释了为什么后面两问的答案都很干净——组件解耦了，你能单独替换其中任意一块。

Q2老脚本还能跑吗？怎么快速适配？启动脚本变了啥？

启动脚本新增的旋钮（不写就用默认，多数人只需关心前两行）

同一个脚本：同步照跑；想开异步只加两行

# 常规同步（等价旧行为，无需任何改动）
python3 -m verl.trainer.main_ppo \
    algorithm.adv_estimator=grpo \
    data.train_files=... actor_rollout_ref.model.path=... \
    trainer.n_gpus_per_node=8 trainer.nnodes=1
# ↑ 默认已是 trainer.use_v1=true, trainer.v1.trainer_mode=sync

# 想开异步（共卡 + partial rollout）：追加两行即可
    trainer.v1.trainer_mode=colocate_async \
    trainer.v1.colocate_async.num_warmup_batches=1

迁移清单：哪些老用法会炸 / 要改

• 直接子类化旧 worker、或依赖 verl/interactions、curriculum sampler、dynamic dataset、旧 tool examples：这些在 #6067（worker→engine）、#6302 等 [BREAKING] 里被废弃/迁移，需要改到 engine 与 AgentLoop 体系。
• 自定义过 rollout / 生成逻辑：不要再改 trainer 内部生成，改成实现一个 AgentLoop（见 Q3 骨架）。
• reward / critic：reward 走 RewardLoopManager（规则或模型），配置路径在 reward.reward_model.*；确认你的老 reward 挂载方式仍匹配。
• 想上 separate_async（分卡全异步）有硬约束：train_batch_size == ppo_mini_batch_size、checkpoint_engine.backend 必须非 naive（nccl/nixl/mooncake）、colocate reward 不支持（需 reward.reward_model.enable_resource_pool=true）。

那我该选哪种 trainer_mode？

共卡 vs 分卡：GPU 到底怎么分？

一个容易被忽略、但直接影响你申请多少卡的点：三种模式里真正改变 GPU 分配的只有 separate_async。sync 和 colocate_async 用的是同一批卡、同样数量，差别只在调度时机（上一节的钩子）。

为什么 separate_async 有这三条硬约束？

这三条不是随意限制，全部由「rollout 跑在另一组卡上、且永不停机」这一点直接推导出来。

看懂异步：一条「塞 1 取 1」的流水线，预热负责起步

V1 主循环本质是生产者 / 消费者流水线：每个 step 里 _add_batch_to_generate()（生产者，fire-and-forget，非阻塞）塞入 1 批 prompt；replay_buffer.sample()（消费者，阻塞轮询）等到「完成的轨迹」够 1 批才取走（还优先取最旧的以压 staleness）。生产与消费解耦——这步塞进去的，不一定是这步消费的那批。

一句话：预热深度 ≈ 流水线深度 ≈ off-policy staleness 预算。预热建立提前量、partial rollout 让长轨迹跨步续跑，两者合起来才让共卡的 colocate_async 在同一批卡上把生成与训练错峰重叠。

Q3训练流程的自由度提高了多少？能方便改哪些？

V1 把「生成逻辑 / 采样策略 / 调度模式 / PPO 每个阶段」都做成了可插拔扩展点。 绝大多数定制，你只需写一个子类 + 一行配置，不用碰主循环。

PPO 每个阶段都是独立方法——step() 里按顺序调用，想改哪步就在 trainer 子类里覆盖对应方法，其它步骤不受影响：

# verl/trainer/ppo/v1/trainer_base.py :: PPOTrainer.step()
_add_batch_to_generate → replay_buffer.sample → [_compute_reward_colocate]
  → _balance_batch → _compute_old_log_prob → [_compute_ref_log_prob]
  → [_compute_values] → _compute_advantage → [_update_critic] → _update_actor
# 生命周期钩子（三种 trainer_mode 就靠它们区分）：
on_train_begin / on_step_begin / on_sample_begin / on_sample_end / on_step_end

下面三张卡片是最常见的三类定制，点开看最小代码骨架（基于当前源码 API，实验阶段接口可能微调）。

# my_agent_loop.py
from typing import Any
from verl.experimental.agent_loop.agent_loop import (
    AgentLoopBase, AgentLoopOutput, register,
)

@register("my_agent")                     # 注册名，供 config / 数据集按名选用
class MyAgentLoop(AgentLoopBase):
    async def run(self, sampling_params: dict[str, Any], **kwargs) -> AgentLoopOutput:
        messages = list(kwargs["raw_prompt"])
        prompt_ids = await self.apply_chat_template(messages)

        # 多轮就在这里 while 循环：生成 → 解析工具调用 → 追加观测 → 再生成
        out = await self.server_manager.generate(          # 向 LLM Server 发请求
            request_id=uuid, prompt_ids=prompt_ids, sampling_params=sampling_params,
        )

        return AgentLoopOutput(
            prompt_ids=prompt_ids,
            response_ids=out.token_ids,
            response_mask=[1] * len(out.token_ids),   # 工具返回段可置 0，不参与 loss
            num_turns=2,
        )

# my_agents.yaml
- name: my_agent
  _target_: my_agent_loop.MyAgentLoop

actor_rollout_ref.rollout.agent.agent_loop_config_path=my_agents.yaml \
actor_rollout_ref.rollout.agent.default_agent_loop=my_agent

# my_sampler.py
from verl.trainer.ppo.v1.replay_buffer import ReplayBuffer

class MyReplayBuffer(ReplayBuffer):
    def sample(self, global_steps: int, partition_id: str, batch_size: int):
        # 自定义优先级 / 难度课程 / staleness 筛选
        batch, metrics = super().sample(global_steps, partition_id, batch_size)
        return batch, metrics

trainer.v1.sampler.custom_sampler.path=my_sampler.py \
trainer.v1.sampler.custom_sampler.name=MyReplayBuffer \
trainer.v1.sampler.max_off_policy_threshold=8      # 内建陈旧度闸门仍可叠加

# my_trainer.py
from verl.trainer.ppo.v1 import PPOTrainer, register_trainer

@register_trainer("my_mode")
class MyTrainer(PPOTrainer):
    def on_sample_end(self):
        self.checkpoint_manager.sleep_replicas()          # 采样完让出显存
    def on_step_end(self):
        if self.global_steps % 2 == 0:                     # 例：每 2 步才同步一次权重
            self.checkpoint_manager.update_weights(self.global_steps)

＊番外 · 放到 slime / AReaL 里看：这套设计不是孤例

如果你也看过 slime（清华 / 智谱）或 AReaL（蚂蚁 / 清华 IIIS），会发现三者在解同一道题—— 解耦生成与训练、加一个数据桥、异步同步权重、控制 staleness。差异主要在抽象哲学和解耦彻底程度。

✓一句话行动指南

• 先别慌：你现有的 GRPO/PPO 脚本大概率照跑——默认 V1 sync ≈ 老同步 PPO，入口命令没变。
• 要吞吐/长轨迹：加 trainer.v1.trainer_mode=colocate_async（或规模够大再上 separate_async + 非 naive 权重后端）。
• 要定制：优先走三个扩展点——AgentLoop（生成）/ ReplayBuffer（采样）/ trainer_mode（调度），别再改主循环。
• 别踩坑：若老代码子类化了旧 worker 或依赖 interactions / curriculum / dynamic dataset，需按 #6067 迁到 engine；use_v1=false 只是临时退路（v0.9.0 移除）。