Mini-GPT (Shakespeare)

Project Background / 项目背景

Mini-GPT is the bridge between reading transformer theory and actually owning the mechanics of autoregressive language modeling. Instead of treating GPT as a black box API, this project makes you build the moving parts yourself and see how modern LLM behavior emerges from simple components.
Mini-GPT 是连接“读懂 transformer 理论”和“真正掌握自回归语言模型机制”的桥梁。它不是把 GPT 当成黑盒 API 来用，而是让你亲手搭出核心部件，看到现代 LLM 的行为是如何从一组并不神秘的模块里涌现出来的。

Problem it solves / 它要解决什么问题

The real problem is not “generate Shakespeare text.” The real problem is understanding how a model turns discrete tokens into contextual representations, prevents future leakage, and learns next-token prediction stably enough to produce coherent samples. This page turns that abstract systems question into something you can inspect line by line.
这个项目真正要解决的并不是“生成莎士比亚文本”，而是理解模型如何把离散 token 变成上下文化表示，如何阻止未来信息泄漏，以及如何稳定地学会 next-token prediction，最终生成连贯文本。它把一个抽象的系统问题，变成你可以逐行检查的实现。

What you learn / 你会学到什么

• ▸ How token embeddings and positional embeddings work together
  ▸ token embedding 和 positional embedding 如何配合
• ▸ How causal masking prevents information leakage from future tokens
  ▸ causal masking 如何阻止未来信息泄漏
• ▸ How transformer blocks stack attention and feed-forward computation
  ▸ transformer block 如何堆叠 attention 与前馈计算
• ▸ How sampling strategy changes the quality and diversity of generated text
  ▸ 采样策略如何改变文本质量与多样性
• ▸ How to reason about context length, perplexity, and training stability
  ▸ 如何理解 context length、perplexity 和训练稳定性

Code walkthrough / 代码要点解释

pip install torch

python mini_gpt_train.py

mini-gpt/
├── input.txt
├── mini_gpt_train.py
└── outputs/
    └── sample.txt

import math
import torch
import torch.nn as nn
import torch.nn.functional as F

text = open("input.txt", "r", encoding="utf-8").read()
chars = sorted(list(set(text)))
stoi = {ch: i for i, ch in enumerate(chars)}
itos = {i: ch for ch, i in stoi.items()}
encode = lambda s: [stoi[c] for c in s]
decode = lambda xs: ''.join(itos[i] for i in xs)

device = 'cuda' if torch.cuda.is_available() else 'cpu'
block_size = 128
batch_size = 32
n_embd = 192
n_head = 6
n_layer = 6
dropout = 0.1
max_iters = 2000
eval_interval = 200
lr = 3e-4

ids = torch.tensor(encode(text), dtype=torch.long)
split = int(0.9 * len(ids))
train_ids, val_ids = ids[:split], ids[split:]


def get_batch(split_name: str):
    data = train_ids if split_name == 'train' else val_ids
    ix = torch.randint(len(data) - block_size - 1, (batch_size,))
    x = torch.stack([data[i:i+block_size] for i in ix])
    y = torch.stack([data[i+1:i+block_size+1] for i in ix])
    return x.to(device), y.to(device)


class Head(nn.Module):
    def __init__(self, head_size: int):
        super().__init__()
        self.key = nn.Linear(n_embd, head_size, bias=False)
        self.query = nn.Linear(n_embd, head_size, bias=False)
        self.value = nn.Linear(n_embd, head_size, bias=False)
        self.register_buffer('tril', torch.tril(torch.ones(block_size, block_size)))
        self.dropout = nn.Dropout(dropout)

    def forward(self, x):
        B, T, C = x.shape
        k = self.key(x)
        q = self.query(x)
        wei = q @ k.transpose(-2, -1) * (k.size(-1) ** -0.5)
        wei = wei.masked_fill(self.tril[:T, :T] == 0, float('-inf'))
        wei = self.dropout(F.softmax(wei, dim=-1))
        v = self.value(x)
        return wei @ v


