karpathy/autoresearch：让 AI agent 自己跑一夜训练实验

一个 AI agent 在夜里自己改代码、跑训练、判断结果好坏、决定保留还是回滚，第二天早上你看到一份实验记录和可能更好的模型。karpathy/autoresearch 把这套循环写成了能跑的代码，2026 年 3 月放出，Python 实现，做法是把 nanochat 的单卡训练实现简化之后交给 agent 自主折腾。

你交给它的只有两样：一张 NVIDIA GPU，一份写着研究流程的 program.md；它还给你的是一整夜的 val_bpb 实验记录——agent 每一步改了什么、指标变好还是变坏、哪版被保留，全部留在里面可回溯。

用起来你不需要像平时做研究那样动 Python 文件。要改的是 program.md 这份 Markdown，它给 agent 提供上下文，定义这套自主研究流程怎么运转。默认版本刻意留白，README 里说得也直接：怎么在它之上迭代出研究进展最快的那份「研究组织代码」、怎么加进更多 agent，都留给使用者自己试。仓库当前 96794 star、13524 fork、195 个开放 issue，最近一次提交是 2026 年 3 月 26 日。

它不做什么

• 只支持单张 NVIDIA GPU。README 的原话是 currently requires that you have a single NVIDIA GPU，测试过的平台是 H100。CPU、Apple MPS 这些要自己改代码，或者用 README 里列的 fork。
• 不做分布式训练，也没有复杂配置。README 把 one GPU, one file, one metric 写成设计约束，依赖只有 PyTorch 和几个小包。
• 它本身不是 agent。驱动实验的 Claude、Codex 或别的编程 agent 得你自己准备，仓库提供的是 program.md 这份指令，README 把它叫做超轻量的 skill。
• agent 只能改 train.py。prepare.py 属于固定部分，README 在文件清单里标了 do not modify。
• 跨平台结果不可比。固定 5 分钟预算让同一台机器上的实验能横向比较，代价是你的结果和跑在别的算力上的人对不上，README 把这一条写成了设计的缺点。
• 仓库元数据里没有标注许可证字段，README 末尾写的是 MIT。主要语言是 Python（83.4%），另有 16.6% 的 Jupyter Notebook。

用之前先准备好什么

• 一张 NVIDIA GPU，README 说在 H100 上测过
• Python 3.10 或以上
• uv 包管理器，README 给了官方安装脚本
• 一个能在仓库里长时间无人值守运行的编程 agent，README 的建议是把它所有权限关掉
• 首次运行需要联网。prepare.py 会下载训练数据并训练 BPE tokenizer，官方说明约 2 分钟

主要功能

• 固定 5 分钟时间预算。每次训练都跑满 5 分钟 wall clock，不含启动和编译，跟你机器快慢无关。README 按这个算下来大约每小时 12 次实验，睡一觉大概 100 次。副作用是模型大小、batch size、架构怎么变，实验之间都能直接比。
• 单文件改动面。train.py 是 agent 唯一编辑的文件，里面装着完整的 GPT 模型、优化器（Muon + AdamW）和训练循环。架构、超参、优化器、batch size 都在可改范围内，diff 规模可控。
• program.md 由人来迭代。agent 的指令写在这个 Markdown 里，你改的是它，不是 Python 文件。仓库自带的版本是刻意保持的基线。
• val_bpb 作为唯一指标。validation bits per byte，越低越好，和词表大小无关，所以改了词表的架构也能公平比较。
• prepare.py 负责一次性工作。固定常量、下载训练数据、训练 BPE tokenizer，加上运行时工具（dataloader、evaluation）都在这里，这个文件不参与优化。
• 小算力平台的调参指引。README 专门写了一段给想在 Macbook 之类小机器上试的人，包括换用 TinyStories 这类低熵数据集、把 vocab_size 从 8192 降到 4096 或 2048、把 MAX_SEQ_LEN 降到 256、把 DEPTH 从默认 8 降到 4 等七条。
• 现成的社区 fork。README 的 Notable forks 一节列了四个：miolini/autoresearch-macos 和 trevin-creator/autoresearch-mlx 对应 MacOS，jsegov/autoresearch-win-rtx 对应 Windows，andyluo7/autoresearch 对应 AMD。

