Karpathy Python GPT 實作指南

研究日期

2026-02-13

簡介

Andrej Karpathy 的 Python GPT 實作（nanoGPT 和 minGPT）是學習 Transformer 架構和大型語言模型（LLM）的理想起點。這些專案專為教育目的設計，以簡潔的程式碼展示 GPT 模型的核心概念，同時保持足夠的實用性以支持實際研究和原型開發。nanoGPT 強調模組化和效率，適合快速實驗；minGPT 則以極簡的約 300 行程式碼呈現 Transformer 核心機制，適合初學者理解架構。

主要特性

nanoGPT

模組化設計：易於修改 Transformer 架構、訓練流程和超參數
從零訓練或微調：支持自訂數據集訓練，或基於預訓練模型微調
高效實現：使用 PyTorch，適合消費級硬體
清晰的代碼結構：包含 model.py、train.py、generate.py 等核心腳本
完整的配置系統：通過 Python 配置文件管理超參數

minGPT

超精簡代碼：約 300 行，專注於 Transformer 解碼器核心
教育導向：清楚展示 GPT 的運作機制
支援訓練和推理：包含完整的訓練循環和文本生成
易於擴展：模組化設計方便添加新功能

工作原理

核心架構

兩個實作都採用標準的 Transformer 解碼器架構：

多頭自注意力機制（Multi-Head Self-Attention）：捕獲序列中的長距離依賴
前饋網絡層（Feed-Forward Layers）：處理特徵轉換
位置編碼（Positional Encoding）：提供序列位置資訊
殘差連接（Residual Connections）：改善梯度流動
層正規化（Layer Normalization）：穩定訓練過程

訓練流程

數據準備：收集並格式化文本數據集
Tokenization：使用 GPT-2 BPE（通過 tiktoken）將文本轉換為 token ID
批次處理：將數據分成批次（batches）和序列塊（blocks）
前向傳播：通過 Transformer 計算預測機率
損失計算：計算交叉熵損失
反向傳播：更新模型權重
驗證與生成：定期評估並生成樣本

主要使用案例

1. 教育與學習

理解 Transformer 機制：閱讀簡潔的代碼，掌握注意力機制、位置編碼等核心概念
實驗不同配置：修改模型大小、注意力頭數等參數，觀察影響

2. 快速原型開發

小規模型訓練：在特定數據集上快速訓練自訂模型
架構實驗：測試不同的變體，如改變注意力機制或層數

3. 研究與實驗

消融研究：測試特定組件對模型性能的影響
訓練動態分析：監控損失曲線，優化超參數

安裝與設定

前置需求

Python 3.8+
PyTorch（推薦 1.10+）
CUDA（如需 GPU 加速）
pip（Python 包管理器）

nanoGPT 安裝步驟

1. 克隆倉庫

1
2


git clone https://github.com/karpathy/nanoGPT
cd nanoGPT

2. 創建虛擬環境（推薦）

1
2
3
4
5
6
7
8
9


# 使用 venv
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 使用 conda
conda create -n nanogpt python=3.10
conda activate nanogpt

3. 安裝依賴

1

pip install -e .

或手動安裝核心依賴：

1

pip install torch numpy tiktoken datasets tqdm wandb

4. 驗證安裝

1

python -c "import torch; import tiktoken; print('✅ Installation successful')"

minGPT 安裝步驟

1. 克隆倉庫

1
2


git clone https://github.com/karpathy/minGPT
cd minGPT

2. 創建虛擬環境

1
2


python -m venv venv
source venv/bin/activate

3. 安裝依賴

1

pip install -e .

核心依賴：

1

pip install torch numpy torchvision

配置範例

nanoGPT 配置文件（`config/train_shakespeare_char.py`）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 模型配置
n_layer = 6          # Transformer 層數
n_head = 6          # 注意力頭數
n_embd = 384        # 嵌入維度
block_size = 256    # 序列長度
dropout = 0.2       # Dropout 比例

# 訓練配置
batch_size = 64     # 批次大小
learning_rate = 3e-4  # 學習率
max_iters = 5000    # 最大迭代次數
eval_interval = 500  # 評估間隔
eval_iters = 200    # 每次評估的迭代數
device = 'cuda'     # 設備（'cuda' 或 'cpu'）

