企业官网建设流程全解析

本文围绕 Harbor 仓库中 BixBench 适配器文档 展开，系统讲解该适配器如何把 205 道来自真实 Jupyter 分析笔记的计算生物学问题转换为 Harbor 标准任务，并完整继承文档中的数据准备、任务生成、容器化执行、双 Agent 模式、LLM 裁判评估与 Parity 对等实验等核心内容。读完后，你将能够独立准备 BixBench 任务目录、选择 Notebook 或终端 Agent 执行评测，并理解验证器（verifier）的奖励计算逻辑与对等实验的抽样方法。

一、BixBench 是什么，以及适配器的定位

BixBench 是面向 AI 智能体的真实世界生物信息学基准，用于评估模型探索生物数据集、执行多步计算分析、并在研究问题语境下解读结果的能力。每个 BixBench 任务包含四个要素：

• 一个数据胶囊（data capsule）：包含生物数据集（CSV、RDS、Excel 文件等）；
• 一道开放式研究问题；
• 用于评估的期望答案；
• 关于原始研究背景的元数据。

适配器的关键属性（以 README 为准）：

评测指标：Resolve rate（解决率），定义为答对问题的比例，奖励为二值（0.0 或 1.0）。

Harbor 本身是面向终端智能体的框架，而原版 BixBench 的 Agent 运行在 Jupyter 笔记环境中。这个根本差异决定了适配器的核心设计：既要"镜像"原版基准的 Notebook 执行模型以保证对等可比，又要改造任务使其能被开箱即用的终端 Agent 评测。下文各节将分别拆解这两条执行路径。

二、适配器目录与生成任务的结构

适配器源码位于adapters/bixbench/，整体布局如下（与 README 中的结构一致）：

adapters/bixbench/ ├── bixbench.yaml # 全量 205 任务 + Jupyter Agent 的 job 配置 ├── bixbench-cli.yaml # 全量 205 任务 + 终端 Agent（codex+gpt-5）的 job 配置 ├── create_parity_subset.py # 确定性生成 50 任务子集 ├── oracle.yaml # 全量 205 任务 + oracle Agent 的 job 配置 ├── parity_experiment.json # 对等实验结果与元数据 ├── parity_subset50.yaml # 50 任务子集 + Jupyter Agent 的 job 配置 ├── pyproject.toml # adapter.py 与 custom_agent 的依赖 ├── uv.lock # 锁定依赖版本 └── src/bixbench ├── adapter.py # 适配器本体，负责打包 Harbor 任务 ├── main.py # adapter.py 的 CLI 封装 ├── custom_agent # 镜像原版 Agent 的自定义 Jupyter Agent │ ├── __init__.py │ └── agent.py └── task-template # 任务模板 ├── environment │ ├── Dockerfile │ ├── Dockerfile-cli │ ├── download_capsule.py # Docker 构建期使用；对 Agent 不可见 │ ├── entrypoint.sh │ └── nbcli # 自定义安装的包 │ └── nbcli │ ├── cli.py # server 的 CLI 封装 │ └── server.py # 维护一个持久 gym env ├── instruction-cli.md ├── instruction.md ├── solution/solve.sh # cat 出 answer.txt ├── task.toml └── tests ├── llm_judge.py # 查询远程裁判比对提交答案与参考答案 └── test.sh # 运行 llm_judge

适配器运行后，每个 BixBench 问题会生成一个独立的 Harbor 任务目录（默认写入datasets/bixbench/，终端模式写入datasets/bixbench-cli/），结构为：

datasets/bixbench/ ├── environment │ ├── data_folder.txt │ └── Dockerfile ├── instruction.md ├── solution │ └── solve.sh ├── task.toml └── tests ├── ground_truth.json ├── llm_judge.py └── test.sh

任务元数据模板 task.toml

task.toml 模板 中的关键取值如下，理解这些默认值对调参排障很重要：

