Skip to main content

笔记

11.03-11.10​

马尔可夫思考​

一站式大模型​

这个从 Long-COT 到马尔科夫思考是不是可以类比为将 Transformer 退化为 RNN ?

  • 您提出的这个类比非常精彩和深刻，在很大程度上是成立的。

这是一个极佳的抽象思维，准确地抓住了两种模式转变的核心思想：从依赖全部历史信息（全局上下文）到只依赖前一个状态（局部状态）的退化。

我们可以从以下几个方面来解析这个类比：

核心共同点：从“全局依赖”到“局部依赖”的退化

  1. Transformer vs. RNN: - Transformer 的核心是 Self-Attention 机制。在处理一个序列时，每个词（token）都可以直接与序列中所有其他词进行交互和计算。它拥有一个“上帝视角”，可以一步到位地看到全局信息。

  • RNN (Recurrent Neural Network) 则是一个严格的序列模型。它在处理第 t 个词时，只能直接访问第 t-1 步传递过来的“隐藏状态”（hidden state）。这个隐藏状态就像是整个过去历史的一个压缩摘要。理论上它包含了过去的所有信息，但实际上，由于梯度消失/爆炸等问题，它对遥远历史的记忆非常有限。

    • 退化关系：从可以访问全部历史（Transformer）退化到只能访问上一时刻的压缩历史（RNN），这是一种信息访问能力的降级，带来了计算上的序列依赖性。

    1. Long-COT vs. 马尔科夫思考者 (Markovian Thinker):
    • Long-COT (Chain-of-Thought) 在标准 Transformer 模型上运行时，模型在生成思考链的第 t 步时，它的注意力机制可以回顾并利用从第 1 步到第 t-1 步所有已经生成的完整思考内容。这同样是一个“上帝视角”，模型可以审视自己完整的“心路历程”。

  • 马尔科夫思考者，根据其定义（Markov Property），在生成第 t 步思考时，其状态只依赖于第 t-1 步的状态，而与 t-2, t-3...等更早的步骤无关。它没有记忆，只看脚下的前一步。

    • 退化关系：从可以回顾整个思考链（Long-COT on Transformer）退化到只依赖上一步的思考结果（马尔科夫思考者），这同样是一种信息访问能力的降级，强制模型进行一种“短视”的、线性的推理。
    方面 (Aspect)Transformer / Long-COTRNN / Markovian Thinker
    信息访问模式全局/并行 (Global/Parallel)局部/序列 (Local/Sequential)
    记忆能力直接访问全部历史上下文依赖于一个压缩的、有损的“状态”
    上下文瓶颈受限于模型的最大上下文窗口存在“隐藏状态”这个严重的信息瓶颈
    核心思想上下文中的任意元素都可以直接交互当前状态只由前一状态决定
    “退化”的体现放弃全局视野，换取简化的序列依赖放弃全局思考链，换取简化的状态转移

类比的精妙之处与局限性

  • 精妙之处：这个类比完美地揭示了两种不同信息处理范式之间的核心差异。无论是在模型架构层面（Transformer vs. RNN）还是在推理过程层面（Long-COT vs. Markovian），都是从一个高维、全局的依赖空间向一个低维、局部的状态空间进行的简化或“退化”。
  • 局限性（或需注意的细节）： a. 架构 vs. 过程：Transformer/RNN 是模型架构，而 Long-COT/马尔科夫思考是运行在这些架构之上的推理过程或算法范式。我们通常是在一个 Transformer 架构上，通过不同的算法来实现或模拟这两种思考过程。 b. RNN 的记忆并非严格马尔科夫：一个标准的 RNN 的隐藏状态理论上是对所有过去信息的编码，而不仅仅是前一个状态。所以 RNN 并非一个严格的一阶马尔科夫过程。但从实践效果上看，它确实更依赖于临近的状态，所以这个类比在精神上是相通的。而“马尔科夫思考者”是更彻底、更极端的“退化”。

结论：

您的类比非常准确。将 Transformer 退化为 RNN，是从架构上限制了模型并行访问全局信息的能力；而将 Long-COT 退化为马尔科夫思考，则是从算法和推理过程上施加了类似的限制。两者都体现了为了简化模型、降低计算复杂度或实现某种特定的序列化结构，而牺牲对完整历史的访问能力。

