GSO 性能优化任务指令模板全解析:从 Agent 提示词到 Harbor 评测管线

原创2026-10-11 13:18:351,741 阅读
文章标签:人工智能大模型模型评测Agent 评测AI 评测Agent 沙箱CLI本地部署

GSO 性能优化任务指令模板全解析:从 Agent 提示词到 Harbor 评测管线

本文围绕 Harbor 仓库中 GSO(Global Software Optimization)适配器所使用的任务指令模板 instruction.md,系统讲解该模板如何定义"优化 Python 仓库运行性能"的 Agent 任务:从占位符填充、任务配置、容器环境、补丁收集、性能计时到 Opt@1 评分判定的完整链路。读者读完可掌握 GSO 任务指令的每一处细节、理解 Harbor 如何将其转换为可复现的评测任务,并能独立运行整套性能优化评测。

GSO 是什么:以性能优化为核心的软件工程基准

GSO(Global Software Optimization)是一个用于评估语言模型开发高性能软件能力的基准。它从多个领域、多种编程语言的代码库中筛选出 102 个有挑战性的优化任务,每个任务提供:

  • 一个带有特定性能瓶颈的代码库(base commit);
  • 一个作为精确规格说明的性能测试脚本(prob_script);
  • 要求 Agent 生成一个补丁(patch)来提升运行时效率;
  • 以专家开发者提交的优化版本(opt_commit)作为衡量标准。

Harbor 通过 GSO → Harbor 适配器 将这一基准整体纳入 Harbor 框架,在保留原始评测逻辑的同时,把任务转换为 Harbor 统一的任务目录结构。任务的"灵魂"——写给 Agent 的指令——正是 instruction.md 这份模板。

instruction.md 模板逐段解析

GSO 的任务指令模板本身只有一份通用骨架,通过占位符机制为每个具体任务定制。模板的核心内容如下:

<uploaded_files>
/workspace/{workspace_dir_name}
</uploaded_files>
I've uploaded a python code repository in the directory {workspace_dir_name}.
Consider the following test script showing an example usage of the repository:

<test_script>
{prob_script}
</test_script>
Can you help me implement the necessary changes to the repository so that
the runtime of the <test_script> is optimized?

任务场景描述

模板先向 Agent 声明"已上传一个 Python 代码仓库",并给出一个演示仓库用法的测试脚本。Agent 被直接询问:能否修改仓库,使该测试脚本的运行时间得到优化?

这里有三个占位符会在任务生成阶段被替换:

占位符 填充内容 来源
{workspace_dir_name} 仓库名,由 record["repo"].replace("/", "__") 生成,如 huggingface__transformers 数据集记录中的 repo 字段
{prob_script} 该任务专属的性能测试脚本 数据集记录中的 prob_script 字段
{install_commands} 仓库的安装命令(经筛选处理) 数据集记录中的 install_commands 字段,经 utils.py 的 get_install_commands() 处理

这一替换逻辑实现在 adapter.py 的 _customize_task() 方法中:

workspace_dir_name = record["repo"].replace("/", "__")
prob_script = record["prob_script"]
install_commands = "\n".join(get_install_commands(gso_instance_from_dict(record)))
content = content.replace("{prob_script}", prob_script)
content = content.replace("{install_commands}", install_commands)
content = content.replace("{workspace_dir_name}", workspace_dir_name)

四条基本准则(Basic guidelines)

模板紧接着给出四条约束 Agent 行为的准则,这是任务可评测性的关键:

  1. 修改非测试文件:任务要求 Agent 修改 /workspace 目录下的非测试文件来提升 <test_script> 的性能。这一条界定了 Agent 的操作边界——测试文件是评测依据,不可改动。
  2. 保持功能等价:修改的同时必须确保仓库与原始版本功能等价。这条约束直接对应评测中"正确性/等价性检查"环节——补丁必须先通过正确性检查,才有资格参与性能评分。
  3. 不做过度优化:不要只针对 <test_script> 中的特定输入做过度优化,要为所示使用场景做通用性能改进。这保证了评测考察的是真实通用的优化能力,而非对样例输入的"应试"。
  4. 可能需要重建:修改可能需要重建仓库才能生效,部分重建耗时较长,需要耐心等待。

四步操作流程

