第 0 章 项目导览与学习路线

在动任何代码之前，先建立全局心智模型。本章回答三个问题：这是什么？能学到什么？怎么学？

0.1 这个项目是什么

ht-gpt 是一个自底向上、工业代码风格的小型 GPT 训练与推理项目，用约 600 行 Python 实现了一条完整的语言模型流水线：

原始文本 ──► 分词编码 ──► 数据切片 ──► 模型构建 ──► 训练 ──► 推理 ──► Web 演示
​

它不手写 Transformer，而是站在 HuggingFace transformers 的肩膀上，专注于把工程流程讲透：配置怎么管、数据怎么来、checkpoint 怎么存续、学习率怎么调度、采样怎么调……

技术栈一览

0.2 你能学到什么

读完这套教程 + 跑通代码，你将掌握：

0.3 文件地图

ht-gpt/
├── config.py      ◄── 第 2 章：GPTConfig + TrainConfig（配置即代码）
├── dataset.py     ◄── 第 3 章：数据下载 + tiktoken 编码 + DataLoader
├── model.py       ◄── 第 4 章：build_model / load_model
├── train.py       ◄── 第 5 章：训练主循环（最重的一章）
├── inference.py   ◄── 第 6 章：GPTGenerator 自回归生成
├── app.py         ◄── 第 7 章：Gradio Web UI
├── requirements.txt
└── README.md
​

运行后还会自动生成：

data/                  # 数据集缓存
checkpoints/           # 训练 checkpoint（含 gpt_final.pt）
​

模块依赖关系

config.py ◄─── 被所有模块依赖（单一配置来源）
    │
    ├── dataset.py  ◄── 只依赖 config 的 block_size
    ├── model.py    ◄── 把 GPTConfig 映射为 HF GPT2Config
    │
    ├── train.py    ◄── 组合 config + dataset + model
    ├── inference.py◄── 组合 config + dataset(encoder) + model
    └── app.py      ◄── 组合 inference（Web 层）
​

清晰的分层：配置层 → 数据/模型层 → 训练/推理层 → 应用层。每层只依赖下一层，不反向依赖。

0.4 数据流全景

这是整个项目最重要的图，贯穿所有章节：

                ┌─────────────────────────────────┐
                │  原始文本（莎士比亚，~1MB）       │
                └─────────────────────────────────┘
                              │
                              ▼  get_dataset()
                              │  本地缓存 → HF datasets → GitHub 直链（三级回退）
                              │
                ┌─────────────────────────────────┐
                │  tiktoken p50k_base 编码         │
                │  → token id 序列（~33 万 token） │
                └─────────────────────────────────┘
                              │
                              ▼  TextDataset 切片
                              │  tokens[i : i+block_size+1]
                              │
                ┌─────────────────────────────────┐
                │  (x, y) 样本对                   │
                │  x = chunk[:-1]  y = chunk[1:]   │
                └─────────────────────────────────┘
                              │
                              ▼  DataLoader 批处理
                              │
                ┌─────────────────────────────────┐
                │  GPT2LMHeadModel（25M 参数）     │
                │  前向 → logits → CE loss         │
                └─────────────────────────────────┘
                              │
                              ▼  AdamW + 余弦退火 + 梯度裁剪
                              │  反向传播更新权重
                              │
                ┌─────────────────────────────────┐
                │  checkpoints/gpt_final.pt        │
                └─────────────────────────────────┘
                              │
                ┌─────────────┴─────────────┐
                ▼                           ▼
        inference.py 命令行         app.py Gradio Web UI
        （temperature + top-k）      （浏览器交互）
​

后续每章都在细化这条流水的某一段。

0.5 核心配置速览

把第 2 章的两组配置先列在这里，方便随时对照：

GPTConfig（模型架构）

默认规模约 25M 参数，单 GPU 几分钟可训完。

TrainConfig（训练流程）

0.6 建议的学习路线

路线 A：先跑后读（推荐新手）

1. 第 1 章：5 分钟跑通冒烟流程，建立「能跑」的信心。
2. 第 2 章：读 config.py，理解所有超参数的含义。
3. 第 3 章：读 dataset.py，搞懂数据怎么变成 (x, y)。
4. 第 4 章：读 model.py，理解模型怎么搭。
5. 第 5 章：读 train.py（最重），逐行理解训练循环。
6. 第 6 章：读 inference.py，搞懂采样策略。
7. 第 7 章：读 app.py，理解 Web UI。
8. 第 8、9 章：工程实践与进阶方向。

路线 B：自顶向下（推荐有基础的同学）

按章节顺序通读，遇到不懂的先标记跳过，第二遍再深入。

学习节奏建议

• 每章配代码一起读：打开对应 py 文件，对照教程逐行看。
• 每章末尾必做动手实验：3 个由浅入深的小练习。
• 不要超过 2 小时不停：Transformer 概念密度高，分块消化效果好。

0.7 学习心法

💡 核心原则：不要试图一次读懂所有细节。先建立「整体数据流」的心智模型，再逐章深入。每章末尾的「动手实验」是关键——读十遍不如跑一遍改一遍。

三条具体建议：

1. 先建立直觉，再抠细节。第一次读不懂余弦退火的数学公式没关系，先知道「学习率会先升后降」这个事实，能用，再回头抠公式。
2. 改一个参数，看一个变化。读完每章，主动改一个超参（比如 n_layer 翻倍），观察 loss 曲线、生成质量的变化。这种「反馈循环」比纯阅读强 10 倍。
3. 善用 print 调试。在每个关键节点打印 tensor 的 shape、loss 的值、lr 的值，让「黑盒」变「白盒」。

0.8 动手实验

1. 跑通冒烟流程：python train.py --max-iters 50 --n-layer 2 --n-embd 64 --n-head 2 --block-size 32，确认环境 OK。
2. 数文件：对照 0.3 的文件地图，把每个 py 文件打开看一眼，确认存在。
3. 画数据流：拿纸笔把 0.4 的数据流图抄一遍，加深记忆。

0.9 下一章

环境装好、心智模型建立后，去 第 1 章 环境准备与首次运行 把项目真正跑起来。