verl工具调用实战：代码执行+搜索全集成

verl工具调用实战：代码执行+搜索全集成

1. 引言：构建具备外部能力的智能代理

在当前大模型后训练（post-training）技术快速发展的背景下，如何让语言模型具备与外部世界交互的能力，成为提升其实际应用价值的关键。传统的监督微调（SFT）和基于人类反馈的强化学习（RLHF）主要聚焦于文本生成质量优化，但难以支持复杂任务中的动态信息获取与可执行逻辑验证。

verl是由字节跳动火山引擎团队开源的强化学习训练框架，专为大型语言模型（LLMs）设计，是 HybridFlow 论文的官方实现。它不仅提供了高效的分布式训练能力，更重要的是，内置了对多轮对话 RL 训练、工具调用（Tool Calling）和安全代码执行环境（Sandbox Fusion）的原生支持，使得开发者可以轻松构建具备“行动力”的智能代理系统。

本文将围绕verl框架中工具调用的核心能力展开，重点实践以下两个关键场景：

• 代码执行：通过 Sandbox Fusion 在隔离环境中运行 Python 代码并返回结果
• 搜索增强：集成检索服务实现外部知识查询，并用于多轮推理决策

最终目标是展示如何利用verl构建一个能够自主调用工具、结合实时数据进行推理的强化学习智能体。

2. 工具调用架构解析：从定义到执行流程

2.1 统一的工具抽象接口

verl中所有工具均继承自BaseTool抽象类，遵循 OpenAI 函数调用标准，确保接口一致性与扩展性。核心方法如下：

class BaseTool: async def create(self, instance_id: Optional[str] = None, **kwargs) -> tuple[str, ToolResponse]: pass @rollout_trace_op async def execute(self, instance_id: str, parameters: dict[str, Any], **kwargs) -> tuple[ToolResponse, float, dict]: pass async def calc_reward(self, instance_id: str, **kwargs) -> float: pass async def release(self, instance_id: str, **kwargs) -> None: pass

该设计实现了工具生命周期的完整管理：创建 → 执行 → 奖励计算 → 资源释放，适用于强化学习训练中的多轮交互场景。

2.2 工具注册与配置机制

工具通过 YAML 配置文件集中管理，便于模块化部署和动态加载。以代码解释器为例：

tools: - class_name: "verl.tools.sandbox_fusion_tools.SandboxFusionTool" config: sandbox_fusion_url: "https://api.sandbox-fusion.example.com/run_code" num_workers: 10 enable_global_rate_limit: true rate_limit: 10 default_timeout: 30 default_language: "python" memory_limit_mb: 1024 tool_schema: type: "function" function: name: "code_interpreter" description: "Execute code in a secure sandbox environment." parameters: type: "object" properties: code: type: "string" description: "The code to execute." required: ["code"]

此配置声明了一个名为code_interpreter的工具，允许 LLM 在生成响应时请求执行任意 Python 代码片段。

2.3 多轮对话中的工具调用流程

当启用多轮对话训练时，verl支持最大 5 轮助手回复（max_assistant_turns: 5），并在每一轮中判断是否需要调用工具：

actor_rollout_ref: rollout: name: sglang multi_turn: enable: True max_assistant_turns: 5 tool_config_path: "./config/tool_config/gsm8k_tool_config.yaml"

整个流程如下：

1. 用户输入问题（如数学题）
2. 模型生成包含tool_call的响应
3. 系统识别并调度对应工具执行
4. 将执行结果作为上下文回传给模型
5. 模型基于新信息继续推理或给出最终答案

这种闭环机制显著提升了复杂任务的解决成功率。

3. 实战一：安全代码执行 —— Sandbox Fusion 集成

3.1 Sandbox Fusion 核心特性

Sandbox Fusion 是verl提供的安全代码执行解决方案，具备以下关键能力：

3.2 配置与初始化

首先确保已正确安装verl并验证版本：

python -c "import verl; print(verl.__version__)" # 输出示例：0.1.0

然后配置sandbox_fusion_tool.yaml文件，指定 API 地址和资源策略。

3.3 工具调用示例：数学表达式求解

假设我们正在处理 GSM8K 数学数据集中的题目：“某商店每天卖出 25 个苹果，每个售价 4 元；另卖出 10 根香蕉，每根 2 元。求一天总收入。”

模型可能生成如下工具调用请求：

{ "name": "code_interpreter", "arguments": { "code": "apple_revenue = 25 * 4\nbanana_revenue = 10 * 2\ntotal_revenue = apple_revenue + banana_revenue\nprint(total_revenue)" } }

Sandbox Fusion 接收到请求后，在隔离环境中执行代码，返回结果：

{ "status": "success", "stdout": "120", "stderr": "", "execution_time": 0.12 }

该结果将被注入对话历史，供模型生成最终回答：“一天的总收入是 120 元。”

3.4 自定义错误处理与重试逻辑

为提高鲁棒性，可在客户端添加重试机制：

import time import requests from typing import Dict, Any def call_sandbox_with_retry( url: str, code: str, language: str = "python", max_retries: int = 3, timeout: int = 30 ) -> Dict[Any, Any]: payload = { "code": code, "language": language, "run_timeout": timeout, "memory_limit_MB": 1024 } for attempt in range(max_retries): try: response = requests.post(url, json=payload, timeout=timeout) if response.status_code == 200: result = response.json() if result["status"] == "success": return result else: print(f"Execution failed: {result.get('stderr')}") elif response.status_code in [502, 503, 504]: print(f"Server error, retrying... ({attempt + 1}/{max_retries})") time.sleep(1 * (attempt + 1)) continue except requests.RequestException as e: print(f"Request failed: {e}, retrying...") time.sleep(1 * (attempt + 1)) raise RuntimeError("Failed to execute code after retries.")