VeRL 框架

AgentFlow​

Situation (背景)​

搭建多 Agent 系统, 主要是针对作业批改的任务, 提高作业批改的准确率, 提高泛化能力, 对于不确定的题目的推理, 给出更加准确的答案。当前工具增强推理方法面临 可扩展性 和 泛化能力 的限制，主流方法如 Search-R1 训练单个 LLM 来交错推理步骤和工具调用，但这种方法在长期推理任务中表现不佳。

Task (任务)​

AgentFlow 旨在构建一个 可训练的、工具集成的智能体框架，通过模块化架构和在线优化算法，在复杂推理任务中实现卓越的规划、工具使用和长期推理能力

Action (行动)​

核心架构设计​
  • 四智能体模块化系统：Planner（规划器）、Executor（执行器）、Verifier（验证器）、Generator（生成器）通过共享内存协调工作
  • Flow-GRPO 优化算法：直接在系统中优化规划器智能体，使用在线强化学习进行长期推理任务优化
技术实现​
  • 核心编排器：Solver 类在 solver.py 中协调整个问题解决工作流程
  • 工具系统集成：支持多种工具包括 base_generator、python_coder、google_search 等
  • 双模式运行：推理模式使用预训练模型，训练模式使用 Flow-GRPO 在线优化

Result (结果)​

性能提升​

AgentFlow（基于 Qwen-2.5-7B-Instruct）在 10 个基准测试中超越顶级基线：

  • 搜索任务：+14.9%提升
  • 智能体推理：+14.0%提升
  • 数学推理：+14.5%提升
  • 科学推理：+4.1%提升
技术突破​
  • 超越大模型：甚至优于约 200B 参数的 GPT-4o 模型
  • 开源贡献：项目已在 NeurIPS 2025 Efficient Reasoning Workshop 被接收，并获得 HuggingFace Daily Paper

Notes​

AgentFlow 项目通过创新的模块化架构和在线优化算法，成功解决了工具增强推理中的关键挑战。其核心价值在于将复杂的推理任务分解为专门的智能体模块，并通过 Flow-GRPO 算法实现持续优化，在保持较小模型规模的同时实现了超越大型模型的性能。

Agent ModulePrimary ResponsibilityKey OperationsCode Location
PlannerPlanning and decision-makingQuery analysis, next step generation, tool selection, verification, output generationagentflow/agentflow/models/planner.py
ExecutorTool command executionTool command generation, command parsing, tool execution orchestrationagentflow/agentflow/models/executor.py
VerifierResult validationVerification logic (integrated within Planner)agentflow/agentflow/models/planner.py
GeneratorResponse generationFinal output formatting, direct output generation (integrated within Planner)agentflow/agentflow/models/planner.py

Planner agent 是 Flow-GRPO 优化的主要目标，使其能够在完整的系统环境中通过强化学习来学习有效的规划策略。

数据传递

您询问的是数据传输过程中的数据结构和轨迹结构。根据代码库上下文, 这涉及到 AgentFlow 系统中的两个核心概念:

数据传输中的数据结构​

在 AgentFlow 中, 数据传输主要通过以下结构进行:

1. Memory 结构​

Memory 类用于在多轮执行过程中存储和传递数据 。每个 action 包含:

  • tool_name: 使用的工具名称
  • sub_goal: 子目标
  • command: 执行的命令
  • result: 工具执行结果
2. 执行流程中的数据传递​

在 Solver.solve() 方法中, 数据按以下方式流转 :

  1. Planner 生成下一步行动, 接收 question、image_path、query_analysis 和 memory
  2. Executor 生成工具命令并执行
  3. 结果更新到 Memory

轨迹(Trajectory)结构​

1. Triplet 基础结构​

轨迹由多个 Triplet 对象组成, 每个 Triplet 代表一次交互 :

  • prompt: 输入提示(包含 token_ids)
  • response: 模型响应(包含 token_ids)
  • reward: 奖励值(可选)
  • metadata: 元数据(如 response_id、agent_name)
2. Transition 结构​