minGPT 配置（命令行參數）

1
2
3
4
5
6
7
8
9


python train.py \
    --device='cuda' \
    --batch_size=64 \
    --block_size=128 \
    --n_layer=4 \
    --n_head=4 \
    --n_embd=128 \
    --learning_rate=3e-4 \
    --max_iters=5000

實際代碼示例

nanoGPT 使用範例

1. 準備數據

1
2
3
4
5


# 使用預置的莎士比亞數據集
python data/shakespeare_char/prepare.py

# 或使用自訂數據集
python data/custom/prepare.py --input_path your_text.txt

2. 訓練模型

1
2
3
4
5


# 使用配置文件訓練
python train.py config/train_shakespeare_char.py

# 從檢查點恢復訓練
python train.py config/train_shakespeare_char.py --resume

3. 生成文本

1
2
3
4
5
6
7


# 使用訓練好的模型生成文本
python sample.py \
    --out_dir=out-shakespeare-char \
    --device='cuda' \
    --prompt="The meaning of life is" \
    --num_samples=10 \
    --max_new_tokens=100

4. Python API 使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


import torch
from model import GPT

# 加載配置
import config.train_shakespeare_char as config

# 初始化模型
model = GPT(config)

# 加載訓練好的權重
checkpoint = torch.load('out-shakespeare-char/ckpt.pt')
model.load_state_dict(checkpoint['model'])
model.eval()

# 生成文本
prompt = "Once upon a time"
x = torch.tensor([char2idx[c] for c in prompt], dtype=torch.long).unsqueeze(0)

with torch.no_grad():
    y = model.generate(x, max_new_tokens=100)
    generated = ''.join([idx2char[i] for i in y[0].tolist()])
    print(generated)

minGPT 使用範例

1. 訓練模型

1
2
3
4
5
6
7
8
9


python train.py \
    --device='cuda' \
    --batch_size=64 \
    --block_size=128 \
    --n_layer=4 \
    --n_head=4 \
    --n_embd=128 \
    --learning_rate=3e-4 \
    --max_iters=5000

2. 生成文本

1
2
3
4
5
6


python generate.py \
    --device='cuda' \
    --model_path='path_to_trained_model.pt' \
    --prompt='Hello, world!' \
    --num_samples=5 \
    --max_new_tokens=100

3. Python API 使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


from mingpt.model import GPT
from mingpt.trainer import Trainer

# 定義模型配置
model_config = GPT.get_default_config()
model_config.model_type = 'gpt-mini'
model_config.vocab_size = 50257
model_config.block_size = 128
model_config.n_layer = 4
model_config.n_head = 4
model_config.n_embd = 128

# 初始化模型
model = GPT(model_config)

# 定義訓練配置
train_config = Trainer.get_default_config()
train_config.learning_rate = 3e-4
train_config.max_iters = 5000
train_config.batch_size = 64

# 創建訓練器
trainer = Trainer(train_config, model)

# 訓練模型
trainer.run()

# 生成文本
prompt = "The future of AI is"
x = tokenizer(prompt)['input_ids']
with torch.no_grad():
    y = model.generate(torch.tensor([x]), max_new_tokens=50)
    generated = tokenizer.decode(y[0].tolist())
    print(generated)

常見坑點與除錯技巧

1. 數據準備問題

問題：Tokenization 錯誤

1
2
3


# 錯誤：未正確處理特殊字符
text = open('data.txt').read()
tokens = tiktoken.get_encoding("gpt2").encode(text)

解決方案：

1
2
3
4
5
6
7
8


# 正確：預處理文本
import tiktoken

text = open('data.txt', encoding='utf-8').read()
# 移除或替換特殊字符
text = text.replace('\x00', '').replace('\ufffd', '')
enc = tiktoken.get_encoding("gpt2")
tokens = enc.encode(text, allowed_special={'<|endoftext|>'})

2. 記憶體不足（OOM）

問題：CUDA out of memory

解決方案：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# 1. 減少批次大小
--batch_size=32  # 從 64 降到 32

# 2. 減少序列長度
--block_size=128  # 從 256 降到 128

# 3. 使用梯度累積
# 在 train.py 中修改
accumulation_steps = 4
if (step + 1) % accumulation_steps == 0:
    optimizer.step()
    optimizer.zero_grad()

