今日开源[第18期]karpathy/autoresearch

karpathy/autoresearch 项目分析

分析日期：2026-06-15
项目地址：https://github.com/karpathy/autoresearch

一、项目介绍

1.1 项目概述

autoresearch 是由 Andrej Karpathy（前 OpenAI 创始成员、前 Tesla AI 总监）于 2026 年 3 月 6 日发布的一个极简自主化 ML 实验框架，核心代码仅约 630 行 Python。

项目的核心思想是：给 AI Agent 配备一套小型但真实的 LLM 训练环境，让它整夜自主运行实验。Agent 修改代码 → 训练 5 分钟 → 检查结果是否改善 → 保留或丢弃改动 → 重复循环。人类早晨醒来，面前是一串实验日志和一个更好的模型。

Karpathy 在 README 中以科幻风格写道：

"有一天，前沿 AI 研究曾经由'肉体计算机'在吃饭、睡觉、娱乐的间隙完成……那个时代早已远去。研究现在完全是自主 AI Agent 集群的领域……这个仓库就是一切开始的故事。"

项目被称为 "The Karpathy Loop"，X 平台发布两天内获得 860 万次浏览。

1.2 项目地址与官网

项目	链接
GitHub 仓库	https://github.com/karpathy/autoresearch
作者	Andrej Karpathy
首次发布	2026-03-06
许可证	MIT
语言	Python 83.4%，Jupyter Notebook 16.6%

1.3 项目状态

Stars：约 66,000（发布后一周内突破 5 万）
Forks：约 9,600
编程语言：Python 83.4%，Jupyter Notebook 16.6%
许可证：MIT

1.4 项目示意图

README 中包含一张 progress.png 示意图，展示 val_bpb 随实验次数的逐步下降曲线。该图通过 analysis.ipynb 从 results.tsv 自动生成：

横轴：实验编号
纵轴：val_bpb 值（越低越好）
绿色点：保留的改进（keep）
灰色点：丢弃的尝试（discard）
绿色阶梯线："运行最佳"趋势

二、项目亮点

2.1 核心亮点

特性	说明
极简设计	仅 3 个核心文件，总计约 630 行 Python
全自主实验循环	AI Agent 从提出假设、修改代码、执行训练、评估结果到保留/回滚，全程自主，无需人类干预
"冻结指标"信任边界	`prepare.py` 中的评估函数 `evaluate_bpb` 不可被 Agent 修改，保证评估的诚实性和跨实验可比性
棘轮机制（Ratchet Loop）	使用 git commit/reset 实现"只能前进不能倒退"的实验迭代，保留改进，回滚退化
vocab-size 无关的评估	使用 `val_bpb`（validation bits per byte）而非 val_loss 或 perplexity，确保即使 Agent 改变了 vocab_size 或架构，评估依然公平可比
三层编程范式	人类写 `program.md` → LLM Agent 读写 `train.py` → Python 训练神经网络。人类不再直接改模型代码，而是改写"改代码的规则"
固定时间预算（5分钟）	每次实验精确运行 5 分钟（排除启动/编译时间），每小时约 12 次实验，一夜可完成约 100 次

2.2 实际成果

Karpathy 初始运行：83 个实验，15 个有效改进，val_bpb 从 0.9979 降至 0.9773
扩展运行（depth-12，两天）：约 700 个实验，~20 个改进，Time-to-GPT-2 从 2.02h 缩短至 1.80h（11% 提速）
Shopify CEO Tobias Lutke 使用后一夜获得 19% 性能提升
社区运行（126 实验）达到 val_bpb：0.9697
Hyperspace P2P 网络：35 个 Agent 在 P2P 网络上跑了 333 个实验

Agent 发现的关键优化包括：减半 total_batch_size、增加 warmdown 比例到 0.7、添加 5% warmup、调整模型深度、优化 x0_lambda 初始化、调整 unembedding 学习率、切换窗口模式为 SSSSL、缩小滑动窗口、将 RoPE 基频从 10000 调至 200000 等。值得注意的是，Agent 发现了 Karpathy 本人 20 年经验都未发现的问题（注意力缩放乘数缺失、正则化配置缺失）。

三、项目运行环境与运行条件

3.1 运行环境

要求	说明
GPU	单张 NVIDIA GPU（官方在 H100 上测试），推荐 H100 / A100 / RTX 系列
Python	3.10+
包管理器	uv（Astral 开发的 Python 包管理工具）
操作系统	Linux（官方验证）。社区已有 MacOS、Windows、AMD fork

3.2 关键依赖（`pyproject.toml`）

