Augment SWE-bench 验证代理

SWE-bench Verified 用于测试 AI 系统在处理来自热门开源项目真实 GitHub 问题的软件工程任务时的表现。一些示例问题可以在 OpenAI 的 关于该基准的原始博客文章 中找到。与大多数专注于孤立 Leetcode 式编程题目的编码基准不同，SWE-bench 涉及代码库导航、针对回归测试套件进行迭代，以及整体上更高的复杂性。

为了在我们首次提交 SWE-bench 测试中达到 65.4% 的成功率，我们结合了 Claude Sonnet 3.7 作为核心驱动模型，并使用 OpenAI 的 o1 作为集成器。我们选择不直接利用自己的模型，而是采用现成的模型来构建一个强大的开源基线代理。

由于 Anthropic 的模型目前在代码生成领域处于最先进水平，我们便将 Claude Sonnet 3.7 用作代理的核心驱动模型，并从 Anthropic 自己关于 SWE-bench 的博客文章中借鉴了代理系统架构：Anthropic 关于 SWE-bench 的博客文章。

功能特性

• 小型且简单的编码代理实现 + SWE-bench Docker 测试框架，易于运行和扩展。
• 实现了我们在 SWE-bench 提交中使用的工具：
  • Bash 命令执行
  • 文件查看与编辑
  • 用于复杂问题解决的序列化思维
• 来自我们 SWE-bench 提交的提示模板 + 系统提示。
• 集成 Anthropic 的 Claude 作为核心代理模型，以及 OpenAI 的模型用于集成。
• 命令审批管理，确保安全执行。
• 多数投票集成器，用于从多个候选方案中选出最佳解。
• 支持在 Docker 容器中运行代理。
• 支持运行 SWE-bench 评估框架。

安装

先决条件

• Docker（我们使用 Docker version 26.1.3, build 26.1.3-0ubuntu1~22.04.1 进行测试。）
• Anthropic API 密钥（用于 Claude 模型）
• OpenAI API 密钥（用于 OpenAI 模型）

设置步骤

1. 克隆仓库：

   git clone https://github.com/augmentcode/augment-swebench-agent.git
   cd augment-swebench-agent
   

2. 安装依赖项：

   ./setup.sh
   source .venv/bin/activate
   

3. 设置您的 API 密钥：

   # 对于 Anthropic Claude 模型
   export ANTHROPIC_API_KEY=your_anthropic_api_key_here
   
   # 对于 OpenAI 模型
   export OPENAI_API_KEY=your_openai_api_key_here
   

使用本仓库的方式

• 交互模式：使用 cli.py 启动交互式代理，用于实验或作为个人编码助手！
• SWE-bench 模式：使用 run_agent_on_swebench_problem.py 在 SWE-bench 问题上运行代理。这与我们用于生成 SWE-bench 提交结果的脚本类似。

以下将详细介绍这两种使用方式！

使用方法（交互模式）

运行 CLI 界面以直接与代理交互。默认情况下，代理将在当前目录下运行。

python cli.py

这将启动一个交互式会话，您可以在其中与代理沟通并为其分配任务。

命令行选项

• --workspace：工作区目录路径（默认：当前目录）
• --problem-statement：提供问题陈述以使代理进入非交互模式（默认：无）
• --needs-permission：是否需要在执行命令前获得许可（默认：假）
• --use-container-workspace：挂载到 Docker 容器中的共享卷路径。如果您使用 --docker-container-id，则必须设置此参数。（默认：无）
• --docker-container-id：要使用的 Docker 容器 ID。如果您使用 --use-container-workspace，则必须设置此参数。（默认：无）

示例：

python cli.py --workspace /path/to/project --problem-statement "修复登录问题"

非交互模式

您可以通过提供问题陈述来让代理以非交互模式运行：

python cli.py --problem-statement "实现按日期排序商品的功能"

使用 Docker

如果您希望使用 Docker 容器作为工作区，则需要同时指定 Docker 容器卷的路径以及 Docker 容器 ID：

python cli.py --use-container-workspace --docker-container-id <container_id> --workspace /path/to/docker/volume

使用方法（SWE-bench 模式）

快速测试运行

