Mini Transformer Lab ハンズオン

このプロジェクトは、LLM の完成品を作るためではなく、Transformer の主要部品を自作コードで触って理解するための最小実験環境です。

物語形式で概念を追う図解と引用つき解説は LLM Foundations Story にあります。各ハンズオンは、その解説の章と連動しています。

0. セットアップ

devbox run install
devbox run test
devbox run build
devbox run site
devbox run site:build
devbox run site:deploy

以降の任意 uv run ... コマンドは、先に devbox shell に入ってから実行してください。

devbox shell

1. Tokenizer の違いを見る

対応する基礎概念: Text Becomes Tokens

devbox run compare
uv run mini-transformer-compare-tokenizers --file data/natural/tiny.txt
uv run mini-transformer-compare-tokenizers --file data/code/tiny.py.txt

見るポイント:

• char は1文字1トークンなので仕組みが単純
• regex は Python の def, return, 空白、記号などをまとまりとして扱う
• 同じテキストでも token_count と vocab_size が変わる

2. 自然言語を学ぶ

対応する基礎概念: The Only Homework: Predict the Next Token, Dataset Is the Model’s World

devbox run train:natural
uv run mini-transformer-generate --run runs/natural-char --prompt "小さなデータでは"

短いデータなので、自然な文章生成というより「次の文字の癖を覚える」挙動が見えます。

3. コードを学ぶ

対応する基礎概念: Text Becomes Tokens, Dataset Is the Model’s World

devbox run train:code
uv run mini-transformer-generate --run runs/code-regex --prompt "def "

見るポイント:

• regex tokenizer は def, return, インデントなどの単位を作る
• コードデータでは括弧、コロン、改行、インデントが重要なパターンになる
• 小さいモデルでも、構文らしい断片は比較的早く出る

4. 次元数を変える

対応する基礎概念: Embedding and d_model, Attention and Heads

同じデータで d_model だけ変えます。

uv run mini-transformer-train --dataset data/natural/tiny.txt --tokenizer char --steps 80 --d-model 32 --n-heads 4 --n-layers 2 --context-length 64 --output-dir runs/d32
uv run mini-transformer-train --dataset data/natural/tiny.txt --tokenizer char --steps 80 --d-model 128 --n-heads 4 --n-layers 2 --context-length 64 --output-dir runs/d128

比較するもの:

• parameters
• train_loss
• valid_loss
• runs/*/sample.txt

目安:

• d_model が大きいほど1トークンを広いベクトルで表せる
• データが小さいと、大きいモデルは汎化より暗記に寄りやすい
• d_model は n_heads で割り切れる必要がある

5. 層数を変える

対応する基礎概念: Layers and Feed-Forward Networks

uv run mini-transformer-train --dataset data/code/tiny.py.txt --tokenizer regex --steps 80 --d-model 64 --n-heads 4 --n-layers 1 --context-length 64 --output-dir runs/code-layer1
uv run mini-transformer-train --dataset data/code/tiny.py.txt --tokenizer regex --steps 80 --d-model 64 --n-heads 4 --n-layers 4 --context-length 64 --output-dir runs/code-layer4

見るポイント:

• 層数は「変換を何段重ねるか」
• 増やすと表現力は上がるが、学習時間も増える
• 小さいデータでは valid loss が悪化することがある

6. 文脈長を変える

対応する基礎概念: Context Length and the Causal Mask

uv run mini-transformer-train --dataset data/natural/tiny.txt --tokenizer char --steps 80 --context-length 32 --output-dir runs/ctx32
uv run mini-transformer-train --dataset data/natural/tiny.txt --tokenizer char --steps 80 --context-length 128 --output-dir runs/ctx128

見るポイント:

• context_length は何トークン前まで見るか
• 長くすると遠い依存関係を扱える
• attention は系列長に対して重くなる

7. データセットを差し替える

対応する基礎概念: Dataset Is the Model’s World, Train Loss and Valid Loss

任意の UTF-8 テキストを置けば使えます。

uv run mini-transformer-train --dataset path/to/your.txt --tokenizer char --steps 200 --output-dir runs/my-text

コードだけを学ばせる場合:

find path/to/code -name "*.py" -maxdepth 4 -print0 | xargs -0 cat > data/code/my-code.txt
uv run mini-transformer-train --dataset data/code/my-code.txt --tokenizer regex --steps 300 --output-dir runs/my-code

注意:

• 個人情報や秘密鍵を含むデータは入れない
• 小さいデータでは覚え込みが起きる
• データの癖、文体、バグ、偏りはそのまま学習対象になる

8. 生成パラメータを変える

対応する基礎概念: Decoding Changes the Voice, Not the Knowledge

同じ run と prompt で、生成時の選び方だけを変えます。

uv run mini-transformer-generate --run runs/natural-char --prompt "小さな" --temperature 0
uv run mini-transformer-generate --run runs/natural-char --prompt "小さな" --temperature 0.8
uv run mini-transformer-generate --run runs/natural-char --prompt "小さな" --temperature 0.8 --top-k 8

見るポイント:

• temperature=0 は安定しやすい
• temperature を上げると出力が揺れやすい
• top-k は候補を絞る
• 生成パラメータは、学習済みの能力や知識を増やすものではない

9. Agent 開発へ接続する

対応する基礎概念: Why This Is Not Yet ChatGPT

この lab のモデルは、system prompt や user prompt に従う assistant ではありません。base language model が「続きを予測する」仕組みを理解するための教材です。

agent 開発に進むときは、次を別々に考えます。

• model が学習済みの能力
• prompt / chat template による入力構造
• tool schema による行動範囲
• RAG による外部知識
• validation による出力検査

この分離ができると、「prompt を強く書けば解決する問題」と「tool 権限、データ、検証で解くべき問題」を切り分けやすくなります。

最小設定の意味

概念と影響の一覧は Concept Impact Checklist にもあります。

ファイル対応

• src/mini_transformer_lab/model.py: Transformer 本体
• src/mini_transformer_lab/tokenizers.py: tokenizer の差分
• src/mini_transformer_lab/data.py: next-token prediction 用 batch
• src/mini_transformer_lab/train.py: 学習 CLI
• src/mini_transformer_lab/generate.py: 生成 CLI
• data/natural/tiny.txt: 自然言語の最小データ
• data/code/tiny.py.txt: コードの最小データ
• docs/LLM_FOUNDATIONS_STORY.md: 図解、概念ごとの影響、外部参考リンク
• src/pages/index.astro: Webページ版の入口
• src/pages/foundations.astro: docs/LLM_FOUNDATIONS_STORY.md を直接描画する Astro ページ
• src/pages/hands-on.astro: docs/HANDS_ON.md を直接描画する Astro ページ
• src/site/remarkDocLinks.mjs: Markdown 内の文書間リンクを Web ルートへ変換する remark plugin
• wrangler.jsonc: Cloudflare Pages の build output 設定
• .github/workflows/cloudflare-pages.yml: Cloudflare Pages への GitHub Actions deploy