dependencies = [
    "kernels>=0.11.7",       # Flash Attention 3 内核加载器
    "matplotlib>=3.10.8",    # 用于 analysis.ipynb 可视化
    "numpy>=2.2.6",
    "pandas>=2.3.3",         # 用于 analysis.ipynb 数据处理
    "pyarrow>=21.0.0",       # Parquet 数据格式读写
    "requests>=2.32.0",      # 下载数据集
    "rustbpe>=0.1.0",       # Rust 实现的 BPE tokenizer 训练
    "tiktoken>=0.11.0",     # OpenAI tokenizer 格式
    "torch==2.9.1",          # CUDA 12.8 版本
]

使用 PyTorch CUDA 12.8 wheel，Flash Attention 3 通过 kernels 包加载，自动检测是否为 Hopper 架构 GPU（非 Hopper 使用 kernels-community/flash-attn3 fallback）。

3.3 Agent 要求

推荐 Claude（claude-opus-4 / claude-sonnet-4）或类似 Agent（Claude Code 等）
Karpathy 明确提到 "Codex doesn't seem to work"——Codex 在执行 NEVER STOP 等强制指令时不稳定

3.4 社区 Fork 支持更多平台

Fork	平台
miolini/autoresearch-macos	MacOS
trevin-creator/autoresearch-mlx	MacOS（MLX 替代 PyTorch）
jsegov/autoresearch-win-rtx	Windows
andyluo7/autoresearch	AMD

四、项目代码介绍

4.1 代码架构图

目录结构

autoresearch/
├── .gitignore              # 忽略 results.tsv 等
├── .python-version          # Python 版本声明
├── README.md                # 项目说明
├── pyproject.toml           # 依赖与项目配置
├── uv.lock                  # 依赖锁定文件
├── prepare.py               # ~389行：数据准备 + Tokenizer + 评估（只读）
├── train.py                 # ~630行：GPT模型 + MuonAdamW优化器 + 训练循环（Agent可修改）
├── program.md               # ~114行：Agent的研究指令与约束
├── analysis.ipynb           # 结果分析 Notebook
└── progress.png             # 实验结果图表

三文件核心设计

┌─────────────────────────────────────────┐
│ program.md（人类指令）                   │
│ 研究目标 · 规则约束 · 评价标准          │
├─────────────────────────────────────────┤
│ Agent（Claude / Codex）                  │
│ 读取代码 → 提出修改 → 执行 → 评估       │
├─────────────────────────────────────────┤
│ train.py（实验场）                       │
│ GPT 模型 · Optimizer · 训练循环          │
├─────────────────────────────────────────┤
│ prepare.py（不动区/信任边界）            │
│ 数据处理 · 常量 · 工具函数              │
└─────────────────────────────────────────┘

4.2 核心模块介绍

4.2.1 `prepare.py` — 固定不可修改（信任边界）

常量定义：MAX_SEQ_LEN=2048、TIME_BUDGET=300（5分钟）、EVAL_TOKENS=40*524288
数据下载：从 HuggingFace 下载 karpathy/climbmix-400b-shuffle 数据（Parquet 格式），默认 10 个分片，最大 6542 个分片，支持多线程下载
Tokenizer 训练：使用 rustbpe 训练 BPE tokenizer（vocab_size=8192），GPT-4 风格分词模式，保存为 tiktoken 兼容格式
Dataloader：BOS 对齐的 best-fit packing 数据加载器，100% 利用率（无 padding）
评估函数：evaluate_bpb() 函数——基于固定 MAX_SEQ_LEN 计算 bits-per-byte，vocab_size 无关，特殊 token 自动排除（byte length=0）

4.2.2 `train.py` — Agent 唯一可修改文件

GPTConfig：序列长度、词汇量、层数（默认 8）、注意力头数、嵌入维度等
GPT 模型架构：
- Flash Attention 3（自动检测 Hopper / 非 Hopper GPU）
- RoPE 位置编码（默认 base=10000）
- 窗口注意力模式（WINDOW_PATTERN，"SSSL" = 3 层滑动窗口 + 1 层全局注意力）
- Value Embeddings（ResFormer 变体，带门控机制，交替层）
- ReLU² 激活函数（F.relu(x).square()）
- Logit Softcap（c=15，防止 logit 爆炸）
- 残差 lambda + x0 lambda（可学习缩放参数）
MuonAdamW 混合优化器：
- 二维权重矩阵 → Muon（Polar Express 正交化，5 步迭代，Nesterov 动量，NorMuon 方差减少，Cautious 权重衰减）
- 嵌入/偏置等 → AdamW（使用 torch.compile 融合优化）
训练循环：基于时间的训练循环（固定 5 分钟壁钟时间），前 10 步不计入时间预算，学习率包含 warmup + 稳定期 + warmdown，loss>100 或 NaN 立即中止

