ART 项目贡献开发与 GPU 训练实战指南：从 prek 质量检查到 2048 强化学习示例

ART 项目贡献开发与 GPU 训练实战指南：从 prek 质量检查到 2048 强化学习示例

【免费下载链接】ARTAgent Reinforcement Trainer: train multi-step agents for real-world tasks using GRPO. Give your agents on-the-job training. Reinforcement learning for Qwen3.6, GPT-OSS, Llama, and more!项目地址: https://gitcode.com/GitHub_Trending/art32/ART

本篇指南基于 ART（Agent Reinforcement Trainer）仓库的 CONTRIBUTING.md 展开，系统讲解参与该项目开发所需的完整链路：从克隆仓库、使用uv安装依赖，到通过prek工具链完成 lint/格式化/类型检查/单测等提交前质量门槛，再到 CI 中如何用指纹化的 uv 缓存加速依赖安装、如何走通 patch/minor/major 三种语义化版本的发布流程，以及最重要的——如何在本地或云端 GPU 机器上把 2048 强化学习示例真正跑起来（含 SSH/VSCode 远程开发、.env配置、wandb 监控与集群清理）。读完你既能通过 ART 的 CI 质量闸门，也能独立完成一次从提交到发布的完整贡献闭环，并上手其 GRPO 训练示例。

一、环境准备：克隆仓库与 uv 依赖安装

ART 是一个 Python 库项目（包名为openpipe-art，要求 Python >= 3.12，见 pyproject.toml），依赖管理统一采用 uv。第一步是克隆仓库并同步依赖：

git clone https://github.com/OpenPipe/ART.git cd ART

提示：以上 URL 是原文档中的公开仓库地址。当前仓库根目录还提供 requirements/backend.vcs.txt 等额外依赖清单，供后端相关开发参考。

安装依赖时，使用--group dev把开发工具链一并装入：

uv sync --group dev

从 pyproject.toml 可以看到dev依赖组包含：ruff（lint/格式化）、pytest与pytest-xdist（并行测试）、nbval（notebook 校验）、ty（类型检查，即文档所述 pyright 的替代/演进版本）、prek（本地检查编排器）、duckdb/pyarrow（轨迹数据处理）以及skypilot（云集群管理，用于下文 GPU 训练）。因此这条命令不仅安装运行库，还一次性配齐了开发、测试与云编排所需的环境。

另外，uv sync会依据 uv.lock 锁定版本，项目同时要求uv版本不低于 0.11.7（见 pyproject.toml）。

二、代码质量检查：prek 工具链

ART 的提交前质量门槛由 prek）中自动执行。

2.1 安装 git hooks（可选）

uv run prek install

安装后，提交代码时相关检查会自动触发，避免把低质量问题带进 PR。

2.2 全量检查与单钩子执行

一次跑完所有检查：

uv run prek run --all-files

也可以单独运行某个钩子，便于针对性地修复问题：

uv run prek run ruff uv run prek run ruff-format uv run prek run pyright uv run prek run uv-lock-check uv run prek run pytest

各钩子职责对照：

对照 CI 中的实际执行命令（.github/workflows/prek.yml）可以发现，CI 依次运行ruff、ruff-format、ty、uv-lock-check，再分别执行 Megatron 轻量测试与tests/unit全量单测，且单测采用--nbval模式同时校验 notebook。如果你的 PR 在 CI 中失败，就在本地重跑对应的 prek 钩子并提交修复，这是文档明确建议的排障闭环。

三、CI 性能工程：指纹化 uv 缓存

ART 的依赖链很重（torch、vLLM、Megatron 等），若每次 CI 都从零解析安装会非常耗时。项目采用"预构建 uv 缓存"方案：把完整的 uv 缓存打包成 GitHub Release 资产，CI 启动时直接解压复用。

3.1 缓存指纹机制

缓存是否命中由指纹决定。指纹由 scripts/ci/compute_uv_fingerprint.py 计算，其输入包括：

• 根 pyproject.toml 与 uv.lock 的 SHA-256；
• Megatron 运行时子项目 megatron_runtime/pyproject.toml 与 megatron_runtime/uv.lock 的 SHA-256；
• CI 基础镜像（默认pytorch/pytorch:2.9.0-cuda12.8-cudnn9-devel）、Python 版本（3.12）、TORCH_CUDA_ARCH_LIST（默认 9.0）等构建上下文。

任何一项变化都会导致指纹变化，CI 随即判定缓存未命中并重建。当前版本指纹结构中还带有fingerprint_schema_version = 12之类的方案版本号，说明这一缓存契约是随项目演进持续迭代的。

