GSO 性能优化任务指令模板全解析:从 Agent 提示词到 Harbor 评测管线
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 行为的准则,这是任务可评测性的关键:
- 修改非测试文件:任务要求 Agent 修改
/workspace目录下的非测试文件来提升<test_script>的性能。这一条界定了 Agent 的操作边界——测试文件是评测依据,不可改动。 - 保持功能等价:修改的同时必须确保仓库与原始版本功能等价。这条约束直接对应评测中"正确性/等价性检查"环节——补丁必须先通过正确性检查,才有资格参与性能评分。
- 不做过度优化:不要只针对
<test_script>中的特定输入做过度优化,要为所示使用场景做通用性能改进。这保证了评测考察的是真实通用的优化能力,而非对样例输入的"应试"。 - 可能需要重建:修改可能需要重建仓库才能生效,部分重建耗时较长,需要耐心等待。
四步操作流程
模板把任务执行过程明确拆成四步,为 Agent 提供了可复现的工作路径:
- 探索仓库:熟悉仓库结构,这是任何优化的前提;
- 建立计时基线:在
/workspace目录创建复现脚本(如/workspace/test_opt.py),用python /workspace/<filename.py>执行并记录耗时; - 修改源码:编辑仓库源代码以提升性能;
- 重建验证:重建后重跑脚本,确认性能确实提升。
值得注意的是,第二步要求 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 来收集补丁并触发评测。其核心流程:
- 导出工作区改动:
git add -A后从暂存区生成patch.diff,并用clean_git_patch()(awk 实现)清理非 diff 行、剔除二进制文件,保证补丁干净可应用; - 空补丁短路:若补丁为空,直接写入
reward: 0与{"status": "empty_patch", "opt_commit": false}结果并退出; - 运行评测:执行
/tests/eval.sh,把输出完整记录到日志; - 调用评分器:用
/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 被判定达到专家优化标准的任务百分比"。单个任务的判定流程是:
- 评测框架对三个版本分别计时:base 提交、Agent 补丁后的版本、参考优化提交
opt_commit; - 补丁必须先通过正确性/等价性检查;
opt_base=True:补丁版本比 base 更快,且相对 base 的几何平均加速比(保留一位小数)至少达到 1.2x;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 明确列出了几项使用限制,引用时需注意:
- Oracle 并非 100% 通过:由于部分任务的 oracle 相对基线并不总是更快,Harbor 中 oracle agent 通过了 102 个任务中的 89 个(87.3% 通过率)。
- 性能波动:运行时环境差异、测量随机性会导致结果波动(机制见上文 Opt@1 小节)。
- 降低波动的建议:多跑几次并取平均;使用足够 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 双重阈值判定是最值得借鉴的两个设计。