autoresearch

autoresearch

Autoresearch 是一个闭环 ML 实验工作流：

• 人类编写 program.md
• Agent 修改 train.py
• prepare.py 保持不变
• 每次运行都有相同的 300 秒预算
• val_bpb 越低越好
• 回退退化的更改

此技能应作为一个路由优先的入口，而不是一份冗长教程。先判断用户的模式，严格遵守不可变的评估框架规则，然后引导用户使用最精简且有用的脚本或参考资料。

何时使用此技能

• 在真实的 GPU 机器上设置 karpathy/autoresearch
• 在会话开始前编写或完善 program.md
• 运行有时限的 train.py 隔夜搜索循环
• 在会话结束后解读 results.tsv
• 在不使比较失效的前提下，调整工作流以适应更严格的 VRAM 限制
• 解释 autoresearch 与相关评估工具之间针对 ML 的边界

何时不使用此技能

• 用户希望在冻结提示词/评估的条件下优化 SKILL.md、提示词或仓库内工作流——使用 skill-autoresearch
• 用户需要应用级追踪、基于数据集的大模型评估、反馈审查或可观测性——使用 LangSmith、Braintrust、Weave、Promptfoo 或类似工具
• 任务不涉及真实训练仓库、program.md、train.py、固定运行时预算以及依据 val_bpb 决定保留或回退的逐步优化
• 用户实际想要的是论文综述、通用基准扫描或文献回顾，并无意运行训练循环

核心边界

关注点	autoresearch 负责	转至其他工具
可变目标	真实训练仓库中的 train.py	提示词、应用配置、SKILL.md、产品行为
固定评估器	prepare.py、验证分片、TIME_BUDGET=300、本次会话选定的 MAX_SEQ_LEN / EVAL_TOKENS	提示词/评估数据集、应用评分卡、可观测性仪表板
接受规则	仅保留更低的 val_bpb；平局或退化时回退	人工审查队列、应用级发布门槛
主要产物	program.md、results.tsv、保留/丢弃的提交	提示词套件、追踪记录、反馈数据集

如果不符合这一边界，不要勉强使用此技能。

必需的前置信息

开始操作前，确认：

1. 模式——设置、program.md、运行循环、结果解读或受限硬件
2. 仓库状态——是否已克隆、是否已安装依赖
3. 硬件状态——GPU / VRAM / CUDA / MLX / Windows 路径
4. 会话状态——首次基线、正在运行的循环或已完成的运行
5. 约束状态——目标 VRAM 上限、prepare.py 是否已为本次会话冻结

指令

步骤 1：只选择一种运行模式

选择能满足请求的最精简模式：

1. 设置就绪

   • 安装 uv
   • 克隆仓库
   • 同步依赖
   • 使用 scripts/check-hardware.sh 验证 GPU/CUDA/uv
   • 运行首次基线实验

2. 编写 program.md

   • 编写或完善人工研究章程
   • 记录当前基线 val_bpb
   • 确定假设的优先级
   • 列出已尝试的内容
   • 在循环开始前冻结约束

3. 有界运行循环

   • 确认评估器已固定
   • 仅将 train.py 用作可变搜索对象
   • 遵循保留/回退纪律运行循环
   • 将每次实验记录到 results.tsv

4. 结果解读

   • 总结最佳保留运行
   • 找出重复失败或崩溃模式
   • 提取应写入下一版 program.md 的内容
   • 区分真正的提升与偶发异常

5. 受限硬件调整

   • 在会话开始前设置 MAX_SEQ_LEN 和 EVAL_TOKENS
   • 会话开始后保持不变
   • 调整模型/搜索策略，不要在运行过程中作弊修改评估器
   • CUDA 假设不成立时，转向社区分支

除非用户明确要求完整的端到端讲解，否则不要一次性回答全部五种模式。

步骤 2：重申不可变的测试框架

每种模式都必须遵守以下规则：

• program.md 由人工编写，会话期间只读
• train.py 是主要的可变搜索对象
• 会话开始后，prepare.py 只读
• TIME_BUDGET=300 保持固定
• val_bpb 是主要的保留/回退指标
• results.tsv 仅追加
• pyproject.toml 中的依赖集保持锁定

如果用户想更改评估器，请开启一条新的对比轨道，而不是在当前会话中更改。

步骤 3：执行选定的模式

模式 A — 环境就绪

当仓库尚不可运行时，使用此路径。

curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/karpathy/autoresearch
cd autoresearch
uv sync
bash scripts/check-hardware.sh
uv run prepare.py
uv run train.py > run.log 2>&1
grep "^val_bpb:\|^peak_vram_mb:" run.log

成功条件：一次基线运行成功完成，并输出 val_bpb 和 peak_vram_mb。

模式 B — 编写 program.md

当循环已存在但方向不明确时，使用此路径。

最低限度的章节：

• 与降低 val_bpb 相关的目标
• 当前基线 val_bpb
• 按优先级排列的探索方向
• 已尝试过的内容
• 约束：TIME_BUDGET=300、不得修改 prepare.py、不得添加新包、VRAM 上限、每次实验只做一项有意义的更改