在训练过程中, 轨迹被转换为 Transition 对象 :

  • state: 状态的 token ID 列表
  • action: 动作的 token ID 列表
  • response_id: 响应标识符
  • agent_name: 代理名称
  • reward: 奖励值
3. 轨迹生成过程​

TraceTree.to_trajectory() 方法将追踪树转换为轨迹 :

  1. 查找所有 LLM 调用
  2. 提取每次调用的 prompt_token_ids 和 response_token_ids
  3. 匹配奖励值到对应的转换
  4. 生成 Triplet 列表
4. 训练数据批次结构​

在训练时, 轨迹被处理为批次数据 :

trace_list = [
    {"prompt_ids": [...], "response_ids": [...]}
    for t in rollout.triplets
]

每个样本包含:

  • reward: 最终奖励
  • trace_list: 轨迹列表
  • data_id: 数据标识符

Notes

训练输出中的 rollout JSON 文件也包含完整的执行轨迹, 但格式不同于训练用的 Triplet 结构 。Rollout JSON 包含更详细的信息如 query_analysis、memory(工具执行历史)和 direct_output, 主要用于分析和调试, 而 Triplet 结构专门为强化学习训练设计, 只包含 token IDs 和奖励信息。

Agent 架构​

This project follows a "Planner-Executor" agentic architecture, which is a common and powerful pattern. Here are the key agents and their functions:

  1. The Planner Agent

  • Role: The "Brain" or "Strategist" of the operation. The Planner is the master agent that orchestrates the entire problem-solving process.

  • Responsibilities:

    • Query Analysis: It first analyzes the user's initial query to understand the core objectives and what kind of information is needed.
    • Step-by-Step Planning: At each step, it looks at the current situation (including the original query and the results from previous steps) and decides on the single best "next step". This involves choosing which tool to use and defining a specific sub-goal for that tool.
    • Context Verification: After a tool is used, the Planner re-evaluates the situation. It decides if the information gathered so far is sufficient to answer the original query. If it is, it gives the "STOP" signal; otherwise, it signals to "CONTINUE" with the next step.

  • Model It Uses: The Planner uses the primary model you specify when you run the script.

    • In quick_start.py, this is controlled by the llm_engine_name parameter, which you've set to your local Ollama model (ollama-deepseek-r1:7b).

    • In the training configuration (train/config.yaml), this corresponds to the main BASE_MODEL (Qwen/Qwen1.5-1.8B-Chat) that is served via vLLM.

    1. The Executor Agent

  • Role: The "Hands" or "Doer" of the operation. The Executor takes the Planner's commands and carries them out.

  • Responsibilities:

    • Command Generation: It receives the tool name and sub-goal from the Planner. Its job is to then formulate the precise, executable code or command for that tool (e.g., generating the correct Python syntax like tool.execute(query = "...")).
    • Command Execution: It then runs this command and captures the output (the result).

  • Model It Uses: The Executor uses its own separate LLM to generate the tool commands. This is where your remote API configuration comes into play.

    • In our latest setup for quick_start.py, we configured the Executor to use executor_llm_engine_name, which is set to "deepseek-r1".

    • This triggers the logic in factory.py to use your remote API endpoint with your API key.

    1. The Tool Agents

This is a subtle but important category. Some of the "tools" are not just simple functions; they are themselves powered by LLMs and act as specialized, single-purpose agents.

  • Role: Specialists that perform a single, well-defined task.
  • Examples from your configuration:
    • Google_Search_Tool: When this tool needs to process results or formulate a better search query, it can use its own LLM.
    • Wikipedia_Search_Tool: Similarly, this tool can use an LLM to summarize articles or extract key information.
    • Base_Generator_Tool: This tool's entire purpose is to act as a generalist agent to answer a query.
  • Models They Use: The models for these tool agents are defined by the TOOL_ENGINE list in your train/config.yaml: TOOL_ENGINE: ["self", "self", "deepseek-r1", "deepseek-r1"]
    • Base_Generator_Tool and Python_Coder_Tool are set to "self", meaning they use the main training model (the same one as the Planner).
    • Google_Search_Tool and Wikipedia_Search_Tool are set to "deepseek-r1", meaning when they need LLM capabilities, they will also call your remote API via the logic in factory.py.

Summary Table

