Harbor AutoCodeBench 适配器实战:20 语言代码生成基准的 Agent 化评测全解析
Harbor AutoCodeBench 适配器实战:20 语言代码生成基准的 Agent 化评测全解析
AutoCodeBench 是一个覆盖 20 种编程语言、强调高难度真实场景的代码生成基准。本指南以 Harbor 仓库中的 AutoCodeBench 适配器文档 为主体,完整讲解如何将 AutoCodeBench 的 200 个任务(AutoCodeBench-Lite200)转换并接入 Harbor 评测框架,涵盖任务生成、Docker 环境构建、Oracle 校验、命令行运行方式与 Parity 一致性验证。读完本文,你将掌握从 HuggingFace 数据集到 Harbor task.toml 任务目录的完整转换链路,能够独立生成数据集、运行单次 Trial 与全量 Job,并复现该适配器与原基准之间的一致性验证实验。
AutoCodeBench 基准与 Harbor 适配概览
AutoCodeBench 是一个大规模代码生成基准,用于评估 LLM 在困难、真实世界编码问题上的代码生成能力,共包含 3,920 道题目,覆盖 20 种编程语言(包括 Python、Java、C++、Go、Rust、JavaScript 等),以单元测试驱动的 pass@k 指标衡量代码正确性。该基准由论文 "AutoCodeBench: Large Language Models are Automatic Code Benchmark Generators" 提出(论文编号 arXiv:2508.09101)。
Harbor 适配器将 AutoCodeBench 任务转换为 Harbor 标准评测格式,核心定位是把原本面向"直接 LLM 提示"的基准,改造为面向 Agent 化评测(agentic evaluation)的基准。本适配器包含 200 个任务,取自 AutoCodeBench-lite 子集(HuggingFace 数据集 tencent/AutoCodeBenchmark 的 autocodebench_lite split),每个语言 10 个任务。
从 adapter_metadata.json 可以确认适配的量化信息:autocodebench_lite 原始 split 共 1,586 个任务,适配后的 benchmark 规模为 1,586,其中 Parity 与 registry 使用的基准规模为 200,抽样率为 0.126(200/1586),支持的 agent 为 openhands。
抽样策略
HuggingFace 的 autocodebench_lite 子集共有 1,586 个任务。适配器按语言分组,每个语言取前 10 个任务(由 --max-per-language 控制,默认 10),形成 20 语言 × 10 = 200 任务的均衡子集。README 明确指出,这些任务被判定为"可稳定求解"(consistently solvable),是对完整基准的精选子集。
主要适配改动
README 概括了四项关键改造:
- 格式转换:从 JSONL 格式转换为 Harbor 标准目录结构(
task.toml、instruction.md、Dockerfile 等); - 评测范式适配:从直接 LLM 提示评测改为面向 Agent 的评测;
- 环境整合:将全部 20 种语言环境整合进每个任务单一的 Dockerfile;
- Oracle 校验:通过
solution/solve.sh提供参考解用于验证。
适配器功能特性
README 总结了适配器的六大能力,结合源码可进一步确认其实现:
| 特性 | 说明 | 源码依据 |
|---|---|---|
| 自动数据管理 | 从 HuggingFace 下载 tencent/AutoCodeBenchmark 数据集,或使用本地 JSONL 文件 |
main.py 的 --jsonl / --use-huggingface 互斥参数 |
| 全面任务生成 | 将 AutoCodeBench-Lite200 的 200 个任务转换为 Harbor 标准格式 | adapter.py 的 generate_task() |
| Docker 化环境 | 每个任务包含支持 20 种语言及所需工具链的 Dockerfile | Dockerfile 模板 |
| Oracle 参考解 | 提供 solution/solve.sh 参考解用于验证 |
solve.sh 模板 |
| 自动化评测脚本 | 通过 tests/test.sh 运行基准单元测试 |
test.sh 模板 |
| 灵活筛选 | 支持按语言、任务 ID 筛选,或限制生成任务数量 | adapter.py 的 run(task_ids=, limit=) |
生成的 Task 目录结构
适配器为每个任务生成如下目录结构(README 原样给出):
autocodebench/
├── {task_id}/
│ ├── task.toml # Terminal-Bench task configuration
│ ├── instruction.md # Task instructions for the agent
│ ├── environment/ # Container definition
│ │ └── Dockerfile
│ ├── solution/ # Oracle/golden solution
│ │ └── solve.sh
│ └── tests/ # Test assets and scripts
│ └── test.sh # Test execution script
其中 task_id 的命名规则可在 adapter.py 中找到实现:task_id = f"{language}_{lang_counts<a href="https://link.gitcode.com/i/ce713f890032f6fd8ab1d319c797d432" target="_blank">language]:03d}",即 python_001、cpp_010 这类格式。从仓库根目录的 [registry.json 可见该适配器实际注册的 200 个任务即按此命名(如 autocodebench-python-001、autocodebench-rust-010 等),其 path 字段均指向 datasets/autocodebench/<task_id>。
值得注意的是,registry.json 中实际出现的 20 种语言前缀为:cpp、csharp、dart、elixir、go、java、javascript、julia、kotlin、perl、php、python、r、racket、ruby、rust、scala、shell、swift、typescript。这与 README Notes 中列举的语言清单(含 Haskell、Lua)略有出入——从仓库实际注册数据看,最终落地的 20 种语言以 registry.json 为准(Racket 与 Shell 取代了 Haskell 与 Lua),读者在使用时需留意这一差异。
适配器代码目录
harbor/adapters/autocodebench/
├── README.md
├── parity_experiment.json
├── run_autocodebench.yaml
├── pyproject.toml
├── uv.lock
└── src/autocodebench/
├── adapter.py
├── main.py
└── task-template/
├── environment/Dockerfile
├── solution/solve.sh
├── task.toml
└── tests/test.sh
其中 pyproject.toml 声明了打包入口:autocodebench = "autocodebench.main:main",使得安装后可直接通过 uv run autocodebench 调用(见 pyproject.toml)。
从源码看适配实现原理
数据模型与抽样逻辑
adapter.py 用 dataclass AutoCodeBenchItem 承载原始 JSONL 记录的核心字段:
task_id/language/difficulty:任务标识、语言与难度;question:题目描述;canonical_solution:标准解(Oracle 解);demo_test_func/full_test_func:演示测试与完整测试函数代码。
_load_items()(adapter.py)实现逐语言抽样:遍历数据集记录,按 language 字段计数,当某语言已选满 max_per_language 个后即跳过后续记录,从而保证每个语言恰好取前 N 个任务。该函数同时支持两条数据路径:本地 JSONL(逐行 json.loads)与内存 dataset(可迭代对象)。
任务写入流程
generate_task()(adapter.py)负责完整的目录生成,逻辑为:
- 若任务目录已存在则先清空(避免残留旧文件);
- 创建
environment/、solution/、tests/三个子目录; - 依次写入
instruction.md、task.toml、Dockerfile、solve.sh、test.sh。
run()(adapter.py)是标准适配器入口:按 task_ids 或 limit 过滤后逐个生成,overwrite=True 时可覆盖已有任务目录,并返回成功生成数量。
instruction.md 的输出格式约束
_write_instruction()(adapter.py)生成的任务指令明确要求 Agent:
Solve the problem and write ONLY the final code to `solution.txt`.
Do not include code fences, tests, commands, or commentary.
即 Agent 必须把最终代码仅写入 /app/solution.txt,且不得包含代码围栏、测试、命令或注释。这是后续验证环节读取 solution.txt 的前提。
task.toml 模板解析
task.toml 模板 定义了 Harbor/ Terminal-Bench 任务配置,生成时由 adapter.py 用真实值替换 {task_id}、{difficulty}、{language}、{keywords} 四个占位符。模板要点:
[task]:任务名tencent/autocodebench__{task_id},keywords 为["autocodebench", <language>],并列出 AutoCodeBench 论文全部作者;[metadata]:记录 difficulty、category=coding、language 与 source=autocodebench;[verifier] timeout_sec = 150.0:验证阶段超时 150 秒;[agent] timeout_sec = 600.0:Agent 单任务执行超时 600 秒;[environment]:build_timeout_sec=900、cpus=1、memory_mb=2048、storage_mb=4096。
Dockerfile:单一镜像承载 20 语言
Dockerfile 模板 基于 jasonchou97/sandbox:tb6 基础镜像,其中 RUN rm -rf /tests /solution 是为了避免与 docker cp 行为冲突(docker cp 会拷贝进已存在目录而非替换),随后设置 WORKDIR /app。20 种语言的 SDK 与运行时全部预置于该基础镜像中,这也是 README 警告镜像体积达数 GB 的原因。
solve.sh:Oracle 解注入
solve.sh 模板 将标准解写入 /app/solution.txt:
cat > /app/solution.txt << 'EOL'
__ORACLE_SOLUTION__
EOL
生成时 __ORACLE_SOLUTION__ 被替换为 canonical_solution,脚本被赋予 0o755 可执行权限(见 adapter.py)。
验证链路:test.sh + test_outputs.py
test.sh 模板 是验证入口:
- 用
uv init初始化临时 Python 环境; - 添加
pytest==8.4.1与sandbox_localwheel 包(/data/sandbox_local_package/dist/sandbox_local-1.0.0-py3-none-any.whl); - 运行
uv run pytest $TEST_DIR/test_outputs.py -rA(TEST_DIR默认/tests); - 依据 pytest 结果向
/logs/verifier/reward.txt写入1(通过)或0(失败),作为评测回报信号。
test_outputs.py 是 adapter.py 内联模板生成的 pytest 测试文件,其验证逻辑包含三层:
test_solution_exists():断言/app/solution.txt存在;test_solution_correct_by_demo_test():用demo_test_func验证(对应原基准的演示测试);test_solution_correct_by_full_test():用full_test_func验证(对应完整单元测试)。
测试通过 sandbox_local.call_sandbox() 提交代码:构造 payload(func_code 为 solution.txt 内容、main_code 为测试函数、lang 为任务语言、超时 60 秒),断言 exec_outcome == "PASSED"。模板中还包含 Elixir 语言的特殊处理 handle_elixir_solution_code():当 Agent 输出的代码缺少 defmodule ... end 包裹时,自动套用 Oracle 解的外壳结构,保证 Elixir 代码可编译。
在 Harbor 中运行评测
Harbor 支持通过数据集注册表、YAML 配置或本地目录三种方式运行评测。
方式一:使用数据集注册表(registry)
从仓库根目录直接运行:
# 使用 oracle agent(参考解)
uv run harbor run -d autocodebench@lite200 --registry-path registry.json
# 使用你指定的 agent 和模型
uv run harbor run -d autocodebench@lite200 --registry-path registry.json -a <agent_name> -m "<model_name>"
其中 autocodebench@lite200 即注册在 registry.json 中的数据集名与版本,--registry-path registry.json 指向仓库根目录的注册表文件。
方式二:使用 Job 配置(YAML)
若已在本地生成任务目录(如 datasets/autocodebench),可借助 run_autocodebench.yaml 运行:
# 使用示例配置 yaml
uv run harbor run -c adapters/autocodebench/run_autocodebench.yaml -a <agent_name> -m "<model_name>"
# 不依赖 yaml,直接指定本地数据集路径
uv run harbor run -p datasets/autocodebench -a <agent_name> -m "<model_name>"
# 恢复之前启动的 job
uv run harbor run -p /path/to/jobs/directory --resume
run_autocodebench.yaml 的默认配置要点:
jobs_dir: jobs:结果默认保存到jobs/目录(可通过 YAML 中的jobs_dir修改);n_attempts: 1、timeout_multiplier: 1.0;orchestrator.type: local,并发 Trial 数n_concurrent_trials: 10;environment.type: docker,force_build: true、delete: true;agents默认配置oracleagent(model_name: oracle),parity 实验时可取消注释openhands+deepseek-v3.2组合;datasets.path: datasets/autocodebench。
上述 CLI 参数(-c/-p/-d/--registry-path/--resume/--n-attempts)均可对应到 Harbor CLI 实现,参见 src/harbor/cli/jobs.py 与 src/harbor/cli/trials.py。
方式三:运行单个 Trial
用于快速测试或调试单个任务:
# 使用 oracle 运行单个 trial
uv run harbor trials start -p datasets/autocodebench/<task_id>
# 使用指定 agent 和模型
uv run harbor trials start -p datasets/autocodebench/<task_id> -a <agent_name> -m "<model_name>"
Trial 输出默认保存到 trials/ 目录(可通过 --trials-dir 修改)。trials start 命令即 src/harbor/cli/trials.py 中定义的 start 子命令。
生成任务目录:CLI 用法
从适配器目录执行打包好的 CLI:
cd adapters/autocodebench
uv run autocodebench
任务默认写入 datasets/autocodebench/(每个任务一个目录)。脚本默认从 HuggingFace 下载 tencent/AutoCodeBenchmark 的 autocodebench_lite 子集(约 1,000 道题),并提取每语言前 10 个任务生成 AutoCodeBench-Lite200 集合。
main.py 定义了完整的命令行参数,结合源码整理如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
--jsonl <path> |
无 | 指定本地 JSONL 文件作为数据源(与 --use-huggingface 互斥) |
--use-huggingface |
未指定时若未给 --jsonl 则自动启用 |
从 HuggingFace 加载数据集(需安装 datasets 包) |
--hf-dataset |
tencent/AutoCodeBenchmark |
HuggingFace 数据集名称 |
--hf-subset |
autocodebench_lite |
HuggingFace subset/split 名称 |
--output-dir |
datasets/autocodebench(仓库根相对路径) |
任务输出目录 |
--task-ids |
无 | 只生成指定任务 ID(如 python_001 java_003) |
--max-per-language |
10 |
每种语言最多选取的任务数 |
--limit |
无 | 按语言限制之后,只生成前 N 个任务 |
--overwrite |
关闭 | 任务目录已存在时是否覆盖 |
底层逻辑由 AutoCodeBenchAdapter 承担:构造函数校验 jsonl_path 与 dataset 只能提供其一;未安装 datasets 且使用 HuggingFace 时会提示 pip install datasets;HuggingFace 加载失败时会建议 huggingface-cli login。
Parity 一致性验证
为确保"在 Harbor 中用适配器运行基准"与"用原 harness 运行基准"等价,适配器通过两步传递等价链完成 Parity 验证(详见 parity_experiment.json):
- 原始 AutoCodeBench ↔ Terminal-Bench 适配器:验证 terminal-bench 适配器与原始基准一致;
- Terminal-Bench 适配器 ↔ Harbor 适配器:验证本 Harbor 适配器与 terminal-bench 适配器一致。
Step 1:原始 AutoCodeBench ↔ Terminal-Bench 适配器
| Agent | Model | Metric | Number of Runs | Dataset Size | Original Benchmark Performance | TB Adapter Performance |
|---|---|---|---|---|---|---|
| OpenHands | DeepSeek-V3.1 | Pass Rate | 3 | 200 tasks (100% of Lite200 set) | 32.2% ± 2.1% | 31.2% ± 1.5% |
Step 2:Terminal-Bench 适配器 ↔ Harbor 适配器
| Agent | Model | Metric | Number of Runs | Dataset Size | TB Adapter Performance | Harbor Adapter Performance |
|---|---|---|---|---|---|---|
| OpenHands | deepseek-v3.2 | Pass Rate | 3 | 200 tasks (100% of Lite200 set) | 55.5% ± 1.3% | 55.5% ± 1.5% |
两个阶段的通过率差异均在标准误差范围内,README 据此判定实现了 perfect parity,确认 Harbor 适配器忠实复现了原始基准的评测。parity_experiment.json 还记录了更细节的逐次运行数据(Stage 2:TB 三次运行 58.0/53.5/55.0,Harbor 三次运行 54.0/58.5/54.0),以及实验日期(Stage 1 为 2025-09-27,Stage 2 为 2026-01-04)。
复现要求
Stage 1:原始基准(对照 Terminal-Bench)
- 克隆 fork 仓库并切换到
tb-adapter/Agent-Openhands分支; - 按照该仓库说明,使用 OpenHands + DeepSeek-V3.1 运行评测。
Stage 2:Harbor 适配器(对照 Terminal-Bench)
- 从 Harbor 根目录安装依赖并设置环境变量:
uv sync --extra dev
# 设置 API keys
export DEEPSEEK_API_KEY="your-key-here"
- 运行 Harbor 评测:
uv run harbor run -p datasets/autocodebench -a openhands -m deepseek/deepseek-chat -n 10 --n-attempts 3
- 将 job 输出的 pass rate 与 Terminal-Bench 结果对比。
结果解读:
- 主指标为 Pass Rate:Agent 生成代码通过全部单元测试的任务占比;
- 通过率在多次运行间取平均并报告标准误差;
- 任务"通过"的判据是全部单元测试成功执行。
注意事项与限制
README 明确列出以下使用边界:
- Lite-200 子集:本适配器使用 AutoCodeBench-Lite200(200 任务、20 语言各 10 个),而非完整 3,920 任务基准;该子集由可稳定求解的任务构成;
- 超大 Docker 镜像:Docker 环境包含全部 20 种语言的 SDK 与运行时,镜像体积达数 GB,首次构建耗时较长;
- 数据源:默认从 HuggingFace(
tencent/AutoCodeBenchmark的autocodebench_lite)下载;离线场景可用--jsonl指定本地 JSONL 文件; - 语言支持:README 声明支持 20 种语言(含 Python、Java、C++、Go、Rust、JavaScript、TypeScript、C#、Ruby、Swift、Kotlin、Scala、PHP、R、Julia、Haskell、Lua、Perl、Dart、Elixir);而 registry.json 实际注册的 20 种语言前缀为 cpp、csharp、dart、elixir、go、java、javascript、julia、kotlin、perl、php、python、r、racket、ruby、rust、scala、shell、swift、typescript,两者存在差异,请以实际注册数据为准;
- 评测耗时:复杂问题或慢速模型评测时间可能很长,应在 job 配置中设置合适的超时;
- 平台要求:必须安装并运行 Docker;部分语言工具链有平台特定要求(主要在 Linux 上测试)。
安装与前提条件
- Docker:必须已安装并处于运行状态;
- Harbor:须完成安装与配置(参见仓库主 README);
- Python 环境:从 Harbor 根目录安装依赖:
uv sync --extra dev
- API Keys:为所选 agent 与模型导出环境变量:
export DEEPSEEK_API_KEY="your-api-key-here"
# 或其他模型供应商的 key(如 ANTHROPIC_API_KEY、OPENAI_API_KEY)
- 数据集下载:首次运行时适配器会自动从 HuggingFace 下载 AutoCodeBench-Lite200 数据集(需要网络连接);
- 磁盘空间:确保有足够空间存放 Docker 镜像(每个任务环境数 GB)。
故障排查
- Docker 错误:执行
docker system prune清理旧容器、镜像与构建缓存;权限问题请确保用户属于docker组或以适当权限运行; - 超时:复杂任务或慢速模型可能超时,可通过 job 配置 YAML 中的
timeout参数调整(对应 task.toml 中[verifier] timeout_sec与[agent] timeout_sec); - HuggingFace 下载问题:确保网络连通;离线场景请先单独下载数据集,再用
--jsonl指定本地文件; - 构建失败:若特定语言工具链(如 Haskell、Scala)的 Docker 构建失败,检查磁盘空间与内存是否充足;
- 测试失败:若测试意外失败,可用启用详细日志的方式运行单个 Trial,验证 Docker 环境是否正确搭建。
引用与致谢
如研究中使用本适配器,请引用 AutoCodeBench 原始论文:
@article{chou2025autocodebench,
title={Autocodebench: Large language models are automatic code benchmark generators},
author={Chou, Jason and Liu, Ao and Deng, Yuchi and Zeng, Zhiying and Zhang, Tao and Zhu, Haotian and Cai, Jianwei and Mao, Yue and Zhang, Chenchen and Tan, Lingyun and Xu, Ziyan and Zhai, Bohui and Liu, Hengyi and Zhu, Speed and Zhou, Wiggin and Lian, Fengzong},
journal={arXiv preprint arXiv:2508.09101},
year={2025}
}
本适配器由 Harbor 团队的 Haowei Lin 开发维护。Issues 与 Pull Requests 请提交至主仓库,并遵循项目的代码风格与提交规范。