# 4. 使用混合精度訓練
scaler = torch.cuda.amp.GradScaler()
with torch.cuda.amp.autocast():
    logits = model(xb, yb)
    loss = F.cross_entropy(logits, targets)
scaler.scale(loss).backward()
scaler.step(optimizer)
scaler.update()

3. 訓練不收斂

問題：損失不下降或震盪嚴重

解決方案：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 1. 檢查學習率
learning_rate = 1e-4  # 試試更小的學習率

# 2. 使用學習率調度器
from torch.optim.lr_scheduler import CosineAnnealingLR
scheduler = CosineAnnealingLR(optimizer, T_max=max_iters)

# 3. 檢查數據質量
print(f"Vocab size: {len(vocab)}")
print(f"Data length: {len(text)}")
print(f"Sample tokens: {tokens[:20]}")

# 4. 添加梯度裁剪
torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)

4. 生成結果不佳

問題：生成的文本重複或無意義

解決方案：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 1. 調整溫度參數
# 溫度越高，生成越隨機；溫度越低，生成越確定性
temperature = 0.8  # 嘗試 0.5 到 1.0 之間

# 2. 使用 top-k 或 top-p 采樣
top_k = 50
top_p = 0.9

# 3. 增加訓練迭代次數
max_iters = 10000  # 增加訓練時間

5. 配置文件問題

問題：配置參數未生效

解決方案：

1
2
3
4
5
6
7
8
9


# 確保配置文件正確導入
import config.train_shakespeare_char as config

# 檢查配置參數
print(f"n_layer: {config.n_layer}")
print(f"batch_size: {config.batch_size}")

# 命令行參數優先
python train.py config/train_shakespeare_char.py --batch_size=128

最佳實踐

1. 數據準備

使用高質量數據：清理數據，移除重複和無效內容
足夠的數據量：小模型建議至少 10MB-100MB 的文本
正確的 Tokenization：使用 GPT-2 BPE 保持與預訓練模型一致
保留特殊字符：適當處換行符、特殊符號等

2. 訓練策略

從小模型開始：先試 124M 參數的模型（n_layer=12, n_embd=768）
監控驗證損失：定期評估，避免過擬合
定期保存檢查點：每 1000-2000 次迭代保存一次
使用 Weights & Biases：記錄訓練曲線，方便分析和調整

1
2


wandb login
python train.py config/train_shakespeare_char.py --wandb_log=True

3. 超參數調整

學習率：從 3e-4 開始，根據損失曲線調整
批次大小：根據 GPU 記憶體調整（32, 64, 128）
序列長度：通常 256-512（nanoGPT）或 128-256（minGPT）
Dropout：0.1-0.3 之間，防止過擬合

4. 效能優化

使用 GPU 加速：確保 device='cuda' 或 device='mps'（Apple Silicon）
混合精度訓練：使用 torch.cuda.amp 加速 1.5-2 倍
數據預加載：使用 DataLoader 的 num_workers 參數

1
2
3


train_loader = torch.utils.data.DataLoader(
    dataset, batch_size=batch_size, shuffle=True, num_workers=4
)

梯度檢查點：對大型模型使用 torch.utils.checkpoint 減少記憶體使用

5. 除錯技巧

打印梯度：檢查梯度是否消失或爆炸

1
2
3


for name, param in model.named_parameters():
    if param.grad is not None:
        print(f"{name}: grad mean={param.grad.mean():.6f}, std={param.grad.std():.6f}")

可視化注意力圖：理解模型注意力模式
生成日誌：記錄每一步的損失和生成樣本
使用單元測試：驗證關鍵組件的正確性

進階功能

1. 微調預訓練模型

1
2
3
4
5


# 下載 GPT-2 權重
python download_model.py 124M

# 微調
python train.py --init_from=gpt2_124M --dataset=your_data

2. 多 GPU 訓練

1
2
3


import torch.distributed as dist
torch.distributed.init_process_group(backend='nccl')
model = torch.nn.parallel.DistributedDataParallel(model)

3. 自訂數據集

1
2
3
4
5


# 在 data/custom/prepare.py 中定義
def prepare_custom_dataset(input_path):
    # 讀取和處理數據
    # 保存為 .bin 或 .pt 文件
    pass

4. 自訂注意力機制

1
2
3
4


