llm.c

用简洁、纯粹的 C/CUDA 实现大型语言模型，无需依赖 245MB 的 PyTorch 或 107MB 的 cPython。目前的重点是预训练，尤其是复现 GPT-2 和 GPT-3 系列小模型，并提供一个并行的 PyTorch 参考实现，位于 train_gpt2.py 中。你可能会发现这个文件与我早期的一个项目 nanoGPT 有些许调整。目前，llm.c 的速度比 PyTorch Nightly 版本快约 7%。除了位于 train_gpt2.cu 中的最前沿主线代码外，我们还提供了一个简单的 CPU fp32 参考实现，包含约 1,000 行干净的代码，全部写在一个文件 train_gpt2.c 中。我希望这个仓库只维护 C 和 CUDA 代码。其他语言或仓库的移植非常欢迎，但应放在独立的仓库中，我乐意在下方的“值得关注的分支”部分链接它们。开发者之间的协作通过 Discussions 和 Discord 进行，可以在 Zero to Hero 频道的 #llmc 频道，或者在 GPU MODE Discord 的 #llmdotc 频道进行。

快速入门

今天了解 llm.c 仓库的最佳方式就是复现 GPT-2（1.24亿参数）模型。讨论 #481 详细介绍了这一过程。我们可以在 llm.c 和 PyTorch 的并行实现中复现 GPT-2 和 GPT-3 系列的其他模型。请查看 scripts README。

调试提示：当你运行 make 命令构建二进制文件时，可以将 -O3 替换为 -g，以便在你喜欢的 IDE（例如 VS Code）中逐步调试代码。

快速入门（单 GPU，仅 fp32）

如果你不需要在多节点上训练，也不关心混合精度，并且对学习 CUDA 感兴趣，那么 fp32（旧版）文件可能更适合你。这些文件是在 llm.c 发展初期“保存”的版本，此后便不再更新。它们更简单、更易移植，也可能更容易理解。你可以这样运行单 GPU 的 fp32 代码：

chmod u+x ./dev/download_starter_pack.sh
./dev/download_starter_pack.sh
make train_gpt2fp32cu
./train_gpt2fp32cu

download_starter_pack.sh 脚本是一个快速简便的入门方式，它会下载一些 .bin 文件帮助你快速上手。这些文件包括：1) 以 fp32 和 bfloat16 格式保存的 GPT-2 1.24亿参数模型；2) 用于单元测试的“调试状态”（一小批数据以及目标激活值和梯度）；3) GPT-2 分词器；以及 3) 经过分词的 tinyshakespeare 数据集。或者，你也可以不运行该脚本，而是手动重新创建这些文件和工件，如下所示：

pip install -r requirements.txt
python dev/data/tinyshakespeare.py
python train_gpt2.py

快速入门（CPU）

适用于“连一块 GPU 都没有”的情况。即使没有 GPU，你仍然可以体验 llm.c 的训练过程！不过进展不会太远。与上述 fp32 版本一样，CPU 版本是 llm.c 更早时期的快照，那时它还只是一个简单的 C 语言参考实现。例如，与其从头开始训练，不如对 GPT-2 小模型（1.24亿参数）进行微调，使其生成类似莎士比亚风格的文本，示例如下：

chmod u+x ./dev/download_starter_pack.sh
./dev/download_starter_pack.sh
make train_gpt2
OMP_NUM_THREADS=8 ./train_gpt2

如果你不想运行启动包脚本，也可以像前一节提到的那样，通过运行 python dev/data/tinyshakespeare.py 和 python train_gpt2.py 来重现完全相同的 .bin 文件和工件。

