waka-gen-modelのモジュール構造：
静的配布と再現性を両立する二系統設計

by

waka-gen-modelは、配布後の実行環境からPythonを消すという判断を起点に設計されています。
この一点から、学習系とブラウザ推論系を別系統にする構成が導かれます。

関連記事

1. 配布後からPythonを消すことが設計の出発点

システムは大きくPython側とJavaScript側に分かれます。

1. 配布後からPythonを消すことが設計の出発点

Python側はSQLiteからの和歌データ抽出、学習用.binへの変換、学習、checkpointの保存までを担います。
語彙90・埋め込み64・2block・2head・95,040パラメータのdecoder-only Transformerが中心1です。

1. 配布後からPythonを消すことが設計の出発点

JavaScript側はWebWorkerとして実装された推論エンジンで、Float32Arrayを使ってブラウザ内で推論を完結させます2。
main threadを塞がないため、生成中もUIが止まりません3。

この分離が成立すると、配布後の実行環境にPythonプロセスもSQLiteも不要になります。
GitHub Pagesや静的ホスティングで動く構成を、アーキテクチャの段階で選び取っています。

2. export層が二系統の変換境界になる

export_web.pyを中心とするWeb bundle層が、PythonとJavaScriptをつなぐ変換境界です。
システム全体で最も壊れやすい箇所でもあります。

2. export層が二系統の変換境界になる

学習済みcheckpointからweights.binを生成する際、optimizer状態は除外してmodel tensorだけをfloat32で書き出します。
manifest.jsonがtensor名・shape・byte offsetを保持し、JavaScript側はこれを読んでweightsを復元します4。
境界の正しさはPythonとJavaScript双方のfinal logitsを最大絶対誤差2e-4未満で照合することで担保しています5。

モデル構造を変えたり中型モデルを追加したりするたびに、この照合が回帰テストとして機能しなければ「学習はできたが推論が狂っている」状態を検出できません6。
checkpoint形式・manifest・catalog・検索データが絡み合うこの層は、将来的に最も手厚いテストが必要になります。

3. 再現性はrun単位のディレクトリに閉じ込める

Python側の学習層は再現性の確保を明示的な目標にしており、runs/<run-id>/配下にconfig・split・vocab・metrics・checkpoint一式をまとめて閉じ込めます。

3. 再現性はrun単位のディレクトリに閉じ込める

checkpointはoptimizer状態と乱数状態まで保存し、復元時に設定一致チェックを走らせます。
「途中から再開したら別の実験になっていた」という事故を、構造として防ぐ設計です。

通常forwardとtrace付きforwardも分離しています。
trace付きforwardはAttention確率やRMS値を追加で返しますが、これは可視化専用の経路です。
通常の学習はtrace付きforwardを通らないため、可視化の要件が学習速度に波及しません。

4. Tokenizerの差分が、logits照合より先に結果を狂わせる

二重実装がリスクとして表面化しやすい箇所はTokenizerです。
PythonとJavaScript両方で、同じ語彙・正規化・特殊token処理を再現しなければなりません。

4. Tokenizerの差分が、logits照合より先に結果を狂わせる

vocab.jsonを単一の真実源にしている点はよいですが、logitsの照合はtokenize後の入力ID列が正しく一致していることを前提にしています7。
正規化処理にズレがあると、同じ文字列を入力しても別のID列が生成され、logits parityの検証より前の段階で結果が狂います。

現行の小型モデルでは影響範囲が小さいですが、モデルを拡張するほどTokenizer差分が引き起こすバグの追跡は難しくなります。
テストが必要な箇所があるとすれば、ここです。

waka-gen-modelの設計をひとことで言うなら、「学習はPythonに残したまま、ブラウザ側を独立して動かせる状態にする」という非対称の役割分担です。
その非対称を支えるexport層と、両側にまたがるTokenizer仕様が、今後の拡張を制約するか解放するかの分岐点になります。

  1. decoder-only Transformerは、各トークンが過去のトークンだけを参照するcausal self-attentionを用いた自己回帰型アーキテクチャです。GPT、Llama、Claudeなど現代の大規模言語モデルがほぼすべてこの構造を採用しています。本プロジェクトのモデルはGeorge Hotz（geohot）によるPython製ミニマリスト深層学習フレームワーク「tinygrad」を使って実装されています。 – Decoder-only model: the architecture every modern LLM uses
  2. Float32ArrayはJavaScriptのTyped Arrayの一種で、32ビット浮動小数点数（Cのfloat型相当）を格納するバイナリバッファです。通常のArrayと異なり型固定のため、テンソル演算のメモリ効率が高く、機械学習の推論実装で広く使われます。 – Float32Array – MDN Web Docs
  3. Web Workers APIはブラウザのmain execution threadとは独立したバックグラウンドスレッドでJavaScriptを実行する仕組みです。DOMへの直接アクセスはできませんが、重い計算処理をオフロードしてUIの応答性を保つのに適しています。 – Web Workers API – MDN Web Docs
  4. 学習済みweightをバイナリファイルに書き出し、別途メタデータでtensor名・shape・byte offsetを管理するパターンは、ONNX Runtimeの大規模モデル向け外部データ形式と同様の考え方です。ONNX Runtime Webでも、2GBを超えるモデルを扱う際に、protobuf本体と外部バイナリを分離してoffset・lengthをメタデータに記録する方式が採用されています。 – Working with Large Models – ONNX Runtime Web
  5. logits（ロジット）はニューラルネットワークの最終層が出力する、softmaxなどの活性化関数を適用する前の生スコアです。各tokenに対応するスコアを表し、softmaxを通すことで確率分布に変換されます。PythonとJavaScript双方のlogitsを数値的に照合することで、モデル移植の正しさを確認できます。 – What are Logits in Machine Learning and Why They Matter
  6. 回帰テストとはソフトウェアの変更後に既存の挙動が意図せず変わっていないかを確認する検証です。CIパイプラインに組み込み、変更のたびに自動実行することで、既知の正常動作からの逸脱を早期に検出できます。 – Regression Testing in CI/CD: Deliver Faster Without Fear – Harness
  7. 「単一真実源（Single Source of Truth: SSOT）」はソフトウェア設計の原則で、特定のデータや仕様を一か所だけに置き、他はそこを参照する構造を指します。複数箇所で同じ情報を管理すると不整合が生じやすいため、語彙ファイルや設定の管理に広く用いられます。 – Single Source of Truth – Wikipedia