实战

LLMs-from-scratch:从零手写一个 GPT 的开源教程

Sebastian Raschka 的开源仓库,用纯 PyTorch 把 GPT 从 token embedding 写到 SFT/DPO 全部实现,目前覆盖最完整的 LLM 教学项目之一。

字号

LLMs-from-scratch:从零手写一个 GPT 的开源教程

GitHub 上讲 LLM 的仓库一抓一大把,但能把整个 GPT 从 forward 写到 SFT/DPO、把每一层都拆到底的,目前最完整的之一:rasbt/LLMs-from-scratch。作者 Sebastian Raschka,Lightning AI 的研究科学家,出版过《Machine Learning with PyTorch and Scikit-Learn》;这本新书《Build a Large Language Model (From Scratch)》由 Manning 出版(ISBN 9781633437166),配套代码就在这个仓库里。

它解决什么问题

想搞清楚 LLM 内部机制的人,撞到的墙都一样:

  • HuggingFace 调包教程太多,AutoModelForCausalLM.from_pretrained 一行完事,但矩阵里在算什么你不知道。
  • 论文复读机太多,attention 公式抄一遍,但代码怎么落地不管。

这个仓库做的事更直接:用 ~400 行 PyTorch,从 token embedding → multi-head attention → LayerNorm → 预训练 → SFT 全跑一遍。代码全包在 Jupyter Notebook 里,每个 nn.Module 都拆到底,没藏任何抽象层。

跑完一遍,你至少能说清楚:(1) 为什么 d_out % num_heads == 0;(2) causal mask 怎么用上三角矩阵实现;(3) SFT 和预训练的 loss 区别在哪;(4) DPO 的隐式 reward 怎么从 ref 模型里抠出来。

怎么用

clone 下来是按章节组织的 Jupyter Notebook,按顺序读:

  • ch02_text_data.ipynb — tokenizer + sliding window 数据集
  • ch03_coding_attention_mechanisms.ipynb — 4 种 self-attention 变体
  • ch04_implementing_gpt_model.ipynb — TransformerBlock + GPTModel
  • ch05_pretraining_on_unlabeled_data.ipynb — 预训练
  • ch06_finetuning_for_classification.ipynb — 分类微调
  • ch07_instruction_finetuning.ipynb — SFT
  • ch08_aligning_models_with_human_feedback.ipynb — DPO/PPO

每章结尾有 exercises,答案在 exercise-solutions.ipynb。环境装法 README 推 uv。

最小可跑路线:开 Colab 免费 GPU,跑 ch04_implementing_gpt_model.ipynb,训一个 124M 的 GPT-2 骨架模型,几小时能出第一个能续写文本的 demo。完整覆盖跑完大概一周。

它怎么工作(架构)

整套代码自底向上分了 4 块:

  1. ch02 — 数据层:用 tiktoken 做 BPE tokenization,用 sliding window 把长文本切成 context_length 大小的训练样本。
  2. ch03 — Attention 层:从 naive self-attention → 带 causal mask → multi-head → 用 torch.nn.functional.scaled_dot_product_attention 的 PyTorch 内核版。每一版都跑同一个 toy 输入,对比输出。
  3. ch04 — 模型层:实现 TransformerBlock(含 LayerNorm + MHA + FFN + 残差连接)+ GPTModel。配置严格对齐 GPT-2 124M:d_model=768, n_heads=12, n_layers=12,能直接加载 OpenAI 官方权重(ch05)。
  4. ch07 + ch08 — 对齐层:SFT 用 instruction-response 格式的数据,DPO 用 ref model + policy model 的 log-ratio 差做隐式 reward。

关键设计:所有矩阵维度都在 GPT_CONFIG_124M 这个 dict 里统一管理,shape 错误基本跑不起来,方便对照 GPT-2 论文里的 Table 2 验证配置。

下面是 ch04_implementing_gpt_model.ipynb 里 MultiHeadAttention 的核心,30 行不到,把 Q/K/V 拆分、scaled dot-product、causal mask、dropout 全包了:

import torch
import torch.nn as nn