以上步骤（1）下载已经分词的 tinyshakespeare 数据集，并下载 GPT-2（1.24亿参数）的权重；（3）使用这些权重在 C 语言中初始化模型，在 tinyshakespeare 数据集上以 AdamW 优化器训练 40 步（批量大小为 4，上下文长度仅为 64），评估验证损失，并采样生成一些文本。老实说，除非你有一台性能强劲的 CPU（并且能够在启动命令中增加 OMP 线程数），否则在 CPU 上训练大型语言模型的效果不会太好，但这或许可以作为一个不错的演示或参考。以下是我 MacBook Pro（Apple Silicon M3 Max）上的输出结果：

[GPT-2]
max_seq_len: 1024
vocab_size: 50257
num_layers: 12
num_heads: 12
channels: 768
num_parameters: 124439808
train dataset num_batches: 1192
val dataset num_batches: 128
num_activations: 73323776
val loss 5.252026
step 0: train loss 5.356189（耗时 1452.121000 ms）
step 1: train loss 4.301069（耗时 1288.673000 ms）
step 2: train loss 4.623322（耗时 1369.394000 ms）
step 3: train loss 4.600470（耗时 1290.761000 ms）
...（截断）...
step 39: train loss 3.970751（耗时 1323.779000 ms）
val loss 4.107781
生成：
---
奔逃而来，
更大的征服者，
带着皇室血脉，
众神中最强大的军队，
进入这奇妙的世界之外。
我不会支持你，因为出生之后是多么甜蜜啊——
Netflix 对抗 repounder，
将不会
繁荣于 Allay 的耳环之下——
---

数据集

位于 /dev/data/(dataset).py 中的数据文件负责下载、分词并将分词结果保存为 .bin 文件，以便 C 语言轻松读取。例如，当你运行：

python dev/data/tinyshakespeare.py

我们会下载并分词 tinyshakespeare 数据集。其输出如下：

将 32,768 个 token 写入 ./dev/data/tinyshakespeare/tiny_shakespeare_val.bin
将 305,260 个 token 写入 ./dev/data/tinyshakespeare/tiny_shakespeare_train.bin

这些 .bin 文件包含一个 1024 字节的头部，随后是以 uint16 格式存储的 token 流，表示使用 GPT-2 分词器得到的 token ID。更多数据集可在 /dev/data 中找到。

测试

我还附带了一个简单的单元测试，用于确保我们的 C 代码与 PyTorch 代码一致。以 CPU 为例，编译并运行如下命令：

make test_gpt2
./test_gpt2

此测试会加载由 train_gpt2.py 生成的 gpt2_124M_debug_state.bin 文件，执行一次前向传播，比较 logits 和损失与 PyTorch 参考实现的结果，然后进行 10 次 Adam 优化迭代，确保损失与 PyTorch 的结果一致。对于 GPU 版本，我们运行：

# fp32 测试（不支持 cuDNN）
make test_gpt2cu PRECISION=FP32 && ./test_gpt2cu
# 混合精度 cuDNN 测试
make test_gpt2cu USE_CUDNN=1 && ./test_gpt2cu

这将分别测试 fp32 路径和混合精度路径。测试应该通过，并打印出 overall okay: 1。

教程

我在这里附上了一个非常简短的教程，位于 doc/layernorm/layernorm.md。它是一个简单、循序渐进的指南，用于实现 GPT-2 模型中的单个层——LayerNorm 层。这是一个很好的起点，可以帮助你理解 C 语言中各层的具体实现方式。

Flash Attention。截至 2024 年 5 月 1 日，我们使用 cuDNN 提供的 Flash Attention。由于 cuDNN 会将编译时间从几秒延长到约一分钟，且该代码路径目前仍处于早期阶段，因此默认情况下已禁用此功能。你可以通过以下方式启用它：

make train_gpt2cu USE_CUDNN=1

这将尝试使用 cuDNN 进行编译并运行。你需要在系统上安装 cuDNN。按照 cuDNN 安装说明，使用 apt-get 安装会获取默认的 cuDNN 软件包集。对于最小化配置，仅安装 cuDNN 开发包即可，例如在 Ubuntu 22.04 上针对 CUDA 12.x 的安装命令如下：

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
sudo apt-get -y install libcudnn9-dev-cuda-12

