SWE-bench 实操指南

代码 benchmark 全景 的 SWE-bench 小节和 SWEbenchFlow 组件介绍了 SWE-bench 在代码评测谱系中的位置——从 HumanEval 的函数补全跃迁到项目级真实 GitHub issue 修复，这是 2023 年代码评测的范式变化。本篇聚焦实操：“Docker 化评测流水线如何运作、patch 的生成格式是什么、Agent 怎么接入评测、环境如何搭”。读完应能跑通 SWE-bench 评测、理解每个 instance 的判定机制、知道常见失败模式怎么排查。

1 评测流水线

完整流程 5 步：

1.1 输入准备

从 HuggingFace 加载数据集。命名空间有两套：SWE-bench/SWE-bench_Verified 是新的主仓库，princeton-nlp/SWE-bench_Verified 是 2024 年迁移前的旧命名空间（仍然可用）。每个 instance 包含关键字段：

• problem_statement：issue 文本，人类描述的 bug 或需求
• base_commit：代码快照点的 git commit hash
• repo：仓库全名（如 django/django）
• FAIL_TO_PASS：修复前失败、修复后应通过的测试列表
• PASS_TO_PASS：修复前已通过、修复后必须继续通过的测试列表（回归检测）
• patch（gold patch）：人类开发者实际合并的 PR patch，用于对比

1.2 模型生成 Patch

模型接收 problem_statement + 代码库上下文，输出 unified diff 格式的 patch。格式必须严格合规，否则后续 apply 会失败。

1.3 Docker 容器构建

每个 instance 有独立的 test spec，据此构建 Docker 镜像（镜像里装好对应 commit 的 Python、依赖库、测试框架）。2024 年 6 月 SWE-bench 全面迁移到容器化评测，彻底解决了”在我机器上能跑”的环境复现问题。每个 instance 的镜像可能几百 MB 到数 GB，完整评测磁盘占用巨大。

1.4 Patch 三级应用

在容器内依次尝试三种 apply 策略，宽容度递增：

1. git apply --verbose — 严格模式，patch 必须完全匹配
2. git apply --verbose --reject — 允许部分 hunk 失败，失败的写到 .rej
3. patch --batch --fuzz=5 -p1 -i — 模糊匹配，容忍 5 行上下文偏移

三种都失败才判为 apply failure。这种宽容机制容忍模型 patch 里细微的空白或行号偏差。

1.5 测试执行与判定

容器内运行 eval.sh，分别执行 FAIL_TO_PASS 和 PASS_TO_PASS 两组测试。Resolved 的条件：

• 全部 FAIL_TO_PASS 通过（原 bug 被修复）
• AND 全部 PASS_TO_PASS 仍通过（没有破坏已有功能）

任一条件不满足就是 unresolved。最常见的失败模式是”修了 bug 但破了已有测试”——PASS_TO_PASS 回归。

SWE-bench 评测流水线

点击任意阶段查看细节, 阶段 5 支持切换测试结果 case

1

Instance 输入

problem_statement + base_commit

→

2

生成 Patch

unified diff

→

3

构建容器

per-instance image

→

4

三级 Apply

git → git reject → patch

→

5

测试 + 判定

FAIL_TO_PASS / PASS_TO_PASS

✓ RESOLVED(当前测试 case: 理想: bug 修复 + 无回归)

上面的组件逐阶段展开流水线：点击阶段 4 可以看到三级 apply 的决策树，点击阶段 5 可以看到 FAIL_TO_PASS / PASS_TO_PASS 的结果矩阵如何推导出 Resolved 状态。

设计动机：Docker 化解决的是环境方差问题。不同 instance 需要不同 Python 版本、不同版本的 numpy / scipy、不同的系统库。没有容器就没有可复现的公平评测。

2 数据集变体与选择

SWE-bench 目前有 5 个主流变体：

变体	实例数	特点	适用场景
Full	2,294 (test)	12 个 Python 仓库，原始集合	全面评测、论文报告
Lite	300	Full 的精选子集	快速迭代、经济评测
Verified	500	OpenAI 人工验证可解性、描述清晰度、测试合理性	最可靠的对比基准
Multilingual	300	9 种编程语言	跨语言代码能力评测
Multimodal	510 (test)	含截图/UI bug 的 issue	视觉理解 + 代码修复

选择建议：

• 日常开发迭代：用 Lite，300 个 instance 几小时跑完，快速验证 prompt/agent 改动。
• 严肃对比评测：用 Verified，这是目前社区共识的基准——人工验证过，SOTA 参考值最可信。
• 论文报告：Full + Verified 都报。Full 体现规模，Verified 体现质量。

instance_id 命名规则：{repo_owner}__{repo_name}-{PR_number}（注意是双下划线）。例如 django__django-16379 表示 django 仓库的第 16379 号 PR 对应的 instance。

3 Patch 生成与 Agent 集成

