Evo-LLM Converter 設計書

バージョン: 1.0 対象: EvoSpikeNet-Core（evospikenet/ 名前空間） 目的: 既存の Transformer ベース大規模言語モデル（LLM）を、EvoSpikeNet のスパイキングニューラルネットワーク（SNN）LLM（SpikingEvoTextLM）へ変換・最適化する CLI／ライブラリツール「Evo-LLM Converter」の設計を定義する。

本書は「正しく動作させる」ことを最優先に、EvoSpikeNet-Core に実在するモジュール・クラス・APIのみを前提とする。実在しない機能（例: INT16 演算）は採用せず、実装済み資産（SpikingEvoTextLM, ChronoSpikeAttention, TASEncoderDecoder, OptimizationPipeline, QPFCAdaptiveController, MetaSTDP, SNNRAGHybrid 等）を組み合わせるオーケストレーション層として Converter を新規実装する。

---

1. スコープと前提

1.1 ゴール

1. 入力 LLM（torch.nn.Module または HuggingFace チェックポイント）を、SpikingEvoTextLM 互換の SNN-LLM へ知識蒸留で変換する。
2. TAS-Encoding によりトークン入力をスパイク列化し、Softmax アテンションを ChronoSpikeAttention（因果的指数減衰）へ置換する。
3. OptimizationPipeline で量子化・剪定・融合を行い、Jetson / Edge TPU / CPU 向けにエクスポートする。
4. 任意で Q-PFC 自己変調推論、Meta-STDP 継続学習、SNN-RAG 記憶参照を接続する。
5. 各段階で数値・性能・精度の検証を行い、合否を判定する。

1.2 非ゴール

• LLM のフルスクラッチ再学習は対象外。蒸留と軽量チューニングのみ。
• INT16 整数演算はコードベースに存在しないため採用しない（量子化は INT8 動的量子化を基本とする）。

1.3 実在コンポーネント前提（検証済み）

機能	実体（ファイル / クラス）	状態
SNN-LLM 本体	evospikenet/models.py SpikingEvoTextLM	実装済
因果アテンション	evospikenet/attention.py ChronoSpikeAttention	実装済（特許 MT25-EV001）
TAS エンコード	evospikenet/encoding.py TASEncoderDecoder	実装済（特許 MT25-EV002）
最適化パイプライン	evospikenet/optimization_pipeline.py OptimizationPipeline	実装済
量子化 / 剪定 / 融合	evospikenet/plugins/builtin/optimization_backends/{quantization,pruning,fusion}_plugin.py	実装済（INT8）
知識蒸留	examples/distill_ann_to_snn.py、evospikenet/api_modules/training_api.py（/api/train/distillation）	実装済
Q-PFC 自己変調	evospikenet/q_pfc_adaptive_control.py QPFCAdaptiveController	実装済（特許 MT25-EV008）
継続学習	evospikenet/plasticity.py MetaSTDP	実装済（特許 MT25-EV016）
SNN-RAG / 記憶	evospikenet/snn_rag.py SNNRAGHybrid、evospikenet/rag_memory_integrator.py RAGMemoryIntegrator	実装済
プラグイン基盤	evospikenet/plugin_factory.py, evospikenet/plugins/__init__.py	実装済
デバイス配備	device_backends/{jetson,edgetpu,cpu}_plugin.py, universal_integration.py JetsonAdapter	実装済（一部 stub）

---

2. アーキテクチャ概要

Evo-LLM Converter は、既存資産を 5 ステージのパイプラインとして直列化するオーケストレータである。

flowchart TD
    A[入力 LLM<br/>torch.nn.Module / HF ckpt] --> B[Stage 1<br/>取り込み・教師モデル化]
    B --> C[Stage 2<br/>SNN-LLM 構成生成<br/>SpikingEvoTextLM]
    C --> D[Stage 3<br/>ANN→SNN 知識蒸留]
    D --> E[Stage 4<br/>最適化パイプライン<br/>量子化/剪定/融合]
    E --> F[Stage 5<br/>オプション統合 +<br/>デバイスエクスポート]
    F --> G[成果物<br/>EvoLLMArtifact]

    subgraph 任意統合
      O1[Q-PFC 自己変調]
      O2[Meta-STDP 継続学習]
      O3[SNN-RAG 記憶参照]
    end
    F -.-> O1
    F -.-> O2
    F -.-> O3

    subgraph 検証
      V1[蒸留収束/perplexity]
      V2[スパース率/遅延]
      V3[精度劣化]
    end
    D -.-> V1
    E -.-> V2
    F -.-> V3

