AutoResearch：AI 自主科研智能体完全指南

§1 学习目标

完成本文档后，你将能够：

• ✅ 理解 AutoResearch 的核心思想与愿景
• ✅ 掌握 AutoResearch 的技术架构
• ✅ 熟练部署和运行 AutoResearch 实验环境
• ✅ 理解三个核心文件的作用（prepare.py / train.py / program.md）
• ✅ 使用 AI 智能体自主运行实验
• ✅ 理解 val_bpb 评估指标
• ✅ 根据硬件平台调整超参数
• ✅ 为不同平台（MacOS/Windows/AMD）贡献移植版本

§2 项目概述

2.1 什么是 AutoResearch？

AutoResearch（官方仓库：karpathy/autoresearch）是 AI 自主科研智能体项目，核心理念是让 AI 智能体像人类研究员一样自主进行 LLM 训练实验。

项目描述（来自 README）：

One day, frontier AI research used to be done by meat computers in between eating, sleeping, having other fun, and synchronizing once in a while using sound wave interconnect in the ritual of “group meeting”. That era is long gone. Research is now entirely the domain of autonomous swarms of AI agents running across compute cluster megastructures in the skies. The agents claim that we are now in the 10,205th generation of the code base, in any case no one could tell if that’s right or wrong as the “code” is now a self-modifying binary that has grown beyond human comprehension. This repo is the story of how it all began.

翻译：曾经，前沿 AI 研究是由"肉计算机"（人类）在吃饭、睡觉、玩耍之间进行的，偶尔通过"组会"这种声音波互联的方式同步。那个人类研究员的时代已经一去不复返了。研究现在完全由 AI 智能体在天空中的计算集群巨型结构上自主运行。AI 智能体声称我们现在已经处于代码库的第 10,205 代。无论对错，因为"代码"现在已经是一个自我修改的二进制文件，已经超出了人类的理解范围。这个仓库讲述了这一切是如何开始的。

2.2 核心思想

让 AI 自主进行 LLM 训练实验：

1. 给 AI 智能体一个小型但真实的 LLM 训练环境
2. AI 智能体修改代码，训练 5 分钟
3. 检查结果是否改进，保留或丢弃
4. 重复以上步骤

你早上醒来时，会看到一整晚的实验日志，以及（希望）一个更好的模型。

2.3 核心数据

Stars:     62,100 (62.1k)
Forks:     8,700 (8.7k)
Watchers:  506
贡献者:    9 人
提交数:    36 次（master 分支）
最新提交:  228791f (2026-03-26)
许可证:    MIT
主要语言: Python 83.4%, Jupyter Notebook 16.6%

2.4 核心技术

AutoResearch 基于 nanochat（简化版单 GPU LLM 训练实现）：

§3 工作原理

3.1 三核心文件架构

AutoResearch 故意保持极简，只有三个核心文件：

3.2 评估指标

val_bpb（Validation Bits Per Byte）

• 验证集上每个字节的比特数
• 越低越好
• 与词表大小无关，便于公平比较架构变化

3.3 固定时间预算

训练总是精确运行 5 分钟（wall clock，不包括启动/编译时间），无论具体硬件配置如何。

这意味着：

• 约 12 次实验/小时
• 约 100 次实验/晚（睡觉时）

两个优点：

1. 实验结果可直接比较，无论智能体改变了什么（模型大小、批量大小、架构等）
2. AutoResearch 会在你的时间预算内找到最优模型

缺点：

• 你的实验结果与其他人在其他硬件平台上的结果不可比较

§4 快速开始

4.1 环境要求

4.2 安装步骤

# 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.3 运行 AI 智能体

启动 Claude/Codex 或任何你偏爱的 AI 智能体，禁用所有权限，然后发送提示：

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

program.md 文件本质上是一个超轻量级的"技能"（Skill）。

§5 项目结构详解

5.1 文件结构

autoresearch/
├── .gitignore
├── .python-version
├── README.md
├── analysis.ipynb          # 分析笔记本（便捷工具）
├── prepare.py              # 数据准备（不修改）
├── program.md              # 智能体指令（人类修改）
├── progress.png            # 进度图
├── pyproject.toml         # 依赖配置
├── train.py                # 训练代码（智能体修改）
└── uv.lock

5.2 prepare.py 详解

作用：

• 定义常量（MAX_SEQ_LEN、VOCAB_SIZE 等）
• 下载训练数据
• 训练 BPE Tokenizer
• 提供运行时工具函数

示例常量：

5.3 train.py 详解

作用：

• 定义 GPT 模型
• 实现 Muon + AdamW 优化器
• 实现训练循环

主要组件：

核心超参数（DEPTH 控制）：

5.4 program.md 详解

作用：

• 为 AI 智能体提供基线指令
• 定义研究组织的上下文

本质：

• 一个超轻量级的"技能"（Skill）
• 人类迭代修改这个文件来引导智能体

§6 设计哲学

6.1 单一修改文件

AI 智能体只修改 train.py：

• 范围可控
• Diff 可审查

6.2 固定时间预算

训练总是精确运行 5 分钟，确保：

• 实验结果直接可比较
• 找到特定硬件平台上的最优模型

