企业官网建设流程全解析

SWE-agent 批量运行（Batch Mode）完全指南：从单问题到并行百问题

【免费下载链接】SWE-agentSWE-agent takes a GitHub issue and tries to automatically fix it, using your LM of choice. It can also be employed for offensive cybersecurity or competitive coding challenges. [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/sw/SWE-agent

SWE-agent 的核心使用方式是sweagent run单实例运行，但当你想在 SWE-bench 等基准上批量验证、跑竞赛题目或处理一批 GitHub Issue 时，就需要切换到sweagent run-batch命令。本文基于 SWE-agent 仓库官方文档，结合 run_batch.py 与 batch_instances.py 的源码实现，系统讲解批量模式下的实例源（instance source）、切片与过滤、并行加速、多模态支持以及结果合并，帮助你从单问题用户升级为可以同时跑上百个 Issue 的进阶用户。

阅读本文前，建议先熟悉命令行基础教程。文中默认示例会在 Docker 沙箱中执行代码，请确保本机已安装 Docker（如遇问题可参考 Docker 排障指南）；若无法运行 Docker，请浏览示例并自行调整部署配置。

第一个示例：跑 SWE-bench 基准

假设你决定用 SWE-agent 并行解决大量 GitHub Issue——这正是run-batch命令的用途。下面的命令会自动下载 3 个 SWE-bench 任务并依次运行：

sweagent run-batch \ --config config/default.yaml \ --agent.model.name gpt-4o \ --agent.model.per_instance_cost_limit 2.00 \ --instances.type swe_bench \ --instances.subset lite \ --instances.split dev \ --instances.slice :3 \ --instances.shuffle=True

逐项解析实例配置

1. --instances.type swe_bench：指定实例源（instance source）。仓库内置了多种实例加载方式，这里选择 SWE-bench 数据集。在源码 batch_instances.py 中，SWEBenchInstances类通过 HuggingFacedatasets.load_dataset加载数据，并把每条数据转换为统一的SimpleBatchInstance格式（见from_swe_bench方法）。
2. --instances.subset lite：SWE-bench 项目提供多个子集。lite是经过启发式过滤的 GitHub Issue 子集，通常更容易被解决。完整子集映射见源码_get_dataset_path方法：full、verified、lite、multimodal、multilingual分别对应princeton-nlp/SWE-Bench、princeton-nlp/SWE-Bench_Verified、princeton-nlp/SWE-Bench_Lite、princeton-nlp/SWE-Bench_Multimodal与swe-bench/SWE-Bench_Multilingual。
3. --instances.split dev：大多数数据集包含dev与test两个划分（SWEBenchInstances.split字段限定为二者之一，默认dev）。
4. --instances.slice :3：切片选项，其行为与 Python 的list[...]切片完全一致（源码_slice_spec_to_slice正是将其拆成start:stop:step并构造slice对象）。你可以用:10取前 10 个，10:20取接下来的 10 个，-10:取最后 10 个，10:20:2取该区间内每隔一个的实例。
5. --instances.shuffle=True：切片前先打乱顺序。注意这是确定性操作（源码中固定random.seed(42)），因此相同命令每次都会返回相同的实例顺序，便于复现实验。

需要注意：批量模式下--agent相关的选项（模型、成本上限等）和--config配置文件依然全部可用，但--problem_statement、--repo、--env这些单实例选项不再适用——它们现在由实例源自动填充。

提示：完整命令行选项参见 RunBatchConfig 参考文档；SWE-bench 实例配置详见 SWEBenchInstances 参考文档。

自动提交评测（sb-cli）

如果你使用 sb-cli 工具，可以在命令中追加--evaluate=True让 SWE-agent 在 SWE-bench 上自动评测。运行期间就会持续向 sb-cli 提交结果，因此整个运行结束后约一分钟内即可收到评测结果。在源码层面，RunBatch.from_config检测到SWEBenchInstances.evaluate=True时会注入 SweBenchEvaluate Hook（continuous_submission_every=30，即每 30 个实例提交一轮）。注意：evaluate与redo_existing不能同时开启，否则旧预测会被重复提交导致结果无效，RunBatchConfig中的校验器会直接抛出ValueError。

从源码看批量运行的执行流程

run_batch.py 中RunBatch.main()的执行路径如下：

1. 调用from_config加载实例列表（通过instances.get_instance_configs()），输出目录默认写入trajectories/<用户名>/<配置名>__<模型名>__<实例源>（set_default_output_dir的逻辑）。
2. 根据num_workers选择单线程循环（main_single_worker）或ThreadPoolExecutor线程池并行（main_multi_worker）。
3. 每个实例会写入run_batch.config.yaml、实例专属的trace/debug/info三级日志文件，以及进度报告run_batch_exit_statuses.yaml。
4. 已有完整.traj轨迹的实例默认会被跳过（should_skip会检查轨迹中是否存在exit_status；空轨迹、无 exit status 的轨迹会被删除并重跑）。如需强制重跑，可加--redo_existing True。
5. 全部完成后调用merge_predictions把各实例目录下的预测合并到preds.json。

多模态 SWE-bench（SWE-bench Multimodal）

SWE-agent 支持SWE-bench Multimodal数据集，其中的 GitHub Issue 带有图片（截图、架构图、UI 原型图）。运行多模态实例的命令如下：

sweagent run-batch \ --config config/default_mm_with_images.yaml \ --agent.model.name claude-sonnet-4-20250514 \ --agent.model.per_instance_cost_limit 2.00 \ --instances.type swe_bench \ --instances.subset multimodal \ --instances.split dev \ --instances.slice :3 \ --instances.shuffle=True

多模态运行的关键差异：

• 配置：使用config/default_mm_with_images.yaml，该配置开启图片处理能力。从配置文件可见其history_processors增加了image_parsing（解析观察中的 base64 图片），并挂载了tools/image_tools（查看图片文件）与tools/web_browser（浏览器交互）两个工具 bundle，max_observation_length也提高到10_000_000以容纳图片数据。
• 子集：使用--instances.subset multimodal访问多模态数据集。
• Token 上限：图片会消耗更多 token，建议相应调高--agent.model.per_instance_cost_limit。
• 多模态工具：tools/image_tools与tools/web_browser提供查看图片和使用浏览器的实用工具。

系统会自动完成以下处理（源码见 batch_instances.py 与 problem_statement.py）：从 GitHub Issue URL 下载图片 → 转换为 base64 编码的 Markdown 格式 → 提供给 AI 模型作为视觉上下文。SimpleBatchInstance.to_full_batch_instance检测到extra_fields中的issue_images时，会构造SWEBenchMultimodalProblemStatement作为问题陈述。

更多配置选项与排障方法，请参阅多模态使用指南。

并行运行：一条命令提速

只需改动一行——添加--num_workers：

sweagent run-batch \ --config config/default.yaml \ --agent.model.name gpt-4o \ --num_workers 3 \ --agent.model.per_instance_cost_limit 2.00 \ --instances.type swe_bench \ --instances.subset lite \ --instances.split dev \ --instances.slice :3 \ --instances.shuffle=True

你会看到底部出现进度条，显示 30 个实例同时运行的效果大致如下：

源码中RunBatch._num_workers会被限制为min(num_workers, len(instances))；多 worker 模式下日志流会降为 WARNING 级别以减少刷屏，进度条始终显示。需要特别留意的是：human 模型（human/human_thought）不能并行运行，RunBatch.__init__会直接抛错。

缓解 Docker 启动瓶颈

当用 Docker 后端并行启动大量容器时，可能会遇到瓶颈效应（例如 CPU 核数较少的平台，容器启动不及时会导致超时）。此时可以设置--random_delay_multiplier 1，让每个 worker 在开始前随机等待0s到1s × worker数的时间，从而缓解 CPU 压力（默认值为0.3）。源码run_instance中的等待公式为time.sleep(random.random() * multiplier * (num_workers - 1))，这能避免所有容器同时启动造成的"惊群"效应。

全部命令行选项参见 RunBatchConfig 参考文档。

从文件加载实例

--instances.type file允许从本地文件加载任务，--instances.path支持.jsonl、.json和.yaml三种格式：

sweagent run-batch \ --config config/default.yaml \ --agent.model.name gpt-4o \ --instances.type file \ --instances.path instances.yaml \ --instances.slice :3 \ --instances.shuffle=True

instances.yaml最简单的形式如下：

- image_name: "python:3.11" # 必须本地已存在或可从 dockerhub 拉取 problem_statement: "A simple test problem" instance_id: "simple_test_problem" - image_name: "python:3.11" problem_statement: "Another test problem" instance_id: "simple_test_problem_2"

警告：instance_id键在 2025 年 3 月 16 日之前叫id，后来为了与标准 SWE-bench 格式兼容而改名，目前两个名字都暂时支持（源码SimpleBatchInstance.handle_legacy_id会在校验前自动把id迁移为instance_id）。

更多可用字段（对应源码 SimpleBatchInstance）：

• repo_name：指定仓库。为空则不使用仓库；不含/时视为 Docker 容器根目录下已存在的仓库；GitHub URL 则克隆对应仓库；否则视为本地仓库路径。
• base_commit：用于重置仓库的提交点，默认HEAD。
• extra_fields：任意附加数据，可在提示词模板格式化时使用（多模态场景下issue_images也放在这里）。

实例加载后会经过统一的过滤 → 切片 → 打乱流水线（_filter_batch_items）：filter是作用于实例 ID 的正则表达式（默认.*匹配全部），过滤后再执行切片。若最终实例为空，from_config会抛出 "No instances to run" 错误，并提示检查 split 名称与过滤条件。

更多字段说明见 SimpleBatchInstance 参考文档；该实例类型的所有命令行选项见 InstancesFromFile 参考文档。

从 HuggingFace 加载实例

如果你把自己的数据集按上述格式上传到 HuggingFace，可以这样加载：

sweagent run-batch \ ... --instances.type huggingface \ --instances.dataset_name "your_username/your_dataset" \ --instances.split "dev" \ --instances.slice :3 \ --instances.shuffle=True

源码中InstancesFromHuggingFace使用datasets.load_dataset(dataset_name, split=split)读取数据，再逐条构造SimpleBatchInstance。其自动生成的id为数据集名_划分名（如my_dataset_dev），会被用作默认输出目录的一部分。

完整选项见 InstancesFromHuggingFace 参考文档。

专家模式：完全自定义每个实例

如果你的需求超出上述简化格式，可以使用expert_file实例源，为每个实例指定完整的Environment、ProblemStatement和Repository配置对象：

sweagent run-batch \ ... --instances.type expert_file \ --instances.path instances.yaml

对应的instances.yaml长这样：

- env: deployment: type: docker image: python:3.11 repo: type: github github_url: "https://github.com/swe-agent/test-repo" problem_statement: type: text text: "A simple test problem" id: "simple_test_problem" - env: deployment: type: docker image: python:3.11 problem_statement: type: text text: "A simple test problem 2" id: "simple_test_problem_2"

与普通file实例源不同，ExpertInstancesFromFile直接以BatchInstance结构（env+problem_statement）校验每条记录，因此可以做到每个实例使用不同的部署配置、仓库和问题陈述，适用于需要精细控制每个任务的场景。仓库的测试用例 test_run_batch.py 验证了expert_file实例源会为每个实例生成独立的.traj文件；expert_instances.yaml 提供了可直接参考的数据样例。

完整选项见 ExpertInstancesFromFile 参考文档。

另外，源码还内置了swesmith实例源（SWESmithInstances），用于加载 SWE-smith 生成的任务；当仓库为私有仓库时会要求设置带repo权限的GITHUB_TOKEN并自动使用镜像克隆。

输出文件与后续步骤

所有生成的补丁（agent 的提交/预测）都会保存到preds.json文件。如果你中途按 Ctrl+C 中断sweagent run-batch，部分预测或该文件本身可能缺失，此时可以用sweagent merge-preds工具修复合并。

preds.json与 SWE-bench 本地运行使用的.jsonl格式非常相似，可以互相转换。将preds.json转为all_preds.jsonl：

from pathlib import Path import json preds = json.loads(Path("preds.json").read_text()) data = [{"instance_id": key, **value} for key, value in preds.items()] jsonl = [json.dumps(d) for d in data] Path("all_preds.jsonl").write_text("\\n".join(jsonl))

从源码看，merge_predictions（merge_predictions.py）会递归扫描各实例目录下的*.pred文件，要求每条预测必须包含model_patch字段（缺失则跳过并告警），重复的instance_id会直接报错，最终以{instance_id: 预测内容}的字典形式写入preds.json。

其他实用选项

• --suffix：在默认输出目录名后追加自定义后缀，便于区分多次实验。
• --env_var_path：指定.env文件加载环境变量（如 API Key）。
• --output_dir：显式指定输出目录。
• --raise_exceptions True：遇到异常时抛出而不是跳过实例，便于调试。
• --progress_bar：控制是否显示进度条（human 模型下永不显示，多 worker 下始终显示）。

下一步：想深入了解在 SWE-bench 及类似基准上运行与对比的方法，请阅读竞赛运行教程。

【免费下载链接】SWE-agentSWE-agent takes a GitHub issue and tries to automatically fix it, using your LM of choice. It can also be employed for offensive cybersecurity or competitive coding challenges. [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/sw/SWE-agent