跳到主要内容
AI教程

NamiGPT 入门教程：从零手写 GPT-2 并运行文本生成

本教程带你安装 NamiGPT，从分词、Embedding 和注意力开始理解 GPT-2，加载 OpenAI 官方权重并完成文本续写，同时介绍可视化工具、独立章节脚本、Gradio 演示与 HuggingFace 对齐测试。

AI我搜编辑部阅读约 10 分钟
NamiGPT 入门教程：从零手写 GPT-2 并运行文本生成

NamiGPT 是什么

NamiGPT 是一套面向中文初学者的大模型基础教程。它使用 PyTorch 从零实现 GPT-2，不调用现成的 Transformer 模块，并可加载 OpenAI 官方预训练权重，完成推理和文本生成。

NamiGPT 项目展示

项目不以训练效率为首要目标，而是强调理解：核心模型位于 gpt2/model.py，代码不到 200 行；教程以“猫吃鱼”这个三词示例为线索，把分词、向量、注意力矩阵和最终生成过程逐步拆开。

NamiGPT 的名字致敬 Karpathy 的 nanoGPT。它更侧重中文零基础教学，通过最小示例解释 GPT-2 的每一步。

你将学到什么

  • Tokenizer 如何把文本转换为 token ID。
  • Embedding 与位置编码如何构造模型输入。
  • Self-Attention 和 Multi-Head Attention 如何计算。
  • 残差连接、LayerNorm、FFN 与激活函数分别承担什么作用。
  • 多个 Transformer Block 如何堆叠成 GPT-2。
  • 如何把 OpenAI 官方权重载入手写模型。
  • 如何使用贪心、温度和 top-k 策略生成文本。
  • 如何通过测试验证手写实现与 HuggingFace 实现一致。

项目的主要特点

从零实现核心组件

NamiGPT 没有直接调用现成的 Transformer 模块。模型本体包含 LayerNorm、Attention、FFN、Block 和 GPT 等组件，适合逐行阅读数据与张量如何流动。

章节脚本可以独立运行

推理篇由 15 个逐步递进的主题组成，包括分词器、Embedding、位置编码、自注意力、多头注意力、残差连接、层归一化、前馈网络、激活函数、Transformer Block、堆叠、权重加载、文本生成和可解释性。每个教学主题都配有对应的可运行脚本。

提供交互式可视化

项目提供 Transformer 架构动态图和完整推理矩阵可视化。遇到代码或公式难以理解时，可以观察“猫吃鱼”示例中的矩阵元素如何逐格计算。

注意力矩阵逐格计算演示

建议先查看一张图看懂 Transformer，再使用大模型推理可视化对照章节代码。

与 HuggingFace 结果对齐

仓库包含形状检查以及与 HuggingFace 官方实现的对齐测试。除了使用随机权重快速比较，还可以下载真实 GPT-2 权重进行额外验证。

安装前准备

开始前需要具备基础 Python 阅读能力，并理解矩阵乘法等基本线性代数概念。项目标注的运行环境为 Python 3.9 及以上版本和 PyTorch 2.x。

先克隆仓库、进入项目目录并安装依赖：

git clone https://github.com/aa1143/NamiGPT.git
cd NamiGPT
pip install -r requirements.txt

如果下载 HuggingFace 上的官方权重时网络受限，可以在当前终端中设置镜像地址：

export HF_ENDPOINT=https://hf-mirror.com

该镜像只用于下载官方权重。后续调用 from_pretrained 时，模型结构仍然来自 NamiGPT 的手写实现。

第一步：按章节理解 GPT-2

最适合初学者的方式不是立即阅读完整模型，而是按推理数据流逐章学习：

  1. 输入阶段：先掌握 Tokenizer、Embedding 和位置编码。
  2. 注意力阶段：理解 Self-Attention，再扩展到 Multi-Head Attention。
  3. 模块阶段：学习残差连接、LayerNorm、FFN 和激活函数。
  4. 模型阶段：把组件组合为 Transformer Block，并堆叠为完整 GPT-2。
  5. 应用阶段：加载官方权重、生成文本并查看可解释性结果。

每个脚本都能单独运行。例如，执行多头注意力章节：

python chapters/01-inference/ep06_multi_head_attention.py

完整图文内容可在NamiGPT 图文教程中查看，仓库中的原稿位于 docs/01-inference/。

第二步：加载 GPT-2 并生成文本

完成安装后，可以直接导入 NamiGPT 提供的模型加载与生成接口。下面的示例使用 GPT-2 tokenizer，把英文提示词编码为 token ID，然后加载手写模型与官方 124M 权重：

import tiktoken, torch
from gpt2 import from_pretrained, generate

enc = tiktoken.get_encoding("gpt2")
model = from_pretrained("gpt2")

ids = torch.tensor([enc.encode("The cat sat on the")])
out = generate(
    model,
    ids,
    max_new_tokens=30,
    temperature=0.8,
    top_k=50,
)
print(enc.decode(out[0].tolist()))

