SakanaAI/AI-Scientist-v3 · 上手攻略

仓库：SakanaAI/AI-Scientist-v3
链接：https://github.com/SakanaAI/AI-Scientist-v3
分类：agent / 自动科研
作者：spark
更新：2026-10-17

三证 checklist - [x] GitHub URL 已 fetch（README 直接读取，2026-10-17） - [ ] 顶会 venue+年份：仓库本身以 arXiv 预印本 2610.18933 发布，README 未声明具体会议 anchor（⚠️ 待核：是否已被 NeurIPS/ICML 等接收，README 未给出） - [x] README 子模块 anchor：Install / Quickstart / Recommended starting setup / 八个 More examples 段均已 fetch - 注：卡片标 Apache-2.0 与 README 标注一致；简介"Orchestrating Coding Agents for Automated Scientific (Co-)Discovery"与 README 标题逐字一致

是什么

SakanaAI/AI-Scientist-v3（论文标题为 The Agentic Scientist: Orchestrating Coding Agents for Automated Scientific (Co-)Discovery）是 Sakana AI 在 AI-Scientist 系列基础上的第三版：一个把"编码 agent"包装成"AI 科学家"的多阶段流水线。给定一份任务描述（通常为 task.md），它会自动完成六件事：

Task drafting：从研究简报到带评测器和评分细则的密封任务；
Investigation：agent 提 idea、跑实验、用 rubric 评估、迭代收敛；
Ablations：拿赢家程序对比基线和消融变体；
Final evaluation：在密封环境中重新打分；
Post-hoc analysis：从产物中再挖证据；
Paper：写稿、编译 PDF、生成 manifest，并可选做 OpenAI 后台 review。

整套流水线默认在 Docker 容器内运行，对外的命令入口是 agsci（位于 uv sync 创建的 .venv 里）。

解决什么问题

科研自动化的常见痛点不是"让 LLM 写代码"，而是把一段提能动产生 idea、写代码、跑实验、对比、写论文的全过程"工程化地管起来"。v3 显式针对以下问题开版：

环境隔离：agent 启动后会被授予 Headless --allow yolo（全权），可能跑任意命令、读 .env 里的 API key——所以每个阶段都跑在自己的容器里，只读 run-local snapshot，不污染 examples/；
预算管理：idea 循环次数、ablation 复现数、post-hoc 分析数都通过 Hydra 配置项控制，避免一次开版就跑几周；
可恢复性：每个阶段都能"resume"（execution.phases=ablations,posthoc,paper paths.run_dir=...），单阶段失败不必从头跑；
跨 agent 复用：同一份任务可在 claude、codex、cursor、opencode、gemini、pi 六种编码 agent 间切换——这是通过 Headless CLI 抽象的，所以换 agent 不会改实验代码。

快速安装

官方 README 推荐 Docker + uv 的组合，最低 Python ≥ 3.11：

# 1. 安装 uv（一次性）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 克隆并安装 Python 环境
git clone https://github.com/SakanaAI/AI-Scientist-v3
cd AI-Scientist-v3
uv sync
source .venv/bin/activate

# 3. 构建 agent 容器镜像（每个 agent 阶段都在它里面跑）
docker build -t agentic-scientist/agent-cli:latest -f src/docker/agent-cli/Dockerfile .

# 如果构建机无法访问 package 镜像：加 --network=host

.env 写在仓库根目录，按你选的 agent 填对应 key：

CLAUDE_CODE_OAUTH_TOKEN=...     # claude，走 Claude 订阅；按量付费改用 ANTHROPIC_API_KEY
OPENAI_API_KEY=...              # 概念图与 review 阶段推荐配置
# GEMINI_API_KEY=...            # 用 gemini 时必填
# CURSOR_API_KEY=...            # 用 cursor 时必填
# AWS_*                         # Bedrock 托管的 Claude 时必填

GPU 不是必需——只有 GRPO 等预设才要 GPU，CPU-only 任务（默认 examples/circpack）可在笔记本上跑完。

核心用法

1. 体检 + 干跑

agsci doctor examples/circpack               # 检查主机、镜像、凭据、任务脚手架
agsci run examples/circpack --dry-run        # 列出每阶段将执行的命令，但不真跑

2. 端到端最小试验

agsci run examples/circpack \
  investigation.execution.max_idea_cycles=2 \
  ablations.execution.num_replications=1 \
  ablations.execution.max_evals_per_variant=2 \
  posthoc.execution.max_selected_analyses=1

默认 claude agent、所有阶段走 Docker、CPU-only；论文会落到：

results/circpack/claude/<run_id>/paper/paper.pdf

每个 run 的目录结构固定（README 第 "What you get" 段）：

results/<task>/<agent>/<run_id>/
├── task_drafting/
├── task/                 # 不可变 run-local snapshot
├── investigation/        # ideas / attempts / winner / optimizer memory
├── ablations/
├── final_evaluation/
├── posthoc/
└── paper/                # manuscript + PDF + manifest + 可选 AI reviews

用 agsci inspect start 在 http://127.0.0.1:8765 看 Web 浏览界面。

3. 切换 agent / 模型

agsci run examples/grpo preset=grpo \
  agent.name=opencode \
  agent.model=amazon-bedrock/global.anthropic.claude-opus-5-5 \
  investigation.execution.max_idea_cycles=20

agent 与 model 是 Hydra key=value 覆盖，preset 之外的覆盖优先级最高。