此外，你还需要 cuDNN 前端库，但它只是头文件。只需将该仓库克隆到你的磁盘上即可。当前的 Makefile 会在你的主目录或当前目录中查找它。如果你将其放置在其他位置，请在 make 命令行中添加 CUDNN_FRONTEND_PATH=/path/to/your/cudnn-frontend/include。

多 GPU 训练

请确保已安装 MPI 和 NCCL，例如在 Linux 系统上：

sudo apt install openmpi-bin openmpi-doc libopenmpi-dev

对于 NCCL，请遵循 官方网站 的说明（例如使用网络安装程序），然后执行以下命令：

make train_gpt2cu
mpirun -np <GPU数量> ./train_gpt2cu

或者直接运行 ./scripts/ 目录下的脚本之一。

多节点训练

请确保已按照“多 GPU 训练”部分的说明安装了 NCCL。

我们目前支持三种多节点训练的方式：

1. 使用 OpenMPI 交换 NCCL ID 并初始化 NCCL。详情请参阅 ./scripts/multi_node/run_gpt2_124M_mpi.sh 脚本。
2. 使用共享文件系统初始化 NCCL。详情请参阅 ./scripts/multi_node/run_gpt2_124M_fs.sbatch 脚本。
3. 使用 TCP 套接字初始化 NCCL。详情请参阅 ./scripts/multi_node/run_gpt2_124M_tcp.sbatch 脚本。

注意：

• 如果你在 Slurm 环境中运行，而你的 Slurm 不支持 PMIx（考虑到 slurm-wlm 已经放弃了对 PMIx 的支持，这种情况很常见），则必须使用文件系统（2）或 TCP（3）方法。要测试你的 Slurm 是否支持 PMIx，请运行：srun --mpi=list，查看输出中是否包含 pmix。
• 如果没有设置 Slurm，也可以使用 mpirun 来启动多节点运行——即 MPI（1）方法。

这三种方法并无优劣之分，我们只是为你提供多种选择，以便你能够在特定环境中进行训练。

实验 / 参数扫描

以一台拥有 4 个 GPU 的机器为例，对 TinyStories 数据集上的学习率进行扫描。运行一个名为 sweep.sh 的 Shell 脚本（当然，在运行之前需要先执行 chmod u+x sweep.sh）：

#!/bin/bash

learning_rates=(3e-5 1e-4 3e-4 1e-3)

for i in {0..3}; do
    export CUDA_VISIBLE_DEVICES=$i
    screen -dmS "tr$i" bash -c "./train_gpt2cu -i data/TinyStories -v 250 -s 250 -g 144 -l ${learning_rates[$i]} -o stories$i.log"
done

# 可以使用以下命令关闭这些会话：
# screen -ls | grep -E "tr[0-3]" | cut -d. -f1 | xargs -I {} screen -X -S {} quit

此示例会打开 4 个 screen 会话，并分别使用不同的学习率运行命令。日志文件 stories$i.log 中会记录所有损失值，你可以根据需要使用 Python 绘制图表。关于如何解析和绘制这些日志文件的快速示例，请参阅 dev/vislog.ipynb。

仓库

关于我希望这个仓库成为什么样子，再补充几句：

首先，我希望 llm.c 成为一个教育平台。例如，我们的 dev/cuda 文件夹就是一个库，存放着所有手动编写且文档详尽的层级内核，从最简单的内核开始，逐步过渡到更复杂、更高效的内核。如果你有新的内核，并且在不同权衡之间有所取舍，请随时在此贡献。

与此同时，我也希望 llm.c 能够足够高效，甚至在实际应用中可用于训练神经网络。例如，作为起点，我们应该能够复现大型 GPT-2（16 亿参数）的训练过程。这就要求我们整合所有最快的内核，包括使用 cuBLAS、cuBLASLt、CUTLASS、cuDNN 等库。我认为这样做也有助于教育目的，可以建立一个专家级别的上限，作为一种衡量标准——比如，你可以说自己编写的内核达到了 cuBLAS 速度的 80% 等。这样，你可以选择进行超快速的训练，也可以选择“拖放”任意想要使用的手动内核来运行。