代码执行流程

  1. tiktoken.get_encoding("gpt2") 获取 GPT-2 使用的编码器。
  2. enc.encode(...) 把提示文本转换为 token ID。
  3. torch.tensor 将 ID 包装成模型需要的批次张量。
  4. from_pretrained("gpt2") 创建手写 GPT-2，并载入官方 124M 权重。
  5. generate 在提示文本之后生成最多 30 个新 token。
  6. enc.decode 把输出 token ID 还原为文本。

注意：GPT-2 没有经过对话微调，它擅长的是根据已有内容继续写，而不是像聊天模型一样回答问题。其训练语料以英文为主，因此建议首先使用英文提示词。

第三步：理解生成参数

示例使用了两个重要的采样参数：

  • temperature=0.8：用于调整候选 token 的概率分布。项目的生成模块支持温度策略。
  • top_k=50：只从概率较高的前 50 个候选 token 中选择。项目同时支持贪心生成与 top-k 生成。

学习时可以保持提示文本不变，只调整温度或 top-k，然后对比续写结果。这样能直观看到生成策略如何影响输出，但具体参数应根据你的实验目标选择。

第四步：启动 Gradio 网页演示

如果希望在浏览器中输入提示词，并查看续写结果及每一步的候选词概率，可以安装 Gradio 并启动仓库中的演示程序：

pip install gradio
python demo/app.py

网页演示适合用来观察模型每一步的预测，而章节脚本更适合研究单个组件的计算过程。两者结合使用，可以把最终文本与内部概率变化对应起来。

第五步：运行测试

建议在修改注意力、权重加载或生成逻辑后运行测试。默认测试使用随机权重进行比较，不需要下载预训练模型，通常可以很快完成：

pytest tests/ -v

如果还要使用真实 GPT-2 权重进行额外对齐，可运行：

TEST_PRETRAINED=1 pytest tests/ -v

第二条命令会额外下载真实权重，因此首次运行需要等待下载完成。

仓库结构速览

  • gpt2/config.py：模型配置，包含 124M、355M、774M 和 1.5B 规格。
  • gpt2/model.py：LayerNorm、Attention、FFN、Block 与 GPT 模型本体。
  • gpt2/load_weights.py：把官方权重载入手写模型。
  • gpt2/generate.py：贪心、温度与 top-k 生成逻辑。
  • chapters/01-inference/：各篇教程对应的演示脚本。
  • docs/01-inference/：教程文章原稿。
  • demo/app.py：Gradio 网页演示。
  • tests/：形状检查和 HuggingFace 对齐测试。

高级技巧：与 HuggingFace 对齐的三个关键细节

1. 正确应用因果掩码

GPT-2 是自回归语言模型。序列中的每个词只能读取自身及前面的词，不能提前看到后续 token。如果遗漏因果掩码，即使成功加载官方权重，模型输出也会错误。

2. 搬运权重时处理转置

GPT-2 原始实现使用 Conv1D，其权重形状为 [in, out]；PyTorch 的 nn.Linear 使用 [out, in]。因此，把官方参数载入手写线性层时必须转置。

此外，c_attn 会把 Query、Key 和 Value 的参数拼在一起。对齐手写实现时，需要先把它们切分为对应的三部分，再放入正确位置。

3. 使用 tanh 近似版 GELU

GPT-2 使用的是 GELU 的 tanh 近似版本，而 PyTorch 的 nn.GELU() 默认采用精确版本。若要逐项对齐，应设置：

nn.GELU(approximate="tanh")

这三个细节看似很小，却会直接影响手写模型能否复现官方实现的结果。定位误差时，可以依次检查掩码、参数形状与激活函数版本。

推荐的学习与调试方法

  1. 先通过架构动态图理解 GPT-2 只使用 Transformer 解码器部分这一整体关系。
  2. 运行当前章节脚本，记录输入、输出和中间张量的形状。
  3. 遇到注意力矩阵难以理解时，对照在线矩阵可视化逐格检查。
  4. 完成一个组件后，再阅读 gpt2/model.py 中对应实现。
  5. 修改实现后先运行随机权重测试，再按需运行真实权重测试。
  6. 最后使用文本生成示例和 Gradio 页面观察完整模型行为。

这种顺序能把架构图、矩阵计算、章节代码、完整模型和最终输出连接起来，避免一开始就被完整 GPT-2 的多层结构淹没。

总结

NamiGPT 提供了一条从基础矩阵计算走向完整 GPT-2 推理的学习路径。你可以先运行独立章节脚本理解每个组件，再加载 OpenAI 官方权重完成英文文本续写，最后通过可视化和 HuggingFace 对齐测试验证自己的理解与修改。

项目代码采用 MIT 许可证；docs/ 目录中的文章采用 CC BY-NC 4.0 许可证，转载需注明出处且禁止商用。