Verl-Tool

VerlTool：基于verl的统一且易于扩展的工具智能体训练框架。

| 论文 | 快速入门 | 训练配方 | DeepWiki | 微信交流群 | Discord |

---

新闻

• [2026/03/01] 🏆 我们的论文已被【ICLR 2026终身智能体研讨会】接收！
• [2025/11/10] VerlTool重新组织了代码库，以提高模块化和可维护性，支持最新的verl（0.6.0）和vllm（0.11.0）版本。更多详情请参阅verl-tool v0.6.0.dev升级说明。
• [2025/09/02] VerlTool的技术报告已发布！详见Hugging Face Daily Paper！
• [2025/06/30] 我们在相同基准上复现了Search-R1，并取得了更高的性能！更多细节请参阅PR和训练README。
• [2025/06/28] 我们支持NL2SQL工具的强化学习训练。更多详情请参阅NL2SQLREADME。
• [2025/06/26] 我们支持DAPO配方的训练。更多详情请参阅DAPO.md。
• [2025/06/18] VerlTool现在正式支持轨迹级别的异步训练，通过工具调用加速了至少2倍的轨迹生成！更多详情请参阅asyncRL.md。
• [2025/06/16] 我们已将verl子模块更新至最新版本（06/16），并修改了一些代码以适配新版本。
• [2025/06/13] 我们为Verl-Tool集成了DeepWiki。欢迎浏览由AI生成的文档，并与Verl-tool代码进行互动。
• [2025/06/06] 我们在README中更新了一篇详细的设计概述，包括如何添加新工具、如何使用工具服务器，以及如何利用verl-tool训练自己的模型。
• [2025/05/31] 我们发布了Verl-tool的训练/评估代码，以ToRL训练作为初始示例（详见X帖子）。我们正在撰写论文，并将于近期发布。

特性

• 🔧 完全解耦演员轨迹生成与环境交互 - 我们将verl作为子模块，以便受益于verl仓库的持续更新。所有工具调用均通过统一的API集成，您只需添加一个Python文件并独立测试，即可轻松添加新工具。
• 🌍 工具即环境范式 - 每次工具交互都会改变环境状态。我们为每条轨迹存储并重新加载环境状态。
• ⚡ 原生工具调用智能体强化学习框架 - verl-tool原生支持智能体与其工具环境之间的多轮交互循环。
• 📊 用户友好的评估套件 - 您可以使用OpenAI API与工具服务器一起启动训练好的模型。只需发送问题，系统便会内部处理所有交互，直接给出最终输出。更多详情请参阅基准测试。

📚 内容链接

• 📖 安装指南
• ⚡ 同步轨迹设计
• 🔄 异步轨迹设计
• 🛠️ 工具服务器设计
• 🎯 训练指南
• 📊 评估指南
• 🔧 更新verl子模块版本
• 📈 现有训练结果
• 🤝 贡献指南

核心贡献者

Dongfu Jiang

Zhuofeng Li

Yi Lu

Zhiheng Lvu

Ping Nie

顾问

Wenhu Chen

Tianyu Pang

Chao Du

致谢

我们感谢以下开源项目使verl-tool成为可能：

• VLLM和SGLang，感谢它们提供的快速大模型推理支持！
• verl，感谢其出色的强化学习框架设计。
• SearchR1、RAGEN和ToRL，感谢它们在工具智能体强化学习训练领域的早期探索。

我们还感谢Netmind.AI、SeaAI Lab和Map，感谢它们提供的GPU支持！

受 Verl-Tool 启发的社区项目

• AgentFlow：在流程中的智能体系统优化

星标历史

徽章

引用

@article{jiang2025verltool,
  title={VerlTool：迈向具备工具使用的整体式智能体强化学习},
  author={Jiang, Dongfu and Lu, Yi and Li, Zhuofeng and Lyu, Zhiheng and Nie, Ping and Wang, Haozhe and Su, Alex and Chen, Hui and Zou, Kai and Du, Chao and others},
  journal={arXiv 预印本 arXiv:2509.01055},
  year={2025}
}

Verl-Tool 快速上手指南

Verl-Tool 是一个基于 verl 的统一且易于扩展的工具智能体（Tool-Agent）训练框架。它原生支持多轮交互式强化学习，实现了 Actor rollout 与环境交互的完全解耦。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 20.04+)
• Python: Python 3.9 - 3.11
• GPU: NVIDIA GPU (支持 CUDA)，建议显存 >= 24GB 以进行高效训练
• 前置依赖:
  • git
  • conda 或 venv (推荐使用 conda 管理环境)

注意：Verl-Tool 强依赖于 verl (RL 框架) 和 vllm (推理引擎)。当前版本支持 verl 0.6.0 和 vllm 0.11.0。

2. 安装步骤

建议使用 Conda 创建独立环境以避免依赖冲突。

第一步：克隆仓库并初始化子模块

Verl-Tool 将 verl 作为子模块管理，因此克隆时必须包含 --recursive 参数。

git clone --recursive https://github.com/TIGER-AI-Lab/verl-tool.git
cd verl-tool

如果已经克隆但未初始化子模块，请执行：

git submodule update --init --recursive

第二步：创建并激活 Conda 环境

conda create -n verl-tool python=3.10 -y
conda activate verl-tool

第三步：安装依赖

安装核心依赖包。由于涉及 CUDA 相关库，请确保您的 CUDA 版本与 PyTorch/vLLM 兼容。

pip install -e .

提示：如果遇到网络问题，可配置 pip 国内镜像源加速下载：

pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

第四步：验证安装

检查关键组件版本是否符合要求：

python -c "import verl; print(verl.__version__)"
python -c "import vllm; print(vllm.__version__)"

确保 verl 版本为 0.6.0 左右，vllm 版本为 0.11.0 左右。

3. 基本使用

Verl-Tool 的核心工作流包括：启动工具服务器、配置训练任务、执行训练。以下以最简单的 ToRL 训练示例为例。

步骤一：了解目录结构

• examples/train/: 包含各种训练食谱（Recipes），如 search_r1, skysql (NL2SQL), dapo 等。
• assets/docs/: 详细的设计文档和指南。

步骤二：运行一个简单的训练示例

假设我们要运行基础的 ToRL 训练示例（具体脚本路径请参考 examples/train 下的实际 README，此处以通用命令结构为例）：

1. 准备数据与配置： 查看 examples/train/torl/ (或类似初始示例目录) 中的配置文件 .yaml。

2. 启动训练： 使用 verl 提供的启动器或直接运行 Python 脚本。通常命令如下：

   # 进入示例目录
   cd examples/train/torl
   
   # 运行训练脚本 (具体脚本名请以实际文件为准，例如 train.py)
   python train.py --config config.yaml
   

   如果是分布式训练，可能需要使用 torchrun 或 ray 启动：

   torchrun --nproc_per_node=8 train.py --config config.yaml
   

步骤三：评估模型

训练完成后，您可以使用内置的评估套件。Verl-Tool 支持通过 OpenAI API 格式与工具服务器交互进行评估。

# 示例：启动评估服务
python evaluate.py --model_path /path/to/saved/model --tool_server_url http://localhost:8000

进阶：添加自定义工具

Verl-Tool 采用“工具即环境”范式。要添加新工具，只需：

1. 在工具注册目录下新建一个 Python 文件。
2. 实现统一的 Tool API 接口。
3. 无需修改核心训练代码，即可自动集成到训练循环中。

更多详细设计请参考 Tool Server Design 和 Training Guide。