然而，出于约束考虑，我希望保持根目录下 llm.c 主线代码的简洁和易读性。如果某个 PR 虽然能将性能提升 2%，但却增加了 500 行复杂的 C 代码，还可能引入一些奇特的第三方依赖，那么我可能会拒绝该 PR，因为其复杂性并不值得。举个具体的例子：在根目录的训练循环中将矩阵乘法的 cuBLAS 实现设为默认，这显然是明智之举——它不仅使主线代码运行得更快，而且只有一行可读的代码，同时也是一个非常常见的依赖项。与此同时，我们可以在 dev/cuda 中保留与 cuBLAS 竞争的手动实现。

最后，我对项目根目录的复杂度会更加敏感，因为那里包含了项目的主文件和默认文件。相比之下，dev/ 文件夹更像是一个试验空间，用于开发内核或类库，并分享有用、相关或具有教育意义的代码，其中一些代码即使局部较为复杂也无妨。

著名的分支

• AMD 支持

  • llm.c 由 @anthonix 开发：支持 AMD 设备，例如 7900 XTX

• C#

  • llm.cs 由 @azret 开发：该项目的 C# 移植版本
  • Llm.cs 由 @nietras 开发：专注于在任何平台上轻松上手的 C# 移植版本。克隆并运行 ✅

• CUDA C++

  • llm.cpp 由 @gevtushenko 开发：使用 CUDA C++ 核心库 的移植版本
    • 该分支曾在 GPU MODE Discord 服务器 的 本次讲座 中被提及。

• C++/CUDA

  • llm.cpp 由 @zhangpiu 开发：使用 Eigen 的移植版本，支持 CPU/CUDA。

• WebGPU C++

  • gpu.cpp 由 @austinvhuang 开发：一个基于原生 WebGPU 的 C++ 可移植 GPU 计算库。旨在成为一个通用库，同时也将 llm.c 内核移植到 WGSL。

• C++

  • llm.cpp 由 @GaoYusong 开发：该项目的 C++ 移植版本，包含一个 C++ 单头文件 tinytorch.hpp 库。

• Go

  • llm.go 由 @joshcarp 开发：该项目的 Go 移植版本。

• Java

  • llm.java 由 @harryjackson 开发：该项目的 Java 移植版本。

• Metal

  • llm.metal 由 @regrettable-username 开发：使用简单的原始 C/Metal 着色语言进行 LLM 训练。

• Mojo

  • llm.🔥 由 @dorjeduck 开发：该项目的 Mojo 移植版本。

• OpenCL

  • llm.c 由 @krrishnarraj 开发：该项目的 OpenCL 移植版本。

• Rust

  • llm.rs 由 @Yijun Yu 开发：以达到相同性能为目标的 Rust 重写版本
  • llm.rs 由 @ToJen 开发：该项目的 Rust 移植版本。

• Swift

  • llm.swift 由 @otabuzzman 开发：该项目的 Swift 移植版本。

• Zig

  • llm.zig 由 @saimirbaci 开发：该项目的 Zig 移植版本。

• Habana Gaudi2

  • llm.tpc 由 @abhilash1910 开发：该项目的 Habana Gaudi2 移植版本。

• Nim

  • llm.nim 由 @Vindaar 开发：该项目的 Nim 移植版本。

讨论区

开发组织方式：

• 如果你在使用仓库时遇到具体问题，请使用 Issues。
• 如果你有代码要贡献，请打开一个 PR。
• 如果你想讨论仓库、提问等，请查看 Discussions。
• 如果需要更快速的交流，我在我的 Zero to Hero Discord 频道 创建了一个新的 #llmc 频道。

许可证

