跳转至

verl/tools 模块总览

模块概述

verl/tools 模块是 verl 框架的工具系统，让 LLM 在强化学习训练过程中能够调用外部工具（如搜索引擎、代码执行器、数学评分器等）。这是实现 Tool-augmented RL（工具增强强化学习）的核心组件。

为什么需要工具系统？

在传统的 RL 训练中，LLM 只能生成文本。但在实际应用中，LLM 可能需要： - 搜索外部知识来回答问题（如 DeepSeek-R1） - 执行代码来验证计算结果 - 放大图片来看清细节 - 提交答案来获取即时反馈

工具系统为 LLM 提供了这些能力，并在训练中通过奖励信号引导 LLM 学会正确使用工具。

模块架构

verl/tools/
├── __init__.py                    # 包初始化（空）
├── schemas.py                     # 数据模式定义（OpenAI 格式）
├── base_tool.py                   # 工具抽象基类
├── mcp_base_tool.py               # MCP 工具基类
├── gsm8k_tool.py                  # GSM8K 数学题工具
├── geo3k_tool.py                  # Geometry3K 几何题工具
├── sandbox_fusion_tools.py        # 沙箱代码执行工具
├── search_tool.py                 # 搜索工具（直接 HTTP）
├── mcp_search_tool.py             # 搜索工具（MCP 协议）
├── image_zoom_in_tool.py          # 图片放大工具
└── utils/
    ├── __init__.py                # 子包初始化（空）
    ├── tool_registry.py           # 工具注册中心（配置加载）
    ├── search_r1_like_utils.py    # 搜索 API 调用工具函数
    └── mcp_clients/
        ├── McpClientManager.py    # MCP 客户端管理器
        └── utils.py               # 令牌桶 + 格式转换

类继承关系

BaseTool
├── SandboxFusionTool     （代码执行）
├── SearchTool            （HTTP 搜索）
├── Gsm8kTool             （数学题评分）
├── Geo3kTool             （几何题评分）
├── ImageZoomInTool       （图片放大）
└── MCPBaseTool           （MCP 工具基类）
    └── MCPSearchTool     （MCP 搜索）

建议阅读顺序

  1. schemas.py - 理解工具系统的数据格式
  2. base_tool.py - 理解工具的生命周期和接口
  3. gsm8k_tool.py - 最简单的工具实现示例
  4. geo3k_tool.py - 另一个简单示例，与 gsm8k 对比
  5. sandbox_fusion_tools.py - 理解 Ray 并发框架和代码执行
  6. search_tool.py - 理解搜索工具和并发框架的复用
  7. utils/search_r1_like_utils.py - 搜索的底层实现
  8. mcp_base_tool.py - 理解 MCP 协议的工具调用
  9. mcp_search_tool.py - MCP 工具的具体实现
  10. utils/mcp_clients/utils.py - MCP 工具函数
  11. utils/mcp_clients/McpClientManager.py - MCP 客户端管理
  12. image_zoom_in_tool.py - 多模态工具
  13. utils/tool_registry.py - 工具的配置和注册
  14. __init__.py / utils/__init__.py - 包初始化

核心概念

工具生命周期

create() → execute() (可多次) → calc_reward() → release()

两种工具类型

  • Native：代码直接运行在 verl 进程中
  • MCP：通过 MCP 协议调用远程服务

并发控制

通过 Ray Actor 实现的令牌桶速率限制 + 执行池，支持高并发的工具调用。

文档列表

文件 讲解文档
__init__.py init.md
schemas.py schemas.md
base_tool.py base_tool.md
mcp_base_tool.py mcp_base_tool.md
gsm8k_tool.py gsm8k_tool.md
geo3k_tool.py geo3k_tool.md
sandbox_fusion_tools.py sandbox_fusion_tools.md
search_tool.py search_tool.md
mcp_search_tool.py mcp_search_tool.md
image_zoom_in_tool.py image_zoom_in_tool.md
utils/__init__.py utils/init.md
utils/tool_registry.py utils/tool_registry.md
utils/search_r1_like_utils.py utils/search_r1_like_utils.md
utils/mcp_clients/McpClientManager.py utils/mcp_clients/McpClientManager.md
utils/mcp_clients/utils.py utils/mcp_clients/utils.md