experiments/lab_bench/README_RUN.md

# LAB-Bench Biomni 实验新手运行指南

这份说明用于运行 Biomni 在 LAB-Bench 上的实验，并且数据集设置要和
`/225040511/project/Hypo_Bio_OS/experiments/lab_bench/scripts` 里的 HypoBioOS
实验保持一致。

```bash
/225040511/project/Biomni/experiments/lab_bench
```

LAB-Bench 数据和代码默认位于：

```bash
/225040511/project/LAB-Bench
```

## 1. 进入 Biomni 项目

```bash
cd /225040511/project/Biomni
```

## 2. 本实验跑什么数据

不要跑 LAB-Bench 全量。为了和 HypoBioOS 对照实验一致，本实验只跑：

- `DbQA`
- `SeqQA`

默认数据设置：

- split: `test`
- dev offset: `45`
- test size: `315`
- seed: `20260514`
- shard count: `10`
- runner threads: `1`

对应 HypoBioOS 脚本里的默认环境变量：

```bash
LAB_BENCH_SPLITS=test
LAB_BENCH_DEV_SIZE=45
LAB_BENCH_TEST_SIZE=315
LAB_BENCH_SUBSET_SEED=20260514
LAB_BENCH_TEST_SHARD_COUNT=10
LAB_BENCH_N_THREADS=1
```

Biomni 这边的 `run_all_labbench_with_biomni.sh` 已经改成只代理 DbQA + SeqQA 子集，不会启动 LAB-Bench 全量 eval。

## 3. 挂 DeepSeek 后端

推荐把 DeepSeek key 写到 Biomni 项目根目录的 `.env`：

```bash
cat > /225040511/project/Biomni/.env <<'EOF'
DEEPSEEK_API_KEY=你的 DeepSeek API Key
DEEPSEEK_MODEL_NAME=deepseek-chat
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
EOF
```

也可以只在当前 shell 里临时设置：

```bash
export DEEPSEEK_API_KEY="你的 DeepSeek API Key"
export DEEPSEEK_MODEL_NAME="deepseek-chat"
export DEEPSEEK_BASE_URL="https://api.deepseek.com/v1"
```

实验脚本会自动把 DeepSeek 变量转换成 Biomni 需要的 Custom provider 配置：

```bash
BIOMNI_SOURCE=Custom
BIOMNI_LLM=$DEEPSEEK_MODEL_NAME
BIOMNI_CUSTOM_BASE_URL=$DEEPSEEK_BASE_URL
BIOMNI_CUSTOM_API_KEY=$DEEPSEEK_API_KEY
```

可以用下面命令确认 key 是否已设置，不会打印 key 内容：

```bash
for k in DEEPSEEK_API_KEY BIOMNI_CUSTOM_API_KEY BIOMNI_SOURCE BIOMNI_LLM BIOMNI_CUSTOM_BASE_URL; do
  if [ -n "${!k:-}" ]; then echo "$k=set"; else echo "$k=unset"; fi
done
```

如果你把 key 写进 `.env`，上面的检查命令在手动 `source .env` 之前可能显示 unset，这是正常的；运行脚本时会自动读取 `/225040511/project/Biomni/.env` 和 `/225040511/project/LAB-Bench/.env`。

## 4. Python 环境

默认使用：

```bash
/225040511/miniconda3/envs/biomni_e1/bin/python
```

如果要换 Python，可以设置：

```bash
export LAB_BENCH_RUNNER_PYTHON=/path/to/python
```

## 5. 快速跑一个小样本

先用 debug 模式验证 DeepSeek、Biomni 和 LAB-Bench 都能跑通：

```bash
/225040511/miniconda3/envs/biomni_e1/bin/python \
  experiments/lab_bench/run_labbench_with_biomni.py \
  --eval DbQA \
  --split test \
  --debug \
  --output experiments/lab_bench/results/debug_dbqa.json
```

成功后会生成：

```bash
experiments/lab_bench/results/debug_dbqa.json
```

## 6. 正式运行 DbQA 和 SeqQA

推荐使用分片脚本。它们默认后台运行、默认断点续跑，并把结果追加到 JSONL。

同时跑 DbQA + SeqQA：

