how-to-train-your-gpt：用 860 行核心程式碼把 LLaMA 3 風格架構拆到骨頭

它解決的是「看得懂論文但寫不出來」這個斷層

市面上的 LLM 教材大致落在兩個極端。一端是呼叫 API 的教學，你寫下 model = GPT().fit(data) 就結束了，對內部一無所知。另一端是 40 頁的論文，符號密度高，預設讀者有 ML 博士背景，卻沒有任何可執行的範例。這個專案想填的是中間那段：README 直接寫明目標讀者是「對 ChatGPT 實際怎麼運作感到好奇的 Python 開發者」，前置需求只有 Python 基礎（變數、函式、類別、pip install），不需要微積分、線性代數，也不需要 PyTorch 經驗。作者自己在 README 開頭承認動機是為了搞懂 attention，並且大量借助 AI 來理解與驗證概念。這個自述很重要，它暗示了內容的定位是學習筆記的整理，而不是權威規格書。讀者要判斷的重點因此不是「這是不是最正確的實作」，而是「它的解釋路徑是否比論文更容易走通」。

架構選型：為什麼是 LLaMA 3 那一套，而不是 GPT-2

README 的架構表列出一組明確的技術組合：RoPE 來自 LLaMA、Mistral、Qwen；RMSNorm 來自 LLaMA、Mistral、Gemma；SwiGLU 來自 PaLM、LLaMA、Gemini；Pre-Norm 來自 GPT-3 與後續所有現代模型；再加上 AdamW、BPE、weight tying 與 mixed precision。作者對這個選擇給了理由：GPT-4 與 Claude 的架構未公開，所以教材選擇「公開可確認的最佳架構」，也就是 LLaMA 3、Mistral、Qwen 2.5 使用的那一套。這是一個務實的決定，但同時也是這份教材最大的取捨。它教你的是 2023 年之後的 decoder-only Transformer 標準配置，代價是你會跳過一些歷史脈絡，例如原始 Transformer 的 post-norm 與 learned positional embedding 為什麼後來被換掉。README 只在 Chapter 6 用一句 pre-norm vs post-norm 帶過，對想理解演化過程的讀者略嫌不足。反過來說，如果你的目標是讀懂現在開源模型 weights 裡的結構，這組選型是對的起點。

資料流：從一個句子到一次預測，中間經過哪些檔案

README 把整個系統拆成八個元件並標了行數：BPE Tokenizer 約 60 行、Embeddings 約 30 行、RoPE 約 70 行、Multi-Head Attention 約 120 行、Transformer Block 約 50 行、完整 GPT 模型約 200 行、訓練管線約 250 行、推論引擎約 80 行。核心模型程式碼合計約 860 行，說明與圖解約 2,600 行。這個比例本身就是一種設計主張：每一行可執行程式碼背後平均有三行解釋。資料流依照章節順序推進，Chapter 2 把文字切成 token，Chapter 3 把 token 映射到 768 維向量，Chapter 4 用旋轉而非加法注入位置資訊，Chapter 5 完成 Q、K、V 與 causal mask 的計算，Chapter 6 加上 RMSNorm、SwiGLU 與殘差連接，Chapter 7 組出 151M 參數的完整模型並解釋 weight tying 與 logits，Chapter 8 接上 cross-entropy 與反向傳播，Chapter 9 用 KV cache 加速生成。README 另外提到有兩份敘事式 walkthrough，會把單一句子逐步走過整個模型，這對照著程式碼讀比單看章節更有效。

怎麼跑起來：從 Colab 到本機的實際路徑

最短路徑是 README 頂部的 Colab 徽章，指向 notebooks/colab_train.ipynb，點開即可在瀏覽器內執行，不需要本機 GPU。要走本機路線，README 給的起手式是 git clone https://github.com/raiyanyahya/how-to-train-your-gpt.git，然後 cd 進目錄。Chapter 1 涵蓋環境設定、GPU 與 CPU 的差異、venv 建立與 PyTorch 基礎。Chapter 10 提供一份可執行的 main.py，把前面所有元件整合在單一檔案裡，README 稱之為 runnable main.py。訓練相關的具體機制在 Chapter 8 展開，包括 AdamW 優化器、cosine warmup 學習率排程、mixed precision 與 gradient accumulation。推論端的控制項在 Chapter 9，包含 KV cache、temperature、top-k、top-p、beam search 與 repetition penalty。這裡要提醒一點：README 被截斷在 Quick Start 的 cd how-to-tra 處，完整的後續步驟我無法從現有材料確認，請直接以 repository 內的 Chapter 1 與 Chapter 10 為準。

