base_tool.py`¶

文件路径¶

verl/tools/base_tool.py

文件概述¶

BaseTool 是 verl 工具系统的抽象基类，定义了所有工具必须实现的接口。它规定了工具的完整生命周期：创建 -> 执行 -> 计算奖励 -> 释放。所有具体工具（如搜索工具、代码执行工具、数学题工具等）都继承自这个类。

核心思想：在强化学习训练中，LLM 需要与外部工具交互。每次交互就是一个"轨迹"（trajectory），工具需要为每个轨迹创建独立实例、执行操作、计算奖励信号、最后释放资源。

关键代码讲解¶

1. 构造函数¶

class BaseTool:
    def __init__(self, config: dict, tool_schema: OpenAIFunctionToolSchema):
        self.config = config
        self.tool_schema = tool_schema or self.get_openai_tool_schema()
        assert self.tool_schema is not None, "Tool schema is not set!"
        self.name = self.tool_schema.function.name
        print(json.dumps(self.tool_schema.model_dump(exclude_unset=True, exclude_none=True), indent=2))

config：工具的配置字典，如超时时间、速率限制等。
tool_schema：工具的 OpenAI 格式描述，告诉 LLM 这个工具叫什么、接受什么参数。
构造时会打印工具 schema 的 JSON 表示，方便调试。

2. 创建工具实例¶

async def create(self, instance_id: Optional[str] = None, **kwargs) -> tuple[str, ToolResponse]:
    if instance_id is None:
        return str(uuid4()), ToolResponse()
    else:
        return instance_id, ToolResponse()

为一条轨迹创建一个工具实例。每个实例有唯一的 instance_id（默认用 UUID 生成）。返回实例 ID 和一个空的 ToolResponse。

3. 执行工具¶

@rollout_trace_op
async def execute(self, instance_id: str, parameters: dict[str, Any], **kwargs) -> tuple[ToolResponse, float, dict]:
    return ToolResponse(text="Updated the tool state."), 0.0, {}

执行工具操作。三个返回值： - ToolResponse：工具返回给 LLM 的文本/图片/视频响应。 - float：这次操作的即时奖励分数（step reward）。 - dict：额外的度量指标（metrics）。

@rollout_trace_op 装饰器用于追踪工具调用的执行轨迹，方便调试和可视化。

4. 计算奖励¶

async def calc_reward(self, instance_id: str, **kwargs) -> float:
    return 0.0

计算工具的最终奖励。这个奖励可能基于工具的内部状态（比如数学题是否答对了）。

5. 释放实例¶

async def release(self, instance_id: str, **kwargs) -> None:
    pass

清理工具实例占用的资源。在轨迹结束后调用。

工具的完整生命周期¶

┌─────────────┐
│   create()  │  为一条轨迹创建工具实例
└──────┬──────┘
       │
       v
┌─────────────┐
│  execute()  │  LLM 调用工具，执行操作（可多次调用）
└──────┬──────┘
       │
       v
┌──────────────┐
│ calc_reward()│  计算这条轨迹的最终奖励
└──────┬───────┘
       │
       v
┌─────────────┐
│  release()  │  释放资源
└─────────────┘

核心类/函数列表¶

类/方法	作用
`BaseTool`	工具抽象基类
`__init__`	初始化工具配置和 schema
`get_openai_tool_schema`	返回工具的 OpenAI 格式描述
`create`	创建工具实例
`execute`	执行工具操作
`calc_reward`	计算奖励
`release`	释放实例资源

与其他模块的关系¶

被具体工具继承：SandboxFusionTool、SearchTool、Gsm8kTool、Geo3kTool、ImageZoomInTool 都继承 BaseTool。
被 MCPBaseTool 继承：MCP 工具的基类也继承自 BaseTool。
依赖 schemas.py：使用 OpenAIFunctionToolSchema 和 ToolResponse。
依赖 rollout_trace：使用 @rollout_trace_op 装饰器追踪执行。

小结¶

BaseTool 定义了 verl 工具系统的核心接口和生命周期。理解这个类是理解整个工具系统的基础——所有具体工具都是这个模板的具体实现。

base_tool.py — verl/tools/base_tool.py¶