class MultiHeadAttention(nn.Module):
    def __init__(self, num_heads: int, head_size: int):
        super().__init__()
        self.heads = nn.ModuleList([Head(head_size) for _ in range(num_heads)])
        self.proj = nn.Linear(num_heads * head_size, n_embd)
        self.dropout = nn.Dropout(dropout)

    def forward(self, x):
        return self.dropout(self.proj(torch.cat([h(x) for h in self.heads], dim=-1)))


class FeedForward(nn.Module):
    def __init__(self):
        super().__init__()
        self.net = nn.Sequential(
            nn.Linear(n_embd, 4 * n_embd),
            nn.ReLU(),
            nn.Linear(4 * n_embd, n_embd),
            nn.Dropout(dropout),
        )

    def forward(self, x):
        return self.net(x)


class Block(nn.Module):
    def __init__(self):
        super().__init__()
        head_size = n_embd // n_head
        self.sa = MultiHeadAttention(n_head, head_size)
        self.ffwd = FeedForward()
        self.ln1 = nn.LayerNorm(n_embd)
        self.ln2 = nn.LayerNorm(n_embd)

    def forward(self, x):
        x = x + self.sa(self.ln1(x))
        x = x + self.ffwd(self.ln2(x))
        return x


class MiniGPT(nn.Module):
    def __init__(self):
        super().__init__()
        vocab_size = len(chars)
        self.token_embedding_table = nn.Embedding(vocab_size, n_embd)
        self.position_embedding_table = nn.Embedding(block_size, n_embd)
        self.blocks = nn.Sequential(*[Block() for _ in range(n_layer)])
        self.ln_f = nn.LayerNorm(n_embd)
        self.lm_head = nn.Linear(n_embd, vocab_size)

    def forward(self, idx, targets=None):
        B, T = idx.shape
        tok_emb = self.token_embedding_table(idx)
        pos_emb = self.position_embedding_table(torch.arange(T, device=idx.device))
        x = tok_emb + pos_emb
        x = self.blocks(x)
        x = self.ln_f(x)
        logits = self.lm_head(x)
        loss = None
        if targets is not None:
            B, T, C = logits.shape
            loss = F.cross_entropy(logits.view(B * T, C), targets.view(B * T))
        return logits, loss

    @torch.no_grad()
    def generate(self, idx, max_new_tokens: int):
        for _ in range(max_new_tokens):
            idx_cond = idx[:, -block_size:]
            logits, _ = self(idx_cond)
            probs = F.softmax(logits[:, -1, :], dim=-1)
            idx_next = torch.multinomial(probs, num_samples=1)
            idx = torch.cat((idx, idx_next), dim=1)
        return idx


model = MiniGPT().to(device)
optimizer = torch.optim.AdamW(model.parameters(), lr=lr)

for step in range(max_iters):
    xb, yb = get_batch('train')
    _, loss = model(xb, yb)
    optimizer.zero_grad(set_to_none=True)
    loss.backward()
    torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0)
    optimizer.step()

    if step % eval_interval == 0:
        model.eval()
        vx, vy = get_batch('val')
        _, vloss = model(vx, vy)
        print(f"step={step} train_loss={loss.item():.4f} val_loss={vloss.item():.4f}")
        model.train()

context = torch.zeros((1, 1), dtype=torch.long, device=device)
print(decode(model.generate(context, 300)[0].tolist()))

Grading Rubric / 完成标准

• ✅ Model trains without mask bugs or divergence / 模型训练无 mask bug、无明显发散
• ✅ Generation quality improves across checkpoints / 生成质量会随着 checkpoint 提升
• ✅ Sampling script supports temperature and top-k / 采样脚本支持 temperature 和 top-k
• ✅ You can explain why each architecture piece exists / 你能解释每个架构部件存在的原因