Harbor 中的 KramaBench 任务指令模板:从提示设计到端到端数据科学 Agent 评测
Harbor 中的 KramaBench 任务指令模板:从提示设计到端到端数据科学 Agent 评测
KramaBench 是 MIT 团队提出的用于评测端到端数据科学 Agent 的基准,要求系统在真实数据湖上自主完成"数据发现—数据清洗—统计分析—产出答案"的完整流水线。本文以 Harbor 仓库中 KramaBench Adapter 的任务指令模板(instruction.md)为核心,完整讲解该模板的三段式提示结构、Jinja2 渲染机制、配套的 task.toml 配置、Docker 环境构建、评测打分流程,以及如何用 harbor jobs / harbor trials 在实际环境中运行评测并对齐原始基准结果。读完本文,你将掌握 KramaBench 任务在 Harbor 中从"指令生成"到"结果产出"的完整链路,并具备自行运行与复现评测的能力。
KramaBench 任务指令模板:三段式提示骨架
每个 KramaBench 任务的 Agent 输入(即 instruction)由模板 instruction.md 定义。模板全文非常精炼,只包含三个 Jinja2 占位符:
Under `/app/data`, consider the following files for analysis:
{{data_file_list}}
{{question}}
Save your {{answer_type}} answer AND NOTHING ELSE in the file `/app/answer.txt`.
模板由三个语义部分构成:
- 数据清单(data_file_list):告诉 Agent 在容器内
/app/data目录下应该关注哪些数据文件,渲染后形如* file_a.csv逐行列出; - 问题(question):来自原基准 workload JSON 中的
query字段的自然语言任务描述; - 答案类型(answer_type):要求 Agent 将最终答案且仅将答案写入
/app/answer.txt,并明确答案的类型约束。
这一"列出文件 → 提出问题 → 固定答案输出位置与格式"的提示骨架,正是 KramaBench 与其他问答类基准的关键差异:它不要求 Agent 输出推理过程或代码,只要求交付最终答案文件,而"如何找到数据、如何清洗、如何计算"全部由 Agent 自主决定,评测端则通过独立的分值函数来验证答案质量。
答案类型映射与严格校验
模板中的 answer_type 占位符不是随意文本,而是由 Adapter 中 adapter.py 定义的 ANSWER_TYPES 字典精确映射:
ANSWER_TYPES = {
"numeric_exact": "EXACT NUMERIC",
"string_exact": "EXACT STRING",
"list_exact": "list (one item per line)",
"numeric_approximate": "numeric",
"string_approximate": "string",
"list_approximate": "list (one item per line)",
}
映射关系覆盖六种题型:精确/近似数值、精确/近似字符串、精确/近似列表。Adapter 在生成任务时会断言 answer_type in ANSWER_TYPES,未知类型直接报错,保证指令文本与后续评测器(evaluate.py)对答案的解析逻辑严格一致——例如 list 类答案按换行拆分、numeric 类答案尝试转 int/float。
模板渲染:Jinja2 定制每个任务
指令模板不是静态文件,而是由 Adapter 在生成任务目录时用 Jinja2 逐任务渲染的。在 adapter.py 的 generate_task 中,Adapter 从克隆的 KramaBench 仓库的 workload/*.json(排除 quick-start-questions.json 与 legal-tiny.json)加载每个问题的 query、answer、deepresearch_subset(相关数据文件子集)与 answer_type,构造如下渲染记录:
record = {
"source_id": source_id,
"dataset_base_image": f"ghcr.io/michaelrglass/kramabench-{domain}:1.0",
"data_file_list": "* " + "\n* ".join(data_sources),
"question": question,
"answer_type": ANSWER_TYPES[answer_type],
"gold_hypo": answer,
"difficulty": difficulty,
"domain_tag": domain,
"answer_type_tag": answer_type,
}
值得注意的细节:
- 数据源归一化:
WeatherEvents_Jan2016-Dec2022_part_*这类分片文件名会被统一映射为完整的WeatherEvents_Jan2016-Dec2022.csv,避免向 Agent 暴露分片细节; - 困难度推断:从
source_id中解析(如xxx-hard-1中的hard),无法解析时回退为medium; - 答案写入:list 类答案被拼接为每行一项的字符串,且检查答案中不含
EOFHYPO分隔符,避免污染 oracle 脚本; - 渲染文件范围:
instruction.md、task.toml、solution/solve.sh、environment/Dockerfile、tests/test.sh五个文件都会用该记录渲染,并额外写出template_fillers.json便于追溯填充内容。
生成的任务目录结构
渲染完成后,每个任务在 datasets/kramabench/{task_id}/ 下形成独立目录,结构如下(详见 README.md):
kramabench/{task_id}/
├── task.toml # 任务配置(超时、资源、验证器)
├── instruction.md # 渲染后的 Agent 指令
├── environment/ # 容器定义
│ └── Dockerfile
├── solution/ # Oracle 参考解
│ └── solve.sh
└── tests/ # 评测资产
├── benchmark/ # 原基准评测代码
├── workload.json # 该任务的原始 workload 数据
├── test.sh # 评测执行脚本
└── evaluate.py # Python 评测脚本
任务 ID 由 KramaBenchAdapter.make_local_task_id 生成:源码 ID 小写化并将下划线替换为连字符,如 instance_123 → kramabench-instance-123。
task.toml:任务级配置参数
每个任务目录中的 task.toml 模板定义了任务运行的关键约束,全部参数在生成时随任务渲染:
| 参数 | 默认值 | 说明 |
|---|---|---|
metadata.difficulty |
{{difficulty}} |
任务难度:easy / medium / hard |
metadata.category |
data-science |
任务类别 |
metadata.tags |
— | 过滤标签,含数据加工、编码、答案类型与领域标签 |
verifier.timeout_sec |
300.0 |
评测(验证)阶段最大耗时(秒) |
agent.timeout_sec |
600.0 |
Agent 完成任务的最大耗时(秒) |
environment.build_timeout_sec |
600.0 |
Docker 镜像构建最大耗时(秒) |
environment.cpus |
1 |
容器分配的 CPU 核数 |
environment.memory_mb |
4096 |
容器内存上限(MB) |
environment.storage_mb |
10240 |
容器存储上限(MB) |
verifier.env.OPENAI_API_KEY |
${OPENAI_API_KEY} |
评测使用的 LLM 密钥(LLM-as-judge 需要) |
其中 verifier.timeout_sec 与 agent.timeout_sec 直接决定评测的成败边界:Agent 超时会被记录为 AgentTimeoutError,验证超时则可能触发重试机制。从 parity 运行日志看,真实运行中确实出现过 AgentTimeoutError 与 AgentSetupTimeoutError 异常,说明超时参数是影响最终得分的实际约束。
环境构建:基础镜像与评测镜像
KramaBench 的 104 个任务共享约 1.7 GB 数据(1,764 个文件,来自 24 个数据源),因此 Adapter 采用基础镜像 + 评测层的两级镜像策略,而不是把数据塞进每个任务目录。
数据基础镜像
六个领域(archeology、astronomy、biomedical、environment、legal、wildfire)各构建一个包含该领域全部输入数据的基础镜像 ghcr.io/michaelrglass/kramabench-${domain}:1.0。构建脚本见 dataset_base_images/Dockerfile:以 t-bench/python-3-13 为基础,通过 --build-arg DOMAIN 指定领域,将 kramabench_repo/data/${DOMAIN}/input/ 拷贝到 /app/data,并预装 pandas、numpy、scikit-learn、sympy、matplotlib、statsmodels、openpyxl、pyarrow、lxml 等数据科学依赖及 uv。数据获取(克隆仓库、下载 Kaggle 数据集)由 get_data.py 完成,镜像已预构建并推送,日常运行 Adapter 无需重复构建。
任务环境镜像
每个任务的 environment/Dockerfile 基于对应领域的基础镜像,仅追加评测依赖层:
FROM {{dataset_base_image}}
# Pre-build the test venv
COPY pyproject.toml uv.lock /tests-seed/
RUN cd /tests-seed && uv sync --frozen && mv .venv /tests-venv && rm -rf /tests-seed
WORKDIR /app
评测用 Python 虚拟环境在镜像构建期就预先同步完成(uv sync --frozen),评测时无需再装依赖,显著缩短了单任务验证时间。
评测链路:从 answer.txt 到奖励分数
评测阶段由 tests/test.sh 与 tests/evaluate.py 完成:
cd /tests
mkdir -p /logs/verifier
export PYTHONPATH=/tests
/tests-venv/bin/python evaluate.py {{source_id}}
evaluate.py 的核心流程是:
- 读取
/app/answer.txt(Agent 的输出,若不存在则尝试/app/output/answer.txt),并对 answer 做strip(); - 加载该任务的
workload.json,取 gold 答案与answer_type; - 按答案类型把答案字符串转换(list 按行拆分、numeric 尝试 int/float);
- 调用原基准的
Evaluator._evaluate_result_for_task计算得分; - 从五种分值中选取唯一的有效类型——
success(精确匹配)、llm_paraphrase(ParaPluie 同义改写检测)、f1、f1_approximate、rae_score(相对绝对误差)——并将布尔值归一化为 0/1,最后写入/logs/verifier/reward.txt,作为 Harbor 的 reward(0–1)。
评分规则一览
| 类型 | 示例问题 | 度量 | 打分 |
|---|---|---|---|
| 字符串(精确) | 要加载的文件名 | Accuracy | 0 / 1 |
| 字符串(近似) | 实验开始的月份 | ParaPluie 改写检测 | 0 / 1 |
| 数值(精确) | 满足谓词的条目计数 | Accuracy | 0 / 1 |
| 数值(近似) | 未来实验观测的预测 | RAE:|ŷ − y| / |y| | 1 / (1 + RAE) |
| 列表(精确) | 要过滤的列名 | F1(精确匹配) | F1 |
| 列表(近似) | 各变量的回归系数 | F1(近似匹配 > 0.9) | F1 |
Oracle 参考解
模板 solution/solve.sh 是 oracle 解:把 gold 答案直接写入 /app/answer.txt。README 与 parity 文档均确认,在 104 个任务上 oracle 全部获得 reward = 1.0(104/104),说明评测链路本身无漏报。
实战运行:从 Adapter 生成到评测执行
方式一:直接使用数据集 Registry(推荐)
在仓库根目录执行:
# 使用 oracle agent(参考解)
uv run harbor jobs start -d kramabench
# 使用指定 Agent 与模型
uv run harbor jobs start -d kramabench -a <agent_name> -m "<model_name>"
方式二:本地生成任务目录后运行
先生成任务目录:
cd adapters/kramabench
python run_adapter.py
# 或按需指定任务与数量
uv run run_adapter.py \
--output-dir ../../datasets/kramabench \
--task-ids <id1> <id2> \
--limit 50
run_adapter.py 默认从 GitHub 克隆 KramaBench 仓库到临时目录后完成转换;也可以 --no-clone-kramabench --kramabench-root <本地路径> 复用已有仓库(两者不可同时指定)。--task-ids、--ids-file、--limit 支持按 ID 白名单、ID 文件或数量限制生成子集。
随后用配置文件或数据集路径运行评测:
# 使用默认适配器配置
uv run harbor jobs start -c adapters/kramabench/kramabench.yaml -a <agent_name> -m "<model_name>"
# 使用本地准备的数据集路径
uv run harbor jobs start -p datasets/kramabench -a <agent_name> -m "<model_name>"
# 恢复之前的 job
uv run harbor jobs resume -p /path/to/jobs/directory
# 单任务快速调试
uv run harbor trials start -p datasets/kramabench/<task_id> -a <agent_name> -m "<model_name>"
默认配置 kramabench.yaml 中可关注:n_attempts: 1(每任务尝试次数)、timeout_multiplier: 1.0、local orchestrator 串行执行(n_concurrent_trials: 1)、Docker 环境 force_build: true 与 delete: true,以及默认的 OpenHands + anthropic/claude-sonnet-4-5 组合。job 结果默认保存在 jobs/,trial 输出默认在 trials/,均可在配置或命令行覆盖。
与原始基准的一致性验证(Parity)
Adapter 团队用 OpenHands v1.1.0 + Claude Sonnet 4.5 在原始 KramaBench 评测框架与 Harbor Adapter 上各独立运行 3 次(每次覆盖全部 104 个任务),对比结果(详见 parity_experiment.json):
| Agent | 模型 | 指标 | 原始基准性能 | Harbor Adapter 性能 |
|---|---|---|---|---|
| OpenHands 1.1.0 | claude-sonnet-4-5 | 平均奖励(%) | 64.9 ± 0.9 | 62.8 ± 2.3 |
置换检验(parity/README.md)结果显示无显著差异(diff = 0.018,p = 0.48),分层 Bootstrap 95% 置信区间亦相互重叠,从统计上确认 Harbor 适配没有改变任务的难度分布。
复现时,原始端需使用带 OpenHands SUT 的 KramaBench fork 逐个领域跑 python evaluate.py --sut OpenHands --workload <domain>,再用 convert_to_harbor_results.py 把 CSV 结果转换为 Harbor result.json 格式(其分值优先级 success → llm_paraphrase → f1 → f1_approximate → rae_score 与 evaluate.py 保持一致);Harbor 端则用 harbor run -p ./datasets/kramabench --agent openhands ... --n-concurrent 1。两条链路的详细运行日志与统计输出都记录在 parity 目录中。
前置条件与注意事项
- OPENAI_API_KEY 必需:KramaBench 评测包含 LLM-as-judge(如 ParaPluie 改写检测),因此运行评测前必须在环境中配置
OPENAI_API_KEY,task.toml 中[verifier.env]已预留该变量透传; - Docker 网络资源:长时间大规模评测可能耗尽 Docker 默认网络,建议定期
docker network prune,必要时在/etc/docker/daemon.json中扩大默认地址池:{ "default-address-pools": [ {"base": "172.17.0.0/12", "size": 24} ] } - 镜像命名:当前数据基础镜像推送到
ghcr.io/michaelrglass/kramabench-${domain}:1.0,README 指出后续应迁移到ghcr.io/laude-institute/t-bench/kramabench-${dataset}:1.0,如果你需要自建镜像,可参考 dataset_base_images/README.md 的构建流程。
小结
从 instruction.md 的三段式提示骨架出发,本文完整梳理了 KramaBench Adapter 在 Harbor 中的实现链路:Adapter 从原始 workload 提取问题、数据子集与答案类型,经 Jinja2 渲染产出任务指令与配置;Docker 双层镜像策略承载约 1.7 GB 的多领域数据;评测端以 /app/answer.txt 为唯一接口,按六种题型计算 0–1 奖励;最后通过 parity 实验从统计上验证了适配保真度。这套模式对任何"数据密集型 + LLM 判分"的端到端 Agent 基准迁移到 Harbor 都有直接的参考价值。