BenchSpan

BenchSpan 是什么？

BenchSpan 帮助团队以更快、更易复现且更易分享的方式运行 AI agent 基准测试。与手动将 agent 接入不同基准框架并将结果复制到散乱文件中不同，BenchSpan 标准化基准执行，并将得分、错误和耗时汇总到有序的运行历史中。

其核心目的是减少运行基准套件（包括数百实例的大规模扫描）的时间和成本，同时通过将运行绑定到 agent 的提交哈希并便于并排比较运行来提升结果的可信度。

主要特性

• 通过 shell 脚本标准化 agent 设置的基准运行器：BenchSpan 可运行通过 bash 命令启动的 agent，减少胶水代码和框架特定接口工作。
• 内置基准库，支持自带基准：可从内置基准集中选择，或使用您提供的基准定义。
• 使用隔离 Docker 容器的并行执行：每个基准实例在独立 Docker 容器中运行，并可并行执行，大幅加速大规模套件的完成时间。
• 自动捕获并组织结果：BenchSpan 捕获得分、轨迹、错误和耗时，并组织好以便后续比较。
• 带提交标签的运行，便于复现和比较：结果标记 agent 的提交哈希，便于团队比较不同运行并了解哪些代码产生哪些数据。
• 仅重跑失败实例：如果运行中出现部分失败（如某些实例的网络错误或限流），可仅重试失败子集，而非重跑全部。

如何使用 BenchSpan

1. 接入您的 agent：编写启动 agent 的 bash 脚本，然后指向 BenchSpan。
2. 选择基准：从 BenchSpan 库中选择，或使用您提供的基准。
3. 运行套件：设置实例数量并启动运行；BenchSpan 使用 Docker 容器并行执行实例。
4. 查看结果：在有序输出中审视结果，使用提交哈希标签比较运行。如有实例失败，仅重跑那些失败实例。

使用场景

• 开发中比较 agent 迭代：更新提示或 agent 代码后运行基准套件，比较不同提交的解决率和失败模式。
• 大规模 SWE 式评估，覆盖数百实例：执行顺序运行不切实际的大型基准套件，并行 Docker 执行缩短总时长。
• 部分失败时无需从头开始恢复：某些实例因限流或超时失败时，仅重跑失败实例，而非重复完整套件。
• 团队协作基准声明：分享单一基准运行记录，避免结果散失在独立表格或聊天消息中。
• 测试不同底层提示或配置的 agent：通过带提交标签的运行追踪哪个提示版本和代码提交产生哪些结果，避免“哪个配置”的争议。

常见问题

• BenchSpan 支持哪些类型的 agent？ 站点说明“任何通过 bash 运行的 agent”均可，即用 shell 命令启动 agent，BenchSpan 将通过此方式集成。

• 基准是顺序运行还是并行运行？ BenchSpan 并行运行基准实例，每个实例隔离在独立 Docker 容器中。

• BenchSpan 如何处理失败运行？ 如果某些实例失败，BenchSpan 可仅重跑失败实例，而非要求重启整个套件。

• 结果如何组织以便比较？ 结果（得分、轨迹、错误和耗时）被捕获并组织，并标记 agent 的提交哈希，便于并排比较。

替代方案

• 本地或单机基准脚本：在笔记本电脑上运行基准套件初期可能更简单，但工作流较慢，且结果往往零散，除非自行构建跟踪和可复现工具。
• 使用 Docker 和自定义适配器的手动编排：可通过容器并行化并为每个基准编写胶水代码，但仍需实现接口适配、恢复逻辑和集中结果历史。
• 临时表格/Notion/Slack 结果记录：将数字复制到共享文档适用于小型实验，但无法自动提供标准化运行管理、提交标签历史或结构化比较。