3.2 CI 中的缓存流程

在 .github/workflows/prek.yml 中：

1. cache-status任务先计算期望指纹，并通过 scripts/ci/github_release_assets.py 查询 Release 资产，判断是否已存在完整分片集；
2. 若未命中，build-cache任务在 CUDA 基础镜像容器内调用 scripts/ci/build_and_push_uv_cache.sh 重新构建并上传缓存；
3. quality-checks任务并行下载分片、解压到UV_CACHE_DIR，随后执行 prek 各钩子。

这意味着依赖变更后的第一次 CI 运行会明显变慢（需要现建缓存），后续运行则直接命中。

3.3 手动重建缓存

如果自动构建失败，可手动执行：

bash scripts/ci/build_and_push_uv_cache.sh

注意该脚本有明确前置条件：

• 需要 GitHub CLI 认证：gh auth login（脚本内部通过gh auth status校验，见 scripts/ci/build_and_push_uv_cache.sh）；
• 运行环境必须与 CI 兼容（相同的基础 CUDA 镜像与工具链），以保证缓存的 wheel 可在 CI 中复用；
• 资产上传受 GitHub 单文件 2GB 限制，脚本默认按 1900 MiB 分片（PART_SIZE_MB），并支持--keep（默认保留 4 个历史指纹）、--skip-build（直接上传已有归档）、--skip-prune（跳过旧资产清理）等参数，详见脚本内置--help输出。

四、发布流程：patch / minor / major 语义化版本

ART 的发布链路是"手动触发草稿 → 人工整理 → 合并即发布"。底层由三个 CI 工作流配合 scripts/bump_version.py 完成。

4.1 触发草稿发布

1. 前往 GitHub Actions 页面手动运行Create Draft Release工作流（对应 .github/workflows/create-draft-release.yml）；
2. 选择版本提升类型：
   • patch：仅修复与微小改动（如 0.3.13 → 0.3.14）；
   • minor：新功能且不破坏兼容（如 0.3.13 → 0.4.0）；
   • major：破坏性变更（如 0.3.13 → 1.0.0）。

版本号实际由 scripts/bump_version.py 依据 SemVer 规则改写pyproject.toml中的project.version字段，并执行uv sync同步锁文件。工作流随后会用gh pr list --state merged拉取自上次 tag 以来合并的 PR 列表，自动生成 Release Notes 模板。

4.2 整理草稿并合并发布

在 Releases 页面编辑草稿，补充 Release Highlights、breaking changes 与人工润色的 changelog（自动生成的 PR 列表只是起点），然后合并工作流自动创建的release/vX.Y.Z版本分支 PR。合并动作会触发 .github/workflows/release.yml：