Agent/ComponentRoleModel Used (in your final configuration)
Planner AgentThe "Brain". Decides what to do next.Local Ollama (ollama-deepseek-r1:7b) for inference / Main BASE_MODEL for training.
Executor AgentThe "Hands". Generates and runs tool commands.Your remote API (deepseek-r1).
Tool Agents (some)Specialists for specific tasks (e.g., Search).Varies. Some use the main model (self), others use your remote API (deepseek-r1).

This separation of concerns is very powerful. It allows you to use a smaller, faster local model for the high-level planning, while leveraging a more powerful, specialized remote model for the heavy-lifting tasks performed by the Executor and certain tools.

算法对比​

Flow-GRPO 沿用了 GRPO 的优势估计与损失，但训练的对象、数据收集方式以及奖励注入链路都围绕 AgentFlow 的“流程化”代理体系做了大幅改造，因此和经典、单轮文本场景里的 GRPO 有几点关键差异：

  • 训练对象定位：经典 GRPO 直接优化单个 LLM 在静态 prompt→completion 数据集上的策略；Flow-GRPO 只微调 AgentFlow 流程中的 Planner，并让其与 Executor / Verifier / Generator 四个子代理协同，在真实多轮记忆与工具调用链里学习决策，侧重点是“系统内在线调度”，而不是单模型输出指出了四模块架构以及“在线优化 planner”的目标）。
  • 数据采集方式：传统 GRPO 在每个 prompt 上并行采样多条回答、离线计算组奖励；Flow-GRPO 通过 AgentFlowTrainer→AgentModeDaemon 把 Ray PPO 训练 loop 接到 AgentFlowServer，每个 batch 都要实际跑一整条任务流程、调用外部工具/LLM，生成 rollout.triplets（prompt/response/token_ids），再回填训练数据。这套“跑流程再学习”, 说明 Flow-GRPO 是“在线环境交互 + 回传轨迹”的做法，而不是对静态语料做策略梯度。
  • 奖励与 Advantage 结构：Flow-GRPO 把流程执行得到的 rollout.final_reward 映射回每一轮的 token level 分布，再拼成完整输入序列，以便 GRPO 算法继续“组平均 → 去均值”地计算 advantage。经典 GRPO 则通常直接用判题器/规则在每个回答结尾给奖励，没有多轮 trace 的展开或 token-level 回填。 总的来说：Flow-GRPO 在优化目标（仍是 GRPO）、但在“交互式数据收集 + 多代理流 + 奖励写回”层面拓展，让 GRPO 适配 AgentFlow 的多轮、工具增强场景；而经典 GRPO 更像单模文本 RLHF。

四个模块​

四个模块都在 agentflow/agentflow/models 下面有对应实现，并且都在 agentflow/agentflow/solver.py 的 construct_solver() 里统一实例化。

  • Action Planner：agentflow/agentflow/models/planner.py 定义 Planner 类。它内部构建 planner ，并提供 generate_base_response、analyze_query、generate_next_step、verificate_context 等核心逻辑。
  • Tool Executor：agentflow/agentflow/models/executor.py 定义 Executor 类，负责根据 planner 给的 context/sub-goal 生成 tool command，再调用 Initializer 缓存的工具实例执行。
  • Executive Verifier：不是独立文件，而是 planner 内 verificate_context() + extract_conclusion() 这套 verifier 流程。
  • Solution Generator：最终答案生成也由 Planner 完成，分别是 generate_final_output() 和 generate_direct_output()。它使用同一 LLM 引擎把 memory 中的行动摘要成详细解和直接输出。

11.29-12.05​

verl​

从零开始的 verl 框架解析

AI Infra VeRL 框架入门&代码带读

Verl GRPO 实现拆解讲解

AgentLighting

verl-agent​

本文从代码结构与关键流程入手，梳理 verl-agent 如何把多轮环境交互、组内强化学习算法（GiGPO/DAPO/GRPO 等）以及多模态大模型训练串联起来。可配合 README.md 了解任务背景，本篇聚焦“源码如何实现这些能力”。

1. 顶层执行路径​