2.1 新規実装するモジュール構成

evospikenet/converters/llm/
├── __init__.py
├── pipeline.py          # EvoLLMConverter（オーケストレータ本体）
├── config.py            # EvoLLMConverterConfig（dataclass + YAML ローダ）
├── stages/
│   ├── ingest.py        # Stage 1: 教師モデル取り込み・トークナイザ整合
│   ├── build_snn.py     # Stage 2: SpikingEvoTextLM 生徒モデル構成
│   ├── distill.py       # Stage 3: ANN→SNN 知識蒸留
│   ├── optimize.py      # Stage 4: OptimizationPipeline 連携
│   └── integrate.py     # Stage 5: Q-PFC/MetaSTDP/SNN-RAG + エクスポート
├── artifact.py          # EvoLLMArtifact（成果物 + 保存/読込）
├── validation.py        # 各ステージの数値・性能検証
└── cli.py               # `evo-llm-convert` エントリポイント

---

3. ステージ別詳細設計

3.1 Stage 1: 取り込み・教師モデル化（stages/ingest.py）

目的: 入力 LLM を蒸留の「教師」として正規化し、トークナイザ・語彙サイズ・次元数を抽出する。

• 入力: torch.nn.Module または HF チェックポイントパス。
• 処理:
• model.eval()、requires_grad_(False)（教師は固定）。
• vocab_size / d_model / n_heads / 層数を取得（HF の config または手動 config.teacher_meta）。
• トークナイザを生徒側と共有できるよう正規化（不一致時は明示エラー、推測で続行しない）。
• 出力: TeacherSpec(model, tokenizer, vocab_size, d_model, n_heads, num_layers)。

3.2 Stage 2: SNN-LLM 生徒モデル構成（stages/build_snn.py）

目的: 蒸留先の SNN-LLM を実在クラスで生成する。

実在 API:

from evospikenet.models import SpikingEvoTextLM

student = SpikingEvoTextLM(
    vocab_size=teacher.vocab_size,
    d_model=config.d_model,                 # 教師より小さく設定可（蒸留）
    n_heads=config.n_heads,
    num_transformer_blocks=config.num_blocks,
    time_steps=config.time_steps,           # 例: 10
    dropout=0.1,
    neuron_type="EvoLIF",
)

• SpikingEvoTextLM は内部で TASEncoderDecoder（入力段のスパイク符号化）と SpikingTransformerBlock（attention_axis="sequence"）を構成済み。よってTAS-Encoding インジェクションと ChronoSpike 系アテンションへの置換は本クラス生成で自動的に満たされる（別途の手作業置換は不要）。
• アテンション軸や τ の制御が必要な場合は、ChronoSpikeAttention(input_dim, hidden_dim, n_heads, time_steps, learnable_tau=...) を直接構成して差し替え可能。
• 出力: 未学習の SpikingEvoTextLM 生徒モデル。

3.3 Stage 3: ANN→SNN 知識蒸留（stages/distill.py）

目的: 教師 LLM の出力分布を生徒 SNN-LLM に転写する。

• 既存資産を利用: リファレンス実装 examples/distill_ann_to_snn.py と、ジョブ起動 API POST /api/train/distillation（training_api.py、teacher_source=local|huggingface）。
• 蒸留損失: ソフトターゲット KL ダイバージェンス（温度 T）＋ 言語モデリング CE の加重和。

  loss = alpha * KL(student_logits / T, teacher_logits / T) * T**2 \
       + (1 - alpha) * CE(student_logits, labels)
  

• 入力: config.distill_dataset（テキストコーパス）、教師 = TeacherSpec.model、生徒 = Stage 2 の SpikingEvoTextLM。
• 検証: 蒸留中の perplexity / KL 収束を validation.py で記録。発散時は早期停止。
• 補足: マーケティング資料の「50〜90% 削減」「1μJ 以下」等の固定値は採用せず、validation.py が実測したエネルギー・遅延・perplexityを成果物に記録する。

3.4 Stage 4: 最適化パイプライン（stages/optimize.py）

目的: エッジ実行のため量子化・剪定・融合を適用する。

実在 API:

from evospikenet.optimization_pipeline import OptimizationPipeline

pipeline = OptimizationPipeline.from_yaml(config.optimization_yaml)
result = pipeline.run(student, continue_on_error=False)
optimized_model = result.model

