Harbor 中的 KramaBench 任务指令模板:从提示设计到端到端数据科学 Agent 评测

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

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`.

模板由三个语义部分构成:

  1. 数据清单(data_file_list):告诉 Agent 在容器内 /app/data 目录下应该关注哪些数据文件,渲染后形如 * file_a.csv 逐行列出;
  2. 问题(question):来自原基准 workload JSON 中的 query 字段的自然语言任务描述;
  3. 答案类型(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 的核心流程是:

  1. 读取 /app/answer.txt(Agent 的输出,若不存在则尝试 /app/output/answer.txt),并对 answer 做 strip();
  2. 加载该任务的 workload.json,取 gold 答案与 answer_type;
  3. 按答案类型把答案字符串转换(list 按行拆分、numeric 尝试 int/float);
  4. 调用原基准的 Evaluator._evaluate_result_for_task 计算得分;
  5. 从五种分值中选取唯一的有效类型——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 都有直接的参考价值。

登录后查看全文
harbor