延续 veRL 的 Hydra + Ray 规范，训练入口位于 verl/trainer/main_ppo.py:34-188：

  1. Hydra 配置 – 读取 verl/trainer/config/ppo_trainer.yaml，将模型、环境、算法、资源需求注入 config。
  2. Ray 初始化 – get_ppo_ray_runtime_env() 统一设定 tokenizer 线程、NCCL 等运行环境，然后用 ray.init(...) 起本地/集群运行时。
  3. TaskRunner – 在单独的 Ray 任务中完成：
    • 下载/定位权重；
    • 通过 agent_system.environments.make_envs() 创建训练/验证环境管理器；
    • 构造 tokenizer/processor、奖励模型 worker、Actor/Critic/Ref worker group；
    • 实例化 TrajectoryCollector（多轮 rollout 管理器）和 RayPPOTrainer；
    • trainer.fit() 进入主循环。

可见源码将“算法策略”与“环境交互”拆分到 verl 与 agent_system 两条线，便于替换/扩展。

2. 仓库结构速览​

路径职责
verl/veRL 主体：Ray Trainer、核心 PPO/GiGPO 算法、模型注册、worker 管理、工具函数。
agent_system/Agent 相关扩展：多环境封装、记忆模块、多轮采样、奖励聚合。
examples/每类算法/环境的启动脚本，方便照搬配置（如 examples/gigpo_trainer/run_alfworld.sh）。
docs/额外说明文档（本文件即位于此处）。
scripts/依赖安装与环境搭建脚本，例如 scripts/install_py310.sh。
tests/针对核心组件的单测/集成测试。

3. 配置与数据流​

3.1 Hydra 配置层​

verl/trainer/config/ppo_trainer.yaml 以模块化字段描述整个训练：

  • data.*：数据路径、token 长度、batch size、是否返回原始 chat、truncation 方式等；
  • actor_rollout_ref.*：单一配置块内描述 Actor、Rollout Engine、Reference 三个角色（策略、采样、对照）；
  • critic.*、reward_model.*：价值网络与奖励模型的并行策略；
  • env.*：agent_system 所需的环境类型、种子、rollout 组数、history length 等；
  • algorithm.*：GiGPO/GRPO/动态 sampling 的开关、clip/entropy/adv 计算策略。

Hydra 允许通过 python -m verl.trainer.main_ppo env.env_name=alfworld/AlfredTWEnv ... 式命令覆盖任何字段，配合 examples/ 中的脚本即可快速切换实验。

3.2 数据集与 DataProto​
  1. RLHFDataset – verl/utils/dataset/rl_dataset.py:37-200 将 Parquet 数据下载到本地缓存，过滤超长提示，支持图文/视频段落解析、工具参数注入等。__getitem__ 返回字典，包含 token、attention mask、原始 prompt/chat、可选的多模态 tensor。
  2. collate_fn – 与 torch Dataset 配套；张量字段堆叠成 batch，非张量字段转换为 np.array(dtype=object)，方便后续混合处理。
  3. DataProto – verl/protocol.py 定义了跨模块统一的数据协议：batch（TensorDict）+ non_tensor_batch + meta_info。pad_dataproto_to_divisor()/unpad_dataproto() 负责让 batch 尺寸整除分布式世界大小，repeat()/union()/from_single_dict() 则让自定义数据结构保持一致。

Ray Worker 之间传递的全部中间结果都被包装成 DataProto，从而规避自定义类型在序列化、全局规约时的碎片化处理。

4. 多轮交互体系​

4.1 TrajectoryCollector​

agent_system/multi_turn_rollout/rollout_loop.py:29-539 构建了“观察 → Prompt → 模型生成 → 环境反馈”的闭环：

  • preprocess_single_sample() 将环境观测（文本/图片/anchor）拼进 chat 模板，统一左填充、截断策略，并在多模态场景下把 <image> 替换为视觉 token，占位符映射由 Qwen2/Qwen3-VL 专用 get_rope_index() 负责。
  • preprocess_batch() 逐样本处理后调用 collate_fn，重新生成 DataProto，确保 meta 信息（数据源、工具参数等）完整保留。
  • vanilla_multi_turn_loop() 在给定 env.max_steps 内循环：
    1. 根据最新观察构建 batch，并裁剪/弹出供模型推理的 keys；
    2. 将输入 pad 到 actor_rollout_wg.world_size 的倍数，调用 Ray Worker (generate_sequences) 得到动作；
    3. 用环境管理器执行动作，写入 reward/done/valid_action 等标记；
    4. 累积 episode 奖励、长度、历史信息，直到全部 done 或达到最大步数；
    5. 交给 EnvironmentManager.success_evaluator() 计算成功率。
  • dynamic_multi_turn_loop() 在算法配置打开 algorithm.filter_groups.enable 时会重复采样，直到收集到足够多的“非同质化”轨迹，这是 DAPO/GiGPO 动态采样的来源。
  • 最终 gather_rollout_data() 只保留 active 样本，把 episode-level reward/length/tool_callings 写回 non_tensor_batch，便于奖励函数直接使用。
