一天一个开源项目（第22篇）：nanochat - 百元级「最好的 ChatGPT」，Karpathy 的极简 LLM 训练套件

引言

这是"一天一个开源项目"系列的第22篇文章。今天带你了解的项目是 nanochat（GitHub），作者是 Andrej Karpathy。项目 slogan 是：The best ChatGPT that $100 can buy（百元能买到的最好的 ChatGPT）。

nanochat 不是又一个臃肿的「LLM 框架」——没有巨型配置对象、没有模型工厂、没有满屏 if-else。它是一个极简、可读、可改、可 fork 的端到端实验套件：从分词、预训练、微调、评估到推理和聊天 Web UI，全部打通；并且通过一个旋钮 --depth（Transformer 层数）自动推导出宽度、头数、学习率、训练步数等，得到计算最优的一族模型。你想「要一个 GPT-2 水平的模型」？把 depth 调到约 26，跑一遍 runs/speedrun.sh，几小时后就能在类 ChatGPT 的界面上和它对话。

你将学到什么

• nanochat 的定位：极简、单机多卡、全流程覆盖的 LLM 训练与对话套件
• 「一个旋钮」设计：--depth 如何决定计算最优的超参与模型规模
• 从 speedrun 到聊天：如何用一条脚本训练出 GPT-2 级模型并用 Web UI 对话
• Time-to-GPT-2 排行榜与 CORE 指标的含义
• 项目目录结构、核心脚本与扩展方式（新能力、身份/人格注入）
• 与 nanoGPT、modded-nanogpt 及常见 LLM 框架的对比

前置知识

• 对 Transformer、GPT 类模型有基本概念
• 了解预训练（pretraining）与微调（finetuning/SFT）的区分
• 会用 Python、PyTorch，对多卡训练（如 torchrun）有粗浅认识更佳
• 有 GPU 环境（单卡或多卡）更利于动手复现

项目背景

项目简介

nanochat 是 Andrej Karpathy 开源的极简 LLM 实验套件，面向单 GPU 节点（如 8×H100），代码量小、结构清晰、便于阅读和修改。它覆盖 LLM 的完整链路：分词（tokenization）、预训练（pretraining）、微调（SFT/RL）、评估、推理与聊天 UI。目标不是做成「可配置一切」的框架，而是提供一个强基线：从零跑到能对话的 ChatGPT 式模型，成本控制在百美元量级（例如 8×H100 约 3 小时、约 72 美元；spot 实例可低至约 20 美元）。

项目解决的核心问题：

• 想亲手训练、微调并和一个小型 LLM 对话，但主流框架过于复杂、认知负担大
• 需要一套计算最优的默认配置，而不是自己调几十个超参
• 希望代码极简、可 hack、易 fork，便于研究和教学
• 预算有限（<1000 美元），希望有明确的时间与成本预期（如「3 小时到 GPT-2」）

面向的用户群体：

• 想端到端跑通 LLM 训练与对话的开发者、学生
• 做小模型与 scaling 研究的研究者
• 希望理解 GPT 类模型从数据到对话全流程的爱好者
• 需要可修改、可复现的基线代码的团队

作者/团队介绍

• 作者：Andrej Karpathy（@karpathy），曾任 Tesla AI 负责人、OpenAI 研究员，斯坦福 CS 博士；以 nanoGPT、零基础神经网络 等教程和项目广为人知。
• 致谢：nanochat 之名来自 nanoGPT；预训练与排行榜设计受 modded-nanoGPT 启发；致谢 HuggingFace（fineweb、smoltalk）、Lambda（算力）、Alec Radford、Sofie @svlandeg 等。
• 项目创建时间：2025 年 10 月（GitHub 显示 created_at 2025-10-13）。

项目数据

• ⭐ GitHub Stars: 43k+
• Forks: 5.6k+
• 版本: 无正式版本号，以 master 为主干；README 与 Discussions 持续更新（如 2026 年 2 月 leaderboard、fp8、batch size 等）。
• License: MIT
• 官网: 无独立官网，以 GitHub 与 Discussions 为主
• 社区: GitHub Discussions、Discord #nanochat；README 推荐用 DeepWiki 提问

