mini-swe-agent 运行 SWE-bench-verified 操作指南

1. 安装

# 进入项目目录
cd /{path}/mini-swe-agent

# 安装（开发模式）
pip install -e .

安装后会得到两个 CLI 命令：mini（交互式）和 mini-extra（批量评测等工具）。

---

2. 核心命令

跑 SWE-bench-verified 的核心命令是 mini-extra swebench：

mini-extra swebench \
  --subset verified \
  --split dev \
  --slice "0:5" \
  -m anthropic/claude-opus-4-6-20260205 \
  -c swebench.yaml \
  -o ./results_verified

参数说明

参数	说明
--subset verified	指定 SWE-bench-verified 数据集（对应 HuggingFace 上的 princeton-nlp/SWE-Bench_Verified）
--split dev	数据集 split，默认 dev
--slice "0:5"	只跑前 5 条 instance（用于快速测试）；去掉则跑全部
-m / --model	模型名称，支持 litellm 的所有后端（Anthropic、OpenAI、OpenRouter 等）
-c / --config	配置文件，默认 swebench.yaml
-o / --output	输出目录，存放 preds.json、轨迹文件和日志
-w / --workers	并行 worker 数量（默认单线程）
--filter	正则过滤 instance ID
--redo-existing	覆盖已有结果重新跑

---

3. 单条 Instance 调试

如果只想跑某一条 instance 调试：

mini-extra swebench-single <instance-id> \
  -m anthropic/claude-opus-4-6-20260205 \
  -c swebench.yaml

单条模式参数说明

参数	说明
-i / --instance	instance ID 或索引数字
-y / --yolo	无需确认，自动执行
--exit-immediately	agent 想结束时直接退出，不弹确认提示
-l / --cost-limit	成本限制（美元），设为 0 表示不限制
-o / --output	轨迹输出文件路径

---

4. 批量运行 SWE-bench-verified

小批量测试（推荐先跑几条验证流程）

mini-extra swebench \
  --subset verified \
  --split dev \
  --slice "0:3" \
  -m anthropic/claude-sonnet-4-5-20250929 \
  -c swebench.yaml \
  -o ./results_verified_test \
  -w 1

全量运行

mini-extra swebench \
  --subset verified \
  --split dev \
  -m anthropic/claude-sonnet-4-5-20250929 \
  -c swebench.yaml \
  -o ./results_verified_full \
  -w 4

只跑特定项目（如 django）

mini-extra swebench \
  --subset verified \
  --filter "^django__" \
  -m anthropic/claude-sonnet-4-5-20250929 \
  -c swebench.yaml \
  -o ./results_verified_django \
  -w 4

---

5. 输出结果结构

运行结束后，输出目录结构如下：

results_verified/
├── preds.json                    # SWE-bench 标准格式的预测结果
│                                 # 可直接用于官方评测脚本
├── exit_statuses_1234567890.yaml # 各 instance 的退出状态
├── minisweagent.log             # 完整运行日志
└── django__django-11011/        # 每个 instance 一个目录
    └── django__django-11011.traj.json   # 完整交互轨迹

preds.json 格式

{
  "django__django-11011": {
    "model_name_or_path": "anthropic/claude-sonnet-4-5-20250929",
    "instance_id": "django__django-11011",
    "model_patch": "diff --git a/django/...  ..."
  },
  ...
}

---

6. 使用官方 SWE-bench 评测

得到 preds.json 后，用 SWE-bench 官方工具评测：

# 安装 swe-bench 评测工具
pip install swebench

# 运行评测
python -m swebench.harness.run_evaluation \
  --dataset_name princeton-nlp/SWE-Bench_Verified \
  --predictions_path ./results_verified/preds.json \
  --max_workers 4 \
  --run_id verified_eval

---

7. 完整实操流程总结

# Step 1: 进入项目目录并安装
cd /{path}/3rd/mini-swe-agent
pip install -e .

# Step 2: 设置 API Key
export ANTHROPIC_API_KEY="sk-..."

# Step 3: 单条调试（验证流程是否正常）
mini-extra swebench-single \
  --subset verified \
  --instance 0 \
  -m anthropic/claude-sonnet-4-5-20250929 \
  -c swebench.yaml \
  -y \
  --exit-immediately

# Step 4: 小批量测试（跑5条看看效果）
mini-extra swebench \
  --subset verified \
  --slice "0:5" \
  -m anthropic/claude-sonnet-4-5-20250929 \
  -c swebench.yaml \
  -o ./results_verified_5 \
  -w 1

# Step 5: 全量运行
mini-extra swebench \
  --subset verified \
  -m anthropic/claude-sonnet-4-5-20250929 \
  -c swebench.yaml \
  -o ./results_verified_full \
  -w 4

# Step 6: 官方评测
python -m swebench.harness.run_evaluation \
  --dataset_name princeton-nlp/SWE-Bench_Verified \
  --predictions_path ./results_verified_full/preds.json \
  --max_workers 4

---

8. 常见问题

问题	解决
Docker 镜像拉取失败	确保已安装 Docker，或改用 --environment-class singularity
API 调用超时/失败	检查 API Key，或调整 model_kwargs 中的参数
想换模型	修改 -m 参数，支持 litellm 的所有模型格式（如 openai/gpt-4o）
想修改 system prompt	复制 swebench.yaml，修改 system_template，用 -c 指定新配置

---

9. 离线使用方法

9.1 为什么需要联网

完整流程中以下步骤需要网络连接：

Agent 运行阶段（mini-extra swebench）：

• 从 HuggingFace 下载 SWE-bench 数据集
• 拉取 SWE-bench Docker 镜像
• 调用大模型 API

评测阶段（swebench.harness.run_evaluation）：

• 拉取 Docker 评测镜像
• 容器内安装依赖（部分需要从 PyPI 下载）

9.2 离线替代方案

如果你处于离线环境，可以预先拉取镜像：

# 1. 先在有网环境列出所有需要的镜像
python -c "
from datasets import load_dataset
ds = load_dataset('princeton-nlp/SWE-Bench_Verified', split='dev')
for inst in ds:
    iid = inst['instance_id'].replace('__', '_1776_')
    print(f'docker.io/swebench/sweb.eval.x86_64.{iid}:latest'.lower())
" > images.txt

# 2. 批量拉取
cat images.txt | xargs -I {} docker pull {}

# 3. 保存镜像（可选，用于迁移到离线机器）
docker save $(cat images.txt | tr '\n' ' ') -o swebench_images.tar

然后在离线机器上：

# 加载镜像
docker load -i swebench_images.tar

9.3 简化验证（不跑完整测试）

如果只是想验证 agent 生成的 patch 格式正确，不跑完整 SWE-bench 评测：

# 本地验证 preds.json 格式是否正确
python -c "
import json
with open('./results_verified_full/preds.json') as f:
    preds = json.load(f)
print(f'共生成 {len(preds)} 个 patch')
for k, v in list(preds.items())[:3]:
    print(f'{k}: patch长度={len(v[\"model_patch\"])}')
"

注意：这不能替代官方评测，官方评测是唯一准确判断 patch 是否正确修复了 issue 的方式。

---

10. 数据集映射

mini-extra swebench 支持的数据集 subset 名称：

Subset name	Dataset
full	princeton-nlp/SWE-Bench
verified	princeton-nlp/SWE-Bench_Verified
lite	princeton-nlp/SWE-Bench_Lite
multimodal	princeton-nlp/SWE-Bench_Multimodal
multilingual	swe-bench/SWE-Bench_Multilingual
smith	SWE-bench/SWE-smith
rebench	nebius/SWE-rebench