🚀 快速入门

请从下方选择一个示例开始。每个示例都包含详细的安装、训练和推理步骤。

任务	描述	性能
LLM 单轮数学	数学问题求解	wandb
LLM 多轮数学	带工具调用的多轮数学问题求解	wandb
LLM 单LoRA单轮数学	使用LoRA微调的数学单轮模型	wandb
VLM 单轮数学	几何3k数学问题求解	wandb
VLM 多轮数学	带工具调用的几何3k数学问题求解	wandb
LLM 五子棋智能体	一个多轮五子棋智能体	wandb
LLM AlfWorld 智能体	一个多轮AlfWorld智能体	wandb
LLM Android World 智能体	一个多轮Android World智能体

📦 安装

🔹 常规设置（客户端与服务器）

克隆仓库

git clone --recurse-submodules https://github.com/open-tinker/OpenTinker.git
cd OpenTinker

安装 OpenTinker

pip install -e .

安装 verl（核心包）

cd verl
pip install -e .
cd ..

💻 客户端设置

完成常规设置后，无需额外步骤。

注意 目前客户端依赖于 verl 的一小部分功能。这种依赖是过渡性的。在未来的版本中，客户端将完全脱离 verl，从而保持完全轻量级，并且独立于训练相关代码。

🧠 服务器设置

除了常规设置外，还需要安装 verl 的依赖项。

您可以选择以下两种方式之一。

方案 1：Docker 安装（推荐）

# 拉取 verl Docker 镜像
docker pull verlai/verl@sha256:3ce56ff018516b28ab9c4f4fc09d3aa67589074495ace75e2674b720aa4d0e5d

# 创建并运行容器
docker run -dit \
  --gpus all \
  --restart=no \
  --entrypoint /bin/bash \
  --net=host \
  --shm-size=10g \
  --cap-add=SYS_ADMIN \
  -v .:/workspace/dev \
  --name tinker \
  verlai/verl@sha256:3ce56ff018516b28ab9c4f4fc09d3aa67589074495ace75e2674b720aa4d0e5d

方案 2：手动安装

您可以手动安装 verl 的依赖项。完成常规设置后，运行：

cd verl
pip install -r requirements.txt
cd ..

这将安装服务器所需的所有 GPU 和训练相关依赖。

⚠️ 警告 手动安装可能会引入版本冲突。为了更好的稳定性和可重复性，我们建议尽可能使用基于 Docker 的设置。

🔐 认证

OpenTinker 内置了一个认证系统，用于保护调度器 API 的访问安全。

配置

编辑 opentinker/scheduler/config/scheduler.yaml:

enable_auth: true # 设置为 true 启用认证，false 禁用认证。
user_db_path: "scheduler_users.db"

快速注册

运行交互式脚本以注册用户并获取 API 密钥：

python opentinker/scheduler/register_user_example.py

有关高级用法（REST API 注册、密钥使用）及详细配置，请参阅 调度器与仪表板指南。

🎮 环境

OpenTinker 提供了一个灵活的环境设计框架，支持多种训练场景。我们的架构包含两个正交维度：

• 数据源：数据依赖型 环境加载结构化数据集（如 parquet 文件）以提供提示，而 无数据型 环境则从模拟器或游戏引擎动态生成提示。
• 交互模式：单轮 环境涉及一次性模型响应，而 多轮 环境则允许通过工具调用和反馈循环进行迭代交互。

这种 2×2 的设计空间产生了四种不同的范式，每种范式都适用于不同的学习目标：

范式	数据源	交互	示例用例
数据依赖 × 单轮	数据集	一次完成	数学推理、问答任务
数据依赖 × 多轮	数据集	迭代进行	工具辅助的问题解决
无数据 × 单轮	模拟器	一次完成	区块机
无数据 × 多轮	模拟器	迭代进行	复杂游戏玩法、对话智能体

📚 文档

• 调度器与仪表板指南 - 配置、使用及 Web 仪表板

📖 引用

@misc{zhu2026opentinkerseparatingconcernsagentic,
      title={OpenTinker：在智能体强化学习中分离关注点}, 
      author={朱思琪和游家轩},
      year={2026},
      eprint={2601.07376},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2601.07376}, 
}

OpenTinker 快速上手指南

OpenTinker 是一个旨在 democratizing（普及化）智能体强化学习（Agentic RL）的开源框架，支持从单轮数学推理到多轮工具调用、游戏代理等多种场景。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 20.04+) 或 macOS。
• Python: 版本 3.9 或更高。
• Git: 用于克隆代码库。
• GPU (可选但推荐): 如果运行服务端训练任务，需要 NVIDIA GPU 及对应的 CUDA 驱动。
• Docker (推荐): 用于服务端部署，以避免依赖冲突。

2. 安装步骤

2.1 克隆代码库

使用以下命令克隆项目及其子模块：

git clone --recurse-submodules https://github.com/open-tinker/OpenTinker.git
cd OpenTinker

2.2 安装核心依赖

首先安装 OpenTinker 主包：

pip install -e .

接着安装核心强化学习包 verl：

cd verl
pip install -e .
cd ..

提示: 国内用户若遇到 pip 下载缓慢，可添加清华源加速： pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

2.3 服务端环境配置（二选一）

如果您仅作为客户端使用（调用已有服务），完成上述步骤即可。若需搭建服务端进行训练，请选择以下一种方式：

方案 A：Docker 部署（推荐）

此方式能确保环境一致性，避免版本冲突。

# 拉取预构建的 verl 镜像
docker pull verlai/verl@sha256:3ce56ff018516b28ab9c4f4fc09d3aa67589074495ace75e2674b720aa4d0e5d

# 启动容器
docker run -dit \
  --gpus all \
  --restart=no \
  --entrypoint /bin/bash \
  --net=host \
  --shm-size=10g \
  --cap-add=SYS_ADMIN \
  -v .:/workspace/dev \
  --name tinker \
  verlai/verl@sha256:3ce56ff018516b28ab9c4f4fc09d3aa67589074495ace75e2674b720aa4d0e5d

方案 B：手动安装

直接在宿主机安装所有 GPU 和训练相关依赖（可能存在版本冲突风险）：

cd verl
pip install -r requirements.txt
cd ..

3. 基本使用

3.1 配置认证（可选）

OpenTinker 内置了调度器 API 的认证系统。如需启用，请编辑配置文件 opentinker/scheduler/config/scheduler.yaml：

enable_auth: true
user_db_path: "scheduler_users.db"

然后运行脚本注册新用户并获取 API Key：

python opentinker/scheduler/register_user_example.py

3.2 运行示例任务

OpenTinker 提供了多种预设任务示例，涵盖数学解题、游戏代理等场景。您可以根据需求选择以下任一任务开始体验（以单轮数学解题为例）：

1. 查看文档: 参考 docs/math_singleturn.md 获取详细参数说明。
2. 执行训练/推理: 根据文档中的命令行指引启动任务。

其他可用任务包括：

• 多轮数学解题 (带工具调用): docs/math_multiturn.md
• LoRA 微调数学任务: docs/math_lora_singleturn.md
• 视觉语言模型 (VLM) 几何解题: docs/vlm_geo3k_singleturn.md
• 五子棋智能体: docs/gomoku_multiturn.md
• AlfWorld 家庭任务代理: docs/alfworld_multiturn.md

每个示例文档均包含了完整的设置、训练和推理步骤。建议初学者从 LLM Single-Turn Math 入手，快速验证环境可用性。