schema_version = "1.0" [task] name = "futurehouse/bixbench__{question_id}" keywords = ["computational_biology", "data_analysis", "bixbench"] [metadata] difficulty = "hard" category = "computational_biology" [verifier] network_mode = "public" # 验证器整体时间预算（秒） timeout_sec = 600.0 [verifier.env] OPENAI_API_KEY = "${OPENAI_API_KEY}" MODEL_NAME = "gpt-4o" # LLM 裁判模型 [agent] network_mode = "public" # Agent 工作时间预算（秒） timeout_sec = 3600.0 [environment] build_timeout_sec = 1800.0 cpus = 2 memory_mb = 8192 storage_mb = 20480 gpus = 0

几个要点：

• 任务名按futurehouse/bixbench__{question_id}模式生成，{question_id}形如bix-37-q4；
• Agent 时间预算1 小时、验证器预算10 分钟，若任务超时可在task.toml或--timeout参数中调整（见"故障排查"一节）；
• 环境固定 2 CPU / 8 GB 内存 / 20 GB 存储、无 GPU，镜像构建超时 30 分钟（构建期需从 HuggingFace 下载数据胶囊，耗时较长，这是build_timeout_sec = 1800的来源）；
• OPENAI_API_KEY通过环境变量注入验证器，MODEL_NAME = "gpt-4o"即 LLM 裁判所用模型。

三、任务生成流程：从 HuggingFace 记录到任务目录

数据加载层 BixBenchLoader

adapter.py 的BixBenchLoader通过datasets.load_dataset("futurehouse/BixBench", split="train")加载数据集，并提供all_question_ids()（返回按字典序排序的全部问题 ID）与load_question(question_id)（按 ID 精确过滤，找不到时直接断言失败）。每条记录被封装为BixBenchRecord，包含question_id、data_folder、question、ideal_answer、eval_mode五个字段。

源码中一个值得注意的细节是eval_mode == "range_verifier"的两种清洗逻辑（adapter.py#L26-L36）：

• cleaned_oracle_answer()：区间题只取下界作为 oracle 答案，保证 oracle 解法能稳定通过裁判；
• cleaned_ideal_answer()：区间题改写为"Between {low} and {high} inclusive"的自然语言表述，作为喂给 LLM 裁判的参考答案。

这解释了 README "Notes & Caveats" 中提到的"judge 提示词被轻微修改以澄清区间评测措辞（necessary to robust oracle solutions）"。

单任务生成 generate_task

BixBenchAdapter.generate_task()（adapter.py#L103-L183）按模板渲染生成六个产物，其中模式切换点是--cli标志：

1. instruction.md：Jupyter 模式取模板instruction.md，终端模式取instruction-cli.md，注入{question}占位符；
2. task.toml：注入{question_id}；
3. tests/ground_truth.json：写入question_id、question与清洗后的ideal_answer；
4. tests/test.sh 与 tests/llm_judge.py：原样拷贝并赋予可执行权限；
5. environment/Dockerfile：Jupyter 模式渲染Dockerfile，终端模式渲染Dockerfile-cli，注入{commit}；
6. solution/solve.sh：渲染{oracle_answer}为<answer>{清洗后的 oracle 答案}</answer>；
7. environment/data_folder.txt：写入该问题对应的数据胶囊文件名（如xxx.zip），供构建期下载脚本读取。

批量入口generate_many()对每个问题单独 try/except，失败的任务会记录(question_id, 错误信息)并继续，最终返回成功/失败两个列表——所以批量转换时部分失败不会中断整个流程。

CLI 命令行参数

main.py 是uv run bixbench背后的 CLI 封装，参数与 README 文档 完全对应：

# 从适配器目录 cd adapters/bixbench # 生成全部 bixbench 任务 uv run bixbench --overwrite # 生成全部 bixbench-cli 任务 uv run bixbench --overwrite --cli # 生成单个任务（按 question id） uv run bixbench --overwrite --question-id bix-37-q4

如果无法自动确定 Harbor commit（非 git 环境），CLI 会报错并提示显式传--commit（main.py#L70-L73）。

四、容器化环境：构建期下载数据胶囊