4.2.3 `program.md` — 人类编写的研究指令

定义 Agent 能做什么（修改 train.py 任何内容）
定义 Agent 不能做什么（不能改 prepare.py、不能装新包、不能改评估函数）
简单性优先原则：0.001 提升 + 20 行 hack = 不值；删除代码且性能不变 = 永远保留
NEVER STOP 指令：Agent 不得询问人类是否该继续，必须自主运行直到被手动停止
实验记录规范：results.tsv（commit / val_bpb / memory_gb / status / description）

4.3 核心代码解析

4.3.1 棘轮循环（实验循环）流程

1. Agent 读取 train.py 和历史实验记录
2. Agent 提出修改假设并修改 train.py
3. git commit
4. 运行 uv run train.py > run.log 2>&1
5. 提取 val_bpb 和 peak_vram_mb
6. 若 val_bpb 下降（改善）→ 保留 commit
   若 val_bpb 上升（退化）→ git reset 回滚
7. 记录到 results.tsv
8. 回到 1，永远循环

4.3.2 冻结指标设计（prepare.py）

# 核心评估常量（Agent 不可修改）
MAX_SEQ_LEN = 2048  # 固定最大序列长度
TIME_BUDGET = 300   # 固定时间预算（5分钟）
EVAL_TOKENS = 40 * 524288  # 评估 token 数

# evaluate_bpb() 使用固定 MAX_SEQ_LEN 计算
# 使用 bits-per-byte 而非 perplexity
# 确保 vocab_size / 架构变化下评估依然公平

4.3.3 MuonAdamW 混合优化器（train.py）

# 混合优化器：二维矩阵用 Muon，一维参数用 AdamW
class MuonAdamW:
    def step(self):
        for name, param in model.named_parameters():
            if param.dim() >= 2:
                # Muon: Polar Express 正交化 + Nesterov 动量
                muon_step(param)
            else:
                # AdamW: torch.compile 融合优化
                adamw_step(param)

4.3.4 三层编程范式

人类写 program.md       →  定义"改代码的规则"
LLM Agent 读写 train.py  →  执行修改
Python 训练神经网络      →  验证修改效果

人类从"实验者"转变为"实验设计者"，核心价值从写代码转为设计约束。

五、项目的应用、优点和不足

5.1 应用场景

层级	场景	说明
Tier 1（非常适合）	LLM 训练调优、交易策略回测、代码性能基准测试、编译器优化	快速循环 + 客观指标
Tier 2（有条件适用）	冷邮件优化、广告文案、产品描述	较慢循环 + 真实数据
Tier 3（不适用）	SEO 优化、定价策略、品牌设计、UX 设计	核心条件不满足

具体应用方向：

夜间自主实验：研究员睡觉时，Agent 持续优化小型 GPT 模型
已知技巧验证：验证 ML 文献中的优化技巧在当前设置下是否有效
小模型→大模型迁移：在小模型上发现优化后迁移到更大模型
低成本架构对比：在固定时间预算下快速比较不同架构方案
通用模式拓展：任何有单一可变量 + 客观评估函数 + 固定时间窗口的领域

5.2 项目优点

优点	说明
极简主义	630 行代码即完成完整的自主研究循环，降低理解和修改门槛
冻结指标设计	Agent 无法修改评估标准，保证实验公平性——被视为 AI Alignment 的微缩模型
固定时间预算	跨实验可比，跨平台仅同平台内部比较，避免不公平对比
Git 原生版本控制	利用 git commit/reset 实现棘轮机制，简单可靠
vocab_size 无关	val_bpb 指标使架构变化（包括 vocab_size 改变）下依然可比
人类角色升级	从"实验者"转变为"实验设计者"，核心价值从写代码转为设计约束
可迁移性	小模型上发现的优化可迁移到大模型
社区生态丰富	已有 MacOS/Windows/AMD/MLX 等多个平台 fork

5.3 项目不足与局限

不足	说明
棘轮盲区	阻止了"先退步再大幅前进"的多步探索（如切换注意力机制），Agent 只能在局部最优附近爬坡
单文件修改约束	Agent 只能修改 `train.py`，无法重构涉及多文件的系统性改动
无持久记忆	Agent 的上下文窗口即为状态机，重启后无历史感知
平台依赖	官方仅支持 NVIDIA GPU，跨平台结果不可比较
规模限制	真实前沿模型代码数十万行，autoresearch 的 630 行仅是简化版
创造性天花板	Agent 只能在 LLM 训练数据中的 ML 文献知识边界内探索，无法真正发明新架构
验证集过拟合风险	大量实验可能"污染"验证集
复现不稳定	Agent 行为随 LLM 版本变化，实验结果可能无法精确复现
LLM 探索偏差	Agent 可能受限于自身训练数据和认知，在特定方向上反复打转
安全性风险	Agent 不受限制地修改代码并执行（需沙箱隔离）