主要功能

核心作用

nanochat 的核心作用是在单机多卡上，用最少心智负担，跑通从数据到可对话 LLM 的全流程，并默认给出计算最优的一族模型（通过 --depth 一个旋钮）：

1. 分词：BPE tokenizer 训练与评估（GPT-4 风格封装）
2. 预训练：base 模型训练，支持分布式与梯度累积，追求「Time-to-GPT-2」极速
3. 微调：SFT（监督微调）、RL 等，配合 tasks（ARC、GSM8K、MMLU、Humaneval、SmolTalk 等）
4. 评估：CORE 分数（DCLM）、bits per byte、各类 task 评估
5. 推理：带 KV Cache 的高效推理引擎
6. 对话：CLI 与 ChatGPT 式 Web UI，可直接与训练好的模型聊天

使用场景

1. 复现「百元 GPT-2」并与之对话

   • 租一台 8×H100（或 8×A100），执行 bash runs/speedrun.sh，约 3 小时后用 python -m scripts.chat_web 启动 Web UI，像用 ChatGPT 一样和模型对话（写诗、问答、看幻觉等）

2. 研究与迭代预训练

   • 用 runs/scaling_laws.sh、runs/miniseries.sh 做 scaling 实验；用 --depth=12 等小模型做约 5 分钟级的快速预训练迭代，通过 wandb 看 val_bpb、core_metric、MFU、tok/s 等

3. 教学与理解全流程

   • 代码精简、无巨型抽象，适合作为「从 token 到 chat」的教材式代码库

4. 为模型注入身份/人格

   • 通过 Discussions 中的 Guide: infusing identity，用合成数据在 SFT 阶段注入人设

5. 扩展新能力

   • 参考 counting r in strawberry 等，在 tasks 中增加新任务或数据格式

快速开始

环境：推荐 Python + uv，项目根目录有 pyproject.toml 与 uv.lock。

一键复现 GPT-2 并对话（需 8×H100 级节点，如 Lambda）：

# 克隆
git clone  && cd nanochat

# 创建虚拟环境并安装依赖（示例）
uv venv && source .venv/bin/activate
uv sync

# 跑完整 pipeline（预训练 + 微调等，约 3 小时）
bash runs/speedrun.sh

训练结束后，启动聊天 Web UI：

source .venv/bin/activate
python -m scripts.chat_web

在浏览器访问终端里打印的 URL（如 ;机器IP>:8000/），即可像 ChatGPT 一样与模型对话。

单 GPU 或小显存：可去掉 torchrun 单卡跑（会慢约 8 倍）；显存不足时在脚本中调小 --device_batch_size（如 32→16→8→4→2→1）。CPU/Apple Silicon：见 runs/runcpu.sh，会大幅缩小模型与步数，仅作演示，效果有限。

核心特性

1. 单一复杂度旋钮 --depth

   • Transformer 层数决定模型规模；其他超参（宽度、头数、学习率、训练步数、weight decay 等）由代码自动按计算最优方式推导，用户只需选「更大或更小」的模型。

2. Time-to-GPT-2 排行榜

   • 以 DCLM CORE 分数衡量「达到 GPT-2 (1.6B) 水平」的墙钟时间；当前约 2.76–3.04 小时（8×H100），README 与 dev/LEADERBOARD.md 持续更新。

3. 全流程覆盖

   • tokenizer 训练与评估、base 预训练、SFT/RL、CORE/bpb 评估、多任务评估、KV Cache 推理、CLI/Web 聊天，一套代码走到底。

4. 极简代码库

   • 无大型框架式配置与工厂，结构清晰（nanochat/ 核心库 + scripts/ 入口 + runs/ 脚本 + tasks/ 任务），便于阅读和改代码。

5. 分布式与单卡统一

   • 多卡用 torchrun，单卡自动退化为梯度累积，结果一致。

6. ChatGPT 式 Web UI

   • scripts.chat_web 提供本地 Web 界面，与训练好的 chat 模型对话。

