experiments/bioagent_bench/README_RUN.md

# BioAgent Bench MCP Scaling 新手运行指南

这份说明用于继续运行 Biomni 在 BioAgent Bench 上的 MCP tool scale 实验。当前实验目录是：

```bash
/225040511/project/Biomni/experiments/bioagent_bench
```

## 1. 进入项目目录

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

## 2. 准备 LLM API Key

实验需要至少设置下面任意一种 key：

```bash
export ANTHROPIC_API_KEY="你的 Anthropic key"
```

或者：

```bash
export OPENAI_API_KEY="你的 OpenAI key"
```

或者使用 DeepSeek：

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

脚本会自动把 `DEEPSEEK_API_KEY` 转成 Biomni 使用的 `BIOMNI_CUSTOM_API_KEY`。

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

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

## 3. 检查 MCP 配置

新增 scale 的配置已经生成在：

```bash
ls -lh experiments/bioagent_bench/configs/mcp_scale_1500.yaml
ls -lh experiments/bioagent_bench/configs/mcp_scale_2000.yaml
```

当前 manifest 在：

```bash
experiments/bioagent_bench/configs/mcp_scale_manifest.json
```

其中：

- `scale_1500`: 378 个 MCP servers，1527 个 tools
- `scale_2000`: 526 个 MCP servers，2000 个 tools

如果以后需要重新生成配置：

```bash
/225040511/miniconda3/envs/biomni_e1/bin/python \
  experiments/bioagent_bench/scripts/generate_mcp_scale_configs.py
```

## 4. 后台运行 1500 和 2000 scale

推荐后台跑，因为完整实验可能需要很久：

```bash
experiments/bioagent_bench/scripts/run_biomni_scaling_experiment.sh \
  --background \
  --scale 1500 \
  --scale 2000
```

脚本启动后会打印：

- `PID`: 后台进程号
- `Log`: 日志文件路径
- `Monitor with`: 查看日志的命令

## 5. 查看运行日志

把下面的路径替换成脚本启动时打印的 log 路径：

```bash
tail -f experiments/bioagent_bench/results/logs/run_biomni_scaling_experiment_YYYYMMDD_HHMMSS.log
```

如果日志里出现：

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

说明第 2 步的 API key 没有在当前 shell 里生效，需要重新 `export` 后再启动。

## 6. 结果输出位置

每个 scale 的原始运行结果会写到：

```bash
experiments/bioagent_bench/runs/scale_1500
experiments/bioagent_bench/runs/scale_2000
```

每个 task 会生成自己的子目录，例如：

```bash
experiments/bioagent_bench/runs/scale_1500/alzheimer-mouse_YYYYMMDD_HHMMSS
```

常见文件包括：

- `run_metadata.json`
- `retrieval_plan.json`
- `execution_log.json`
- `execution_log.txt`
- `output_validation.json`
- `final_answer.txt`
- task 对应的最终输出文件

汇总指标会写到：

```bash
experiments/bioagent_bench/results/scale_1500_mcp_metrics.json
experiments/bioagent_bench/results/scale_1500_task_metrics.json
experiments/bioagent_bench/results/scale_1500_task_metrics.csv
experiments/bioagent_bench/results/scale_1500_bioagent_bench_rule_eval.json

experiments/bioagent_bench/results/scale_2000_mcp_metrics.json
experiments/bioagent_bench/results/scale_2000_task_metrics.json
experiments/bioagent_bench/results/scale_2000_task_metrics.csv
experiments/bioagent_bench/results/scale_2000_bioagent_bench_rule_eval.json
```

总表会更新到：

```bash
experiments/bioagent_bench/results/experiment1_scaling_table.json
experiments/bioagent_bench/results/experiment1_scaling_table.csv
```

## 7. 断点续跑

runner 默认带 `--skip-completed`，所以中途失败后可以直接重新运行同一条命令。已经完成的 task 会被跳过，未完成的 task 会继续跑。

```bash
experiments/bioagent_bench/scripts/run_biomni_scaling_experiment.sh \
  --background \
  --scale 1500 \
  --scale 2000
```

## 8. 只跑单个 scale

例如只跑 1500：

```bash
experiments/bioagent_bench/scripts/run_biomni_scaling_experiment.sh \
  --background \
  --scale 1500
```

只跑 2000：

```bash
experiments/bioagent_bench/scripts/run_biomni_scaling_experiment.sh \
  --background \
  --scale 2000
```

## 9. 前台调试

如果想直接在终端里看报错，可以用前台模式：

```bash
experiments/bioagent_bench/scripts/run_biomni_scaling_experiment.sh \
  --foreground \
  --scale 1500
```

前台模式会占住当前终端，适合调试，不适合长时间完整实验。

## 10. 快速检查是否完成

查看每个 scale 是否有 batch summary：

```bash
ls -lh experiments/bioagent_bench/runs/scale_1500/latest_batch_summary.json
ls -lh experiments/bioagent_bench/runs/scale_2000/latest_batch_summary.json
```

查看汇总表是否更新：

```bash
ls -lh experiments/bioagent_bench/results/experiment1_scaling_table.csv
```