MIT

llm.c 快速上手指南

llm.c 是一个使用纯 C/CUDA 实现的大型语言模型（LLM）训练项目，无需依赖庞大的 PyTorch 或 Python 环境。本项目专注于复现 GPT-2 和 GPT-3 系列模型的预训练过程，代码简洁高效，适合学习 CUDA 编程和理解 LLM 底层原理。

环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu 20.04/22.04) 或 macOS (Apple Silicon 支持 CPU 版本)
• 编译器: GCC 或 Clang (支持 C99 标准)
• GPU 训练: NVIDIA GPU + CUDA Toolkit (建议 12.x 版本)
• 多卡/多机训练: 需安装 OpenMPI 和 NCCL

前置依赖

确保已安装以下基础工具：

# Ubuntu/Debian 示例
sudo apt-get update
sudo apt-get install -y build-essential git wget curl

# 若需 GPU 加速，请安装 CUDA Toolkit
# 若需多卡训练，请安装 MPI
sudo apt-get install -y openmpi-bin libopenmpi-dev

注意：本项目核心逻辑为 C/CUDA，但数据预处理脚本依赖 Python。如需自行处理数据，请安装 Python 及依赖：

pip install torch numpy transformers datasets tiktoken wandb tqdm

安装步骤

1. 克隆仓库

git clone https://github.com/karpathy/llm.c.git
cd llm.c

2. 下载启动包（推荐新手）

项目提供了一键脚本，自动下载预训练权重、分词器和测试数据集（TinyShakespeare）：

chmod u+x ./dev/download_starter_pack.sh
./dev/download_starter_pack.sh

该脚本会生成 .bin 格式的二进制文件，包含 GPT-2 (124M) 权重、调试状态及 Tokenized 数据。

3. 编译项目

根据硬件环境选择编译目标：

• 单卡 GPU 训练 (FP32 精度，易读性高):

  make train_gpt2fp32cu
  

• 单卡 GPU 训练 (混合精度，性能更强，需 cuDNN):

  make train_gpt2cu USE_CUDNN=1
  

• 纯 CPU 训练 (仅用于演示或无 GPU 环境):

  make train_gpt2
  

调试提示: 若需在 IDE (如 VSCode) 中打断点调试，请将 make 命令中的优化标志 -O3 替换为 -g。

基本使用

场景一：单卡 GPU 快速训练 (FP32)

适合初学者学习 CUDA 内核实现。运行编译好的二进制文件即可开始训练：

./train_gpt2fp32cu

程序将加载下载的 GPT-2 权重，在 TinyShakespeare 数据集上进行微调，并输出训练损失和生成的文本样本。

场景二：纯 CPU 运行演示

适用于没有 NVIDIA GPU 的用户（如 MacBook M 系列芯片）。由于速度限制，仅建议运行少量步数作为参考：

# 设置线程数 (根据 CPU 核心数调整，例如 8)
OMP_NUM_THREADS=8 ./train_gpt2

预期输出示例:

[GPT-2]
max_seq_len: 1024
vocab_size: 50257
...
step 0: train loss 5.356189 (took 1452.121000 ms)
step 1: train loss 4.301069 (took 1288.673000 ms)
...
generating:
---
Come Running Away,
Greater conquer With the Imperial blood...
---

场景三：验证代码正确性 (单元测试)

编译并运行测试程序，确保 C/CUDA 实现与 PyTorch 参考实现的计算结果一致：

# CPU 测试
make test_gpt2
./test_gpt2

# GPU 测试 (混合精度)
make test_gpt2cu USE_CUDNN=1 && ./test_gpt2cu

若输出 overall okay: 1，则表示测试通过。

进阶：自定义数据集

若不直接使用启动包，可手动运行 Python 脚本处理数据：

python dev/data/tinyshakespeare.py

这将生成 tiny_shakespeare_train.bin 和 tiny_shakespeare_val.bin 文件，供 C 程序读取。