how-to-train-your-gpt：コメント付きコードでTransformerを書き直す教材

「APIを呼べるが中身を知らない」層に向けた教材

多くのLLM入門は二つの極に寄る。model = GPT().fit(data)のようにライブラリ呼び出しだけを教えるか、40ページの論文と密な数式を前提にするかである。READMEはこの二つを明示的に対比し、本リポジトリをその中間に置いている。対象読者はPythonの基本（変数、関数、クラス、pip install）だけを持つ開発者で、微積分や線形代数、PyTorchの経験は不要とされている。読者は約3,500行のコメント付きコードを読み切る意欲を求められる。ゴールはattentionが「動く」と知ることではなく、スケーリングに1/√d_kが入る分散の議論、RoPEが回転で相対位置を表す仕組み、pre-normがpost-normより深いネットワークで優る理由、逆伝播で勾配がどこを流れるかを説明できる状態だとREADMEは書いている。

12章の積み上げと28本の解説ファイル

構成はChapter 0の概観から始まり、1 Setup、2 Tokenization、3 Embeddings、4 Positional Encoding、5 Attention、6 Transformer Block、7 Complete GPT Model、8 Training Pipeline、9 Inference、10 Full Script、11 Glossaryと続く。READMEはChapter 0から順に読むことを指示しており、各章が前の章を前提にする。本編とは別に、RoPE、attention、RMSNorm、SwiGLU、KV cache、AdamW、mixed precisionといった個別技術を掘り下げる28本のstandalone explainerが置かれ、1文がモデル全体を通過する様子を追う2本のnarrative walkthroughも用意されている。Chapter 5はREADME内でTHE COREと位置づけられ、Q、K、V、スケーリング、causal maskを8ステップで追う構成になっている。

LLaMA 3系の構成を採用する理由と、採用しない部分

実装するのはdecoder-only Transformerで、READMEはGPT-4やClaudeのアーキテクチャは非公開であると明記したうえで、公開情報で確認できる最新構成としてLLaMA 3、Mistral、Qwen 2.5が使う要素を採用すると述べている。具体的には、学習パラメータを持たない相対位置表現としてのRoPE、LayerNormより15%高速で同等とされるRMSNorm、情報の通過と遮断を学習するSwiGLU、100層超でも安定するとされるpre-norm、vanilla Adamより汎化が良いとするAdamW、未知語やemojiも扱えるBPE、パラメータを30%削減しつつ学習信号を改善するとされるweight tying、速度2倍・メモリ半減・品質同等とされるmixed precisionである。これらはREADMEの主張であり、本記事で検証はしていない。Chapter 7ではSwiGLU込みで151Mパラメータのモデルを組む。

何がどれだけの行数で書かれるか

READMEの内訳では、BPEトークナイザが約60行、Embeddingsが約30行、RoPEが約70行、Multi-Head Attentionが約120行、Transformer Blockが約50行、Full GPT Modelが約200行、Training Pipelineが約250行、Inference Engineが約80行。合計で約860行がコア実装、約2,600行が説明と図にあたる。Attentionの120行にはcausal maskの適用とスケーリングが含まれ、Inference Engineの80行にはKV cache、temperature、top-k/p、beam search、repetition penaltyが含まれるとREADMEは説明する。モデル本体が200行程度に収まる点は、読者が全体を一度に把握するうえで現実的な規模である。一方、Training Pipelineの250行はデータローダ、勾配累積、学習率スケジューラを含むため、章の中では最も密度が高くなる。

動かすまでの手順とColab前提

READMEのQuick Startはgit clone https://github.com/raiyanyahya/how-to-train-your-gpt.gitで取得し、cdでリポジトリに入るところまでを示している（取得部分はREADMEの抜粋が途中で切れている）。バッジにはOpen In Colabが用意され、notebooks/colab_train.ipynbをColab上で開く導線がある。環境構築はChapter 1のchapters/01_setup.mdが担当し、GPUとCPUの違い、venv、PyTorchの基本を扱う。第10章のchapters/10_full_script.mdには、全構成要素を1ファイルにまとめた実行可能なmain.pyが示される。つまり読むだけの章と、手元で走らせる章が分かれている。READMEには依存パッケージのバージョン固定やrequirements.txtの記載が見当たらないため、実際に動かす際はChapter 1の指示に従って自分で環境を決める必要がある。

学習用であることを明示している点と、その帰結

バッジにpurpose: learning onlyとあり、READMEも本リポジトリをinteractive textbookと呼ぶ。これは制約として読むべきで、学習済みチェックポイントの配布や、大規模コーパスでの学習手順、分散学習の設定は資料からは確認できない。151Mパラメータは構造を理解するには十分だが、実用的な生成品質を狙う規模ではない。また主言語がJupyter Notebookであるため、差分管理やレビュー、CIといったソフトウェア開発の作法とは相性が良くない。章の本文はMarkdownでchapters/以下に、実行可能なコードはnotebooks/以下に分かれている。コードを自分のリポジトリに取り込んで改変する場合、Notebookのセルを分割してテストを書く作業は読者側の負担になる。

代替としてのnanoGPTとの違い

同じ「小規模GPTを一から書く」目的ではAndrej KarpathyのnanoGPTがよく知られる。nanoGPTは再現可能な学習スクリプトと設定ファイルを中心に据え、GPT-2相当の構成を短いコードで動かすことを優先する。対して本リポジトリは、コード量そのものより注釈と解説の厚みを優先し、RoPE、RMSNorm、SwiGLU、KV cacheといったLLaMA 3系の要素を個別のexplainer付きで扱う。nanoGPTが「動かして結果を見る」教材だとすれば、こちらは「1行ずつ理由を確認する」教材である。すでにnanoGPTで学習ループを回した経験がある読者にとって、本リポジトリの価値は主にChapter 4から6と28本のexplainerに集約される。逆に、まず学習を回して損失曲線を見たいだけならnanoGPTのほうが早い。

ライセンスと維持コストの見取り図

ライセンスはMITで、法的助言はできないが、コードの再利用や改変、再配布の条件は比較的緩い部類にあたる。教材の文章とコードが同一リポジトリにあるため、コードだけを自社リポジトリに移す場合もMITの表示義務を確認しておきたい。最終pushは2026-08-30で、リリースは取得できていない。バージョン番号による互換性の約束がないため、PyTorch側のAPI変更が入った場合、Chapter 1やChapter 10のコードがそのまま動く保証はない。学習のためにフォークして自分の手元で直す前提で使うのが現実的である。

編集部の結論

MLの予備知識がなく、attentionの内部計算を自分の手で書きながら理解したいPython開発者に向く。逆に、既にTransformerを実装した経験があり、学習済みモデルやファインチューニング済みチェックポイントをすぐ使いたい人には不要である。着手前に、chapters/01_setup.mdでGPUとCPUのどちらを前提にしているか、notebooks/colab_train.ipynbがColabの無料枠で完走するかを自分の環境で確かめ、Chapter 7の151Mパラメータ構成が自分のマシンのメモリに収まるかを先に計算しておくこと。

公式情報源

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