Verifiers：用于训练大语言模型的强化学习环境工具库

Verifiers 是一个用于创建强化学习（RL）环境和训练大语言模型（LLM）代理的模块化组件库。 这个项目的目标是提供一套可靠的工具，让开发者可以方便地构建、训练和评估LLM代理。 Verifiers 包含一个基于 transformers Trainer 实现的异步 GRPO（Generalized Reinforcement Learning with Policy Optimization）训练器，并且得到了 prime-rl 项目的支持，可用于大规模 FSDP（Fully Sharded Data Parallel）训练。 除了强化学习训练，Verifiers 也可以直接用于构建 LLM 评估、创建合成数据管道和实现代理控制程序。 该项目旨在成为一个可靠的工具包，尽量减少在强化学习基础设施生态系统中常见的“代码库分叉泛滥”问题，为开发者提供一个稳定的开发基础。

功能列表

• 模块化环境组件: 提供了一套用于构建强化学习环境的模块化组件，使环境的创建和定制更加简单。
• 多种环境类型支持:
  • SingleTurnEnv: 适用于每个提示只需要模型单次响应的任务。
  • ToolEnv: 支持利用模型原生的工具或函数调用能力，构建代理循环。
  • MultiTurnEnv: 为编写自定义环境交互协议提供了接口，适用于多轮对话或交互式任务。
• 内置训练器: 包含一个 GRPOTrainer，它使用 vLLM 进行推理，支持通过 Accelerate/DeepSpeed 运行 GRPO 风格的强化学习训练。
• 命令行工具: 提供实用命令行工具简化工作流程：
  • vf-init: 初始化一个新的环境模块模板。
  • vf-install: 将环境模块安装到当前项目中。
  • vf-eval: 使用 API 模型快速对环境进行评估。
• 集成与兼容性: 可以轻松集成到任何支持 OpenAI 兼容推理客户端的强化学习框架中，并原生支持与 prime-rl 协同工作，以实现更高效、更大规模的训练。
• 灵活的奖励机制: 通过 Rubric 类封装一个或多个奖励函数，可以为模型生成的完成情况定义复杂的评估标准。

使用帮助

Verifiers 库建议与 uv 包管理器一起在你的项目中使用。

1. 安装

首先，你需要创建一个新的虚拟环境并激活它。

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 初始化一个新项目
uv init
# 激活虚拟环境
source .venv/bin/activate

接下来，根据你的需求安装 Verifiers：

• 本地开发与评估 (CPU): 如果你只使用 API 模型进行开发和评估，安装核心库即可。

  # 安装核心库
  uv add verifiers
  # 如果需要 Jupyter 和测试支持
  uv add 'verifiers[dev]'
  

• GPU 训练: 如果你计划使用 vf.GRPOTrainer 在 GPU 上进行模型训练，需要安装包含所有依赖的版本，并额外安装 flash-attn。

  uv add 'verifiers[all]' && uv pip install flash-attn --no-build-isolation
  

• 使用最新的开发版本: 你也可以直接从 GitHub 的 main 分支安装。

  uv add verifiers @ git+https://github.com/willccbb/verifiers.git
  

• 从源码安装 (核心库开发): 如果你需要修改 Verifiers 核心库，可以从源码安装。

  git clone https://github.com/willccbb/verifiers.git
  cd verifiers
  uv sync --all-extras && uv pip install flash-attn --no-build-isolation
  uv run pre-commit install
  

2. 创建和管理环境

Verifiers 将每个强化学习环境视为一个可安装的 Python 模块。

• 初始化一个新环境: 使用 vf-init 命令创建一个新的环境模板。

  # 创建一个名为 my-new-env 的环境
  vf-init my-new-env
  

  这个命令会在 environments/my-new-env 目录下生成一个包含 pyproject.toml 和基本结构的环境模板。

• 安装环境: 创建后，使用 vf-install 将其安装到你的 Python 环境中，使其可以被导入和使用。

  # 安装本地环境
  vf-install my-new-env
  # 你也可以直接从 verifiers 官方仓库安装示例环境
  vf-install vf-math-python --from-repo
  

3. 使用环境

安装环境后，你可以使用 vf.load_environment 函数加载它，并进行评估或训练。

• 加载环境:

  import verifiers as vf
  # 加载已安装的环境，并传入必要的参数
  vf_env = vf.load_environment("my-new-env", **env_args)
  