4.2 环境与记忆​

agent_system/environments/env_manager.py 针对不同任务提供派生类，兼顾多模态输入、动作合法性校验以及“组内共享初始状态”的需求：

  • SearchEnvironmentManager (env_manager.py:45-131) 将搜索日志写入 SearchMemory，按模板拼装任务提示，并在 success_evaluator 中区分数据源（方便分别统计 success rate）。
  • AlfWorld/Sokoban/WebShop/... (env_manager.py:133-517) 则利用 SimpleMemory 储存历史，支持 history_length 控制上下文窗口、额外的可行动作展示等。
  • GymCardEnvironmentManager & AppWorldEnvironmentManager 展示了视觉输入（算式图像）和结构化 supervisor 提示的组合方式。
  • make_envs() (env_manager.py:602-699) 负责根据 config.env.env_name 动态导入 env_package 下的构建函数，并把投影函数（自然语言动作 → 环境 action id）注入各自的 EnvironmentManager。

记忆模块由 agent_system/memory/memory.py:19-184 提供：SimpleMemory/SearchMemory 统一 reset()/store()/fetch() 接口，返回已格式化的历史片段，供模板直接使用。新增任务只需继承 BaseMemory 并在对应环境管理器中替换即可。

4.3 Episode 奖励​

EpisodeRewardManager (agent_system/reward_manager/episode.py:20-95) 演示了如何把环境回传的 episode_rewards/episode_lengths 写入 reward_tensor。当存在外部 rm_scores 时直接透传，否则默认把 reward 对齐到响应序列最后一个 token，并按需打印 prompt/response 以便调试。

5. PPO / GiGPO 算法栈​

5.1 RayPPOTrainer​

RayPPOTrainer（定义见 verl/trainer/ppo/ray_trainer.py，由 main_ppo.py:169-188 实例化）协调以下角色：

  • role_worker_mapping：将 Role.ActorRollout/Critic/RewardModel/RefPolicy 绑定到对应 Ray 远程类；FSDP、Megatron 版本在 verl/workers/fsdp_workers.py、verl/workers/megatron_workers.py 中定义。
  • ResourcePoolManager：按照 trainer.nnodes × trainer.n_gpus_per_node 描述的资源矩阵调度 Worker。
  • traj_collector 与 envs：在 collect_trajectories 阶段调用上节介绍的多轮交互。
  • reward_fn：调用 Episode 奖励或自定义 RM，把 scalar 奖励贴回轨迹。
5.2 核心算法​

verl/trainer/ppo/core_algos.py 聚焦 Advantage 计算与 KL 控制器：

  • AdaptiveKLController/FixedKLController 提供可切换的 KL 约束策略（行 31-59）。
  • compute_gae_advantage_return() 实现标准 GAE（行 76-134）。
  • compute_grpo_outcome_advantage()、compute_grpo_passk_outcome_advantage() 针对 GRPO/GiGPO 的组内归一化逻辑，把同一 group 的 returns 做差或做标准化（行 137 起）。

在 GiGPO 模式下，config.env.rollout.n 控制“每个提示生成多少条轨迹”以构成 group；TrajectoryCollector 会把同组样本分配同一个 uid（rollout_loop.py:314-324），从而让 Advantage 汇总正确匹配。

5.3 动态过滤​

GiGPO/DAPO 的“动态采样”通过 filter_group_data() (agent_system/multi_turn_rollout/utils.py:122-199) 实现：若同组 reward 完全一致则整体丢弃，保证梯度主要来自存在差异的轨迹。dynamic_multi_turn_loop() 则会在过滤后继续 roll until 满足 batch 要求。

