LanguageModel アーキテクチャ互換性・アーティファクト契約

• ステータス: 導入済み契約（本番適用・legacy移行は別作業）
• 最終更新: 2026年8月3日
• 対象: EvoSpikeNet-Core と、Mineral Exploration などの SDK 経由で LanguageModel を学習・選択・推論するアプリケーション

目的

アプリケーション UI から d_model を変更して複数の LanguageModel を作成する場合でも、各モデルを誤認せず、正しい構成・Tokenizer・checkpoint で学習、追加学習、推論できるようにする。

d_model は単独ではモデルを識別しない。モデル互換性は、アーキテクチャ、層構成、SNN パラメータ、Tokenizer、語彙、checkpoint を含む不変のモデル仕様で判定する。

適用範囲と非対象

• 対象: dense SpikingEvoTextLM、SparseEventMemoryLM、将来の MemoriedSpikeNetLM を含む LanguageModel のアーティファクト登録、追加学習、推論選択。
• 対象: Mineral Exploration の LanguageMode UI、API、SDK adapter、Core training artifact の接続契約。
• 非対象: 異なる d_model 間の重み変換、層の増減を伴う継続学習、語彙行列の部分転写。これらは明示的な model surgery / migration 機能として別途設計する。

SparseEventMemoryLM は dense SpikingEvoTextLM と別アーキテクチャであり、checkpoint を相互に読み込めない。詳細は Sparse Event-Memory LM 仕様書 を参照する。

現状の確認結果（2026年8月3日）

Core

Core の学習スクリプトは、保存時に重み、config.json、Tokenizer を artifact bundle に含める。追加学習時に有効な base_model_path と同じディレクトリの config.json が存在すれば、保存済み構成を読み取り、モデルを構築して strict な load_state_dict() を実行する。

このため異なる d_model のモデルは、モデルごとに独立した完全な artifact bundle を保持し、その bundle 固有の構成でロードする限り共存可能である。一方で形状の異なる重みは strict load で失敗し、互換性を意味しない。

ChronoSpikeAttention は次の制約を持つ。

\[d_{model} \bmod n_{heads} = 0\]

モデル規模は概算で次のように増加する。

\[P \approx 2Vd + 12Bd^2\]

ここで \(V\) は語彙数、\(d\) は d_model、\(B\) は transformer block 数である。特に block 部分は \(d_{model}\) の二乗に比例するため、d_model を2倍にすると必要なパラメータと optimizer state は大幅に増える。

Mineral Exploration

LanguageMode UI/API は、d_model、n_heads、num_blocks、time_steps、neuron_type、architectureを不変model_specとして登録・一覧表示する。Core はcheckpoint、config.json、Tokenizer、SHA-256付きartifact_manifest.jsonを保存し、SDKはその永続URIを返す。

モデル台帳のstorage/models/language/{model_id}/model.jsonは、model_spec、manifest、親モデル、ジョブIDを保存する。既存レコードでこれらがない場合はlegacy_unverifiedと表示し、追加学習を禁止する。session://...は表示互換用であり、再開・推論には使わない。

追加学習と推論のpreflightは、checkpoint/config/Tokenizerの実体、SHA-256、configとmanifestのmodel_spec、選択アーキテクチャを検証する。Docker再起動を伴うデプロイとlegacy artifactの管理者移行は別作業である。

正式な model_spec 契約

各登録モデルは、次の不変 model_spec を保存しなければならない。値を変更する操作は新しい model_id を作成する新規学習とする。

{
  "model_spec_version": 1,
  "model_family": "spiking_text_lm",
  "architecture": "dense_chronospike",
  "d_model": 128,
  "n_heads": 4,
  "num_transformer_blocks": 2,
  "time_steps": 20,
  "neuron_type": "EvoLIF",
  "vocab_size": 32000,
  "tokenizer": {
    "name": "cl-tohoku/bert-base-japanese-v3",
    "revision": "optional-immutable-revision",
    "files_sha256": "optional-tokenizer-bundle-digest"
  },
  "core": {
    "artifact_format_version": 1,
    "core_version": "recorded-build-or-commit"
  }
}

model_spec とは別に、登録レコードは少なくとも次を持つ。

{
  "checkpoint_uri": "durable-uri-to-model.pt",
  "config_uri": "durable-uri-to-config.json",
  "tokenizer_uri": "durable-uri-to-tokenizer-bundle",
  "artifact_sha256": "bundle-or-manifest-digest",
  "parent_model_id": null,
  "training_job_id": "lmtrain-..."
}

• model_uri は後方互換の表示用別名として維持できるが、checkpoint_uri の代替にしてはならない。
• config.json は model_spec と矛盾してはならない。登録時に両者を比較する。
• URI は再起動後にも解決できる durable storage を指す。セッション ID だけでは要件を満たさない。
• digest は重み、構成、Tokenizer bundle の取り違え検出に用いる。

API と UI の導入仕様

新規学習

LanguageMode の新規学習リクエストは、model_spec のうち利用者が選択可能なフィールドを明示的に含める。最低限、次を追加する。