教材的邊界：它是學習專案，不是訓練框架

README 的徽章裡有一條寫得很直白：purpose 是 learning only。這不是客套話，而是使用上的硬邊界。整個專案是 Jupyter Notebook 為主，沒有提供預訓練 checkpoint，沒有分散式訓練支援，沒有模型版本管理，也沒有推論伺服器或量化部署路徑。Chapter 7 的模型規模是 151M 參數，這個量級可以在單張消費級 GPU 上跑通流程，但距離實用模型還很遠。另一個更根本的限制是資料。教材教你如何實作 BPE 分詞器與訓練迴圈，但沒有描述如何取得、清洗、去重與授權一份足以訓練出可用模型的語料。這意味著你完成教材後得到的是「能訓練」的能力，而不是「已訓練好」的模型。如果你需要的是拿現成模型做微調，這份教材會讓你在資料管線那一段卡住，因為它根本不處理那個問題。

和 Hugging Face transformers 的路線差異在哪

拿 Hugging Face transformers 對照最清楚。transformers 提供的是經過封裝的模型類別、AutoTokenizer、Trainer API 與 hub 上的預訓練權重，你幾行程式就能載入一個 LLaMA 並開始微調，內部實作被抽象掉了。這個專案走的是完全相反的路：它不給你任何封裝，要求你自己寫出 tokenizer、attention、訓練迴圈與推論引擎，換來的是每一行都看得見。差異不只在抽象層次，也在維護模式。transformers 有團隊維護、版本迭代與向後相容承諾；這份教材是單一作者的教學專案，最後推送時間為 2026 年 8 月 30 日，沒有對應的 release 記錄，API 變動不會有遷移指南。選擇哪一條，取決於你要的是「用模型」還是「懂模型」。兩者不衝突，但同時進行的話，教材的價值會被 API 的便利性抵銷掉。

授權、維護成本與升級時要檢查什麼

授權是 MIT，這表示你可以自由使用、修改、再散布這些程式碼，包含商業用途，條件是保留著作權聲明與授權條款。這裡不構成法律建議，實際使用前請自行確認 repository 內的 LICENSE 檔案內容。維護成本方面，材料只顯示這是一個持續推送的個人教學專案，沒有 release、沒有版本標籤，也沒有說明支援的 PyTorch 版本範圍。這對學習用途影響不大，但如果你打算把 Chapter 10 的 main.py 當成專案起點，就要預期自己承擔後續的相容性維護。升級時最該檢查的是 Chapter 8 的 mixed precision 路徑與 Chapter 9 的 KV cache 實作，這兩處最依賴 PyTorch 的底層 API，在不同版本之間行為差異也最大。另外，README 提到 Chapter 11 有一份架構溯源表與參數拆解，那份表在你比對自己的實作與 LLaMA 3 官方配置時會比章節正文更實用。

編輯結論

如果你已經會寫 Python 函式與類別，卻始終沒搞懂 attention 的 Q、K、V 到底在做什麼，這份教材值得從 Chapter 0 依序讀到 Chapter 10，並且把 notebooks/colab_train.ipynb 開起來對照。如果你要的是能直接微調、部署的生產級框架，這裡沒有 checkpoint 管理、分散式訓練或推論伺服器，請轉向 Hugging Face transformers 或 torchtitan。動手前先確認三件事：你的 PyTorch 版本能否跑 Chapter 8 的 mixed precision 路徑、你的硬體是否撐得住 Chapter 7 那個 151M 參數模型、以及 Chapter 10 的 main.py 是否與前面章節的介面完全一致。

官方來源

1. Issues
2. License: MIT
3. raiyanyahya/how-to-train-your-gpt on GitHub
4. README