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本篇指南基于 ARTAgent 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依赖组包含rufflint/格式化、pytest与pytest-xdist并行测试、nbvalnotebook 校验、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各钩子职责对照钩子作用仓库配置依据ruff导入排序与 lintpyproject.toml 中select [I]并按known-first-party [art]组织导入ruff-format代码格式化项目同时在 dev 依赖中引入ruff0.12.1pyright/ty静态类型检查pyproject.toml 配置了tool.ty规则与allowed-unresolved-imports允许本地未装的可选依赖通过解析uv-lock-check校验pyproject.toml与uv.lock一致依赖变更时需uv sync重新生成锁文件pytest运行单元测试测试入口集中在 tests/unit对照 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-256Megatron 运行时子项目 megatron_runtime/pyproject.toml 与 megatron_runtime/uv.lock 的 SHA-256CI 基础镜像默认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 中cache-status任务先计算期望指纹并通过 scripts/ci/github_release_assets.py 查询 Release 资产判断是否已存在完整分片集若未命中build-cache任务在 CUDA 基础镜像容器内调用 scripts/ci/build_and_push_uv_cache.sh 重新构建并上传缓存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 触发草稿发布前往 GitHub Actions 页面手动运行Create Draft Release工作流对应 .github/workflows/create-draft-release.yml选择版本提升类型patch仅修复与微小改动如 0.3.13 → 0.3.14minor新功能且不破坏兼容如 0.3.13 → 0.4.0major破坏性变更如 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.ymlbuild-package通过 scripts/build_package.py 构建 wheel/sdist 并上传产物runtime-smoke在 GPU runner 上对 wheel 做冒烟测试校验ensure_vllm_runtime与 vLLM 运行时补丁可正常加载publish创建 git tag、把dist/*上传到草稿 Release、将草稿转为正式 Release并通过 PyPI 官方 Action 发布到 PyPIopenpipe-art。此外该工作流还提供workflow_dispatch手动发布入口可指定版本号与可选的历史构建产物artifact_run_id直接补发。五、GPU 训练本地或云端 VM 的准备工作CONTRIBUTING.md 的核心实操部分是把 ART 的强化学习示例跑在真实 GPU 上。5.1 配置环境变量cp .env.example .env在.env中按需填写密钥。仓库根目录的 .env.example 实际包含以下变量变量是否必需说明WANDB_API_KEY建议SSH 到新机器用本地后端训练时用于向 Weights Biases 上报指标GIT_USER_NAME/GIT_USER_EMAIL可选在新机器上做 git 提交时的身份GITHUB_TOKEN可选向私有仓库提交时可能需要HF_TOKEN可选训练 Llama 3.1 等门控模型时需要OPENPIPE_API_KEY可选OpenPipe API 密钥TOGETHER_API_KEY可选部署模型到 Together 时使用AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_REGION/BACKUP_BUCKET可选S3 日志与模型备份配置5.2 硬件要求文档明确要求机器至少具备1 张 H100 或 A100-80GBGPU。更低规格的 GPU 可能也能运行但训练会明显变慢。ART 的 2048 示例在 1×H100 实例上经过验证见下文。5.3 命令行连接云端 VM如果使用云 VM最简单的方式是直接 SSHssh art这里的art是 SSH 配置别名通常由 SkyPilot 或本地 SSH config 管理——SKyPilot 已包含在 dev 依赖组中pyproject.toml仓库根目录的 skypilot-config.yaml 与 examples/multinode 展示了集群定义方式。六、VSCode 远程开发连接 GPU 实例跑 notebook如果偏好图形化开发可按以下步骤在 VSCode 中连接 GPU 实例安装 Remote-SSH 扩展在 VSCode 左侧 Activity Bar 的 Extensions 视图中搜索并安装Remote-SSH配置远程主机默认扩展在设置中打开Remote.SSH: Default Extensions添加以下扩展ms-python.pythonPython 语言支持ms-toolsai.jupyterJupyter notebookeamodio.gitlensGit 增强charliermarsh.ruffRuff 格式化/lint连接主机打开命令面板执行Remote-SSH: Connect to Host...选择art打开工作目录点击Open Folder选择sky_workdirSkyPilot 工作目录并确认运行 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-Instructmax_seq_length8192项目名为2048使用art.local.LocalBackend作为训练/推理后端model.register(backend)完成注册每个训练步通过art.gather_trajectory_groups并行采集轨迹SIMULTANEOUS_GAMES 18即每步并行 18 局游戏并对轨迹组调用ruler_score_group来自 art/rewards/ruler.pyENABLE_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 实例持续计费。九、为文档仓库添加新页面MintlifyART 的文档站由 Mintlify 驱动新增页面遵循固定流程克隆 ART 仓库在 CLI/IDE 中打开/docs目录运行npx mintlify dev在浏览器中本地预览文档在相关目录下创建新的.mdx文件参考现有页面的 title/sidebar 写法在 docs/docs.json 的navigation.groups中为页面添加导航入口浏览器中确认渲染正常后提交 PR。从 docs/docs.json 可以看到当前文档站分为 Get Started、Fundamentals、Features、Integrations、Tutorials、Resources、Experimental 等分组所有页面文件位于 docs 目录下如 docs/fundamentals/art-backend.mdx、docs/features/mcp-rl.mdx新增页面照此结构挂载即可。十、贡献流程小结一次完整的 ART 贡献可以归纳为以下闭环git clone并uv sync --group dev搭建开发环境本地用uv run prek run --all-files通过格式/lint/类型/锁文件/单测五道检查提交 PR等待 CI 中相同的 prek 钩子验证首次依赖变更时 CI 会先重建 uv 缓存速度较慢属正常现象合并后按需触发create-draft-release工作流选择 patch/minor/major整理草稿并合并发布 PR自动完成打 tag、发布 Release 与 PyPI 上架若涉及训练验证在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考