# 在 model.py 中修改
class CausalSelfAttention(nn.Module):
    # 添加稀疏注意力、線性注意力等變體
    pass

常見問題解答

Q: nanoGPT 和 minGPT 哪個適合我？

A: 如果你想學習 GPT 核心概念，從 minGPT 開始；如果你想實際訓練模型或進行實驗，選 nanoGPT。

Q: 需要多大的 GPU？

A: 訓練 124M 參數的模型，至少需要 8GB VRAM。小模型可在 4GB GPU 上運行。

Q: 可以在 CPU 上訓練嗎？

A: 可以，但速度很慢。建議使用雲端 GPU（Colab、RunPod 等）或本地 GPU。

Q: 如何評估模型質量？

A: 觀察驗證損失曲線，檢查生成文本的連貫性，計算困惑度（Perplexity）。

Q: 可以用於中文嗎？

A: 可以，但需要確保 tokenizer 支持中文，或使用中文特定的 tokenizer。

Q: 訓練需要多長時間？

A: 取決於數據集大小和模型大小。小模型（124M 參數）在單個 GPU 上可能需要數小時到數天。

參考資料

官方資源

nanoGPT GitHub - 完整的 nanoGPT 實作
minGPT GitHub - 極簡的 minGPT 實作
Let’s build GPT: from scratch, in code, spelled out - Karpathy 的完整教學影片

教學文章

Let’s Build the GPT Tokenizer - fast.ai 的 tokenizer 指南
Exploring NanoGPT - 深入探索 nanoGPT
Train your own language model with nanoGPT - 實戰教學

技術深度

mingpt/model.py - minGPT 模型原始碼
State of GPT 2023 - Karpathy 的 GPT 狀態演講

社群資源

minGPT Discussion - fast.ai 論壇討論
NanoGPT Reddit - 相關討論串

總結

Karpathy 的 Python GPT 實作是學習和實驗 Transformer 模型的絕佳資源。nanoGPT 提供完整的訓練流程和靈活的配置系統，適合實際應用；minGPT 以極簡代碼展示核心機制，適合教育目的。通過遵循本指南的安裝步驟、配置範例和最佳實踐，你可以快速上手並開始訓練自己的 GPT 模型。記住從小模型開始，監控訓練進度，並不斷調整和優化以獲得最佳結果。

研究來源註記：本筆記主要基於 Exa Deep Researcher 的全面研究報告。Codex Subagent 原本負責補充實作細節，但執行進展緩慢，因此改為綜合官方文檔和社群資料來完善實作導向內容。

Karpathy Python GPT 實作指南

研究日期

簡介

主要特性

nanoGPT

minGPT

工作原理

核心架構

訓練流程

主要使用案例

1. 教育與學習

2. 快速原型開發

3. 研究與實驗

安裝與設定

前置需求

nanoGPT 安裝步驟

1. 克隆倉庫

2. 創建虛擬環境（推薦）

3. 安裝依賴

4. 驗證安裝

minGPT 安裝步驟

1. 克隆倉庫

2. 創建虛擬環境

3. 安裝依賴

配置範例

nanoGPT 配置文件（config/train_shakespeare_char.py）

minGPT 配置（命令行參數）

實際代碼示例

nanoGPT 使用範例

1. 準備數據

2. 訓練模型

3. 生成文本

4. Python API 使用

minGPT 使用範例

1. 訓練模型

2. 生成文本

3. Python API 使用

常見坑點與除錯技巧

1. 數據準備問題

2. 記憶體不足（OOM）

3. 訓練不收斂

4. 生成結果不佳

5. 配置文件問題

最佳實踐

1. 數據準備

2. 訓練策略

3. 超參數調整

4. 效能優化

5. 除錯技巧

進階功能

1. 微調預訓練模型

2. 多 GPU 訓練

3. 自訂數據集

4. 自訂注意力機制

常見問題解答

Q: nanoGPT 和 minGPT 哪個適合我？

Q: 需要多大的 GPU？

Q: 可以在 CPU 上訓練嗎？

Q: 如何評估模型質量？

Q: 可以用於中文嗎？

Q: 訓練需要多長時間？

參考資料

官方資源

教學文章

技術深度

社群資源

總結

nanoGPT 配置文件（`config/train_shakespeare_char.py`）