最適化 YAML（既定テンプレート）:

optimization_pipeline:
  steps:
    - type: "quantization"   # QuantizationPlugin（INT8 動的量子化, backend=fbgemm）
      config: { backend: "fbgemm" }
    - type: "pruning"        # PruningPlugin（構造的剪定）
      config: { amount: 0.3, method: "l1_unstructured" }
    - type: "fusion"         # FusionPlugin（モジュール融合）
      config: { fuse_groups: [["linear", "act"]] }

• 量子化は INT8 のみ（torch.quantization.quantize_dynamic、対象 nn.Linear）。INT16 は非対応のため設定不可。
• continue_on_error=False を既定とし、ステップ失敗時はパイプライン全体を失敗とする（部分成果物の暗黙採用を防ぐ）。

3.5 Stage 5: オプション統合 + デバイスエクスポート（stages/integrate.py）

目的: 任意機能を接続し、ターゲットデバイス向け成果物を生成する。

デバイスエクスポート（plugin_factory 経由）:

from evospikenet.plugin_factory import PluginFactory
from evospikenet.plugins import PluginType

factory = PluginFactory()
device_plugin = factory.get_plugin(PluginType.DEVICE, config.target_device)  # jetson|edgetpu|cpu
device_plugin.optimize_model(optimized_model)
device_plugin.convert_format(optimized_model, output_path)

- Jetson は JetsonAdapter（universal_integration.py）の ONNX→TensorRT 経路も選択可（一部 stub のため未対応箇所は明示警告し対応経路へフォールバック）。

---

4. 任意機能（オプトイン）

機能	実体	既定
Q-PFC 自己変調推論	QPFCAdaptiveController（q_pfc_adaptive_control.py）	無効
継続学習（破滅的忘却回避）	MetaSTDP（plasticity.py）	無効
オンデバイス知識参照	SNNRAGHybrid / RAGMemoryIntegrator	無効

4.1 Q-PFC 自己変調推論

モデル出力の認知エントロピー（不確実性）に応じて推論の深さを自律調整する。実在 API:

from evospikenet.q_pfc_adaptive_control import QPFCAdaptiveController

controller = QPFCAdaptiveController(device="cpu", risk_tolerance=0.5, enable_learning=True)
ctrl = controller.forward(predictions=logits, entropy=entropy, alpha_t=alpha_t)

- 推論ランタイムで出力ロジットからエントロピーを算出し、forward() の制御出力で推論ステップ数／閾値を変調する。簡単な入力は低コスト、複雑な入力は深い推論へ。

4.2 Meta-STDP 継続学習

from evospikenet.plasticity import MetaSTDP, STDP

meta = MetaSTDP(base_stdp=STDP(...), meta_learning_rate=0.001, energy_budget=1.0)
meta.compute_weight_updates(spike_history, synapse_matrix)
meta.adapt_to_feedback(performance_feedback=..., energy_feedback=...)

- 配備後、新規ドメイン知識を追加学習しても過去知識を保持。

4.3 SNN-RAG 記憶参照

from evospikenet.snn_rag import SNNRAGHybrid
from evospikenet.rag_memory_integrator import RAGMemoryIntegrator

rag = RAGMemoryIntegrator.from_config(config.rag_yaml)
context = rag.enrich_query_context(query, entities=[...])

- LLM 内部知識をセマンティック／エピソード記憶へ分離し、外部参照可能な RAG としてコンパイル。

いずれも既定無効。config.options で明示有効化した場合のみ適用する（過剰な自動付与をしない）。

---

5. 設定スキーマ（config.py）

@dataclass
class EvoLLMConverterConfig:
    model_path: str
    distill_dataset: str
    output_dir: str
    # Stage 1
    teacher_meta: dict | None = None         # 自動抽出失敗時の手動指定
    # Stage 2（生徒モデル）
    d_model: int = 512
    n_heads: int = 8
    num_blocks: int = 6
    time_steps: int = 10
    # Stage 3（蒸留）
    distill_temperature: float = 2.0
    distill_alpha: float = 0.5               # KL と CE の加重
    max_steps: int = 10000
    # Stage 4
    optimization_yaml: str = "config/llm_optimization.yaml"
    # Stage 5
    target_device: str = "jetson"            # 'jetson' | 'edgetpu' | 'cpu'
    export_format: str = "onnx"              # 'onnx' | 'pt'
    # options
    enable_qpfc: bool = False
    enable_meta_stdp: bool = False
    enable_snn_rag: bool = False
    rag_yaml: str | None = None