```bash
export LAB_BENCH_SPLITS=test
export LAB_BENCH_DEV_SIZE=45
export LAB_BENCH_TEST_SIZE=315
export LAB_BENCH_SUBSET_SEED=20260514
export LAB_BENCH_TEST_SHARD_COUNT=10
experiments/lab_bench/run_dbqa_seqqa_biomni_experiment.sh --background --resume
```

只跑 DbQA：

```bash
experiments/lab_bench/run_dbqa_biomni_experiment.sh --background --resume
```

只跑 SeqQA：

```bash
experiments/lab_bench/run_seqqa_biomni_experiment.sh --background --resume
```

默认每个 eval 分成 10 个 shard 并行跑。可以调整 shard 数：

```bash
export LAB_BENCH_TEST_SHARD_COUNT=5
experiments/lab_bench/run_dbqa_seqqa_biomni_experiment.sh --background --resume
```

## 7. 前台调试

如果想直接在终端看到错误，使用前台模式：

```bash
experiments/lab_bench/run_dbqa_biomni_experiment.sh --foreground --resume
```

或者：

```bash
experiments/lab_bench/run_seqqa_biomni_experiment.sh --foreground --resume
```

前台模式会占住当前终端，适合调试；长时间正式实验建议用后台模式。

## 8. 结果位置

DbQA 分片结果：

```bash
experiments/lab_bench/results/dbqa_batch/dbqa_results.jsonl
experiments/lab_bench/results/dbqa_batch/dbqa_reasoning.log
```

SeqQA 分片结果：

```bash
experiments/lab_bench/results/seqqa_batch/seqqa_results.jsonl
experiments/lab_bench/results/seqqa_batch/seqqa_reasoning.log
```

`*_results.jsonl` 每行是一道题的紧凑结果，包含：

- `question`
- `answer`
- `agent_answer`

`*_reasoning.log` 保存每题的 prompt、raw output 和 Biomni reasoning log，方便排查错误。

## 9. 断点续跑和重新开始

默认推荐断点续跑：

```bash
experiments/lab_bench/run_dbqa_seqqa_biomni_experiment.sh --background --resume
```

脚本会跳过已经存在于 `*_results.jsonl` 里的问题。

如果要清空旧结果重新跑：

```bash
experiments/lab_bench/run_dbqa_seqqa_biomni_experiment.sh --background --fresh
```

## 10. 常用参数

切换 split。为了和 HypoBioOS 正式实验一致，默认用 `test`：

```bash
export LAB_BENCH_SPLITS=test
```

Biomni 分片脚本一次只支持一个 split。如果设置成 `dev test`，脚本会退出，避免和 HypoBioOS 默认测试集设置混淆。

调整 dev/test 数量：

```bash
export LAB_BENCH_DEV_SIZE=45
export LAB_BENCH_TEST_SIZE=315
```

固定抽样种子：

```bash
export LAB_BENCH_SUBSET_SEED=20260514
```

Biomni A1 runner 是有状态的，脚本默认：

```bash
LAB_BENCH_N_THREADS=1
```

不建议改成更大的值。

## 11. 检查是否在跑

查看后台进程：

```bash
ps -ef | grep lab_bench | grep -v grep
```

查看结果是否持续增长：

```bash
wc -l experiments/lab_bench/results/dbqa_batch/dbqa_results.jsonl
wc -l experiments/lab_bench/results/seqqa_batch/seqqa_results.jsonl
```

查看最近 reasoning log：

```bash
tail -80 experiments/lab_bench/results/dbqa_batch/dbqa_reasoning.log
tail -80 experiments/lab_bench/results/seqqa_batch/seqqa_reasoning.log
```

## 12. 常见报错

如果看到：

```text
No LLM API key found.
```

说明脚本没有读到 DeepSeek key。检查：

```bash
ls -lh /225040511/project/Biomni/.env
```

并确认 `.env` 里至少有：

```bash
DEEPSEEK_API_KEY=你的 DeepSeek API Key
DEEPSEEK_MODEL_NAME=deepseek-chat
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
```

如果使用临时环境变量，确认你是在同一个 shell 里先 `export`，再启动脚本。