3.1 预测 JSON 格式

模型的输出需要按以下格式组织成 JSONL 文件，每行一个 instance：

{
  "model_name_or_path": "my-model",
  "instance_id": "django__django-16379",
  "model_patch": "--- a/django/db/models/query.py\n+++ b/django/db/models/query.py\n@@ -1234,7 +1234,7 @@\n..."
}

三个字段缺一不可。注意第三个字段是 model_patch，不是 prediction（常被误写）。值必须是合法的 unified diff 字符串。

3.2 SWE-agent：标杆级 Agent 实现

SWE-agent 是与 SWE-bench 同期推出的 agent 框架，设计思路影响了后续整个领域：

• ACI（Agent-Computer Interface）：为 LM 优化的工具接口，不是原始 bash。原生 bash 对 LM 太啰嗦（ls 一次打几百行、出错信息冗长），ACI 定义了更紧凑的 open/edit/scroll/search 等工具。
• Agent 循环：Observe（查看文件、错误信息）→ Think（LM 推理）→ Act（编辑、搜索、运行测试）三步循环。
• Config YAML 驱动：行为、工具集、prompt 模板全在 YAML 里配置，代码层只负责执行。
• 当前状态：SWE-agent 已进入维护模式，开发重心转到 mini-swe-agent。

3.3 mini-swe-agent：极简设计胜过复杂

mini-swe-agent 是 SWE-agent 团队的新作，agent 核心类约 100 行 Python——比 SWE-agent 简单一个数量级。它在 SWE-bench Verified 上达 >74%（Gemini 3 Pro），证明了”精巧的极简设计 + 强 LM”比”复杂的 agent 框架 + 弱 LM”更有效。已取代 SWE-agent 成为主要开发方向。

3.4 自建 Agent 接入

SWE-bench 评测与 agent 实现是解耦的。你只需输出符合格式的 prediction JSONL，用任何框架（LangChain / AutoGen / 自写）都可以。评测器不关心 agent 内部怎么工作，只关心最终 patch 是否合法、是否通过测试。

4 环境搭建与常见坑

4.1 硬件需求

资源	建议
磁盘	120GB+（Docker image 累积体积大；Full 评测建议 200GB+）
内存	16GB 最低，32GB 推荐
CPU	8 核推荐
Docker	必须安装，Linux 容器

4.2 ARM / Apple Silicon 特殊处理

默认拉取的镜像是 x86_64。在 ARM 机器上需要：

# 本地构建 ARM 镜像
python -m swebench.harness.run_evaluation \
  --namespace ''   # 空 namespace 表示本地构建而非从 registry 拉
  --predictions_path preds.jsonl \
  --run_id my_run

ARM 支持目前仍为实验性，部分 instance 的依赖可能在 ARM 上无法构建。

4.3 常见坑（5 个）

1. 磁盘爆满：Docker image 累积能到数百 GB。定期 docker system prune -a 清理停止的容器和未使用镜像。
2. Patch 格式错误：非合法 unified diff 会静默失败（不报错，直接判 unresolved）。开发时先用 git apply --check 本地验证 patch 合法性。
3. PASS_TO_PASS 回归：最常见的失败模式。修了 bug 但破了已有测试。agent 在 edit 前最好跑一遍 PASS_TO_PASS 里的关键测试，改完后再跑一遍确保没破坏。
4. Instance creation 暂停：维护者已暂停自定义 instance 创建功能（即从新的 PR 构造新的评测实例）。现在只能用官方发布的数据集。
5. 评测超时：某些 instance 的测试套件运行时间很长（sympy、matplotlib 某些测试 10+ 分钟）。注意评测器的 timeout 配置，不够长会误判 timeout。

4.4 替代方案：sb-cli

如果不想本地维护 Docker 环境，用官方的 sb-cli——云端评测服务，跑在 AWS 上。把 prediction JSONL 提交上去，几分钟到几小时返回结果。适合小团队、临时评测、或者 Docker 环境不稳定的情况。

5 总结

• Resolved rate 解读：当前 Verified SOTA >74%（mini-swe-agent + Gemini 3 Pro），Full SOTA 较低（Full 的 instance 质量参差，一些 bug 甚至人类都难复现）。报告分数时一定要注明具体变体。
• 与函数级 benchmark 互补：HumanEval / MBPP 测”能否写代码”，SWE-bench 测”能否做软件工程”——项目级代码理解、多文件修改、测试回归控制是完全不同的能力维度。
• SWE-bench 的局限：Full/Lite/Verified 都是 Python-only；issue 描述质量不一；部分 instance 需要领域知识（数学库、Web 框架）。做跨语言评测要看 Multilingual。

想看代码评测的整体谱系，回去看 代码 benchmark 全景。想看 Agent 能力层级的系统视角（单次 tool call 到多步 agent），看 Agent benchmark 全景。