作为一次测试运行，您可以执行以下命令。它将为 5 个问题中的每个问题生成 2 个候选解决方案，并对每个候选解决方案运行评估步骤。最后，它还会提供如何对结果进行集成的说明。

python run_agent_on_swebench_problem.py --num-examples 5 --num-candidate-solutions 2

您可以增加 --num-examples 和 --num-candidate-solutions 参数，以运行更多问题并生成更多候选解决方案。但请注意，这将花费更长的时间并产生更高的成本。

命令行选项

• --num-examples：要运行的示例数量（默认：无，即运行所有示例）
• --shard-ct：将工作拆分为多少个分片（默认：1）
• --shard-id：要运行的分片 ID（从 0 开始计数，默认：0）
• --num-processes：每个示例使用的进程数量（默认：8）
• --num-candidate-solutions：每个示例要生成的候选解决方案数量（默认：8）

运行更多示例

SWE-bench Verified 总共有 500 个示例。需要注意的是，这可能需要较长时间，因此本仓库支持多级并行处理：

1. 首先，建议使用 8 个进程，即 --num-processes 参数。超过这个数量，Docker 可能会出现问题。
2. 其次，我们支持将数据集拆分为多个分片，即 --shard-ct 和 --shard-id 参数。这样可以相对容易地将工作分配到多台机器上，从而避免 Docker 在超过 8 个进程时出现的问题。

在我们的实验中，为每个问题运行 1 个候选解决方案的完整评估耗时约 2 小时。当时我们将 10 个分片分配到不同的 Pod 中（由 Kubernetes 管理），每个 Pod 运行 8 个进程。

请记住，像我们一样并行运行 80 个代理可能会触发 Anthropic 的速率限制。而您可能没有我们那样高的 Anthropic API 速率限制。因此，您可能需要减少 --shard-ct 和/或 --num-processes 的值。

假设您想使用 10 个分片，每个分片 8 个进程，那么您需要在 10 台不同的机器上分别运行以下命令，每次更改 --shard-id 参数，从 0 到 9：

python run_agent_on_swebench_problem.py --shard-ct 10 --shard-id <worker_index> > logs.out 2> logs.err

多数投票集成器

多数投票集成器是一种工具，它利用大语言模型从多个候选方案中选出最佳解决方案。其工作原理是将问题的多个候选解决方案提交给 OpenAI 的 o1 模型，并请求该模型分析并选择最普遍认同的方案。

工作原理

1. 该工具接收一个包含问题的 JSON 文件，每个问题都附有多个候选解决方案（差异）。
2. 对于每个问题，它使用 build_ensembler_prompt 函数构建提示。
3. 将提示发送至 o1 模型。
4. 大语言模型会分析所有候选解决方案，并选出最佳的一个。
5. 工具从大语言模型的响应中提取所选解决方案的索引。
6. 最终结果会被保存到一个 JSON 文件中。

使用方法

python majority_vote_ensembler.py path/to/input.jsonl --output_path path/to/output.json --workers 8

参数说明：

• path/to/input.jsonl 是一个包含问题和候选解决方案的 JSONL 文件（格式请参考 example_ensembler_dataset.jsonl）。
• --output_path 指定保存结果的路径。
• --workers 设置用于并行处理的工作线程数量（默认为 8）。

示例

python majority_vote_ensembler.py example_ensembler_data.jsonl --output_path example_ensembler_results.json

输入格式

输入的 JSONL 文件应包含一系列问题对象，每个问题对象的结构如下。diffs 是由智能体生成的候选解决方案，而 eval_outcomes 则是针对每个候选解决方案运行评估框架后得到的结果，其中索引与 diffs 数组中的索引相对应。

{
  "id": "problem-1",
  "instruction": "添加一个计算阶乘的函数",
  "diffs": [
    "```diff\n@@ -10,3 +10,10 @@\n def function():\n     return x\n+\n+def new_function():\n+    return y\n```",
    "...其他候选解决方案..."
  ],
  "eval_outcomes": [
    {
      "is_success": true
    },
    {
      "is_success": false
    },
    {
      "is_success": true
    }
  ]
}

输出格式

输出的 JSON 文件将包含一个结果对象数组，每个对象的结构如下：

