Reasoning Gym

🧠 关于

Reasoning Gym 是一个由社区创建的 Python 库，包含程序化数据集生成器和可算法验证的推理环境，用于通过强化学习（RL）训练推理模型。其目标是生成具有可调复杂度的几乎无限量的训练数据。

目前，它提供了 100 多个 涉及多个领域的任务，包括但不限于 代数、算术、计算、认知、几何、图论、逻辑，以及许多常见的 游戏。

有些任务只有一个正确答案，而另一些任务，例如 魔方 和 倒计时，则有多个正确解法。为此，我们提供了一个标准接口来对解决方案进行程序化验证。

🖼️ 数据集图库

在 GALLERY.md 中，您可以找到 reasoning-gym 中所有可用数据集的示例输出。

⬇️ 安装

reasoning-gym 包需要 Python >= 3.10。

通过 pip 从 PyPI 安装最新发布的包：

pip install reasoning-gym

请注意，该项目目前仍在积极开发中，PyPI 上发布的版本可能比 main 分支落后几天。

✨ 快速入门

使用 Reasoning Gym 生成任务非常简单：

import reasoning_gym
data = reasoning_gym.create_dataset('leg_counting', size=10, seed=42)
for i, x in enumerate(data):
    print(f'{i}: q="{x['question']}", a="{x['answer']}"')
    print('metadata:', x['metadata'])
    # 使用数据集的 `score_answer` 方法进行算法验证
    assert data.score_answer(answer=x['answer'], entry=x) == 1.0

输出：

0: q="如果你有 1 只海蛞蝓、1 只鹿，一共有多少条腿？", a="4"
metadata: {'animals': {'sea slug': 1, 'deer': 1}, 'total_legs': 4}
1: q="如果你有 2 只绵羊、2 只狗，一共有多少条腿？", a="16"
metadata: {'animals': {'sheep': 2, 'dog': 2}, 'total_legs': 16}
2: q="如果你有 1 只螃蟹、2 只龙虾、1 名人类、1 头牛、1 只蜜蜂，一共有多少条腿？", a="42"
...

使用关键字参数传递特定于任务的配置值：

reasoning_gym.create_dataset('leg_counting', size=10, seed=42, max_animals=20)

创建包含多种任务类型的复合数据集，并可选择性地设置各任务的相对权重：

from reasoning_gym.composite import DatasetSpec
specs = [
    # 在这里，腿部计数任务将占任务总数的三分之二
    DatasetSpec(name='leg_counting', weight=2, config={}),  // 默认配置
    DatasetSpec(name='figlet_font', weight=1, config={"min_word_len": 4, "max_word_len": 6}),  // 指定配置
]
reasoning_gym.create_dataset('composite', size=10, seed=42, datasets=specs)

对于使用 Reasoning Gym 训练模型最简单的方式，我们建议使用 verifiers 库，该库直接支持 RG 任务。详情请参阅 examples/verifiers。不过，RG 数据也可以与任何主流的 RL 训练框架一起使用。

Cascade Scorer 会依次应用宽松的回退匹配器——字符串、数值和符号数学——以减少因格式差异（如 LaTeX 包裹、大小写、数字表示）导致的假阴性。安装 pip install reasoning-gym[scoring] 即可获得符号数学验证功能。

from reasoning_gym import cascade_score

assert cascade_score(answer=r"\text{42}", expected="42") == 1.0

🔍 评估

运行评估脚本的说明已在 eval/README.md 中提供。

不同推理模型的评估结果将在 reasoning-gym-eval 仓库中跟踪记录。

🤓 训练

training/ 目录包含了我们为论文所进行的 RG 训练实验的完整细节。在我们的实验中，我们使用自定义的数据集代码，在运行时动态生成 RG 样本，并访问 RG 的评分函数作为训练奖励。请参阅 training/README.md 以复现我们的实验。

为了更即插即用的体验，提前构建数据集可能会更容易。请参阅 scripts/hf_dataset/ 中的一个简单脚本，该脚本允许生成 RG 数据并将其转换为 HuggingFace 数据集。要使用该脚本，请在 YAML 文件中构建您的数据集配置。您可以在 数据集图库 中找到任务列表和可配置参数。然后使用所需的参数运行 save_hf_dataset.py。

该脚本会将每个数据集条目保存为一行，包含 question、answer 和 metadata 列。RG 的评分函数期望从每一行中获取条目对象以及模型响应，从而得到奖励值。因此，调用评分函数非常简单：

from reasoning_gym import get_score_answer_fn

for entry in dataset:
    model_response = generate_response(entry["question"])
    rg_score_fn = get_score_answer_fn(entry["metadata"]["source_dataset"])
    score = rg_score_fn(model_response，entry)
    # 对分数做些什么...

👷 贡献

请参阅 CONTRIBUTING.md。

如果您有关于数据集生成器的想法，请在此处创建一个问题，或在 GPU-Mode Discord 服务器 的 #reasoning-gym 频道中与我们联系。

🚀 使用 Reasoning Gym 的项目

以下是基于 Reasoning Gym 构建的一些优秀项目列表：