7. 研究友好

   • 提供 scaling_laws、miniseries 等脚本；PR 需披露 LLM 辅助写作部分（见 Contributing）。

项目优势

为什么选择 nanochat？

• Karpathy 背书：nanoGPT 同源，设计哲学一致，适合学习与二次开发
• 百元级可复现：成本与时间预期明确（~$72\mathrm{/}3h\text{或}spot$20）
• 教学与科研兼顾：既可作为「从零到对话」的教材，也可做 scaling/预训练研究基线
• 极简可 fork：无臃肿抽象，改几处就能做实验或教学变体

项目详细剖析

架构与目录结构

项目以「库 + 脚本 + 运行配置」分层：

• nanochat/：核心库
  • gpt.py：GPT Transformer
  • tokenizer.py：BPE 封装
  • dataloader.py、dataset.py：分布式数据与 tokenization
  • optim.py：AdamW、Muon，单卡与分布式
  • engine.py：推理与 KV Cache
  • checkpoint_manager.py： checkpoint 读写
  • core_eval.py：CORE 分数（DCLM）；loss_eval.py：bits per byte
  • execution.py：模型可执行 Python 作为工具（若启用）
  • ui.html：聊天前端静态资源
• scripts/：入口
  • base_train.py / base_eval.py：预训练与评估
  • chat_sft.py / chat_rl.py：微调；chat_cli.py / chat_web.py：对话
  • tok_train.py / tok_eval.py：分词训练与评估
• runs/：一键脚本
  • speedrun.sh：从零到 GPT-2 级并对话
  • scaling_laws.sh、miniseries.sh：研究与 miniseries
  • runcpu.sh：CPU/MPS 小规模演示
• tasks/：评估与数据
  • ARC、GSM8K、MMLU、Humaneval、SmolTalk、spellingbee 等，以及 TaskMixture / TaskSequence 与自定义 jsonl（customjson.py）

「一个旋钮」：depth 与计算最优

nanochat 的设计核心是：用户只设 --depth（层数），其余（宽度、头数、学习率、训练步数、weight decay 等）由代码按计算最优关系自动算出，从而得到一族在不同规模上都是「算力用得最值」的模型。GPT-2 能力对应的模型大约在 depth 24–26；改 depth 即可得到更大或更小的 miniseries 模型。任何对 repo 的改动都被要求在不同 depth 下都合理，避免只针对某一规模调参。

预训练与排行榜

预训练是当前开发重点。Time-to-GPT-2 定义为：在 8×H100 节点上，墙钟时间达到超过 GPT-2 (1.6B) 的 DCLM CORE 分数（0.256525）。README 中的表格会更新最佳时间（目前约 2.76–3.04 小时）、val_bpb、CORE、描述、日期与 commit。研究时可用小 depth（如 12）做短时预训练，在 wandb 中观察 val_bpb、core_metric、MFU、tok/s 等，快速验证想法。

扩展与定制

• 新能力：在 tasks/ 中增加新任务或数据格式，参考 counting r in strawberry。
• 身份/人格：用合成数据参与 SFT，见 Guide: infusing identity。
• 数据与 repackage：dev/repackage_data_reference.py 等与 pretraining 数据分片相关。

依赖与运行环境

• Python：项目含 .python-version，推荐用 uv 管理环境
• PyTorch：核心依赖；支持 CUDA、理论上可尝试 xpu/mps 等，但非全部路径都经充分测试
• GPU：speedrun 针对 8×H100（或 8×A100，稍慢）；单卡或小显存需调小 device_batch_size 或使用 runcpu.sh 类脚本

项目地址与资源

官方资源

• GitHub: github.com/karpathy/na…

适用人群

• 想亲手训练并和 LLM 对话的开发者：百元级、一条脚本、几小时即可得到可对话模型
• 做小模型与 scaling 研究的研究者：极简基线、单旋钮、排行榜与脚本齐全
• 教学：适合作为「从 token 到 chat」的全流程教学代码
• 需要可读、可改、可 fork 的基线：无巨型框架，便于在 nanochat 之上做自己的变体

欢迎来我中的个人主页找到更多有用的知识和有趣的产品