6. 模型与 Worker 框架​

6.1 模型注册​

verl/models/registry.py:1-58 列出了在 Megatron/FSDP 场景下支持的架构（Llama、Qwen2、Mistral 等），并按 model_arch → module + class 的映射动态导入。ModelRegistry.load_model_cls() 根据 value 标记返回 actor/ref 还是 critic/rm 的模型类，确保不同角色复用统一的并行实现。

6.2 Worker 角色​

在 main_ppo.py:88-144 中，根据 config.actor_rollout_ref.actor.strategy 选择 RayWorkerGroup（FSDP/FSDP2）或 NVMegatronRayWorkerGroup，并将 Actor/Rollout/Ref/Critic/RewardModel 远程化。每个 worker 内部：

  • 负责加载对应权重（LoRA 时设置 lora_rank/lora_alpha 等）；
  • 执行前向/反向/梯度同步（FSDP 或 Megatron pipeline）；
  • 在 ActorRolloutRefWorker.generate_sequences() 中调用推理引擎（vLLM / HF / sglang，取决于 actor_rollout_ref.rollout.name）。

Ray Worker 的解耦设计使得替换并行策略（如切换到 FSDP2 或 Megatron）无需修改 TrajectoryCollector/EnvironmentManager。

7. 扩展指引​

场景步骤
新增环境1) 在 agent_system/environments/env_package/<env> 实现 build_*_envs 与 <env>_projection；2) 在 env_manager.py 中新增 <Env>EnvironmentManager，或复用 EnvironmentManagerBase + 定制 build_text_obs; 3) 在 make_envs() 中注册分支；4) 在 examples/<algo>/run_xxx.sh 增加配置覆盖。
自定义记忆继承 agent_system/memory/base.py，实现 reset/store/fetch；在对应环境管理器中替换 self.memory 即可，为多来源信息（如工具调用结果）提供特化格式。
接入新奖励参考 EpisodeRewardManager.__call__()，实现自定义 reward manager 并在 main_ppo.py:145-155 处通过配置选择。
接入新算法1) 在 verl/trainer/ppo/core_algos.py 添加 Advantage/clip 逻辑；2) 若需要动态策略，在 TrajectoryCollector 或 utils.filter_group_data 中扩展过滤策略；3) 通过 Hydra 配置暴露新开关。
扩展模型/引擎1) 在 verl/models 中注册新架构；2) 根据需要在 verl/workers 下补充 Worker；3) 在配置中声明 actor_rollout_ref.rollout.name / model.path 等。

8. 示例脚本与测试​

  • examples/gigpo_trainer/ 集成了 ALFWorld、WebShop、Sokoban 等任务的 bash 启动脚本，演示如何配置 GiGPO（env.rollout.n > 1）和 LoRA finetune。
  • examples/gigpo_dynamic_trainer/ 打开动态过滤以复现论文中的 Dynamic GiGPO。
  • examples/prompt_agent/ 展示评估/推理阶段如何跳过训练管线直接装载策略模型。
  • tests/ 目录提供了最小化单元测试样例（例如 dataset/trainer 级别），帮助在改动源码后快速验证关键路径。

9. 常见排查思路​

  1. 批尺寸不整除 – 查看 TrajectoryCollector.preprocess_batch() 之后 pad_dataproto_to_divisor() 是否被调用；若自定义处理引入了额外字段但未 pop，会导致 Ray Worker 无法序列化。
  2. 环境上下文过长 – 检查对应环境管理器的 history_length 与模板逻辑（例如 WebshopEnvironmentManager.build_text_obs() 在超过 13k 字符时会回退到无历史模板）。
  3. 奖励恒为 0 – 确认 episode_rewards 是否真的写入 non_tensor_batch（rollout_loop.py:363-388），以及奖励管理器是否启用了 normalize_by_length。
  4. 多模态 OOM – 图片会被 process_image() 限制在 [256^2, 2048^2] 像素区间，可按需调整；此外记得在配置中设置合适的 max_prompt_length 与 ppo_max_token_len_per_gpu。