1. build-package通过 scripts/build_package.py 构建 wheel/sdist 并上传产物；
2. runtime-smoke在 GPU runner 上对 wheel 做冒烟测试（校验ensure_vllm_runtime与 vLLM 运行时补丁可正常加载）；
3. publish创建 git tag、把dist/*上传到草稿 Release、将草稿转为正式 Release，并通过 PyPI 官方 Action 发布到 PyPI（openpipe-art）。

此外该工作流还提供workflow_dispatch手动发布入口，可指定版本号与可选的历史构建产物artifact_run_id直接补发。

五、GPU 训练：本地或云端 VM 的准备工作

CONTRIBUTING.md 的核心实操部分，是把 ART 的强化学习示例跑在真实 GPU 上。

5.1 配置环境变量

cp .env.example .env

在.env中按需填写密钥。仓库根目录的 .env.example 实际包含以下变量：

5.2 硬件要求

文档明确要求机器至少具备1 张 H100 或 A100-80GBGPU。更低规格的 GPU 可能也能运行，但训练会明显变慢。ART 的 2048 示例在 1×H100 实例上经过验证（见下文）。

5.3 命令行连接云端 VM

如果使用云 VM，最简单的方式是直接 SSH：

ssh art

这里的art是 SSH 配置别名，通常由 SkyPilot 或本地 SSH config 管理——SKyPilot 已包含在 dev 依赖组中（pyproject.toml），仓库根目录的 skypilot-config.yaml 与 examples/multinode 展示了集群定义方式。

六、VSCode 远程开发：连接 GPU 实例跑 notebook

如果偏好图形化开发，可按以下步骤在 VSCode 中连接 GPU 实例：

1. 安装 Remote-SSH 扩展：在 VSCode 左侧 Activity Bar 的 Extensions 视图中搜索并安装Remote-SSH；
2. 配置远程主机默认扩展：在设置中打开Remote.SSH: Default Extensions，添加以下扩展：
   • ms-python.python（Python 语言支持）
   • ms-toolsai.jupyter（Jupyter notebook）
   • eamodio.gitlens（Git 增强）
   • charliermarsh.ruff（Ruff 格式化/lint）
3. 连接主机：打开命令面板，执行Remote-SSH: Connect to Host...，选择art；
4. 打开工作目录：点击Open Folder，选择sky_workdir（SkyPilot 工作目录）并确认；
5. 运行 notebook：找到 2048 示例 notebook 并运行。

七、跑通 "2048" 强化学习示例

文档提到在/examples/2048/2048.ipynb运行示例，并使用Qwen/Qwen2.5-14B-Instruct在 1×H100 实例上完成验证。需要如实说明的是：当前仓库快照的 examples/2048 目录中实际包含的是 display_benchmarks.ipynb 与训练脚本 train.py，你可以在 notebook 或脚本两种形态中选择其一执行。

从 examples/2048/train.py 可以看到这个示例的核心训练逻辑：

• 通过art.TrainableModel声明模型（示例中基座模型为Qwen/Qwen2.5-3B-Instruct，max_seq_length=8192），项目名为2048；
• 使用art.local.LocalBackend作为训练/推理后端，model.register(backend)完成注册；
• 每个训练步通过art.gather_trajectory_groups并行采集轨迹（SIMULTANEOUS_GAMES = 18，即每步并行 18 局游戏），并对轨迹组调用ruler_score_group（来自 art/rewards/ruler.py，ENABLE_RULER = True）以 Ruler 规则模型打分作为奖励；
• 训练 40 步（TRAIN_STEPS = 40），学习率 1e-5，每步训练后用model.log记录指标。

notebook 形态在本地 backend 下执行同样的流程。训练进度通过 Weights & Biases 在https://wandb.ai/your-wandb-organization/agent-reinforcement-training页面监控，文档指出训练 1 步之后就能在val/reward上看到立竿见影的提升。

排障提示：训练输出默认开到最大详细级别。若遇到问题，把 vLLM 或 torchtune 日志、绘制的 packed tensors 图直接复制/截图给维护者，是文档推荐的最有效 debug 信息。

八、训练结束后清理集群

训练完成后，若使用云端 VM，用 SkyPilot 直接拆除集群：

uv run sky down art

本地训练则直接停止训练进程即可，避免 GPU 实例持续计费。

九、为文档仓库添加新页面（Mintlify）

ART 的文档站由 Mintlify 驱动，新增页面遵循固定流程：

1. 克隆 ART 仓库；
2. 在 CLI/IDE 中打开/docs目录；
3. 运行npx mintlify dev在浏览器中本地预览文档；
4. 在相关目录下创建新的.mdx文件（参考现有页面的 title/sidebar 写法）；
5. 在 docs/docs.json 的navigation.groups中为页面添加导航入口；
6. 浏览器中确认渲染正常后提交 PR。

从 docs/docs.json 可以看到当前文档站分为 Get Started、Fundamentals、Features、Integrations、Tutorials、Resources、Experimental 等分组，所有页面文件位于 docs 目录下（如 docs/fundamentals/art-backend.mdx、docs/features/mcp-rl.mdx），新增页面照此结构挂载即可。

十、贡献流程小结

一次完整的 ART 贡献可以归纳为以下闭环：

1. git clone并uv sync --group dev搭建开发环境；
2. 本地用uv run prek run --all-files通过格式/lint/类型/锁文件/单测五道检查；
3. 提交 PR，等待 CI 中相同的 prek 钩子验证（首次依赖变更时 CI 会先重建 uv 缓存，速度较慢属正常现象）；
4. 合并后按需触发create-draft-release工作流，选择 patch/minor/major，整理草稿并合并发布 PR，自动完成打 tag、发布 Release 与 PyPI 上架；
5. 若涉及训练验证，在 H100/A100-80GB 机器上配置.env，运行 2048 示例并用 wandb 观察val/reward提升，结束后用uv run sky down art清理。

按此流程，你可以像维护者一样完成从代码质量到发布上线的全链路操作，并借助 2048 示例亲手验证 ART 的 GRPO 强化学习训练效果。

【免费下载链接】ARTAgent Reinforcement Trainer: train multi-step agents for real-world tasks using GRPO. Give your agents on-the-job training. Reinforcement learning for Qwen3.6, GPT-OSS, Llama, and more!项目地址: https://gitcode.com/GitHub_Trending/art32/ART