10分钟跑通microgpt-c:纯C版GPT从编译、训练到推理的完整入门教程
10分钟跑通microgpt-c:纯C版GPT从编译、训练到推理的完整入门教程
microgpt-c 是一个用纯 C 语言从零实现的 GPT(GPT 语言模型):无需 GPU、无需任何第三方依赖,一条 gcc 命令即可编译,运行后会自动完成训练 + 推理全流程——训练出能"编名字"的迷你 GPT,并在纯 CPU 上测出约 260 万 tokens/秒 的推理速度。对于想搞懂 Transformer 内部机制的初学者来说,这是目前门槛最低、最适合上手的项目之一。
一、microgpt-c 是什么?为什么值得玩
大多数"从零实现 GPT"的教程都基于 Python + PyTorch,代码动辄上千行、依赖一堆框架。而 microgpt-c 把整个 GPT 压缩进一个 C 文件:
- 🚫 零依赖:只用了 C 标准库和数学库,不需要装 CUDA、PyTorch 或任何框架
- ⚡ 单文件实现:全部核心逻辑就 microgpt.c 一个文件(约 790 行)
- 📉 自带训练循环:运行时自动在 names.txt(3 万多个英文人名)上训练 20000 步
- 🏃 自带推理与性能基准:训练完直接采样 10 个名字,并跑一次高速推理 benchmark
- 🔬 工业级优化手法:AVX2 向量化、手写的快速
exp、KV Cache、Adam 优化器、梯度裁剪一应俱全
简单说:它既是一个能跑的 GPT,也是一份可以逐行读懂的 GPT 教学代码。
项目文件结构一览
| 文件 | 说明 |
|---|---|
| microgpt.c | 唯一的核心源码:数据集加载、分词、模型前向/反向传播、训练循环、推理采样、性能测试 |
| names.txt | 训练数据集,约 3.2 万行英文人名,一行一个 |
| README.md | 编译与运行说明 |
| Articles/Building GPT from Scratch in Pure C (Step-by-Step).md.md) | 官方配套教程,逐段讲解每个 C 函数背后的原理(强烈推荐阅读) |
二、快速上手:克隆仓库并用一条命令编译 microgpt-c
1. 获取代码
仓库只包含上面 3 个核心文件,克隆非常快:
git clone https://gitcode.com/gh_mirrors/mi/microgpt-c
cd microgpt-c
2. 一键编译(官方推荐命令)
gcc -O3 -march=native -ffast-math -o microgpt microgpt.c -lm
这条命令里的每个参数都在为速度服务:
| 参数 | 作用 |
|---|---|
-O3 |
开启 GCC 最高级别优化 |
-march=native |
启用当前 CPU 的全部指令集(AVX、FMA 等) |
-ffast-math |
允许更激进的浮点运算优化(牺牲极少量精度) |
-lm |
链接数学库(sqrt、exp 等函数) |
💡 提示:
-march=native只能在当前机器上编译运行,生成的二进制换台电脑可能跑不起来。如果要发布,建议去掉该参数。
3. 运行
./microgpt
就这么简单——没有配置文件、没有命令行参数,程序会一口气把"加载数据 → 建词表 → 训练 20000 步 → 采样生成 → 性能测试"全部做完。
三、看懂运行输出:训练 loss 与推理结果
正常运行后,输出大致如下(数值每次略有不同):
num docs: 32033
vocab size: 27
num params: 8320
step 1 / 20000 | loss 3.3178 (avg 3.3002)
step 5000 / 20000 | loss 2.6062 (avg 2.2945)
step 10000 / 20000 | loss 1.9652 (avg 2.2562)
step 15000 / 20000 | loss 2.6978 (avg 2.2153)
step 20000 / 20000 | loss 2.3462 (avg 2.2188)
--- inference ---
sample 1: kayley
sample 2: maria
sample 3: arana
...
sample 10: mailyn
c fp32+AVX2 2,631,689 tok/sec
逐段解读:
num docs: 32033:成功加载了 32033 个人名文档(每行一个名字,就是一个"文档")vocab size: 27:词表大小为 27 —— 26 个英文字母 + 1 个起始符BOS。这是一个字符级 tokenizer,不依赖任何预训练分词器num params: 8320:整个模型只有 8320 个参数(约 32 KB),装得下任何计算器loss逐渐下降:交叉熵损失从 3.3 左右降到 2.2 附近,说明模型正在学会"英文人名的拼写规律"(首字母大写、常见元音组合、名字结尾的字母偏好……)--- inference ---:进入推理阶段,模型从BOS出发逐字采样,生成 10 个"新名字"c fp32+AVX2 2,631,689 tok/sec:性能基准——纯 C + AVX2 指令集,单核 CPU 每秒可生成约 263 万个 token
生成结果为什么是"奇怪但合理的名字"?
注意看生成的 arana、saria、amari——它们不是数据集中已有的名字,而是模型学到的"名字分布"的采样结果:拼写上完全像真人名,但可能并不存在。这恰恰说明模型不是死记硬背,而是学到了概率规律。🎉
四、10 分钟读懂内部原理:训练、反向传播与推理
microgpt.c 的结构和标准 GPT 完全一致,只是用 C 重新实现了每一块。按代码顺序,整个程序可以分为 5 个阶段:
1. 数据加载与字符级分词
load_dataset():逐行读取 names.txtbuild_tokenizer():扫描全部字符,按 ASCII 排序生成 26 个字母 + 1 个BOS的迷你词表
对应源码位置:microgpt.c#L83-L129
2. 超小的 GPT 架构
模型由 microgpt.c#L132-L137 中的几个宏定义,非常迷你:
| 超参数 | 值 | 含义 |
|---|---|---|
N_EMBD |
16 | 词向量维度 |
N_LAYER |
1 | Transformer 层数(只有 1 层) |
N_HEAD |
4 | 注意力头数 |
BLOCK_SIZE |
16 | 上下文窗口长度 |
MLP_DIM |
64 | MLP 隐藏层维度 |
对比 GPT-3 的 96 层、12288 维,这里每一维都在"故意做小"——为了在纯 CPU 上秒级训完。
3. 前向传播与训练循环
main() 中的训练循环(microgpt.c#L616-L700)每步做四件事:
- 前向:
gpt_forward()逐位置嵌入 → RMSNorm → 多头注意力 → MLP → 输出 logits,并缓存 KV(kv_keys/kv_vals就是 KV Cache 的实现) - 反向:
gpt_backward()从损失逐层算回梯度,包括最容易出错的注意力反向(softmax 雅可比矩阵) - 梯度裁剪:全局梯度范数超过 1.0 时按比例缩放,保证训练稳定
- Adam 更新:手写 Adam 优化器 + 余弦退火学习率(
lr = 3e-3起步,按 cosine 曲线衰减)
对应实现:microgpt.c#L374-L456(前向)、microgpt.c#L459-L563(反向)
4. 推理采样
训练结束后进入采样模式(microgpt.c#L705-L724):
- 从
BOS出发,每步做一次前向,得到 27 个词的概率分布 - 用
temperature = 0.5锐化分布,再通过weighted_choice()按概率随机抽样 - 抽到
BOS就停(表示"名字结束了"),否则继续拼下一个字符
5. 极致性能优化(本项目最大看点)
microgpt.c 之所以能跑 260 万 tok/s,靠的是一系列"极限微操":
- 固定宽度手写内核:
dot16/dot4/dot64针对维度 16/4/64 各写了专用 AVX2 点积函数,完全展开循环,见 microgpt.c#L251-L274 - Schraudolph 快速 exp:用位操作近似
expf,误差约 1 ULP,但快 3-4 倍,见 microgpt.c#L35-L39 - KV Cache:自回归生成时不重算历史 Key/Value
#pragma GCC optimize:在源码顶部直接声明启用 AVX2/FMA 指令集,见 microgpt.c#L6-L9
这些手法正是把 LLM 推理引擎做到极致速度的常见套路,microgpt-c 让你在一个小模型上就能把它们全部看明白。
五、常见问题(FAQ)
Q1:编译报错 -march=native 相关错误?
说明编译器/系统对该指令集支持不佳,去掉 -march=native 重新编译即可,功能完全不受影响,只是速度略慢。
Q2:运行时提示 Cannot open names.txt?
程序从当前工作目录读取 names.txt,请确保在仓库根目录下运行 ./microgpt。
Q3:没有 GPU 能跑吗? 能。本项目全程纯 CPU,这正是 microgpt-c 的设计目标——最"原子化"的 GPT 实现。
Q4:想深入理解每段代码的原理? 阅读官方分步教程 Articles/Building GPT from Scratch in Pure C (Step-by-Step).md.md),它从随机数生成讲到注意力反向传播,逐函数配原理推导。
六、总结:microgpt-c 适合谁?
✅ 初学者:不用装任何框架,10 分钟跑通"编译 → 训练 → 推理"完整链路,亲眼看着 loss 下降、看着模型生成第一个名字 ✅ C 语言学习者:790 行代码涵盖指针、数组、位操作、结构体、手写优化器等硬核知识点 ✅ 推理优化爱好者:KV Cache、AVX2 内核、快速 exp、梯度裁剪——LLM 推理引擎的核心技巧一次看全 ✅ 想真正搞懂 GPT 的人:它把"生成式预训练 Transformer"的每一个部件都摊开给你看,没有黑盒
一条 gcc 命令,一个 32 KB 的模型,260 万 tokens/秒的 CPU 推理速度——这就是 microgpt-c,最原子化的 GPT 打开方式。🚀