GitHub には LLM を解説するリポジトリが山ほどあるが、GPT の forward から SFT/DPO まで通しで書き、各層を細部まで分解しているものは多くない。その中でも特に完成度が高いのが rasbt/LLMs-from-scratch だ。作者は Lightning AI のリサーチサイエンティスト、Sebastian Raschka。『Machine Learning with PyTorch and Scikit-Learn』の著者でもある。新著『Build a Large Language Model (From Scratch)』は Manning から刊行されており(ISBN 9781633437166)、このリポジトリはその公式コードになっている。
何の課題を解決するか
LLM の内部動作を理解したい人が必ず直面する壁がある。
- HuggingFace のラッパーを使ったチュートリアルは多すぎる。
AutoModelForCausalLM.from_pretrainedのワンライナーで完結するが、行列の中で実際に何が計算されているかは見えない。 - 論文の写経も多く、attention の数式は載っているが、コードへの落とし込みは省略されている。
このリポジトリの方針は明快だ。およそ 400 行の PyTorch で、token embedding → multi-head attention → LayerNorm → 事前学習 → SFT までを一気に走らせる。コードはすべて Jupyter Notebook に収められ、nn.Module は抽象化なしで分解されている。
一周走らせれば、最低限 次のような問いに自分の言葉で答えられるようになる:(1) なぜ d_out % num_heads == 0 が必要なのか、(2) causal mask は上三角行列をどう使うのか、(3) SFT と事前学習の loss は何が違うのか、(4) DPO の暗黙的な reward は ref モデルからどう取り出すのか。
使い方
clone すると、章立てで整理された Jupyter Notebook が並ぶ。順番に読み進める形だ。
ch02_text_data.ipynb— tokenizer + sliding window データセットch03_coding_attention_mechanisms.ipynb— 4 種類の self-attention バリアントch04_implementing_gpt_model.ipynb— TransformerBlock + GPTModelch05_pretraining_on_unlabeled_data.ipynb— 事前学習ch06_finetuning_for_classification.ipynb— 分類ファインチューニングch07_instruction_finetuning.ipynb— SFTch08_aligning_models_with_human_feedback.ipynb— DPO/PPO
各章の末尾には exercises が用意され、解答は exercise-solutions.ipynb にまとまっている。環境のセットアップは README が uv を推奨している。
最小ルートは Colab の無料 GPU を開き、ch04_implementing_gpt_model.ipynb を実行して 124M の GPT-2 スケルトンを学習させる。数時間程度でテキストを續かせるデモが動く。すべてをやり通すなら、およそ一週間程度を見ておけばいい。
アーキテクチャ
コードはボトムアップで 4 つの層に分かれている。
- ch02 — データ層:
tiktokenで BPE tokenization を行い、sliding window で長文をcontext_lengthサイズの訓練サンプルに切り出す。 - ch03 — Attention 層:naive self-attention → causal mask 付き → multi-head → PyTorch 内蔵の
torch.nn.functional.scaled_dot_product_attentionを使う版まで段階的に実装。各版で同じ toy 入力を走らせ、結果を比較する。 - ch04 — モデル層:
TransformerBlock(LayerNorm + MHA + FFN + 残差接続を含む)とGPTModelを実装。設定は GPT-2 124M に厳密に合わせる:d_model=768, n_heads=12, n_layers=12。OpenAI の公式重みをそのまま読み込める(ch05)。 - ch07 + ch08 — アライメント層:SFT は instruction-response 形式のデータ、PPO/DPO は ref モデルと policy モデルの log-ratio 差から暗黙的 reward を計算する。
重要な設計方針として、すべての行列次元は GPT_CONFIG_124M という dict に集約されている。shape が間違っていればほぼ確実に例外で止まるため、GPT-2 論文の Table 2 と突き合わせながら設定を確認しやすい。
以下は ch04_implementing_gpt_model.ipynb にある MultiHeadAttention のコア部分だ。30 行足らずで、Q/K/V 分割、scaled dot-product、causal mask、dropout をすべて内包している。
import torch
import torch.nn as nn
class MultiHeadAttention(nn.Module):
def __init__(self, d_in, d_out, context_length, dropout, num_heads, qkv_bias=False):
super().__init__()
assert d_out % num_heads == 0, "d_out must be divisible by num_heads"
self.d_out = d_out
self.num_heads = num_heads
self.head_dim = d_out // num_heads
self.W_query = nn.Linear(d_in, d_out, bias=qkv_bias)
self.W_key = nn.Linear(d_in, d_out, bias=qkv_bias)
self.W_value = nn.Linear(d_in, d_out, bias=qkv_bias)
self.out_proj = nn.Linear(d_out, d_out)
self.dropout = nn.Dropout(dropout)
self.register_buffer(
"mask", torch.triu(torch.ones(context_length, context_length), diagonal=1)
)
def forward(self, x):
b, num_tokens, d_in = x.shape
keys = self.W_key(x).view(b, num_tokens, self.num_heads, self.head_dim).transpose(1, 2)
queries = self.W_query(x).view(b, num_tokens, self.num_heads, self.head_dim).transpose(1, 2)
values = self.W_value(x).view(b, num_tokens, self.num_heads, self.head_dim).transpose(1, 2)
attn_scores = queries @ keys.transpose(2, 3)
attn_scores.masked_fill_(self.mask.bool()[:num_tokens, :num_tokens], -torch.inf)
attn_weights = torch.softmax(attn_scores / self.head_dim**0.5, dim=-1)
attn_weights = self.dropout(attn_weights)
context_vec = (attn_weights @ values).transpose(1, 2).contiguous().view(b, num_tokens, self.d_out)
return self.out_proj(context_vec)
この cell を走らせる前に、入力テンソルを用意しておく。
x = torch.randn(2, 6, 768) # batch=2, tokens=6, d_model=768
mha = MultiHeadAttention(768, 768, context_length=1024, dropout=0.1, num_heads=12)
mha(x).shape
# torch.Size([2, 6, 768])
shape が想定通りなら、行列分解は正しく動いている。Q/K/V を (b, tokens, d_out) から (b, tokens, num_heads, head_dim) に reshape して transpose(1, 2) で並べる——これがマルチヘッドを並列計算するための核となる操作で、論文の図を眺めるより一度 cell を実行してみる方が早い。
良い点・悪い点
良い点:
- 抽象化を一切隠さない。
nn.TransformerEncoderやAutoModelは使わず、全層を自分で実装する。 - 配套書籍は Manning 刊で、章構成やレイアウトが普通の repo より厳密。各章末に "Summary" + "Exercises" という学術フォーマットが揃っている。
- Qwen3 / DeepSeek の重みロード章が追加されており、近年のトレンドにも追随している。LoRA や KV cache の実装もカバー。
悪い点:
- Jupyter 中心のため、
pip installしてそのままライブラリとして使う形にはなっていない。from llms_from_scratch import GPTModelはできないので、コードを自前で取り込む必要がある。 - 124M モデルは現代の LLM 基準では小さく、ChatGPT のような出力は得られない。基本的に教育目的であり、production モデルを学習する場ではない。
- RLHF/PPO の章(ch08)は事前学習部分より浅い。DPO にはコードが付くが、理論導出はかなり省かれている。アライメントを実務でやりたい場合は、HuggingFace TRL のドキュメントや Christiano らの原論文をあたる必要がある。
実際に試してみた
clone 後、ch04 配套の gpt_train.ipynb を Colab T4 で開き、124M モデルを 5k step 回した。loss は ~11 から ~3.5 まで下がった。生成サンプルは文法的には自然で、たとえば "Once upon a time" という prompt からは童話の冒頭をそれらしく續らせる。ただし事実関係はすべて捏造で、124M なら普通にそういうものだ。
ch03 末尾の attention 可視化も分かりやすかった。第 1 層で学習されるのは隣接 token へのアラインメント(「the」が「cat」に注目するような局所依存)で、長距離依存は深い層でようやく現れる。これは BERTology 系論文で報告されている観察と一致する。この部分は、attention map を自分の目で見るまで「なぜ transformer が動くのか」が腹落ちしない。
もう一点。ch07 の SFT では instruction-data.json(Alpaca スタイル)が使われているが、データ量は多くない。それでも 124M モデルが instruction format を学ぶには十分で、loss の下がり方は事前学習より速く、2k step で安定する。小さいモデル + 高品質データという典型例といえる。
向いている人・向いていない人
向いている:
- transformer の内部で実際に何が計算されているかを把握したい現役エンジニア——読み終えれば、どんな attention 実装でも code review できる。
- 面接で attention の式を手元で導いて見せる必要がある人——まさにこういう教材が頼りになる。
- PyTorch の基礎は持っているが LLM の内部には触れていない、ML 入門から LLM へ移行中の人。
向いていない:
- プロダクション品質のモデルを今すぐ欲しい人——HuggingFace を当たるのが早道。
- 7B+ の学習を回したい人——このリポジトリは教育用で、FSDP / ZeRO / tensor parallelism は扱わない。
- PyTorch 自体がほぼ初めてのビギナー——公式の 60 分入門を先に一通りやってから来るのが安全。
依存は PyTorch + Python のみで、サードパーティは tiktoken / datasets / wandb の 3 つだけ。