[
  {
    "id": "problem-1",
    "instruction": "添加一个计算阶乘的函数",
    "response": "[大语言模型的完整响应文本]",
    "selected_diff_index": 2,
    "selected_diff": "[被选中的差异内容]",
    "is_eval_success": true
  }
]

开发

运行测试

pytest

添加新工具

要向智能体添加新工具：

1. 在 tools/ 目录下创建一个新的工具类。
2. 实现所需的方法（如 run_impl、get_tool_param 等）。
3. 将该工具添加到 tools/agent.py 中智能体的工具列表中。

自定义智能体提示

智能体的提示定义在 prompts/ 目录中。您可以通过修改相应文件中的模板字符串来定制提示。

自定义多数投票集成器

您可以自定义多数投票集成器，方法如下：

• 修改 prompts/ensembler_prompt.py：更改用于集成的提示模板。
• 修改 process_problem 函数中的 get_client 调用，以更换使用的 LLM 模型。

贡献

欢迎贡献！请开立议题或提交拉取请求。

许可证

本项目采用 MIT 许可证授权。

Augment SWE-bench Agent 快速上手指南

Augment SWE-bench Agent 是一个开源的软件开发智能体，专为解决真实的 GitHub 问题而设计。它结合了 Claude Sonnet 3.7 作为核心驱动和 OpenAI o1 作为集成器，在 SWE-bench Verified 基准测试中取得了优异成绩。该工具支持代码库导航、回归测试迭代及复杂问题解决。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux 或 macOS（Windows 用户建议使用 WSL2）
• Docker：已安装并运行 Docker Engine（测试版本：26.1.3 或更高）。
  • 国内用户可参考 Docker 中国镜像加速 配置以提升拉取速度。
• Python：建议 Python 3.8+（脚本将自动创建虚拟环境）
• API 密钥：
  • Anthropic API Key（用于 Claude 模型）
  • OpenAI API Key（用于 o1 模型及结果集成）

安装步骤

1. 克隆仓库

git clone https://github.com/augmentcode/augment-swebench-agent.git
cd augment-swebench-agent

2. 安装依赖

运行设置脚本并激活虚拟环境：

./setup.sh
source .venv/bin/activate

提示：如果 ./setup.sh 执行缓慢，可检查 requirements.txt 并使用国内 pip 源手动安装： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 配置 API 密钥

导出您的 API 密钥到环境变量：

# 配置 Anthropic (Claude)
export ANTHROPIC_API_KEY=your_anthropic_api_key_here

# 配置 OpenAI (o1)
export OPENAI_API_KEY=your_openai_api_key_here

基本使用

本工具提供两种主要模式：交互式模式（适合日常辅助开发）和 SWE-bench 模式（适合批量评测）。

模式一：交互式使用 (Interactive Mode)

这是最简单的使用方式，您可以直接与 Agent 对话，让它帮您修复代码或实现功能。

启动交互会话：

python cli.py

非交互式运行（直接下达任务）： 如果您想直接让 Agent 处理一个具体任务而不进入对话模式：

python cli.py --problem-statement "Fix the login issue in auth.py"

常用参数说明：

• --workspace: 指定工作目录（默认为当前目录）。
• --needs-permission: 设置为 True 可在执行命令前要求人工确认（更安全）。
• --docker-container-id: 若需在特定 Docker 容器中运行，需配合此参数及 --use-container-workspace 使用。

模式二：SWE-bench 基准测试 (SWE-bench Mode)

用于在标准的 SWE-bench 问题上运行 Agent 并生成解决方案。

快速测试运行： 以下命令将对 5 个问题各生成 2 个候选解决方案，并自动运行评估：

python run_agent_on_swebench_problem.py --num-examples 5 --num-candidate-solutions 2

结果集成（多数投票）： 生成多个候选方案后，使用 o1 模型进行“多数投票”以选出最佳方案：

python majority_vote_ensembler.py path/to/input.jsonl --output_path results.json --workers 8

进阶提示

• 并行加速：在处理大量数据时，可通过 --shard-ct 和 --shard-id 参数将任务分片，以便在多台机器或多进程下并行运行，绕过 Docker 进程数限制。
• 成本控制：增加 --num-candidate-solutions 会显著提高 Token 消耗和时间，请根据需求调整。