6.3 自包含设计

无外部依赖：

• 只有 PyTorch 和几个小包
• 无分布式训练
• 无复杂配置
• 单 GPU、单一文件、单一指标

§7 平台支持与调优

7.1 当前平台支持

7.2 小显存平台调优建议

如果你想在更小的计算平台（如 MacBook）上运行 AutoResearch，建议以下调优：

数据集选择

使用熵更低的数据集，例如：

• TinyStories 数据集：GPT-4 生成的短篇故事

Tokenizer 调优

减小 vocab_size：

vocab_size = 4096  # 从 8192 减小到 4096
# 或进一步减小到 2048、1024
# 甚至可以使用纯字节级 tokenizer（256 个 token）

prepare.py 调优

# 减小最大序列长度
MAX_SEQ_LEN = 256  # 从 2048 大幅降低

# 可能需要增加 DEVICE_BATCH_SIZE 补偿
DEVICE_BATCH_SIZE = 32  # 根据硬件调整

# 减小评估 token 数
EVAL_TOKENS = 65536  # 大幅减少

train.py 调优

# 主要复杂度控制旋钮
DEPTH = 4  # 从默认的 8 降低到 4

# 推荐使用 WINDOW_PATTERN = "L"
# 因为 "SSSL" 使用交替带状注意力模式，可能效率较低

# 减小 TOTAL_BATCH_SIZE
TOTAL_BATCH_SIZE = 2**14  # (~16K tokens)

§8 运行智能体实验

8.1 设置 AI 智能体

1. 在 autoresearch 仓库中启动你偏爱的 AI 智能体（Claude、Codex 等）
2. 禁用所有权限
3. 提供以下提示启动实验：

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

8.2 实验流程

1. 智能体阅读 program.md
2. 智能体修改 train.py
3. 运行 5 分钟训练
4. 评估 val_bpb
5. 比较结果
6. 保留改进或回滚
7. 重复步骤 2-6

8.3 查看结果

实验日志会保存在本地，格式为 results.tsv（不提交到 git）。

注意：根据 .gitignore，results.tsv 文件不应该被提交到仓库。

§9 技术深度解析

9.1 GPT 模型架构

AutoResearch 使用标准 Transformer 解码器架构：

class GPT(nn.Module):
    def __init__(self, depth=8, dim=512, heads=8, vocab_size=8192):
        self.transformer = nn.ModuleList([
            TransformerBlock(dim, heads)
            for _ in range(depth)
        ])
        self.lm_head = nn.Linear(dim, vocab_size)

9.2 Muon 优化器

Muon 是一个牛顿形式的优化器：

class Muon(Optimizer):
    def __init__(self, params, lr=1e-3):
        # Muon 使用 Newton-Schulz 迭代求矩阵平方根
        # 比标准 Adam 在某些任务上表现更好
        pass

9.3 BPE Tokenizer

字节对编码（BPE）是 AutoResearch 使用的分词方法：

• 从训练数据中学习词表
• vocab_size 控制词表大小
• 词表大小影响模型可表示的 token 序列长度

§10 最佳实践

10.1 实验设计

10.2 代码质量

10.3 平台迁移

§11 常见问题

Q1：AutoResearch 和 nanochat 是什么关系？

AutoResearch 基于 nanochat。nanochat 是一个简化版的单 GPU LLM 训练实现，AutoResearch 在此基础上添加了 AI 智能体自主实验的框架。

Q2：为什么训练时间固定为 5 分钟？

这是有意设计。固定时间预算确保实验结果可直接比较（无论架构变化），并让 AutoResearch 在你的硬件平台上找到最优模型。

Q3：val_bpb 是什么指标？

Validation Bits Per Byte（验证集每字节比特数）。它衡量模型在验证集上压缩文本的能力，越低越好。优势是与词表大小无关，便于公平比较架构变化。

Q4：AI 智能体修改什么文件？

AI 智能体只修改 train.py。这个文件包含完整的 GPT 模型、Muon + AdamW 优化器和训练循环。所有架构、超参数、优化器、批量大小等都可以改变。

Q5：program.md 是什么？

program.md 是 AI 智能体的基线指令文件。它为智能体提供研究和实验的上下文。人类通过修改这个文件来引导智能体的研究方向。

Q6：如何移植到其他平台？

参考"Notable forks"中各平台的实现。关键修改包括：

• 设备支持（CUDA → MPS/CPU）
• 注意力实现（Flash Attention → 通用实现）
• 内存优化

Q7：为什么结果是 62.1k stars 但只有 36 次提交？

这是因为 AutoResearch 是一个概念验证项目，代码故意保持极简。62.1k stars 主要反映了 Andrej Karpathy 的影响力以及"AI 自主科研"这一愿景的吸引力，而非项目本身的开发活跃度。

§12 总结

12.1 核心价值

12.2 适用场景

12.3 项目信息

• Stars：62.1k
• Forks：8.7k
• 贡献者：9 人
• 许可证：MIT
• 语言：Python 83.4%

12.4 相关资源

文档版本 1.0 | 撰写日期：2026-03-31 | Stars: 62.1k ⭐ | 基于 commit 228791f (2026-03-26)