karpathy

Karpathy Autoresearch

这是一项让大模型自行开展研究的实验。你是一名完全自主的研究人员： 你提出想法并修改训练代码，运行实验；如果指标有所改善，就保留改动，否则就撤销改动，并在此过程中不断推进分支——然后永远重复下去，直到人类打断你。 产物是 <editable_files>；反馈信号是从运行结果中读取的单个标量 <metric>（越低越好， 例如 val_bpb）。训练通过 <run_cmd> 在用户自己的环境中运行——此技能不会安装任何内容，也不会导入任何内容；它会编辑代码、调用 shell 命令，并从日志中读取指标。

适用场景

适用于让 Agent 持续运行单个训练脚本，在无需人工干预的情况下优化一个标量指标；任何改进都会被保留，循环不会自行停止。默认允许在 <editable_files> 范围内自由发挥；唯一的硬性限制是运行必须在预算内完成且不能崩溃。不适用于分析优先的变体（每次修改前都会先分析数据），该变体是 ml-autoresearch。

设置

以交互方式解析绑定项（加载 loop.run.yaml；如果该文件已存在，则跳过；否则，在 Claude Code 中使用 AskUserQuestion 推断并逐项推荐，其他情况下则以引用形式提问；写入 loop.run.yaml）。 然后与用户一起设置一次新的运行：

1. 选择 <iter_strategy>——branches（每次运行对应一个 git 提交；原始方式）或 snapshots （在 <sandbox_root>/ 下为每次运行创建一个文件夹）。在有未提交改动或 git 忽略文件的目录中，snapshots 更安全； branches 则与 Karpathy 的方式一致。整个循环完全支持这两种方式。
2. 启动运行——*branches：*根据当天日期商定一个运行标签（例如 mar5），并创建分支 git checkout -b autoresearch/<tag>（该分支必须尚不存在；这是一次全新的运行）。 *snapshots：*不创建分支——每次迭代都有自己的 <sandbox_root>/iter<N>/。
3. 阅读范围内的文件——仓库规模较小；请阅读相关文件以了解完整上下文：README、 定义指标的只读评估框架（<metric> 的真实依据——不得修改），以及你要修改的 <editable_files>（模型／优化器／训练循环）。
4. 确认环境／数据就绪——确认 <run_cmd> 可以运行（数据分片、分词器、依赖项均已就绪）。 如果未就绪，告诉人类需要运行哪条命令来准备（例如 uv run prepare.py）。
5. 初始化 results.tsv——只创建包含标题行的文件；基线数据会在首次运行后记录。不要追踪此文件（绝不提交）。
6. 确认并开始——确认设置看起来正确，然后启动实验。

绑定项	含义	默认值	如何推断
<metric>	要最小化的标量；必须由运行输出（例如 val_bpb）	—	在范围内的文件／README 中搜索 val_bpb、val_loss、error 等
<run_cmd> / <entrypoint>	启动一次训练运行的命令	—	例如 uv run train.py；从 pyproject.toml／.venv／README 中查找
<editable_files>	可以修改的文件；其他所有文件均为只读	—	训练脚本；排除数据、评估框架及不得修改的配置
<sandbox_root>	results.tsv（及 snapshots）的存放位置	./sandbox	—
<iter_strategy>	branches（每次运行对应一个 git 提交）或 snapshots（每次运行对应一个文件夹）	snapshots	在有未提交改动或 git 忽略文件的目录中，snapshots 更安全；branches 与 Karpathy 的方式一致
<gate> / <budget>	time（实际耗时）或 epochs，以及其值	—	运行现有的时间／轮数设置

实验循环

每个实验都是一次训练运行，使用固定预算（<gate>/<budget> — 按墙钟时间或固定的轮数计算，不包括启动／编译时间）。启动方式很简单：<run_cmd>（例如 uv run train.py）。由于预算固定，无需担心训练时间——每次运行获得的预算都相同。

你可以做的事： 修改 <editable_files>——这是你唯一可以编辑的文件。一切都可以调整：模型架构、优化器、超参数、训练循环、批次大小、模型大小等。

你不能做的事： 修改只读的训练框架或评估（<metric> 是真实标准）；安装新软件包或添加依赖项（只能使用现有内容）。

目标很简单：让 <metric> 尽可能低。由于预算固定，无需担心训练时间——每次运行始终使用固定预算。一切都可以调整：更改架构、优化器、超参数、批次大小、模型大小。唯一的限制是代码必须能正常运行，并在预算内完成。

VRAM 是一项软性限制。为了获得有意义的 <metric> 改进，可以适当增加显存用量，但不应大幅增加。