• Verifiers：在可验证环境中使用 LLM 进行强化学习
• (NVIDIA) ProRL：长期强化学习扩展大型语言模型的推理边界
• (Nous Research) Atropos - 一个 LLM RL Gym
• (PrimeIntellect) SYNTHETIC-2：一个大规模开源推理数据集
• (Gensyn) RL Swarm：一个用于行星尺度协作式强化学习的框架
• (Axon RL) GEM：一个全面的强化学习环境框架
• (Meta FAIR) OptimalThinkingBench：评估 LLM 中的过度思考与不足思考
• (Gensyn) 分享即关怀：通过集体 RL 经验共享实现高效的 LM 后训练
• (MILA) 针对 LLM 推理的自进化课程
• (MILA) 递归式自我聚合解锁大型语言模型中的深度思考
• (NVIDIA) BroRL：通过扩大探索范围来扩展强化学习
• (NVIDIA) Nemotron 3 Super：面向代理式推理的开放、高效混合专家架构 Mamba-Transformer 模型
• (Apple) 多语言推理 Gym：程序化推理环境的多语言扩展

📝 引用

如果您在研究中使用了本库，请引用以下论文：

@misc{stojanovski2025reasoninggymreasoningenvironments,
      title={REASONING GYM：用于具有可验证奖励的强化学习的推理环境},
      author={Zafir Stojanovski 和 Oliver Stanley 和 Joe Sharratt 和 Richard Jones 和 Abdulhakeem Adefioye 和 Jean Kaddour 和 Andreas Köpf},
      year={2025},
      eprint={2505.24760},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2505.24760},
}

⭐️ 星标历史

Reasoning Gym 快速上手指南

Reasoning Gym 是一个用于训练推理模型的 Python 库，它通过程序化生成数据集和算法可验证的推理环境，支持使用强化学习（RL）生成近乎无限的训练数据。目前涵盖代数、算术、逻辑、几何、图论及多种游戏等超过 100 种任务类型。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：>= 3.10
• 前置依赖：无特殊系统级依赖，需确保 pip 可用

💡 国内加速建议：建议使用清华或阿里云镜像源加速安装过程。

安装步骤

通过 pip 安装最新发布的版本：

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

若需要使用符号数学验证功能（cascade scorer），请安装额外依赖：

pip install "reasoning-gym[scoring]" -i https://pypi.tuna.tsinghua.edu.cn/simple

⚠️ 注意：该项目处于活跃开发中，PyPI 版本可能略滞后于 GitHub 主分支。如需最新功能，可从源码安装。

基本使用

1. 生成单一任务数据集

以下示例展示如何生成“数腿”任务的数据集，并进行算法验证：

import reasoning_gym

# 创建数据集：10 条数据，固定随机种子
data = reasoning_gym.create_dataset('leg_counting', size=10, seed=42)

for i, x in enumerate(data):
    print(f'{i}: q="{x["question"]}", a="{x["answer"]}"')
    print('metadata:', x['metadata'])
    
    # 使用内置评分函数进行算法验证
    assert data.score_answer(answer=x['answer'], entry=x) == 1.0

输出示例：

0: q="How many legs are there in total if you have 1 sea slug, 1 deer?", a="4"
metadata: {'animals': {'sea slug': 1, 'deer': 1}, 'total_legs': 4}
1: q="How many legs are there in total if you have 2 sheeps, 2 dogs?", a="16"
metadata: {'animals': {'sheep': 2, 'dog': 2}, 'total_legs': 16}

2. 自定义任务参数

可以通过关键字传递任务特定的配置：

# 限制最大动物数量为 20
reasoning_gym.create_dataset('leg_counting', size=10, seed=42, max_animals=20)

3. 创建复合数据集

组合多个任务类型，并可设置权重和独立配置：

from reasoning_gym.composite import DatasetSpec

specs = [
    # leg_counting 占 2/3 权重，使用默认配置
    DatasetSpec(name='leg_counting', weight=2, config={}),
    # figlet_font 占 1/3 权重，自定义单词长度配置
    DatasetSpec(name='figlet_font', weight=1, config={"min_word_len": 4, "max_word_len": 6}),
]

# 生成包含混合任务的复合数据集
reasoning_gym.create_dataset('composite', size=10, seed=42, datasets=specs)

4. 使用级联评分器（Cascade Scorer）

为减少因格式差异（如 LaTeX、大小写、数字表示）导致的误判，可使用级联评分器：

from reasoning_gym import cascade_score

# 即使答案包含 LaTeX 格式，也能正确匹配
assert cascade_score(answer=r"\text{42}", expected="42") == 1.0

5. 在训练流程中获取奖励分数

若需将生成的数据用于模型训练，可通过以下方式动态获取评分函数：

from reasoning_gym import get_score_answer_fn

for entry in dataset:
    # 假设这是你的模型生成的回答
    model_response = generate_response(entry["question"])
    
    # 根据元数据获取对应的评分函数
    rg_score_fn = get_score_answer_fn(entry["metadata"]["source_dataset"])
    
    # 计算奖励分数
    score = rg_score_fn(model_response, entry)
    
    # 使用 score 进行后续训练逻辑...