• architecture
• d_model
• n_heads
• num_blocks
• time_steps
• neuron_type
• seq_len
• learning_rate

API は Core に要求を送る前に、以下を検証する。

1. 全ての数値が正であり、サービスが定める上限内であること。
2. \(d_{model} \bmod n_{heads} = 0\) であること。
3. architecture 固有のパラメータだけが指定されていること。
4. 選択デバイスのメモリ見積もりとジョブ上限を満たすこと。dense SpikingEvoTextLM は Mineral の GPU 容量検証により、現在 Core から見える GPU の空き VRAM に対して要求構成を検証する。
5. 語彙数・Tokenizer 情報を解決できること。

UI は任意の巨大値を既定で受け付けず、承認済みの Small / Base / Large プリセットを提供する。詳細値を許可する場合も、API と同じ制約を表示前に検証する。

容量検証は batch_size、seq_len、learning rate、その他のモデル構成を自動変更しない。UI は容量不足を表示して開始を無効化し、起動 API は構成を変更せず HTTP 422 を返す。Core/SDK は有効な提出構成をそのまま実行する。GPU の選択、推定式、H100 を含む移植性、実行時 OOM の制約は LanguageModel GPU 容量検証ポリシー を参照する。

追加学習

追加学習はアーキテクチャ変更ではない。ベースモデルを選択した時点で model_spec と Tokenizer を読み取り専用表示し、Core の base_model_path に解決可能な checkpoint_uri を渡す。

次の項目は完全一致しなければならない。

区分	必須一致項目
構造	model_family、architecture、d_model、n_heads、num_transformer_blocks、time_steps、neuron_type
入出力	vocab_size、Tokenizer name/revision/digest
artifact	checkpoint、config、Tokenizer bundle がすべて取得可能で digest が一致

不一致、欠損、legacy な仕様不明モデルは、Core の重みロードまで進めず HTTP 422 の互換性エラーとして拒否する。新しい構成で学習したい場合は training_type: new を使用する。

推論

推論は選択した model_id の登録済み artifact manifest からのみ構築する。UI の現在の学習フォーム値、環境変数の既定値、別モデルの d_model を推論構築に流用してはならない。

推論前に API は以下を確認する。

1. model_spec、checkpoint、config.json、Tokenizer bundle が存在する。
2. config.json と model_spec が一致する。
3. artifact digest が一致する。
4. モデル品質が生成可能と判定されている。
5. SDK/推論サーバが指定された artifact URI をロードできる。

失敗時は garbled text や別モデルでの代替推論を返さず、モデル・artifact・互換性のどれが失敗したかを含む明示的なエラーを返す。

互換性マトリクス

操作	条件	扱い
異なる d_model の新規学習	個別の完全 artifact bundle と model_spec を登録	許可
モデル A/B の個別推論	選択モデル自身の構成・Tokenizer・重みをロード	許可
同一仕様の追加学習	構造・Tokenizer・artifact 検証が全て成功	許可
異なる d_model への追加学習	state dict のテンソル形状が異なる	拒否
同じ d_model だが block/head/time-step/neuron が異なる追加学習	実行意味または重み形状が異なる	拒否
同じ構造だが語彙/Tokenizer が異なる追加学習	embedding/output 行列または token 意味が異なる	拒否
dense と sparse の相互ロード	checkpoint 形式とモデル実装が異なる	拒否
仕様不明の既存モデルへの追加学習	十分な再現性情報がない	拒否または管理者による manifest 移行後に許可

移行と後方互換

既存の model.json に model_spec がないモデルは legacy_unverified と表示する。

• 推論は、artifact manifest を復元・検証できる場合だけ許可する。
• 追加学習は、管理者が checkpoint、config、Tokenizer bundle を登録し、model_spec を確定するまで禁止する。
• ログから推測した d_model や Tokenizer は証跡ではない。推測値を正式な互換性判定に使わない。
• 既存 API の model_uri はすぐに削除せず、checkpoint_uri への移行完了まで読み取り専用互換フィールドとして扱う。

受入基準

実装完了とするには、少なくとも次を自動テストで確認する。

1. d_model=8 と d_model=16 の二つの artifact を登録し、一覧で仕様を区別できる。
2. 各モデルの推論が各自の config/Tokenizer/checkpoint を選び、相互に混線しない。
3. 異なる d_model、head 数、block 数、Tokenizer、architecture の追加学習が、ジョブ起動前に理解可能な 422 エラーとなる。
4. 同一仕様の追加学習が checkpoint を実際にロードし、親子 lineage を記録する。
5. checkpoint/config/Tokenizer の欠損または digest 不一致では推論・追加学習を拒否する。
6. UI のモデル一覧と選択欄に、architecture と主要サイズ（d_model、heads、blocks、Tokenizer）を表示する。
7. 現在実行中の学習ジョブの request/artifact を、仕様導入作業が変更しない。

関連文書

• 機能実装ステータス
• LLM Training System
• LanguageModel GPU 容量検証ポリシー
• SDK Sparse Event-Memory LM ガイド
• MEMERIED SpikeNetLM 音声・画像・マルチモーダル拡張仕様
• English version