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

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

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

0.1 这个项目是什么

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

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

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

技术栈一览

0.2 你能学到什么

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

0.3 模块地图

本项目把一条流水线拆成六个模块，每个模块职责单一、只依赖下一层：

运行后还会自动生成两个目录：数据集缓存目录（约 1MB）与训练 checkpoint 目录（含最终模型，25M 规模约 100MB）。

模块依赖关系

配置层  ◄─── 被所有模块依赖（单一配置来源）
    │
    ├── 数据层    ◄── 只依赖配置的上下文长度
    ├── 模型层    ◄── 把配置映射为框架参数
    │
    ├── 训练入口  ◄── 组合 配置 + 数据 + 模型
    ├── 推理层    ◄── 组合 配置 + 数据(编码器) + 模型
    └── 应用层    ◄── 组合 推理层（Web 层）
​

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

0.4 数据流全景

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

                ┌─────────────────────────────────┐
                │  原始文本（莎士比亚，~1MB）       │
                └─────────────────────────────────┘
                              │
                              ▼  数据获取（三级回退）
                              │  本地缓存 → 框架数据集 → 直链下载
                              │
                ┌─────────────────────────────────┐
                │  tiktoken p50k_base 编码         │
                │  → token id 序列（~33 万 token） │
                └─────────────────────────────────┘
                              │
                              ▼  数据集切片
                              │  tokens[i : i+block_size+1]
                              │
                ┌─────────────────────────────────┐
                │  (x, y) 样本对                   │
                │  x = chunk[:-1]  y = chunk[1:]   │
                └─────────────────────────────────┘
                              │
                              ▼  DataLoader 批处理
                              │
                ┌─────────────────────────────────┐
                │  GPT2LMHeadModel（25M 参数）     │
                │  前向 → logits → 交叉熵损失      │
                └─────────────────────────────────┘
                              │
                              ▼  AdamW + 余弦退火 + 梯度裁剪
                              │  反向传播更新权重
                              │
                ┌─────────────────────────────────┐
                │  最终模型权重快照                │
                └─────────────────────────────────┘
                              │
                ┌─────────────┴─────────────┐
                ▼                           ▼
        命令行推理                   Web UI 交互界面
        （temperature + top-k）      （浏览器交互）
​

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

0.5 核心配置速览

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

GPTConfig（模型架构）

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

TrainConfig（训练流程）

0.6 建议的学习路线

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

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

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

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

学习节奏建议

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

0.7 学习心法

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

三条具体建议：

1. 先建立直觉，再抠细节。第一次读不懂余弦退火的数学公式没关系，先知道「学习率会先升后降」这个事实，能用，再回头抠公式。
2. 改一个参数，看一个变化。读完每章，主动改一个超参（比如层数翻倍），观察 loss 曲线、生成质量的变化。这种「反馈循环」比纯阅读强 10 倍。
3. 善用 print 调试。在每个关键节点打印张量的 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 的模块地图，把每个模块打开看一眼，确认存在。
3. 画数据流：拿纸笔把 0.4 的数据流图抄一遍，加深记忆。

0.9 下一章

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