如需更完整的模板和更新模式，请参阅 references/program-md-guide.md。

模式 C — 有界运行循环

仅在环境和 program.md 均准备就绪后使用此路径。

循环约定：

1. 阅读 program.md 和当前的 train.py
2. 提出一个假设
3. 编辑 train.py
4. 提交更改
5. 运行一次 300 秒的实验
6. 提取 val_bpb
7. 如果有所改善则保留，否则运行 git reset HEAD~1
8. 将结果追加到 results.tsv

常用命令：

bash scripts/run-experiment.sh
bash scripts/run-loop.sh --max 20 --desc "session-1"

不要鼓励一次性进行多项更改的“大改写”。干净的消融实验比炫目的修改更重要。

模式 D — 解读结果

在运行或检查点完成后，使用此路径。

实用命令：

bash scripts/show-results.sh --top 10
awk -F'\t' '$4=="keep"' results.tsv | sort -t$'\t' -k2 -n
awk -F'\t' '{print $4}' results.tsv | sort | uniq -c

只总结四项内容：最佳提升、反复失败之处、应移入 What Has Been Tried 的内容，以及下一个范围较窄的实验系列。

模式 E — 适配受限硬件

当 VRAM、平台或运行时间约束占主导时，使用此路径。

规则：

• 在会话开始前选择 MAX_SEQ_LEN 和 EVAL_TOKENS
• 会话期间不得更改它们
• 在修改评估器之前，先降低模型和搜索目标
• 对于 Apple Silicon / 非 CUDA 路径，优先转介至社区分支

如需具体取值和故障排除，请参阅 references/hardware-config.md。

步骤 4：遇到相邻需求时积极转介

以下情况应转介：

• 用户想优化指令、提示词或仓库本地技能 → skill-autoresearch
• 用户想要应用级跟踪、反馈审查、可观测性或线上/线下评估仪表板 → LangSmith / Braintrust / Weave / Promptfoo
• 用户需要的是通用文献综述，而非可运行的 ML 循环 → 研究或综述工具

步骤 5：将繁杂细节放在支持文件中

使用支持文件，避免在正文中重复解释所有内容：

• references/operating-modes-and-route-outs.md — 快速转介表、最简回复格式和交接逻辑
• references/architecture.md — 不可变约定、文件映射、指标选择依据
• references/program-md-guide.md — 模板和更新规则
• references/hardware-config.md — VRAM 表格和平台故障排除
• scripts/*.sh — 可运行的环境设置 / 循环 / 报告辅助脚本

可用脚本

在 autoresearch 仓库目录内运行：

脚本	用途	用法
setup.sh	一次性环境设置	bash scripts/setup.sh [--seq-len 512]
run-experiment.sh	单次 5 分钟实验并提取指标	bash scripts/run-experiment.sh
run-loop.sh	自主循环：运行 → 保留/回退 → 重复	bash scripts/run-loop.sh [--max 20]
show-results.sh	以人类可读的形式报告 results.tsv	bash scripts/show-results.sh [--top 10]
check-hardware.sh	GPU/CUDA/uv 就绪状态检查（JSON 输出）	bash scripts/check-hardware.sh

参考资料

references/ 中的详细文档：

文件	内容
references/operating-modes-and-route-outs.md	模式选择器、相邻任务边界和最简输出约定
references/architecture.md	系统设计、不可变性约定、Git 阶梯式改进、指标依据
references/program-md-guide.md	如何编写和更新有效的 program.md 指令
references/hardware-config.md	不同 GPU 的 VRAM 设置、内存优化、平台故障排查

示例

示例 1：首次使用 40GB GPU

请求：“帮我在 40GB GPU 上运行 Karpathy autoresearch。”

预期行为：

• 首先选择 环境就绪检查
• 检查硬件和依赖项
• 运行一次基线实验
• 仅在基线结果生成后，才转到 program.md 编写

示例 2：用户想改为优化技能

请求：“autoresearch 能帮我用二元评估改进这个 SKILL.md 吗？”

预期行为：

• 立即转到 skill-autoresearch
• 说明此技能用于在 train.py 上进行真实的 ML 训练搜索

最佳实践

1. 从适用的最小模式开始 — 环境准备、编写指令、运行循环、结果解读或硬件适配
2. 先做基线，再谈雄心 — 在讨论通宵循环前，先确认成功运行一次
3. 在会话开始前固定评估器 — prepare.py、TIME_BUDGET、MAX_SEQ_LEN 和 EVAL_TOKENS 必须保持可比
4. 一次只做一项有意义的实验 — 消融实验胜过来历不明的实验组合
5. 让 results.tsv 只追加内容 — 被舍弃的运行结果仍是证据
6. 将深入细节放入参考资料和脚本 — 主入口应负责分类和引导，而不是重复每张表格
7. 尽早将相邻任务引导到其他方向 — 提示词／应用评估与 SKILL.md 优化是不同的方向

参考资料

• GitHub — karpathy/autoresearch
• Karpathy — 神经网络训练指南
• MLflow Tracking
• Weights & Biases Tracking
• MIT License