evalstone/evalscope/docs/zh/third_party/swe_bench.md

SWE-bench

简介

SWE-bench 是评估大型语言模型（LLMs）在真实软件工程任务上能力的基准测试套件，每个样本对应一个真实 GitHub 仓库的 Issue–PR 配对，模型需要产出可通过单元测试的代码补丁（patch）。

EvalScope 集成 SWE-bench 后提供两种评测模式：

• Oracle 单轮模式：将检索到的相关代码上下文一次性提供给模型，模型直接生成 patch
• Agentic 多轮模式：仅向模型提供 issue 描述，模型在每个实例独立的 SWE-bench Docker 容器中通过 bash 多轮探索、修改源码并提交 patch（兼容 mini-swe-agent 流程）

两种模式对比

维度	Oracle 单轮模式	Agentic 多轮模式
输入信息	problem_statement + 预先检索的代码上下文	仅 problem_statement
上下文获取方式	由 inference_dataset_id 预先注入（oracle / BM25）	模型自主在容器内 bash 探索 /testbed
模型交互	单轮请求，直接输出 patch	多轮 agent loop（默认上限 250 步）
工具调用	无	bash 工具，支持 toolcall / backticks 两种协议
提交机制	模型输出 diff 即视为提交	模型打印哨兵 COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT 后由系统抓取 git diff
Docker 使用阶段	仅评测阶段运行测试	推理 + 评测阶段都需要
评测数据集	swe_bench_verified / swe_bench_verified_mini / swe_bench_lite	swe_bench_verified_agentic / swe_bench_verified_mini_agentic / swe_bench_lite_agentic / swe_bench_multilingual_agentic
评测代价	相对低，单轮推理	较高，多轮推理 + 长时间容器交互

适用场景

• Oracle 模式：适合快速建立基线、对比不同检索策略效果，或在算力/时间有限时进行低成本试跑
• Agentic 模式：适合评估模型作为「软件工程 agent」的端到端能力（自主探索代码、编写补丁、迭代调试），更贴近真实开发场景

数据集说明

核心评测数据集（两种模式共用名字根）

下列数据集通过 Issue–PR 配对与单元测试验证评估模型，从全量到精选满足不同评估需求：

• SWE-bench Verified（swe_bench_verified）：从 SWE-bench 测试集中精选的 500 个人工验证样本，质量经过严格把关
• SWE-bench Verified Mini（swe_bench_verified_mini）：50 样本的轻量子集，存储需求约 5GB（vs 原版 130GB），保持与原集相同的难度分布
• SWE-bench Lite（swe_bench_lite）：来自 11 个流行 Python 项目的 300 个 Issue–PR 配对
• SWE-bench Multilingual：来自 42 个仓库、覆盖 9 种编程语言的 300 个精选 Issue–PR 任务。EvalScope 仅支持该数据集的 agentic 模式。

Oracle 模式专属：推理数据集（inference_dataset_id）

不同检索方式格式化的 SWE-bench 版本，差异在于代码上下文的检索方式与上限：

• princeton-nlp/SWE-bench_oracle：使用 Oracle 检索（理想化检索结果，用作上限基准），默认值
• princeton-nlp/SWE-bench_bm25_13K：BM25 检索，代码上下文限制 13,000 tokens（cl100k_base）
• princeton-nlp/SWE-bench_bm25_27K：BM25 检索，限制 27,000 tokens
• princeton-nlp/SWE-bench_bm25_40K：BM25 检索，限制 40,000 tokens

Agentic 模式专属：评测数据集

在核心数据集名字后加 _agentic 后缀触发 agentic 多轮评测：

• swe_bench_verified_agentic — SWE-bench Verified（500 样本）
• swe_bench_verified_mini_agentic — SWE-bench Verified Mini（50 样本，约 5GB）
• swe_bench_lite_agentic — SWE-bench Lite（300 样本）
• swe_bench_multilingual_agentic — SWE-bench Multilingual（覆盖 9 种编程语言的 300 个样本）

安装依赖

SWE-bench 使用 Docker 来确保评估的可复现性。

1. 安装 Docker：参考 Docker 安装指南 在你的机器上安装 Docker
2. Linux 用户额外配置：建议查看 安装后配置步骤 以获得更好的体验
3. 安装 Python 依赖：

pip install evalscope
pip install swebench==4.1.0

提示：正确配置 Docker 是运行 SWE-bench 评估的前提条件，请确保安装完成后 Docker 服务正常运行。

首次运行 swe_bench 任务时，系统需要构建/下载必要的 Docker 镜像，资源消耗较高：

- **时间消耗**：完整 SWE-bench Verified 数据集的镜像构建可能耗时数小时
- **存储需求**：完整集需预留约 130GB 存储；Mini 集约 5GB

**建议**：首次运行请确保磁盘空间和时间预算充足，并选择网络状况良好的环境。