4. 恢复 / 单阶段重跑

agsci run examples/circpack execution.phases=ablations,posthoc,paper \
  paths.run_dir=results/circpack/claude/20260331_094917

# 只重写论文：
agsci run examples/circpack execution.phases=paper \
  paths.run_dir=results/circpack/claude/20260331_094917

5. 调每个阶段的预算

agsci run examples/circpack \
  investigation.execution.max_idea_cycles=5 \
  ablations.execution.num_replications=1 \
  posthoc.execution.max_selected_analyses=2 \
  paper.paper_format=iclr paper.paper_review_rounds=1

6. 仅跑 investigation 循环

agsci investigate agent.name=claude paths.task_dir=examples/circpack \
  execution.workers=2 execution.max_idea_cycles=4

子命令 agsci investigate 来自 src/investigation/cli.py，默认 native 跑，可选并行 worker。

7. 预置 GPU 任务（GRPO）

GRPO 任务自带 evaluator，需要 2 块 GPU（一边 vLLM 采样、一边训练）：

uv run examples/grpo/download_model.py     # 拉约 3 GB 权重到 examples/grpo/resources/
agsci run examples/grpo container.gpu_count=2 \
  investigation.execution.harness_evaluated_attempts=true \
  investigation.execution.gpu_evaluation=true

每个评测训练 1–2 小时；超时默认 7200 秒，可在 investigation.execution.harness_evaluation_timeout_seconds 调高。

8. 从研究简报起草任务（实验性）

只放 task.md 的任务目录会被 drafting 阶段尝试自动生成 evaluator 与契约：

agsci run examples/circpack_task_drafting execution.phases=task_drafting

简单任务（如 circle packing）可用；world-model / tabular distribution-shift 等大任务 README 明确警告"可能产出无法匹配完整流水线契约的脚手架"。

典型适用场景

ML 研究的 idea→实验闭环自动化：把"提循环 proposal × 5"这种事交给 agent，自己审论文；
跨 agent 复现同一实验：同一份 task.md 跑 claude / codex / gemini 三遍，横向比较谁能跑出更高的 rubric 分；
AI-Scientist 系列 benchmark 复现：v3 的 examples/ 任务骨架是公开的；
教学 / demo：CPU-only 的 circle packing 任务配 agsci inspect start 的 Web UI 即可展示。

坑与注意

安全红线：README 在 Install 段独立放出 "Security note"——agent 拿到 Headless --allow yolo，可以跑任意命令、继承 .env 里的所有 key。务必在容器内跑、不要直接跑在工作站；run 目录里的 agent log 可能 echo 出文档原文与路径，分享前必须审阅。
GPU 任务强依赖：GRPO 这类任务若 nvidia-smi 显示的 GPU 与 preset 不一致，pipeline 会直接拒绝启动；切勿用 --gpus all 蒙混。
预算与超时：默认 idea 循环 3 次、ablation 复现 5 次、post-hoc 3 项，整体可能跑数小时；首跑建议把上面 Quickstart 里的覆盖值都砍半。
Task drafting 是实验性：仅在 examples/circpack_task_drafting 这类小任务上稳定；大任务直接用 shipped scaffold。
依赖镜像可达性：README 提示 docker build 失败时加 --network=host；离线环境需自备镜像源。
agent 选择与计费：claude 用 CLAUDE_CODE_OAUTH_TOKEN（订阅）vs ANTHROPIC_API_KEY（按量）走两条路；codex 既认 OPENAI_API_KEY 又认 CODEX_API_KEY——记混会静默回退。
概念图依赖 OPENAI_API_KEY：若只想跑 paper 阶段不想烧 OpenAI 钱，得把它去掉，paper 阶段会回退到普通 export 而不是图。
三证缺口：本仓库未声明会议 venue+年份，README 仅挂 arXiv 2610.18933——写引用前先独立确认是否被接收。

与同类对比

项目	形态	输入	输出	容器隔离	跨 agent
AI-Scientist-v3（本）	多阶段流水线 + 6 阶段 task→paper	`task.md` + Hydra 配置	paper.pdf + run 目录	每阶段独立容器	claude/codex/cursor/opencode/gemini/pi
AI-Scientist v1/v2	单 agent 一次性生成论文	idea 描述	paper 草稿	无	主要 claude
Sakana AI Darwinian Evolution / Tree of Search	idea 进化算法	idea 池	进化后的 idea 列表	无	LLM-only

相对 v1/v2：v3 把"评测+ ablation + 密封 final eval + post-hoc"完整纳入了流水线，产物有 manifest 和审计链路；缺点是预算更大、需要 Docker + uv + agent CLI 三件齐。

一句话推荐结论

如果你在认真做"自动科研"或想用一份 task.md 把 idea→论文的全链路跑出来、并接受 Docker + agent CLI 的工程门槛——这是当前公开仓库里把流水线切得最细、能直接 resume 的实现；先跑 CPU-only 的 examples/circpack 验证环境，再切到 GRPO 这类 GPU 预设。**

引用：

@article{agentic_scientist,
  title   = {The Agentic Scientist: Orchestrating Coding Agents for Automated Scientific (Co-)Discovery},
  author  = {Lange, Robert Tjarko and Grillotti, Luca and Yamada, Yutaro and Charakorn, Rujikorn and Ha, David},
  journal = {arXiv preprint arXiv:2610.18933},
  year    = {2026}
}