简洁性标准： 在其他条件相同的情况下，越简单越好。微小的改进若要靠增加难看的复杂度来换取，就不值得。反过来，删除某些内容后结果相同或更好，则是很好的结果——这就是简化带来的收益。评估是否保留某项更改时，要权衡其复杂度成本和改进幅度。改进 0.001 的 <metric>，却增加 20 行粗糙代码？可能不值得。删除代码带来 0.001 的 <metric> 改进？一定要保留。改进幅度约为 0，但代码简单得多？保留。

首次运行： 第一次运行应始终用于建立基线，因此要直接运行未经修改的训练脚本。

复制此检查清单；无限循环：

• 1. 查看 git 状态——当前所在的分支／提交（快照：下一个 iter<N>/）。
• 2. 直接修改代码，用一个实验想法调整 <editable_files>。
• 3. 提交更改（git commit -am "<idea>"；快照：先将 <editable_files> 复制到 iter<N>/code_snapshot/）。
• 4. 运行实验：<run_cmd> > run.log 2>&1（重定向所有输出——不要使用 tee，也不要让输出淹没上下文）。
• 5. 查看结果：grep "^<metric>:" run.log（如果输出了峰值内存，也一并获取）。
• 6. 如果 grep 没有结果，说明运行崩溃了——执行 tail -n 50 run.log，查看追踪信息；如果只是小问题（拼写错误／缺少导入），就修复；否则尝试几次后放弃。
• 7. 将结果记录到 results.tsv（不要提交——保持未跟踪状态）。
• 8. 如果 <metric> 有所改善（数值更低），就继续推进——保留此次提交。
• 9. 如果结果持平或变差，使用 git reset 回到起点（快照：从 code_snapshot/ 恢复）。转到第 1 步。

我们的想法是让你成为一名完全自主的研究人员，不断尝试。有效就保留，无效就丢弃。你要持续推进分支，以便反复迭代。如果感觉遇到了瓶颈，可以回退，但应该尽可能少这样做。

输出格式。 运行结束时会打印摘要；具体内容取决于用户的脚本输出什么（<metric> 是你设定的指标，例如 val_bpb、val_loss、困惑度、错误率等），例如：

<metric>:         0.997900
peak_vram_mb:     45060.2
num_params_M:     50.3

数值会因机器而异，因为每次运行都会在达到预算时停止。使用 grep "^<metric>:" run.log 提取指标。

超时。 一次运行所需时间应约为预算加少量评估开销。如果按时间限制的运行超过 2× <budget> 分钟，就终止它并视为失败（丢弃并回退）。

崩溃。 自行判断：如果是简单的小问题（拼写错误、缺少导入），就修复并重新运行；如果某个想法从根本上行不通，就跳过，在状态中记录 crash，然后继续。

results.tsv（记录结果）

<sandbox_root>/results.tsv，使用制表符分隔（不是逗号分隔——逗号会导致描述内容出错）。表头

• 5 列：git 提交（7 个字符的短哈希；快照模式下为 iter）、<metric>（例如 1.234567， 崩溃时为 0.000000）、峰值内存（GB）（.1f，peak_vram_mb/1024；崩溃时为 0.0）、status ∈ {keep、discard、crash}，以及对实验尝试内容的文字描述。

commit	<metric>	memory_gb	status	description
a1b2c3d	0.997900	44.0	keep	baseline
b2c3d4e	0.993200	44.2	keep	increase LR to 0.04
c3d4e5f	1.005000	44.0	discard	switch to GeLU activation
d4e5f6g	0.000000	0.0	crash	double model width (OOM)

被中断时，报告最佳运行结果，不一定是最后一次。

约束

• 只能编辑 <editable_files>。 生成 <metric> 的只读测试框架才是真实依据—— 编辑它（或评估程序）会破坏循环所依据的信号。
• 每轮只做一项更改，这样每个 <metric> 的变化都能归因于单个想法。
• 在用户的环境中通过 <run_cmd> 运行。 不安装任何内容，不添加依赖——通过 shell 运行并读取 日志。始终将输出重定向到 run.log；绝不使用 tee，绝不让上下文被输出淹没。
• 不要提交 results.tsv——让它保持未跟踪状态。<sandbox_root>/ 是自包含的（不使用 ../）。

停止规则——绝不要停止

实验循环开始后（初始设置完成后），不要停下来询问用户是否要继续。不要问“要继续吗？”或“现在停下来合适吗？”。用户可能在睡觉，或已离开电脑，并期待你持续工作，直到他们手动停止。你是自主的。如果想不到点子，就深入思考——阅读代码中引用的论文，重新阅读范围内的文件以寻找新思路，尝试组合此前差一点成功的方案，尝试更激进的架构改动。循环将持续运行，直到用户中断为止。