YAML から EvoLLMConverterConfig.from_yaml(path) で読み込む。

---

6. 成果物（artifact.py）

@dataclass
class EvoLLMArtifact:
    optimized_model_path: str          # デバイス向け変換済 SNN-LLM
    student_config: dict               # SpikingEvoTextLM 構成
    distillation_report: dict          # perplexity, KL 収束, ステップ数
    options_manifest: dict             # 有効化した Q-PFC/MetaSTDP/SNN-RAG 設定
    metrics: dict                      # 実測: スパース率, 遅延, エネルギー, 精度劣化
    provenance: dict                   # 教師モデルハッシュ, ステージログ, ツールバージョン

provenance に教師モデルのハッシュと各ステージのログを記録し、再現可能性・監査性を担保する。

---

7. 検証と受け入れ基準（validation.py）

検証項目	方法	既定しきい値
蒸留収束	検証セット perplexity / KL の単調改善	発散 0 件
生徒前方推論	SpikingEvoTextLM.forward がコーパスで成功	例外 0 件
量子化健全性	量子化後にキャリブレーションセットで推論成功	例外 0 件
スパース率	剪定後の非ゼロ重み比率	設定 amount ±5%
精度劣化	教師 vs 生徒のタスク指標差	≤ 設定許容（既定 5%）
オプション整合	有効化機能のフック接続が成功	接続失敗 0 件

すべての必須検証を満たした場合のみ EvoLLMArtifact を「合格」とマークする。1 つでも失敗した場合は成果物を保存しつつ非合格として明示する（暗黙の成功扱いをしない）。

---

8. CLI（cli.py）

evo-llm-convert \
  --config config/evo_llm_convert.yaml \
  --model-path ./checkpoints/my_llm \
  --target-device jetson \
  --output-dir ./out/evo_llm

主要サブコマンド: - convert: フルパイプライン実行。 - validate: 既存成果物に対して validation.py の検証のみ再実行。 - inspect: 教師モデルのメタ情報（語彙・次元・層数）を出力し、teacher_meta 作成を支援。

---

9. 実装フェーズ計画

フェーズ	内容	主要成果
P1	骨組み + Stage 1/2（取り込み・生徒構成）+ CLI 雛形	SpikingEvoTextLM 生徒の生成
P2	Stage 3（知識蒸留）+ 収束検証	蒸留済 SNN-LLM
P3	Stage 4/5（最適化・デバイスエクスポート）	Jetson/EdgeTPU 出力
P4	オプション統合（Q-PFC / MetaSTDP / SNN-RAG）	自己変調・継続学習・RAG 接続
P5	E2E 検証・受け入れ基準・ドキュメント整備	合否判定付き成果物生成

---

10. リスクと対策

リスク	対策
教師トークナイザと生徒の不一致	Stage 1 で整合検証し、不一致は明示エラー（推測で続行しない）。
INT16 等の非実在機能への依存	量子化は INT8 のみに限定し、設定スキーマで INT16 を受け付けない。
Jetson/EdgeTPU 変換の一部が stub	未対応経路は実行時に明示警告し、対応済経路（INT8 / ONNX）へフォールバック。
蒸留の精度劣化	受け入れ基準（精度劣化 ≤ 5%）で自動ゲート。未達時は非合格マーク。
蒸留の発散	perplexity/KL を監視し早期停止、ハイパラ調整を促す。
snntorch 不在環境	models.py / attention.py の identity フォールバックを活用し最小機能で動作継続。

---

付録 A: 参照実装マップ（実在 API）

用途	import
SNN-LLM	from evospikenet.models import SpikingEvoTextLM
因果アテンション	from evospikenet.attention import ChronoSpikeAttention
TAS	from evospikenet.encoding import TASEncoderDecoder
最適化	from evospikenet.optimization_pipeline import OptimizationPipeline
蒸留	examples/distill_ann_to_snn.py、POST /api/train/distillation（training_api.py）
Q-PFC	from evospikenet.q_pfc_adaptive_control import QPFCAdaptiveController
継続学習	from evospikenet.plasticity import MetaSTDP, STDP
RAG / 記憶	from evospikenet.snn_rag import SNNRAGHybrid; from evospikenet.rag_memory_integrator import RAGMemoryIntegrator
プラグイン	from evospikenet.plugin_factory import PluginFactory; from evospikenet.plugins import PluginType