跳转至

verl/experimental 模块总览

模块定位

verl/experimental 是 verl 框架的实验性功能模块，包含尚在开发或验证阶段的高级特性。这些功能围绕一个核心目标：提升大语言模型强化学习训练的效率和灵活性。

架构总览

verl/experimental/
├── __init__.py                          # 空初始化文件
├── agent_loop/                          # Agent 循环框架（核心基础设施）
│   ├── __init__.py                      # 导出核心类，触发注册
│   ├── agent_loop.py                    # 核心：AgentLoopBase, AgentLoopWorker, AgentLoopManager
│   ├── single_turn_agent_loop.py        # 单轮对话 Agent 循环
│   ├── tool_agent_loop.py              # 多轮工具调用 Agent 循环（状态机）
│   ├── tool_parser.py                   # 工具调用解析器（Hermes / GPT-OSS 格式）
│   ├── utils.py                         # 配置路径解析与格式化工具
│   └── prometheus_utils.py              # Prometheus 监控配置
│
├── dataset/                             # 数据集抽象层
│   ├── __init__.py
│   └── sampler.py                       # 抽象采样器接口（课程学习支持）
│
├── dynamic_dataset/                     # 动态数据集生成
│   ├── __init__.py
│   └── dynamicgen_dataset.py            # 训练迭代间动态生成新数据
│
├── fully_async_policy/                  # 全异步训练（最复杂）
│   ├── fully_async_main.py              # 入口：FullyAsyncTaskRunner
│   ├── fully_async_trainer.py           # 异步训练器
│   ├── fully_async_rollouter.py         # 异步推理器（流式生成）
│   ├── message_queue.py                 # 消息队列（训练-推理解耦）
│   ├── param_sync.py                    # 参数同步器
│   ├── detach_utils.py                  # 数据组装与指标聚合
│   ├── megatron_utils.py                # Megatron 参数快照
│   ├── fsdp2_utils.py                   # FSDP2 参数快照
│   ├── agent_loop/                      # 全异步专用 Agent 循环
│   │   ├── __init__.py
│   │   ├── agent_loop.py                # FullyAsyncAgentLoopManager
│   │   ├── partial_tool_agent_loop.py   # 可中断/恢复的工具调用循环
│   │   └── partial_single_turn_agent_loop.py  # 可中断/恢复的单轮循环
│   ├── sglang_rollout/                  # SGLang 推理引擎适配
│   │   ├── __init__.py
│   │   └── sglang_async_server.py
│   ├── vllm_rollout/                    # vLLM 推理引擎适配
│   │   ├── __init__.py
│   │   └── vllm_async_server.py
│   └── unittest/                        # 单元测试 / 示例
│       └── simple_streaming_demo.py
│
└── one_step_off_policy/                 # 一步离策略训练
    ├── main_ppo.py                      # 入口：OneStepTaskRunner
    ├── ray_trainer.py                   # 流水线化训练器
    ├── utils.py                         # 工具函数（need_critic）
    ├── distributed_utils.py             # 分布式通信（IPv6 支持）
    └── agent_loop/                      # 一步离策略专用 Agent 循环
        ├── __init__.py
        └── agent_loop.py               # OneStepOffAgentLoopManager

核心架构图

┌─────────────────────────────────────────────────────────────────────┐
│                        实验性功能架构                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │                    训练模式（三种）                             │  │
│  │                                                               │  │
│  │  ┌─────────────┐  ┌──────────────────┐  ┌─────────────────┐  │  │
│  │  │ 标准同步训练 │  │ 一步离策略训练    │  │ 全异步训练       │  │  │
│  │  │ (verl核心)   │  │ (one_step_off)   │  │ (fully_async)   │  │  │
│  │  │             │  │                  │  │                 │  │  │
│  │  │ 推理→训练   │  │ 推理与训练       │  │ 推理与训练       │  │  │
│  │  │ 严格串行    │  │ 流水线重叠       │  │ 完全解耦        │  │  │
│  │  │             │  │ (asyncio)        │  │ (MessageQueue)  │  │  │
│  │  └─────────────┘  └──────────────────┘  └─────────────────┘  │  │
│  │        ↑                   ↑                     ↑            │  │
│  │        │                   │                     │            │  │
│  │        └───────────────────┴─────────────────────┘            │  │
│  │                            │                                  │  │
│  │                    ┌───────┴───────┐                          │  │
│  │                    │  Agent Loop   │  ← 所有模式共用的推理框架 │  │
│  │                    │  (agent_loop/)│                          │  │
│  │                    └───────┬───────┘                          │  │
│  │                            │                                  │  │
│  │              ┌─────────────┼─────────────┐                   │  │
│  │              ↓             ↓             ↓                   │  │
│  │     ┌──────────────┐ ┌──────────┐ ┌─────────────┐           │  │
│  │     │SingleTurnLoop│ │ToolLoop  │ │PartialLoop  │           │  │
│  │     │(单轮生成)    │ │(工具调用) │ │(可中断恢复) │           │  │
│  │     └──────────────┘ └──────────┘ └─────────────┘           │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │                    数据层                                     │  │
│  │  ┌──────────────────────┐  ┌────────────────────────────┐    │  │
│  │  │ dataset/sampler.py   │  │ dynamic_dataset/           │    │  │
│  │  │ 抽象采样器           │  │ 动态数据生成               │    │  │
│  │  │ (课程学习接口)       │  │ (训练间新数据生成)         │    │  │
│  │  └──────────────────────┘  └────────────────────────────┘    │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │                    基础设施层                                  │  │
│  │  ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐    │  │
│  │  │ param_sync   │ │ message_queue│ │ distributed_utils  │    │  │
│  │  │ 参数同步     │ │ 消息队列     │ │ NCCL/IPv6 通信     │    │  │
│  │  └──────────────┘ └──────────────┘ └────────────────────┘    │  │
│  │  ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐    │  │
│  │  │ fsdp2_utils  │ │megatron_utils│ │ prometheus_utils   │    │  │
│  │  │ FSDP2 快照   │ │Megatron 快照 │ │ 监控配置           │    │  │
│  │  └──────────────┘ └──────────────┘ └────────────────────┘    │  │
│  └───────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