class MultiHeadAttention(nn.Module):
    def __init__(self, d_in, d_out, context_length, dropout, num_heads, qkv_bias=False):
        super().__init__()
        assert d_out % num_heads == 0, "d_out must be divisible by num_heads"
        self.d_out = d_out
        self.num_heads = num_heads
        self.head_dim = d_out // num_heads
        self.W_query = nn.Linear(d_in, d_out, bias=qkv_bias)
        self.W_key   = nn.Linear(d_in, d_out, bias=qkv_bias)
        self.W_value = nn.Linear(d_in, d_out, bias=qkv_bias)
        self.out_proj = nn.Linear(d_out, d_out)
        self.dropout = nn.Dropout(dropout)
        self.register_buffer(
            "mask", torch.triu(torch.ones(context_length, context_length), diagonal=1)
        )

    def forward(self, x):
        b, num_tokens, d_in = x.shape
        keys = self.W_key(x).view(b, num_tokens, self.num_heads, self.head_dim).transpose(1, 2)
        queries = self.W_query(x).view(b, num_tokens, self.num_heads, self.head_dim).transpose(1, 2)
        values = self.W_value(x).view(b, num_tokens, self.num_heads, self.head_dim).transpose(1, 2)
        attn_scores = queries @ keys.transpose(2, 3)
        attn_scores.masked_fill_(self.mask.bool()[:num_tokens, :num_tokens], -torch.inf)
        attn_weights = torch.softmax(attn_scores / self.head_dim**0.5, dim=-1)
        attn_weights = self.dropout(attn_weights)
        context_vec = (attn_weights @ values).transpose(1, 2).contiguous().view(b, num_tokens, self.d_out)
        return self.out_proj(context_vec)

跑这个 cell 之前先准备输入张量:

x = torch.randn(2, 6, 768)  # batch=2, tokens=6, d_model=768
mha = MultiHeadAttention(768, 768, context_length=1024, dropout=0.1, num_heads=12)
mha(x).shape
# torch.Size([2, 6, 768])

形状对得上就说明你的矩阵拆解没问题。Q/K/V 从 (b, tokens, d_out) reshape 到 (b, tokens, num_heads, head_dim) 再 transpose(1, 2),这是把多头并行算的核心动作,论文里那张图看十遍不如跑一遍这个 cell。

它哪里好 / 哪里不好

好的地方:

  1. 不藏任何抽象层——没有 nn.TransformerEncoder、AutoModel,所有层都自己实现。
  2. 配套书是 Manning 出版的,章节结构和排版比普通 repo 严谨得多,章节末尾有 "Summary" + "Exercises" 标准学术格式。
  3. 加了 Qwen3 / DeepSeek 权重加载章节,跟得上近两年的节奏。还补了 LoRA 和 KV cache 实现。

不好的地方:

  1. Jupyter 为主,没法直接当生产库 pip install 拿来调——from llms_from_scratch import GPTModel 不存在,得自己抄代码。
  2. 124M 模型在现代 LLM 标准下偏小,跑不出 ChatGPT 那种效果,主要还是教学目的。这仓库不是用来训 production 模型的。
  3. 对 RLHF/PPO 章节(ch08)写得比预训练部分浅很多,DPO 部分给了代码,但理论推导比较简略。想搞对齐工程的人得另找资料,比如 HuggingFace TRL 的文档或 Christiano 等人的原始论文。

我试了下

clone 完开了 ch04 配套的 gpt_train.ipynb,在 Colab T4 上跑 124M 模型 5k step,loss 从 ~11 降到 ~3.5。生成的样本语法连贯,比如 prompt "Once upon a time" 能续写完整的童话开头,但事实全是编的(这在 124M 模型上正常)。

ch03 末尾的 attention 可视化特别清楚,第 1 层学到的是相邻 token 对齐("the" 关注 "cat" 这种局部依赖),深层才出现长距离依赖——和 BERTology 论文里观察对得上。这部分光看论文讲不清楚,亲眼看到 attention map 才能感觉到 transformer 为什么 work。

另一个我注意到的点:ch07 的 SFT 数据用的是 instruction-data.json(Alpaca 风格),数据量不大,但足以让 124M 模型学会 instruction format——loss 降得比预训练阶段快,2k step 就稳了。这是小模型 + 高质量数据的典型案例。

谁该用

适合:

  • 想搞懂 transformer 内部到底在算什么的在职工程师——读完你能 code review 任何一份 attention 实现。
  • 面试被问 attention 公式想现场推一遍的人——这个仓库就是你的救命稻草。
  • ML 入门到 LLM 的过渡期,PyTorch 基础有了但没碰过 LLM 内部的人。

不适合:

  • 想直接拿生产级模型的人,出门左转 HuggingFace。
  • 想跑 7B+ 模型训练的人,这仓库只教学,不涉及 FSDP / ZeRO / tensor parallelism。
  • 完全不懂 PyTorch 基础的新手,建议先过一遍官方 60 分钟入门再来碰这个仓库。

依赖只有 PyTorch + Python,第三方就 tiktoken / datasets / wandb 三个。

原文链接:github.com/rasbt/LLMs-from-scratch

来源: https://github.com/rasbt/LLMs-from-scratch