此函数实现了网络异常和执行失败的自动重试，保障训练稳定性。

4. 实战二：搜索工具集成 —— 外部知识增强推理

4.1 搜索工具设计原理

对于依赖最新或特定领域知识的问题（如天气、股价、新闻事件），仅靠预训练知识无法准确作答。verl提供SearchTool类，支持对接任意检索服务 API。

典型应用场景包括：

• 实时信息查询（“今天北京气温多少？”）
• 事实核查（“马斯克何时收购 Twitter？”）
• 数据支撑决策（“特斯拉最近三个季度营收对比”）

4.2 搜索工具配置示例

tools: - class_name: "verl.tools.search_tool.SearchTool" config: retrieval_service_url: "https://api.retrieval.example.com/search" num_workers: 120 rate_limit: 120 timeout: 30 topk: 3 tool_schema: name: "web_search" description: "Search the web for up-to-date information." parameters: type: "object" properties: query_list: type: "array" items: { "type": "string" } description: "List of search queries." required: ["query_list"]

4.3 协同工作流：搜索 + 代码执行

许多复杂任务需结合搜索与计算能力。例如：

“查找苹果公司过去三年的净利润，并计算年均增长率。”

第一步：发起搜索请求

{ "name": "web_search", "arguments": { "query_list": ["Apple Inc net profit last 3 years"] } }

返回结构化数据（模拟）：

{ "results": [ {"year": 2021, "net_profit": 94.67}, {"year": 2022, "net_profit": 99.80}, {"year": 2023, "net_profit": 97.00} ] }

第二步：生成分析代码并执行

模型提取数据后，调用code_interpreter进行计算：

profits = [94.67, 99.80, 97.00] cagr = ((profits[-1] / profits[0]) ** (1/2) - 1) * 100 print(f"CAGR: {cagr:.2f}%")

执行结果：CAGR: 1.21%

第三步：生成自然语言回答

“根据数据显示，苹果公司过去三年的净利润分别为 94.67B、99.80B 和 97.00B 美元，年均复合增长率约为 1.21%。”

这一完整链条展示了verl如何支持跨工具协作的复杂推理任务。

4.4 性能优化：并发控制与连接池

为应对高频搜索请求，verl使用 Ray 分布式框架实现高效并发管理：

@ray.remote(concurrency_groups={"acquire": 1, "release": 10}) class TokenBucketWorker: def __init__(self, rate_limit: int): self.rate_limit = rate_limit self._semaphore = threading.Semaphore(rate_limit) @ray.method(concurrency_group="acquire") def acquire(self): self._semaphore.acquire() @ray.method(concurrency_group="release") def release(self): self._semaphore.release()

同时使用 HTTP 连接池减少 TCP 握手开销：

import requests class SearchClient: def __init__(self, base_url: str, pool_connections: int = 50): self.session = requests.Session() adapter = requests.adapters.HTTPAdapter( pool_connections=pool_connections, pool_maxsize=pool_connections ) self.session.mount("http://", adapter) self.session.mount("https://", adapter) self.base_url = base_url

这些优化显著提升了大规模训练中的工具调用吞吐量。

5. 多模态与工具调用的融合潜力

尽管本文聚焦于文本+工具调用场景，但verl同样支持视觉语言模型（VLM）的强化学习训练。结合图像理解与工具调用，可实现更强大的多模态代理能力。

例如，在 Geometry3K 几何题数据集中，模型可：

1. 解析图像中的图形结构
2. 调用code_interpreter执行几何公式计算
3. 利用web_search查阅定理证明
4. 最终输出图文并茂的答案

此类系统的训练配置需启用多模态字段：

data: image_key: "images" train_batch_size: 512 max_prompt_length: 1024 max_response_length: 2048 model: path: "Qwen/Qwen2.5-VL-7B-Instruct" rollout: name: "vllm" engine_kwargs: vllm: disable_mm_preprocessor_cache: true

未来，随着 VLM 与工具调用的深度融合，verl有望成为构建通用人工智能代理的核心基础设施之一。

6. 总结

本文深入探讨了verl框架在工具调用方面的核心能力与工程实践，重点完成了以下内容：

1. 架构理解：解析了verl的工具抽象机制与多轮对话集成方式；
2. 代码执行实战：实现了基于 Sandbox Fusion 的安全代码执行流程，并加入重试与错误处理；
3. 搜索工具集成：展示了如何对接外部检索服务，并与代码执行协同完成复杂推理；
4. 性能优化建议：提出了并发控制、连接池、缓存等提升系统效率的方法；
5. 多模态展望：指出了工具调用与视觉语言模型结合的广阔前景。

verl通过模块化设计和生产级优化，降低了构建具备“行动能力”智能代理的技术门槛。无论是数学推理、数据分析还是实时问答，开发者均可基于其灵活的 API 快速搭建高性能的强化学习系统。

对于希望探索 AI Agent 落地路径的研究者和工程师而言，verl不仅是一个训练框架，更是一套完整的智能代理生态系统。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。