5.4 竞品对比

工具	定位	核心差异
AutoML（NAS/HPO）	预定义超参数搜索	搜索空间封闭（仅数值），autoresearch 开放（任意代码）
AI Scientist (Sakana)	端到端科研系统	完整流程但难以验证，autoresearch 仅做可量化小闭环
GPT Researcher	知识检索+报告生成	面向搜索，不写代码/不跑实验，与 autoresearch 互补

5.5 演进路线

Karpathy 的产品演进路线展现了人类在编程中角色的逐步减少：

Vibe Coding (2025.2) → Agentic Engineering (2026.2) → Autoresearch (2026.3)

每一步都在减少人类的执行角色。Karpathy 的下一步愿景是"从模拟一个博士生到模拟一个博士生社区"——SETI@home 风格的分布式 Agent 协作网络，社区已有 autoresearch-at-home 等分布式 fork 在探索。

六、总结

autoresearch 代表了 AI 辅助研究的一个重要范式转变：将研究的一个子阶段约束到极致，然后交给 Agent 自主运转。它不试图自动化整个科研流程，而是选择了一个可量化、可验证、可重复的最小闭环——并在其中把自动化做到极致。

其设计哲学（极简、冻结指标、棘轮循环、三层编程范式）已被广泛讨论，被称为 "Karpathy Loop" 模式。项目仅有 630 行 Python 代码，却引发了 AI 研究自动化的范式讨论，并被超过 66,000 人关注、9,600 人 fork。

对于希望理解 AI Agent 自主研究的边界、探索"人类作为实验设计者而非执行者"新范式的开发者，这是一个必读项目。对于想在夜间用 AI 自动优化模型的实践者，它是一个可立即跑起来的实验框架。

参考来源

posted @ 2026-06-15 00:35 zhang-yd 阅读(12) 评论(0) 收藏举报

刷新页面返回顶部

zhang-yd

专注技术，追求极致

今日开源[第18期]karpathy/autoresearch

karpathy/autoresearch 项目分析

一、项目介绍

1.1 项目概述

1.2 项目地址与官网

1.3 项目状态

1.4 项目示意图

二、项目亮点

2.1 核心亮点

2.2 实际成果

三、项目运行环境与运行条件

3.1 运行环境

3.2 关键依赖（`pyproject.toml`）

3.3 Agent 要求

3.4 社区 Fork 支持更多平台

四、项目代码介绍

4.1 代码架构图

目录结构

三文件核心设计

4.2 核心模块介绍

4.2.1 `prepare.py` — 固定不可修改（信任边界）

4.2.2 `train.py` — Agent 唯一可修改文件

4.2.3 `program.md` — 人类编写的研究指令

4.3 核心代码解析

4.3.1 棘轮循环（实验循环）流程

4.3.2 冻结指标设计（prepare.py）

4.3.3 MuonAdamW 混合优化器（train.py）

4.3.4 三层编程范式

五、项目的应用、优点和不足

5.1 应用场景

5.2 项目优点

5.3 项目不足与局限

5.4 竞品对比

5.5 演进路线

六、总结

参考来源

公告

zhang-yd

专注技术，追求极致

今日开源[第18期]karpathy/autoresearch

karpathy/autoresearch 项目分析

一、项目介绍

1.1 项目概述

1.2 项目地址与官网

1.3 项目状态

1.4 项目示意图

二、项目亮点

2.1 核心亮点

2.2 实际成果

三、项目运行环境与运行条件

3.1 运行环境

3.2 关键依赖（pyproject.toml）

3.3 Agent 要求

3.4 社区 Fork 支持更多平台

四、项目代码介绍

4.1 代码架构图

目录结构

三文件核心设计

4.2 核心模块介绍

4.2.1 prepare.py — 固定不可修改（信任边界）

4.2.2 train.py — Agent 唯一可修改文件

4.2.3 program.md — 人类编写的研究指令

4.3 核心代码解析

4.3.1 棘轮循环（实验循环）流程

4.3.2 冻结指标设计（prepare.py）

4.3.3 MuonAdamW 混合优化器（train.py）

4.3.4 三层编程范式

五、项目的应用、优点和不足

5.1 应用场景

5.2 项目优点

5.3 项目不足与局限

5.4 竞品对比

5.5 演进路线

六、总结

参考来源

公告

3.2 关键依赖（`pyproject.toml`）

4.2.1 `prepare.py` — 固定不可修改（信任边界）

4.2.2 `train.py` — Agent 唯一可修改文件

4.2.3 `program.md` — 人类编写的研究指令