Agentic RL 训练
===================

Last updated: 07/15/2025.

概述
----------
Agentic RL 的目标是将强化学习提高后端模型性能，使其应用于 Agent。在训练过程中，开发了一系列功能：

1. 基于服务器的异步 rollout
2. 多轮对话和工具调用
3. 基于 LangGraph 的 Agent


本文档解释了系统原理和使用方法，以帮助用户实现 Agentic RL。


基于服务器的异步 Rollout
---------------------------------

由于 Agent 需要通过各种工具调用与环境交互，为了避免在等待工具调用返回结果期间 GPU 空闲，本系统使用基于 asyncio 的协程机制来异步执行每个 rollout 请求，从而提高训练性能。为支持异步 rollout，推理引擎（服务器）和 Agent（客户端）在架构上分离，实现了一个基于服务器的系统，具有以下目标：

1. 启用负载均衡机制，在多个 GPU 之间平衡负载，并减少长尾请求对性能的影响。为此，将流模式（recipe\stream_mode）中的调度能力实现为一个配方。
2. 防止 Agent 特定功能（如追踪）影响推理引擎。

系统架构
~~~~~~~~~~~~~~~~~~~

.. image:: https://github.com/eric-haibin-lin/verl-community/blob/main/docs/agent_loop.png?raw=true

有关内部设计详情，请参考 :doc:`Agent 循环<../advance/agent_loop>`。

系统组件
~~~~~~~~~~~~~~~~~

+--------------------------+----------------------------------------------------------------------------+
| 组件                     | 角色                                                                       |
+==========================+============================================================================+
| AgentLoop                | 客户端，实现 Agent 功能                                                    |
+--------------------------+----------------------------------------------------------------------------+
| AsyncLLMServerManager    | 推理网关，为 AgentLoop 提供生成接口                                        |
+--------------------------+----------------------------------------------------------------------------+
| AsyncServer              | 服务器，每个实例连接到一个推理引擎的 DP 组                                |
+--------------------------+----------------------------------------------------------------------------+

**"generate" 接口**

在客户端和服务器之间使用基于 ray actor 的 "generate" 函数，而不是标准的聊天完成 API。这是因为 token 到文本的转换可能是不可逆的。例如，从 "<think>" 转换的 token 将不同于 LLM 生成的 token。在训练阶段，必须严格使用 LLM 推理生成的 token，以避免在计算优势时出现不准确，这可能会影响模型性能。服务器提供基于 token 的 API 有助于客户端保持工具调用生成的文本与 LLM 返回的 token 之间的关系，从而输出正确的 token 进行训练。


**推理引擎适配**
AsyncServer 统一向上层提供 generate 函数，为 SGLang 和 vLLM 分别实现以隐藏底层差异：

1. SGLang AsyncServer 使用 SGLang 引擎的 async_generate 接口，该接口位于每个 TP 组的第一个 GPU 上。因此，AsyncServer 需要通过 ray actor 远程调用 async_generate。
2. vLLM AsyncServer 使用 vLLM 引擎的 generate 接口，该接口可以通过 ZMQ 与 TP 组中的 GPU 通信，并在 AsyncServer 中直接调用。


使用示例
~~~~~~~~~~~~~

请按照 :doc:`GSM8K 示例<../examples/gsm8k_example>` 准备数据集和模型检查点。

使用 agent loop 需要两个选项：

- `data.return_raw_chat=True`
- `actor_rollout_ref.rollout.mode=async`

此示例默认使用 sglang 推理引擎，您也可以修改 rollout_name 来使用 vllm。

.. code-block:: bash

    bash examples/grpo_trainer/run_qwen2-7b_seq_balance.sh


多轮对话和工具调用
---------------------------------------

请按照 :doc:`多轮 Rollout 支持<../sglang_multiturn/multiturn>` 准备工具和配置文件。

Tool Agent Loop 有一个额外要求：在数据集中添加一个 "agent_name" 字段。在 rollout 期间，它将根据此字段选择使用 tool_agent_loop 或 single_turn_agent（默认）。

使用示例
~~~~~~~~~~~~~

.. code-block:: bash

    # 安装 mlflow 以查看工具调用和 LLM 追踪
    pip install mlflow

    # 这将下载并预处理 GSM8K 数据集到 ~/data/gsm8k/ 并添加 "agent_name" 字段。
    python examples/data_preprocess/gsm8k_tool_agent_loop.py

    # 使用工具调用开始训练，并启用基于 mlflow 的追踪以帮助调试 rollout 详情
    bash examples/sglang_multiturn/run_qwen2.5-3b_gsm8k_tool_agent_mlflow.sh

    # 训练完成后，启动 mlflow 服务器以查看追踪
    mlflow ui -h 0.0.0.0 -p 5000 --backend-store-uri sqlite:////tmp/mlruns.db

    # 然后，您可以在浏览器中打开 http://<your ip address>:5000 来查看追踪


注意：在训练期间，由于模型有时可能无法生成正确的工具调用标签，会在控制台输出错误消息 "Failed to decode tool call"，这并不表示训练异常。


请按照 :doc:`Rollout 追踪<../advance/rollout_trace>` 了解更多关于追踪功能的信息。



Agent 框架
---------------

系统架构
~~~~~~~~~~~~~~~~~~~

.. image:: https://github.com/eric-haibin-lin/verl-community/blob/main/docs/langgraph_agent.png?raw=true

系统组件
~~~~~~~~~~~~~~~~~

+--------------------------+-----------------------------------------------------------------------------------------------+
| 组件                     | 角色                                                                                          |
+==========================+===============================================================================================+
| ChatModel                | LangChain 的 LLM 对象，用于适配 AsyncLLMServerManager 提供的“generate” api                   |
+--------------------------+-----------------------------------------------------------------------------------------------+
| RectAgentLoop            | Agent 适配层，默认支持一个简单的 LangGraph Agent。                                          |
|                          | 可以派生新类来支持用户定义的 Agent，并需要实现 run 函数来完成 Agent 调用。                 |
+--------------------------+-----------------------------------------------------------------------------------------------+
| AsyncServer              | 服务器，每个实例连接到一个推理引擎的 DP 组。                                                |
+--------------------------+-----------------------------------------------------------------------------------------------+


有关详情，请参考文档 "recipe/langgraph_agent/example/README.md"。