三种训练模式对比

特性 标准同步 一步离策略 全异步
推理-训练关系 串行 流水线重叠 完全并行
策略一致性 完全一致 差一步 可能差多步
GPU 利用率 较低 中等 最高
实现复杂度 简单 中等 复杂
需要消息队列 否 否 是
需要参数版本管理 否 否 是
支持中断/恢复 否 否 是
入口文件 verl 核心 main_ppo.py fully_async_main.py

推荐阅读顺序

第一阶段：理解基础框架

  1. 01_init.md - 模块入口，了解整体结构
  2. agent_loop/03_agent_loop.md - 最重要的文件，理解 Agent 循环核心架构
  3. agent_loop/01_init.md - Agent 循环的注册机制
  4. agent_loop/04_single_turn_agent_loop.md - 最简单的 Agent 循环实现

第二阶段：理解工具调用

  1. agent_loop/06_tool_parser.md - 工具调用解析
  2. agent_loop/05_tool_agent_loop.md - 多轮工具调用的状态机

第三阶段：理解数据层

  1. dataset/02_sampler.md - 数据采样抽象
  2. dynamic_dataset/02_dynamicgen_dataset.md - 动态数据生成

第四阶段：理解一步离策略训练（较简单的异步方案）

  1. one_step_off_policy/01_main_ppo.md - 入口与配置
  2. one_step_off_policy/02_ray_trainer.md - 流水线化训练
  3. one_step_off_policy/03_utils.md - 工具函数
  4. one_step_off_policy/04_distributed_utils.md - 分布式通信
  5. one_step_off_policy/agent_loop/02_agent_loop.md - 异步 Agent 循环

第五阶段：理解全异步训练（最复杂）

  1. fully_async_policy/01_fully_async_main.md - 全异步入口与架构
  2. fully_async_policy/05_message_queue.md - 消息队列
  3. fully_async_policy/06_param_sync.md - 参数同步
  4. fully_async_policy/02_fully_async_trainer.md - 异步训练器
  5. fully_async_policy/03_fully_async_rollouter.md - 异步推理器
  6. fully_async_policy/04_detach_utils.md - 数据处理工具
  7. fully_async_policy/agent_loop/02_agent_loop.md - 全异步 Agent 循环
  8. fully_async_policy/agent_loop/03_partial_tool_agent_loop.md - 可中断恢复的工具调用

第六阶段：推理引擎适配

  1. fully_async_policy/vllm_rollout/01_vllm_async_server.md - vLLM 适配
  2. fully_async_policy/sglang_rollout/01_sglang_async_server.md - SGLang 适配

关键设计模式

1. 注册模式（Registry Pattern）

Agent 循环通过 @register("name") 装饰器注册，支持通过 Hydra 配置动态选择：

@register("single_turn")
class SingleTurnAgentLoop(AgentLoopBase):
    ...

@register("tool")
class ToolAgentLoop(AgentLoopBase):
    ...

2. 状态机模式（State Machine）

ToolAgentLoop 使用显式状态机管理多轮对话：

PENDING → GENERATING → PROCESSING_TOOLS → GENERATING → ... → TERMINATED

3. 分层管理模式

AgentLoopManager          # 管理多个 Worker
  └── AgentLoopWorker     # 管理推理服务器 + Agent 循环
        ├── AsyncLLMServerManager  # 管理 vLLM/SGLang 服务器
        └── AgentLoopBase          # 执行具体的生成逻辑

4. 生产者-消费者模式

全异步训练中，Rollouter 生产样本放入 MessageQueue，Trainer 消费样本进行训练：

Rollouter → MessageQueue → Trainer
    ↑                         │
    └── ParameterSynchronizer ←┘

前置知识

阅读本模块前，建议了解以下概念：

  • PPO（近端策略优化）：RLHF 中最常用的强化学习算法
  • Ray：分布式计算框架，用于管理多节点的 Worker
  • asyncio：Python 异步编程框架
  • vLLM / SGLang：高性能 LLM 推理引擎
  • FSDP / Megatron：分布式训练框架
  • NCCL：NVIDIA 的 GPU 间通信库

文件统计

子目录 文件数 说明
agent_loop/ 7 Agent 循环核心框架
dataset/ 2 数据采样抽象
dynamic_dataset/ 2 动态数据生成
fully_async_policy/ 16 全异步训练（含子目录）
one_step_off_policy/ 6 一步离策略训练（含子目录）
总计 34 （含 __init__.py）