两条 Dockerfile 的差异

两种模式共享基础镜像futurehouse/bixbench:aviary-notebook-env（官方 BixBench 镜像，内置 Jupyter 支持与常用生物信息学包），但 Dockerfile 与 Dockerfile-cli 的后续步骤不同：

• Jupyter 版：额外设置NB_WORK_DIR=/workspace、NBCLI_HOST/PORT/URL环境变量（nbcli 服务监听127.0.0.1:8080），pip install从 Harbor 仓库按{commit}安装nbcli包，并从 GitHub 按{commit}拉取download_capsule.py与entrypoint.sh；最后设置ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]。
• 终端版：只装huggingface_hub==1.2.3，构建期执行python3 /app/download_capsule.py --cli，不安装 nbcli、不设置 entrypoint，容器直接以WORKDIR /workspace交付给终端 Agent。

两版都有一个共同技巧：构建完成后执行pip uninstall -y huggingface_hub并删除download_capsule.py、data_folder.txt——下载工具只在构建期存在，运行期对 Agent 不可见，防止 Agent 绕过任务重新拉取数据。

构建期脚本 download_capsule.py

download_capsule.py 的完整流程：

1. 从/app/data_folder.txt读取胶囊 zip 文件名（断言必须以.zip结尾）；
2. 用hf_hub_download从futurehouse/BixBench数据集下载，缓存放在容器内/tmp/hf_cache而不是~/.cache；
3. 解压到/tmp/<name>，若存在嵌套的Data目录则把内容上移一层；
4. 安全清理：删除任何Notebook目录和所有.ipynb文件——胶囊中原本附带的是研究者的完整分析笔记（含答案推导过程），必须剔除以防泄漏答案；
5. 把数据拷贝到/workspace，清理临时文件与 HF 缓存。

模式分叉在最后一步：--cli模式只创建一个空的notebook.py占位文件即退出；Jupyter 模式则用nbformat生成一个空 Jupyter 笔记notebook.ipynb（带 Python 3 kernelspec 元数据），供 Agent 从零开始写分析代码。

Jupyter 模式的 entrypoint 与 nbcli

entrypoint.sh 是 Jupyter 版容器的入口脚本：

1. 后台启动nbcli-server，日志重定向到/tmp/nbcli-server.log（排障时看这里）；
2. 循环轮询http://127.0.0.1:8080/health健康端点，每 0.5 秒一次、最多 30 次（约 15 秒），通过后才继续；
3. 若容器命令为空则tail -f /dev/null保持存活，否则exec "$@"执行主命令。

nbcli包是连接"容器外 Agent"与"容器内持久 Notebook 环境"的桥梁。从 cli.py 看，nbcli支持reset和step两个子命令，其中step接收一个 JSON 消息（如nbcli step '{"tool_calls": [...]}'），通过 HTTP POST 发给 server 端，server 端（server.py）维护一个持久 gym env 执行 Notebook 工具调用（edit_cell、list_workdir、submit_answer等）。CLI 侧的请求超时设为1200 + 5秒，源码注释说明这是与原版><answer> short answer to question </answer>

• Jupyter 模式下，这一步由submit_answer({answer})工具调用自动完成（Agent 无需手写文件）；
• 终端模式下，Agent 直接写文件即可。

Oracle 解法的 solve.sh 只有一行实质逻辑：echo '{oracle_answer}' > /workspace/answer.txt，其中{oracle_answer}在生成任务时已渲染为带<answer>标签的答案（区间题取下界）。

验证器：test.sh + llm_judge.py

test.sh 先安装openai==2.14.0再运行python /tests/llm_judge.py。llm_judge.py 的评估逻辑：