模板把任务执行过程明确拆成四步,为 Agent 提供了可复现的工作路径:

  1. 探索仓库:熟悉仓库结构,这是任何优化的前提;
  2. 建立计时基线:在 /workspace 目录创建复现脚本(如 /workspace/test_opt.py),用 python /workspace/<filename.py> 执行并记录耗时;
  3. 修改源码:编辑仓库源代码以提升性能;
  4. 重建验证:重建后重跑脚本,确认性能确实提升。

值得注意的是,第二步要求 Agent "创建脚本计时",这正是一个强制的科学方法——先量化基线,再对比优化结果,避免主观臆断。

从模板到任务:Harbor 如何生成一个 GSO 任务

指令模板只是任务目录的一部分。使用 run_adapter.py 可以按需生成任务目录:

# 从适配器目录运行,生成全部任务
python run_adapter.py
# 或指定任务 ID 与数量
uv run run_adapter.py \
  --output-dir ../../datasets/gso \
  --task-ids <id1> <id2> \
  --limit 50

run_adapter.py 支持 --output-dir(输出目录,默认 datasets/gso)、--task-ids(显式指定源任务 ID)、--ids-file(从文本文件逐行读取 ID,支持 # 注释)和 --limit(只生成前 N 个任务)等参数。运行前它会先尝试用 uv pip install gsobench 安装依赖,失败时回退到 pip install gsobench(见 run_adapter.py 的 _install_dependencies())。

每个生成的任务目录结构如下(来自 README):

gso/
├── {task_id}/
│   ├── task.toml                 # 任务配置
│   ├── instruction.md            # 面向 Agent 的任务指令(本模板填充后的成品)
│   ├── environment/              # 容器定义
│   │   └── Dockerfile
│   ├── solution/                 # Oracle/黄金解法
│   │   └── solve.sh
│   └── tests/                    # 测试资产与脚本
│       ├── test.sh
│       ├── eval.sh
│       ├── gso_evaluate.py
│       └── gso_test_{N}.py

任务 ID 由源基准 ID 转换而来:GSOAdapter.make_local_task_id() 将 instance_123 规范化为 gso-instance-123(小写化并把下划线替换为连字符),见 adapter.py。

任务配置:task.toml 的每一处字段

生成后的 task.toml 是 Harbor 任务目录的配置文件,模板中的资源占位符({cpu_count}、{memory_mb}、{storage_mb})在生成时被替换为固定值(4 CPU、8192 MB 内存、10240 MB 存储,见 adapter.py 的 _customize_task())。其字段含义如下:

version = "1.0"

[metadata]
author_name = "Manish Shetty, Naman Jain, Jinjian Liu, Vijay Kethanaboyina, Koushik Sen, Ion Stoica"
author_email = "manishs@berkeley.edu"

difficulty = "hard"
category = "performance_optimization"
tags = ["optimization", "python"]

[verifier]
# 评测(验证)允许的最大时间(秒)
timeout_sec = 3600

[agent]
# Agent 完成任务允许的最大时间(秒)
timeout_sec = 10800

[environment]
# 构建 Docker 镜像允许的最大时间(秒)
build_timeout_sec = 600

# 容器资源限制
cpus = 4
gpus = 0
memory_mb = 8192
storage_mb = 10240

结合 Harbor 官方任务配置文档 docs-mintlify/tasks/configuration.mdx,可以理解这些字段的定位:[verifier] 段控制评测阶段(GSO 给到 1 小时的超长验证窗口,因为要多次计时)、[agent] 段控制 Agent 执行阶段(3 小时)、[environment] 段控制容器资源与构建超时。Harbor 的通用原则是尽量把环境细节下沉到 environment/ 规格中(如 Dockerfile),task.toml 只保留必要字段。

运行环境:Dockerfile 中的玄机

环境 Dockerfile 模板在生成时会被替换 {docker_image}(形如 slimshetty/gso:gso.eval.x86_64.<instance_id>)与 {workspace_dir_name}。它的关键设计包括:

  • 符号链接工作区:ln -sf /testbed /workspace/{workspace_dir_name} 把评测目录 /testbed 链接到 /workspace 下的仓库名目录,正好呼应指令模板中 <uploaded_files> 声明的路径;
  • 环境变量就绪:激活 /testbed/.venv 虚拟环境、预置 PYTHONPATH、关闭 uv 与 pip 缓存(UV_NO_CACHE=1、PIP_NO_CACHE_DIR=1);
  • 独立评测环境:额外创建 /opt/gso-venv(Python 3.12)并安装 gsobench,用于运行评测脚本 gso_evaluate.py,把"评测"与"被测仓库"的 Python 环境隔离,避免污染。

补丁收集与评测:从 test.sh 到 gso_evaluate.py

Agent 完成任务后,Harbor 会执行 tests/test.sh 来收集补丁并触发评测。其核心流程:

  1. 导出工作区改动:git add -A 后从暂存区生成 patch.diff,并用 clean_git_patch()(awk 实现)清理非 diff 行、剔除二进制文件,保证补丁干净可应用;
  2. 空补丁短路:若补丁为空,直接写入 reward: 0 与 {"status": "empty_patch", "opt_commit": false} 结果并退出;
  3. 运行评测:执行 /tests/eval.sh,把输出完整记录到日志;
  4. 调用评分器:用 /opt/gso-venv/bin/python /tests/gso_evaluate.py 解析评测日志,产出最终奖励。

eval.sh:三方计时的编排

eval.sh 并非模板文件,而是由 utils.py 的 get_eval_script() 在任务生成时动态构造的。它编排了三条计测主线:

  • base 基线:git checkout {base_commit} 后安装、计时——得到优化前的性能;
  • patch 候选:apply_patch "/tmp/patch.diff" 后安装、计时——得到 Agent 补丁的性能;
  • commit 专家参考:git checkout {opt_commit} 后安装、计时——得到专家优化提交的性能。

其中 install_repo 是脚本内定义的辅助函数,来自 INSTALL_HELPER 模板,逐条执行筛选后的安装命令;RUN_BASE/RUN_PATCH/RUN_COMMIT 则用 timeit 循环执行性能测试。脚本还对每段计时输出打上独特的起止标记(如 START_BASE_OUTPUT/END_BASE_OUTPUT),供评分器解析。此外脚本内部做了一些兼容性处理:把 git clean -xfd 从安装命令中剔除(避免删除结果文件)、重置远程 origin 失败容忍(|| true)、固定 setuptools<82(保护旧 setup.py 项目的 pkg_resources)并禁用 HF Hub Xet 后端。

gso_evaluate.py:Opt@1 的判定逻辑

tests/gso_evaluate.py 是最终的评分入口,它调用 gso.harness.grading.metrics.get_eval_report() 获取评测报告,然后按优先级推导任务状态:

状态 触发条件
empty_patch 补丁为空(patch_is_None)
base_failed base 基线未能成功运行
patch_failed 补丁未能成功应用
test_failed 补丁未通过正确性测试
passed 以上均通过

最终奖励为:reward = 1 if opt_commit else 0,结果 JSON 还附带 opt_base、time_stats、opt_stats 供深入分析。

Opt@1 指标怎么算

根据 README 的详细说明,Opt@1 是"单次 rollout 被判定达到专家优化标准的任务百分比"。单个任务的判定流程是:

  1. 评测框架对三个版本分别计时:base 提交、Agent 补丁后的版本、参考优化提交 opt_commit;
  2. 补丁必须先通过正确性/等价性检查;
  3. opt_base=True:补丁版本比 base 更快,且相对 base 的几何平均加速比(保留一位小数)至少达到 1.2x;
  4. opt_commit=True:在前者基础上,补丁版本相对专家提交的调和平均加速比高于 0.95,即性能在专家水平的约 5% 以内。

README 还提示:由于这是墙钟计时基准且样本量小(大多数仓库 timeit 的 number=1 仅重复 5 次,重型仓库甚至只 1 次),CPU 负载、资源争用或降频都可能让耗时跨越 1.2 或 0.95 的硬阈值,从而翻转 opt_commit 与 Opt@1。

在 Harbor 中运行 GSO 评测

生成任务目录后,即可用 Harbor 的标准命令执行评测(以下命令均来自 README):

# 用 oracle agent(参考解法)评测整个数据集
uv run harbor run -d gso

# 指定 Agent 与模型
uv run harbor run -d gso -a <agent_name> -m "<model_name>"

# 使用任务配置 YAML
uv run harbor run -c adapters/gso/run_gso.yaml -a <agent_name> -m "<model_name>"

# 使用本地准备的数据集路径
uv run harbor run -p datasets/gso -a <agent_name> -m "<model_name>"

# 恢复之前中断的 job
uv run harbor job resume -p /path/to/jobs/directory

任务结果默认保存在 jobs/ 目录(可通过 YAML 中的 jobs_dir 配置)。快速调试单个任务则用:

# 单个任务 + oracle 参考解法
uv run harbor trial start -p datasets/gso/<task_id>

# 单个任务 + 指定 Agent 与模型
uv run harbor trial start -p datasets/gso/<task_id> -a <agent_name> -m "<model_name>"

单任务结果默认保存在 trials/ 目录(可用 --trials-dir 修改)。

run_gso.yaml 的关键配置

run_gso.yaml 是官方提供的评测配置:

jobs_dir: jobs
n_attempts: 1
timeout_multiplier: 1.0
n_concurrent_trials: 10
quiet: false
environment:
  type: daytona
  delete: true
agents:
  - name: openhands
    model_name: gpt-5.1
    kwargs:
      version: 1.4.0
datasets:
  - path: datasets/gso

对照 Harbor 的 Job 配置模型 src/harbor/models/job/config.py 可以理解这些字段:n_concurrent_trials 控制最大并发 trial 数(JobConfig 中默认 4,此处调为 10),n_attempts 是每个任务的重试次数,timeout_multiplier 是任务超时倍率,environment.type: daytona 表示在 Daytona 云运行时中执行且结束后删除环境(delete: true)。

Parity 验证:与原始基准的一致性

适配器是否忠实还原了原基准,需要数据说话。根据 parity_experiment.json 与 README 的记录,团队使用 OpenHands@1.4.0 + gpt-5.1-2025-11-13 (high)、运行 2 次、覆盖全部 102 个任务(100% 采样率),得到:

Agent 模型 指标 运行次数 数据集规模 原基准性能 Harbor 适配器性能
OpenHands@1.4.0 gpt-5.1-2025-11-13 (high) Opt@1 2 102 任务(100%) 13.7% ± 1.0% 13.2% ± 1.5%

该结果说明适配后性能与原基准保持一致(差异处于波动范围)。同时 adapter_metadata.json 记录了更完整的元数据:适配规模 102、parity 采样率 1.0、parity 成本 600(美元)、parity 匹配 Agent 为 OpenHands@1.4.0+gpt-5.1-2025-11-13 (high)。

复现 parity 实验只需:

uv run harbor run -c adapters/gso/run_gso.yaml

已知注意事项

README 明确列出了几项使用限制,引用时需注意:

  1. Oracle 并非 100% 通过:由于部分任务的 oracle 相对基线并不总是更快,Harbor 中 oracle agent 通过了 102 个任务中的 89 个(87.3% 通过率)。
  2. 性能波动:运行时环境差异、测量随机性会导致结果波动(机制见上文 Opt@1 小节)。
  3. 降低波动的建议:多跑几次并取平均;使用足够 RAM/CPU 的机器(推荐 64 CPU、256 GB 内存)或 Daytona 云运行时;所有运行与 Agent 对比使用同一台机器;降低并发(--n-concurrent)以减少资源争用;尽量保持环境一致(避免其他重型进程)。

环境准备与故障排查

运行 GSO 评测前需满足(来自 README):

  • Docker 已安装并运行;
  • Harbor 已安装可正常工作;
  • Python 环境依赖:uv sync --extra dev;
  • Agent/模型 API 密钥以环境变量形式导出:设置 LLM_API_KEY 与 LLM_BASE_URL;
  • 复现 parity 实验时还需设置:
export OPENHANDS_AGENT_ENABLE_JUPYTER="false"
export OPENHANDS_MAX_ITERATIONS=150

已知问题:若使用 Daytona 环境,OpenHands 启动时偶发 Connection refused 错误,需要重跑该任务。

小结

GSO 的 instruction.md 表面上只是一份简短的 Agent 提示词,但它是整个评测链路的"总纲":它定义了任务目标(优化运行时)、约束(功能等价、不过度优化)、边界(只改非测试文件)与科学流程(先计时、再优化、后验证)。Harbor 适配器通过占位符注入将这份模板实例化为 102 个具体任务,并配套 task.toml 资源配额、Dockerfile 双虚拟环境隔离、test.sh 补丁收集、eval.sh 三方计时与 gso_evaluate.py 的 Opt@1 判定,最终以 uv run harbor run -c adapters/gso/run_gso.yaml 一键复现与原始基准一致的评测。若要在自己的性能优化评测中复刻这套方法,instruction.md 的四步流程与 1.2x/0.95 双重阈值判定是最值得借鉴的两个设计。

登录后查看全文
harbor