このファイルは v0.4 (2026-05) 以前の README.md を docs/ に移動したもの。 プロジェクトが P0 (設計フェーズ) の段階で書かれた、実装計画寄りの紹介文。 v1 リリース後は利用者向けの新 README.md がプロジェクト直下に置かれているのでそちらを参照。 本ファイルは履歴記録目的で残してある。
Transformer の inference (推論) 動作 を 行列のセル 1 個ずつ何が起きているか の粒度で観察できるブラウザ用シミュレータ。姉妹プロジェクト nn-anatomy (MLP 版) の哲学を Transformer に拡張したもので、大学情報系学部の 3〜4 年次以上 (深層学習・NLP の応用科目) を対象にする。
ステータス: 設計フェーズ (P0) 設計書を
design.mdに書いた段階。実装はこれから (P1: matrix.js + tokenizer + PyTorch 参照実装)。 動くものはまだ無い。MLP 版が完成版なので、まずはそちらを参照のこと。
方針: forward (推論) のみ。学習機能はシミュレータ本体に含めない。重みは別途 numpy で hand-crafted (人手構築) で書いた preset JSON を読み込んで使う。8 サンプル × T=5 で SGD 学習させても attention map が綺麗に分化しないリスクが高いため、教育的には人手で意図したパターンを埋め込むほうが目的に適う、という判断。Backward / 学習の核は MLP 版で習得済みであることが前提。
詳細・段階定義は design.md §3「スコープ (Tier 定義)」を参照。
| ID | 単語 | 種別 |
|---|---|---|
| 0-2 | これ / それ / 私 | 指示詞・代名詞 |
| 3-6 | 猫 / 花 / 本 / 小説 | 名詞 |
| 7-9 | 大きい / 美しい / 人気 | 形容詞 |
| 10-11 | 読む / 好き | 動詞 |
| 12-14 | は / が / を | 助詞 |
| 15 | です | コピュラ |
これらで組める例文 (T=5):
design.md §6.2 参照)nn-anatomy-transformer/
├── README.md ← 本ファイル
├── docs/
│ ├── design.md ← 全機能仕様 (P0 完了)
│ ├── math-notes-transformer.md (P8 で完備)
│ ├── lesson-plans-transformer.md(P8 で完備)
│ └── implementation-notes.md (実装ログ)
├── src/
│ ├── index.html
│ ├── style.css
│ └── js/
│ ├── rng.js (MLP 版から流用、PE 生成内部用)
│ ├── tokenizer.js (P1) — 16 語固定 encode/decode
│ ├── matrix.js (P1) — flat-array 行列演算
│ ├── presets.js (P3) — デフォルト preset を inline
│ ├── model.js (P3) — createTransformer / forward
│ ├── lessons.js (P6) — Lesson T1〜T9
│ ├── view.js (P4) — 行列ヒートマップ + pan/zoom
│ ├── explain.js (P5) — 式の展開
│ └── controller.js
├── presets/ ← hand-crafted 重みの JSON
│ ├── japanese-mini-v1.json
│ ├── induction-head.json
│ ├── knowledge-lookup.json
│ └── random-init.json
├── tests/
│ ├── js/
│ ├── py/ numpy 参照実装
│ └── fixtures/
├── tools/
│ ├── bundle.py (MLP 版から流用)
│ ├── build_preset.py 設計書 §6.9 に従って hand-crafted preset JSON を構築 (numpy)
│ └── inline_preset.py デフォルト preset を src/js/presets.js に展開
├── build/
├── Makefile
├── pyproject.toml (numpy + pytest)
├── package.json
└── .gitignore
node --test)uv sync # numpy + pytest が .venv に入る (数秒、PyTorch は使わない)
node --version
make help # 利用可能なタスク
design.md §12)| フェーズ | 内容 | 状態 |
|---|---|---|
| P0 | 設計書 + プロジェクト雛形 | 完了 |
| P1 | matrix.js + tokenizer.js + numpy 参照実装 | 完了 (JS 27 / Python 13) |
| P2 | tools/build_preset.py + デフォルト preset 構築 (hand-crafted) | 完了 (Python 23 + preset 26.1 KB、self-check 16/16 pass) |
| P3 | Tier 1 model.js (forward only) + presets.js inline | 完了 (JS 39 / Python 36、計 75 件パス、attention fixture 数値一致) |
| P4 | Tier 1 view.js (静的描画) + pan/zoom + 最小 controller | 完了 (build = 53.6 KB、Tier 1 が画面に出る) |
| P5 | セルクリック → 式の展開 (explain.js) + Attention Map 常駐 | 完了 (build = 72.1 KB、X/Q/K/V/scores/attn/attnOut/Y の 8 種で 3 段板書) |
| P6 | Tier 1 Lesson T1-T5 + UI Lesson セレクタ | 完了 (build = 85.6 KB、JS 47/Python 36 = 83 件パス) |
| P7 | Tier 2 (Multi-Head + 残差 + LN + FFN) + Lesson T6-T8 | 未着手 |
| P5 | Tier 1 explain.js + interactivity | 未着手 |
| P6 | Tier 1 Lesson T1-T5 + 8 文セレクタ | 未着手 |
| P7 | Tier 2 (Multi-Head + 残差 + LN + FFN) + Lesson T6-T8 | 未着手 |
| P8 | Tier 3 (多 Block + 複数 Preset 切替) + Lesson T9 + ドキュメント完備 | 未着手 |