1. 读取/tests/ground_truth.json（含question与清洗后的ideal_answer）；
2. 若/workspace/answer.txt不存在（Agent 未提交），打印错误并直接退出——不写 reward.json，验证器因此报错，该 trial 被排除出汇总（与原版基准"answer=None 在 postprocessing 中被过滤"的处理一致）；
3. 若存在，用正则<answer>(.*)</answer>提取答案（提取失败则用原始文本）；
4. 调用 OpenAI 裁判模型（MODEL_NAME环境变量，默认 gpt-4o），提示词改编自原版BixBench/bixbench/prompts.py：给出问题、正确答案与待判答案，要求输出"是否等价"的二值分数；
5. 通过chat.completions.parse的结构化输出解析为JudgeResponse{binary_score: bool}——这就是 README 中"enable structured model outputs"修改的具体体现；
6. 写/logs/verifier/reward.json，格式为{"reward": 0.0|1.0}。

整体流程对应文档中的三要点：开放式问题由 LLM 裁判（参考问题与参考解）评分；奖励二值化；结果写入/logs/verifier/reward.json。

七、在 Harbor 中运行评测

方式一：Dataset Registry（推荐）

在 harbor 仓库根目录，借助 Harbor 的 Registry & Datasets 直接运行：

# 使用 oracle agent uv run harbor run -d bixbench # 使用原版基准的 SimpleAgent（no image, gpt-4o） uv run harbor run -d bixbench \ --agent-import-path bixbench.custom_agent:BixbenchJupyterAgent # 指定任意 Agent 与模型 uv run harbor run -d bixbench -a <agent_name> -m "<model_name>"

方式二：本地任务目录 + Job 配置

如果本地自备了任务目录或自定义子集，可用harbor run或harbor trial。从 harbor 根目录：

# Jupyter notebook Agent 版本 uv run harbor run -c adapters/bixbench/bixbench.yaml # 终端 Agent 版本 uv run harbor run -c adapters/bixbench/bixbench-cli.yaml

或不带配置直接指定路径：

uv run harbor run -p datasets/bixbench --agent-import-path bixbench.custom_agent:BixbenchJupyterAgent

恢复此前中断的 job：

uv run harbor job resume -p /path/to/jobs/directory

结果默认保存在jobs/目录（可在 YAML 配置的jobs_dir中修改，如bixbench.yaml中即jobs_dir: jobs）。

方式三：单个 Trial

# 测试 oracle 解法（task_id 即 question_id，如 bix-37-q4） uv run harbor trial start -p datasets/bixbench/{task_id} -a oracle

Trial 输出默认在trials/目录（可用--trials-dir修改）。自定义 Agent 的调试姿势也见 agent.py 文件头注释：harbor run -p datasets/bixbench/bix-3-q1 --agent-import-path bixbench.custom_agent:BixbenchJupyterAgent -m "gpt-4o" --ak mock_agent=true --ak max_steps=2。

八、Parity 对等实验

对等实验用于验证 Harbor 适配器相对原版 BixBench 的保真度。基准对照组是原版基准的v1.5 4o-no-image 设置，完整结果与元数据记录在 parity_experiment.json：

parity_experiment.json中还保留了逐次运行明细（如 Jupyter 组三次分别 0.12 / 0.20 / 0.18，原版三次 0.22 / 0.14 / 0.12），可核对均值与方差。

抽样方法：对等实验从 205 个任务中随机抽 50 个、每个任务重复 3 次。抽样由 create_parity_subset.py 完成，固定SEED = 42（random.Random(SEED).sample(task_names, 50)），从仓库根目录 registry.json 中name == "bixbench"的条目读取全量任务名并去重排序后抽样，保证结果确定性可复现；抽出的 50 个任务名即硬编码在parity_subset50.yaml的task_names列表中。

运行原版基准（约每个 replica 一小时）：

git clone --branch parity <原版对等实验分支> cd BixBench # 以 replica_id=1,2,3 重复（需 OPENAI_API_KEY） uv run bixbench/generate_trajectories.py --config_file bixbench/run_configuration/4o_no_image_parity50.yaml --replica_id=1 # LLM as a judge（需 OPENAI_API_KEY） uv run bixbench/postprocessing.py --config_file bixbench/run_configuration/postprocessing_4o_no_image_parity50.yaml