Oracle 单轮评测模式

下面以 qwen-plus 模型评测 swe_bench_verified 为例：

import os
from evalscope import TaskConfig, run_task

task_cfg = TaskConfig(
    model='qwen-plus',
    api_url='https://dashscope.aliyuncs.com/compatible-mode/v1',
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    eval_type='openai_api',  # 使用 API 模型服务
    datasets=['swe_bench_verified'],  # 也可选择 'swe_bench_verified_mini' 或 'swe_bench_lite'
    dataset_args={
        'swe_bench_verified': {
            'extra_params': {
                'build_docker_images': True,                              # 是否构建评测所需的 Docker 镜像，首次运行建议 True
                'pull_remote_images_if_available': True,                  # 远程有可用镜像时优先拉取，建议 True
                'inference_dataset_id': 'princeton-nlp/SWE-bench_oracle'  # 推理数据集，可选 BM25_13K / 27K / 40K / oracle
            }
        }
    },
    eval_batch_size=5,  # 推理批大小 / 并行评测任务的工作线程数（docker 容器数量）
    limit=5,            # 限制评测数量便于快速测试，正式评测时建议去掉
    generation_config={
        'temperature': 0.1,
    }
)
run_task(task_cfg=task_cfg)

评测中间结果保存在 outputs/xxxxx/swebench_log 目录下，包含 patch.diff 等文件。最终结果示例：

+-----------+--------------------+----------+----------+-------+---------+---------+
| Model     | Dataset            | Metric   | Subset   |   Num |   Score | Cat.0   |
+===========+====================+==========+==========+=======+=========+=========+
| qwen-plus | swe_bench_verified | mean_acc | default  |     5 |     0.2 | default |
+-----------+--------------------+----------+----------+-------+---------+---------+

Agentic 多轮评测模式

在 agentic 模式下，模型只接收原始 problem_statement（不提供 oracle 上下文），并在每个实例独立的 SWE-bench Docker 容器中驱动多轮 agent 循环：使用 bash 探索 /testbed、编辑源文件，最终通过打印哨兵字符串 COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT 提交 git diff。

动作协议

action_protocol 参数控制模型与 bash 的交互方式：

协议	描述	适用模型
toolcall（默认）	OpenAI function-calling，注册单个 bash 工具，支持并行工具调用	支持 function-calling 的模型
backticks	模型将命令包裹在 ```mswea_bash_command ... ``` 围栏块中，每轮一条命令	不支持 function-calling 的模型

运行示例

下面示例完全对齐 tests/benchmark/test_agent.py 中的 test_swe_bench_verified_mini_agentic 用例：

import os
from evalscope import TaskConfig, run_task

task_cfg = TaskConfig(
    model='qwen3-max',
    api_url='https://dashscope.aliyuncs.com/compatible-mode/v1',
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    eval_type='openai_api',
    datasets=['swe_bench_verified_mini_agentic'],  # 也可选 'swe_bench_verified_agentic'、'swe_bench_lite_agentic' 或 'swe_bench_multilingual_agentic'
    dataset_args={
        'swe_bench_verified_mini_agentic': {
            'extra_params': {
                'action_protocol': 'toolcall',           # 动作协议：'toolcall' 或 'backticks'
                'max_steps': 250,                        # agent 循环最大步数
                'command_timeout': 60.0,                 # 单条 bash 命令的超时（秒）
                'build_docker_images': True,             # 准备评测所需镜像，首次运行建议 True
                'pull_remote_images_if_available': True, # 远程有可用镜像时优先拉取
                # 'force_arch': 'arm64',                 # Apple Silicon 用户可显式指定为 'arm64'，默认 '' 自动检测
            }
        }
    },
    eval_batch_size=5,  # 并行容器数量
    limit=3,            # 限制评测数量便于快速测试，正式评测时建议去掉
    generation_config={
        'temperature': 0.7,
        'parallel_tool_calls': True,
        'stream': True,
    }
)
run_task(task_cfg=task_cfg)

参数说明

参数	类型	默认值	说明
action_protocol	str	toolcall	模型与 bash 的交互协议，可选 toolcall / backticks
max_steps	int	250	每个样本 agent 循环的最大步数
command_timeout	float	60.0	单条 bash 命令超时秒数
build_docker_images	bool	True	是否准备 Docker 镜像（构建或拉取）
pull_remote_images_if_available	bool	True	是否优先从远程仓库拉取已构建好的镜像
force_arch	str	''	强制指定镜像架构，可选 '' / arm64 / x86_64，留空自动检测

Agentic 模式在**推理和评测两个阶段**都需要 Docker 运行。每个样本会从预构建的 SWE-bench 镜像启动独立容器，因此 `eval_batch_size` 实际上控制了同时存在的容器数量，请根据机器资源酌情调整。