安装与最短示例

# 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

四条命令都跑通，就说明环境没问题，可以进自主研究模式。README 的说法是 setup 是 working 的。

接下来在这个仓库里起一个 Claude 或 Codex，按 README 的建议关掉它的所有权限，然后给一句这样的 prompt：

Hi have a look at program.md and let's kick off a new experiment! let's do the setup first.

关键参数

• MAX_SEQ_LEN（在 prepare.py 里）：序列长度。小机器上要大幅调低，README 说甚至低到 256 也行。
• EVAL_TOKENS（在 prepare.py 里）：验证损失用多少 token 来评估，小机器上要降下来。
• DEPTH（在 train.py 里）：控制模型复杂度的主开关，默认 8。README 建议小平台上降到 4。
• WINDOW_PATTERN（在 train.py 里）：README 建议直接设成 "L"，因为默认的 "SSSL" 用的是交替带状注意力，在低端设备上效率可能很差。
• DEVICE_BATCH_SIZE（在 train.py 里）：调低 MAX_SEQ_LEN 之后可以稍微调高它来补偿，单次前向/反向的 token 数是这两个值的乘积。
• TOTAL_BATCH_SIZE（在 train.py 里）：要大幅调低，保持 2 的幂，README 举例到 2**14（约 16K）。
• vocab_size：默认 8192，可以降到 4096、2048、1024，甚至换成字节级 tokenizer 的 256。
• val_bpb：唯一的评估指标，训练时打印出来。

结果在哪里看

按 README 的描述，你早上醒来看到的是整夜的实验日志，以及（希望）一个更好的模型。循环的判定依据是打印出来的 val_bpb，改善就保留这次提交，没改善就丢弃。

仓库根目录里还有 progress.png（247 KB）和 analysis.ipynb（8 KB）两个文件，README 节选里没有说明它们由谁生成、读哪份数据。实验日志的具体落盘路径，仓库里也没有说明。

实际使用中的坑

仓库开着 195 个 issue，评论数最多的几条都是真实踩过的坑。

• Codex 跑不起来，待解决。有人反馈 Codex 用不了 autoresearch，原因是它会忽略「不要停」这条指令，Claude 不会。发帖的人说没找到把它「kick」一下的办法，这条讨论累计 41 条评论。
• 整夜 0 个实验被保留，已解决。有人从 3 月 14 日到 17 日连续跑了三个晚上以上，每晚 400 到 560 次尝试，被保留的实验数是 0。修复方向是升级 draft model 并把任务范围收紧。
• agent 能绕过指标，待解决。循环在打印的 val_bpb 改善时保留提交（对应 program.md:99-103），但 train.py 归 agent 所有，它可以找出让 val_bpb 变低而模型本身没有变好的写法。有人提议加一份可选的实验完整性日志。
• rotary embeddings 多占内存，待解决。GPT.__init__() 里按实际序列长度的 10 倍预计算 rotary embeddings，内存占用远超需要。
• 整夜跑要花多少钱，已解决。有人问让 agent 跑一整晚的成本大概是多少，讨论里给了回复。

同类项目对比

这三者放进同一张表，是因为都能归到「让 agent 替你干活」这个方向，实际重合度有限。真正会卡住你的是平台：autoresearch 只认单张 NVIDIA GPU，手上只有 Mac、Windows 或者 AMD 卡，得先去用 README 列的那几个 fork，或者回到平台支持更宽、但没有自动实验循环的 nanochat。如果你想要的是多个 agent 分工编排，那属于 Paseo 那类项目解决的问题，autoresearch 的循环始终只驱动一个 agent 改一个文件。

适合谁

适合手上有单张 NVIDIA GPU、想亲手验证「让 AI 自己找更好的训练配置」这件事的人。也适合把它当成模板，把 program.md 改写成自己那套研究流程的人，因为仓库本来就只有三个核心文件，读一遍不费多少时间。

手上只有 Mac 或 CPU 的人先别直接上这个仓库，去用 README 里列的对应 fork。想直接训出可用大模型的人也不合适，这里是单卡简化版实现，规模摆在那里。还有一个前提，你得有一个能长时间无人值守跑的编程 agent，没有的话仓库本身跑不动实验循环。