运行 Harbor 适配器版本（3 次运行加验证约 4 小时，需 OPENAI_API_KEY）：

# 在 harbor/ 内，含三次尝试 uv run harbor run -c adapters/bixbench/parity_subset50.yaml # 按 run 分组统计 cd adapters/bixbench uv run split_trials.py --jobdir {jobdir}

九、安装与前置条件

• Docker（必需）；

• Python ≥ 3.11；

• 安装 Harbor 及依赖：

  cd harbor uv sync --group dev

• 安装 BixBench 适配器依赖：

  cd harbor/adapters/bixbench uv sync

• HuggingFace 认证（数据集访问）：

  huggingface-cli login

• 预拉取官方镜像：

  docker pull futurehouse/bixbench:aviary-notebook-env

  该镜像包含 Jupyter 支持与常用生物信息学包。

已知限制：据 README 引用的原版 BixBench 仓库已知问题，该镜像目前仅在 linux/arm64 上可用——在 x86_64 机器上运行前务必确认这一点，这是本适配器最常见的环境级阻塞点。

十、故障排查与注意事项

常见故障

• 超时：任务执行超过预期时，增大 task.toml 模板 中[agent]的timeout_sec（默认 3600 秒）或通过--timeout标志调整；构建慢则关注build_timeout_sec（默认 1800 秒）。
• nbcli server 无响应：检查容器内/tmp/nbcli-server.log。服务本应由 entrypoint.sh 自动启动并做健康检查；NbcliError发生率 <1%，可通过重试缓解（parity_subset50.yaml中已配置对NbcliError的max_retries: 2）。

与原版基准的差异说明（README "Notes & Caveats"）

1. 执行模型差异：Harbor 面向终端 Agent，原版是 Jupyter Agent。为公平对等，自定义BixbenchJupyterAgent模拟原版；同时另设计了bixbench-cli数据集接受 codex、claude code 等通用终端 Agent，它们拥有 Jupyter 工具箱之外的工具。
2. 提示词差异：instruction.md为对等实验从原版逐字重建，其中包含submit_answer、edit_cell等工具使用指令，对通用终端 Agent 不可用，因此bixbench与bixbench-cli的 prompt 不同。
3. 裁判提示词微调：llm_judge.py的 prompt 模板相对原版有轻微修改——澄清区间评测措辞（保证 oracle 解法稳健通过）并启用结构化模型输出。
4. 未调用 submit_answer 的后果：自定义 Agent 可能始终未调用submit_answer，此时/workspace/answer.txt不存在，llm_judge.py直接返回而不写 reward，验证器抛RewardFileNotFoundError。这一处理与原版基准一致（该 trial 被排除出统计而非计 0 分）。

十一、引用

如果在你的研究中使用了 BixBench，请按 README 要求引用：

@misc{mitchener2025bixbenchcomprehensivebenchmarkllmbased, title={BixBench: a Comprehensive Benchmark for LLM-based Agents in Computational Biology}, author={Ludovico Mitchener and Jon M Laurent and Alex Andonian and Benjamin Tenmann and Siddharth Narayanan and Geemi P Wellawatte and Andrew White and Lorenzo Sani and Samuel G Rodriques}, year={2025}, eprint={2503.00096}, archivePrefix={arXiv}, primaryClass={q-bio.QM} }

小结与延伸阅读

BixBench 适配器展示了 Harbor "一个基准、多种执行范式"的典型适配思路：用task-template统一任务契约（instruction / task.toml / solution / tests），用--cli标志切换两条执行链（nbcli 持久 Notebook 环境 vs 裸终端 + 数据文件），用同一套 LLM 二值裁判保证跨模式可比，最后以固定种子的 50 任务 3 次重复对等实验量化保真度（16.0% ± 3.1% vs 16.7% ± 2.4%）。核心文件均可在仓库中直接查证：适配器文档、转换逻辑、CLI 入口、自定义 Jupyter Agent、裁判实现、对等实验数据。Issues 与贡献请提交至主仓库，并遵循项目编码风格与提交规范。