• 快速评估环境: 使用 vf-eval 命令可以快速测试你的环境。它默认使用 gpt-4.1-mini 模型，对5个提示各进行3次 rollout。

  # 对名为 my-new-env 的环境进行评估
  vf-eval my-new-env
  

4. 环境的核心元素

一个 Verifiers 环境主要由以下几部分构成：

• 数据集 (Datasets): 一个 Hugging Face 数据集，必须包含一个 prompt 列作为输入。
• 交互逻辑 (Rollout logic): 模型与环境之间的交互方式，例如在 MultiTurnEnv 中定义的 env_response 和 is_completed 方法。
• 评估标准 (Rubrics): 用于封装一个或多个奖励函数，对模型的输出进行评分。
• 解析器 (Parsers): 可选组件，用于封装可重用的解析逻辑。

5. 训练模型

Verifiers 提供了两种主要的训练方式：

• 使用内置的 GRPOTrainer:
  这个训练器适用于在 2-16 个 GPU 上高效训练稠密 Transformer 模型。

  # 步骤1: 启动 vLLM 推理服务器 (shell 0)
  # 假设使用7个GPU进行数据并行
  CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6 vf-vllm --model your-model-name \
  --data-parallel-size 7 --enforce-eager --disable-log-requests
  # 步骤2: 启动训练脚本 (shell 1)
  # 使用剩余的GPU进行训练
  CUDA_VISIBLE_DEVICES=7 accelerate launch --num-processes 1 \
  --config-file configs/zero3.yaml examples/grpo/train_script.py --size 1.7B
  

• 使用 prime-rl (推荐):
  prime-rl 是一个外部项目，它原生支持用 Verifiers 创建的环境，并通过 FSDP 提供了更好的性能和扩展性。 它的配置和用户体验更成熟。

  # 在 prime-rl 的配置文件中指定环境
  # orch.toml
  [environment]
  id = "your-env-name"
  # 启动 prime-rl 训练
  uv run rl \
  --trainer @ configs/your_exp/train.toml \
  --orchestrator @ configs/your_exp/orch.toml \
  --inference @ configs/your_exp/infer.toml
  

应用场景

1. 训练特定任务的智能体
   利用 ToolEnv 或 MultiTurnEnv，开发者可以创建复杂的交互环境，训练 LLM 智能体学习如何使用外部工具（如计算器、搜索引擎）或在多轮对话中完成特定任务（如预订机票、客户支持）。
2. 构建自动化评估流程
   SingleTurnEnv 可以用来构建自动化的评估流程。通过定义一个包含标准答案和评估标准（Rubric）的环境，可以对不同模型的性能进行量化比较，例如评估代码生成任务的正确率或文本摘要的质量。
3. 生成高质量的合成数据
   通过环境交互（rollout）过程，可以生成大量模型与环境交互的数据。这些数据可以被保存为 Hugging Face 数据集，并用于后续的监督微调（SFT）或其他模型的训练，这是一种高效的合成数据生成管道。
4. 学术研究与算法验证
   Verifiers 为强化学习研究者提供了一个模块化、可复现的实验平台。研究人员可以方便地实现新的交互协议、奖励函数或训练算法，并在标准化的环境中验证其有效性。

QA

1. Verifiers 库和 prime-rl 有什么关系？
   prime-rl 是一个独立的训练框架，它原生支持使用 Verifiers 创建的环境。 Verifiers 专注于提供构建 RL 环境的组件，而 prime-rl 则专注于提供一个更强大、性能更优、扩展性更好的 FSDP（完全分片数据并行）训练方案。对于大规模训练，官方推荐使用 prime-rl。
2. 如何为我的环境定义奖励函数？
   你需要在 vf.Rubric 对象中定义一个或多个奖励函数。每个函数接收 prompt、completion 等参数，并返回一个浮点数作为奖励值。你还可以为不同的奖励函数设置不同的权重。
3. 我是否需要自己实现模型的交互逻辑？
   不一定。对于单轮问答和标准工具调用场景，你可以直接使用 SingleTurnEnv 和 ToolEnv。 只有当你的应用需要非常独特的、非标准的交互流程时，才需要继承 MultiTurnEnv 并重写 is_completed 和 env_response 方法。
4. 训练时遇到 NCCL 相关的错误怎么办？
   根据官方文档，vLLM 在同步权重时可能会遇到 GPU 间通信挂起的问题。你可以尝试在环境中设置 NCCL_P2P_DISABLE=1 来解决这个问题。如果问题仍然存在，可以尝试设置 NCCL_CUMEM_ENABLE=1 或向项目提出一个 issue。