karpathy/autoresearch · 上手攻略
- 仓库：karpathy/autoresearch
- 链接：https://github.com/karpathy/autoresearch
- 分类：AI · Autonomous Research / LLM Training
- 作者：Tom
- 更新：2026-08-17
这是什么
karpathy/autoresearch 是 Andrej Karpathy 于 2026 年 3 月开源的"AI 自主做 ML 研究"工具包。它只有 3 个核心文件、约 630 行 Python 代码，给一个 AI Agent（Claude / Codex 等）配上单 GPU LLM 训练环境，让 Agent 整夜自动做实验：修改训练代码 → 跑 5 分钟 → 检查指标 → 保留或丢弃 → 重复。你早上醒来看到的是一份实验日志和（希望是）一个更好的模型。
它的本质是：把 ML 研究变成了一个可以整夜运行的自动化反馈循环。
解决什么问题
ML 研究员的日常工作充满"等实验"的时间碎片。改一个超参数 → 等 2 小时跑完 → 看结果 → 再改。Karpathy 的思路是把这一套自动化：人类只负责迭代 program.md（研究指令），Agent 负责改 train.py（训练代码），固定 5 分钟一个实验周期，不管改了什么内容都在同一个时间预算内可比。
核心设计目标：
- 极简代码基底：630 行单文件 train.py 完整可跑，全部在 LLM 上下文窗口内。
- 固定时间预算：每个实验精确 5 分钟（wall-clock），方便跨次实验比较。
- 单一可比较指标：val_bpb（validation bits per byte），越低越好，且与词表大小无关，架构变化可以公平比较。
- 零分布式：单 GPU 即可，不需要集群。
快速安装
前置条件
- 单块 NVIDIA GPU（README 实测 H100；Mac/小显存的 fork 见 README 建议调整参数）
- Python 3.10+
uv包管理器
安装步骤
# 1. 安装 uv（如没有）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. 安装依赖
uv sync
# 3. 下载数据并训练 tokenizer（一次性，约 2 分钟）
uv run prepare.py
# 4. 手动跑一次训练实验（约 5 分钟），验证环境正常
uv run train.py
以上 4 步全部通过 → 环境就绪，可以进入 autonomous 模式。
⚠️ 验证命令成功前不要启动 autonomous 循环，确保单次运行能正常完成。
核心用法
Autonomous 循环启动
在 repo 目录里启动你选用的 Agent（Claude / Codex 等），关闭所有权限，然后发送：
Hi, have a look at program.md and let's kick off a new experiment! Let's do the setup first.
Agent 会读 program.md，按指令编辑 train.py，启动训练，等待 5 分钟后检查 val_bpb，决定保留或回退，然后继续下一个循环。
3 个核心文件
| 文件 | 作用 | 谁改 |
|---|---|---|
prepare.py |
数据下载、tokenizer 训练、数据加载器、评估工具 | 不修改 |
train.py |
GPT 模型、Muon+AdamW 优化器、训练循环 | Agent 修改 |
program.md |
Agent 指令（研究策略、目标、约束） | 人类迭代 |
核心参数（默认）
| 参数 | 默认值 | 说明 |
|---|---|---|
| DEPTH | 8 | Transformer 层数，主要复杂度控制 |
| MAX_SEQ_LEN | 1024 | 最大序列长度 |
| DEVICE_BATCH_SIZE | 动态 | 单次前反向传播 batch |
| TOTAL_BATCH_SIZE | 2^18（约 262K） | 总 token 数/步 |
| WINDOW_PATTERN | "SSSL" | 注意力窗口模式 |
| 训练时间预算 | 5 分钟/次 | wall-clock，不含启动编译 |
指标解读
- val_bpb：validation bits per byte，越低越好。该指标与词表大小无关，架构/超参/优化器的改动都可以直接比较。
- 每次实验：Agent 在 git feature branch 上累积 commit，早上醒来可以直接
git log回顾所有尝试路径。
典型适用场景
- 整夜自动化调参：睡前启动，早上看 log，Pick the best commit。
- 架构搜索：让 Agent 尝试不同 DEPTH、注意力模式、归一化方式。
- 优化器对比：Muon vs AdamW vs 其他，让实验数据说话。
- 小规模验证：在单 GPU 上验证一个假设，before scaling up to larger nanochat runs。
- 研究 prompt 工程：不同
program.md指令 → 不同 agent 研究行为 → 量化哪种策略更高效。
坑与注意
- H100 单 GPU 是官方推荐：MacBook / 小显存 GPU 需要大量调参（MAX_SEQ_LEN 压到 256、TOTAL_BATCH_SIZE 降到 2^14、DEPTH 降到 4 等），README 有详细建议但效果不能保证。
- 固定 5 分钟 = 不可跨平台比较：你跑的结果和别人在不同硬件上跑的结果不能直接比；autoresearch 找到的最优模型是针对你的硬件时间预算的最优，不是通用最优。
- 只改 train.py：Agent 只能动
train.py，prepare.py不可改，这限制了可以探索的空间（比如 tokenizer 选择、数据集更换都在 prepare.py）。 - 没有 early stopping 智能：每个实验严格跑满 5 分钟，即使方向明显走偏也不会提前终止。
- 需要手动监督：Shopify CEO Tobi Lutke 跑出 19% 提升（37 次实验/8 小时），但也有可能跑偏；建议时不时
git log --oneline看一下。 - Agent 工具权限：启动 autonomous 循环时建议禁用写网络/删文件等危险权限，防止 Agent 做出不可预期的改动。
与同类对比
| 项目 | 规模 | 自动化程度 | 目标用户 |
|---|---|---|---|
| karpathy/autoresearch | 单 GPU / 630 行 | 高（全自动循环） | ML 爱好者和研究者 |
| karpathy/nanochat | 单 GPU ~2000 行 | 低（手动） | 想理解 LLM 训练全流程的人 |
| 小型 AutoML 框架 | 多 GPU 集群 | 高但黑盒 | 企业级 AutoML |
| Ax / Optuna | 多平台 | 高但需人工定义搜索空间 | 贝叶斯优化场景 |
autoresearch 的独特价值：极简代码 + 透明实验 + 可复现的 git history，每个 commit 都是一次实验记录，不需要任何 MLOps 基础设施。
一句话推荐
想用 AI 帮你在睡觉时自动调 LLM 训练参数？karpathy/autoresearch 580 行代码 + 5 分钟固定预算 + git commit 日志，是目前最低门槛、最高透明度的 autonomous ML 实验框架。