SDK デバイスプラグイン開発ガイド

[!NOTE] 最新の実装状況は 機能実装ステータス (Remaining Functionality) を参照してください。

概要

このガイドは、EvoSpikeNet の DevicePlugin を SDK 利用者/開発者が追加するための最短手順を示します。

対象: - CPU/GPU/NPU/量子ランタイムなどの新しい実行バックエンドを統合したい - 既存のモデル変換・最適化・デプロイ処理をプラグイン化したい

前提

• Python 3.10+
• EvoSpikeNet-Core の開発環境
• pip install -e . 済み

オプション依存（必要時）:

# IBM Quantum 連携を含む例
pip install -e ".[quantum]"

# Jetson / EdgeTPU / Loihi など
pip install -e ".[jetson]"
pip install -e ".[edge_tpu]"
pip install -e ".[loihi]"

実装インターフェース

DevicePlugin は次のメソッド実装が必須です。

• get_metadata()
• initialize()
• activate()
• deactivate()
• get_capabilities()
• optimize_model()
• convert_format()
• deploy_model()

参照: - evospikenet/plugins/device_plugin.py - evospikenet/plugins/builtin/device_plugins.py - evospikenet/plugins/builtin/ibm_quantum_plugin.py - evospikenet/plugins/builtin/device_backends/ibm_neurochip_plugin.py

IBM Quantum 実装で利用できる追加 API:

• check_runtime_connectivity()
• run_sampler()
• run_estimator()

IBM NeuroChip 実装で利用できる追加 API:

• run_simulator()
• run_northpole()

G-QuAT 実装で利用できる追加 API:

• run_simulator()
• run_g_quat()

テンプレートとサンプル

最小テンプレートは次にあります。

• examples/sdk/programs/device_plugin_template.py
• examples/sdk/programs/ibm_quantum_runtime_demo.py
• examples/sdk/programs/ibm_neurochip_demo.py
• examples/sdk/programs/ibm_neurochip_northpole_mock_e2e.py
• examples/sdk/programs/g_quat_mock_e2e.py
• examples/sdk/programs/vqe_neuron_layer_demo.py
• examples/sdk/programs/loihi_brain2loihi_demo.py

このサンプルで確認できる内容: - CustomDevicePlugin の最小実装 - PluginFactory への登録 - 変換・デプロイのスモーク実行

実行例:

python examples/sdk/programs/device_plugin_template.py
python examples/sdk/programs/ibm_quantum_runtime_demo.py
python examples/sdk/programs/ibm_neurochip_demo.py
python examples/sdk/programs/ibm_neurochip_northpole_mock_e2e.py
python examples/sdk/programs/g_quat_mock_e2e.py
python examples/sdk/programs/vqe_neuron_layer_demo.py
python examples/sdk/programs/loihi_brain2loihi_demo.py

NorthPole mock E2E を安定実行する推奨コマンド:

PYTHONPATH=. python examples/sdk/programs/ibm_neurochip_northpole_mock_e2e.py

G-QuAT mock E2E を安定実行する推奨コマンド:

PYTHONPATH=. python examples/sdk/programs/g_quat_mock_e2e.py

同期状況の一覧は PLUGIN_DOC_SYNC_MATRIX.md を参照してください。

Loihi simulator の詳細手順は SDK_LOIHI_BRAIN2LOIHI_GUIDE.md を参照してください。

設定ファイル連携

SDK で DevicePlugin を運用する場合、次の設定ファイルを併用します。

• config/device_plugins.yaml: デバイス有効化、優先度、フォールバックチェーン
• config/settings.yaml: プラグイン設定ファイル参照と全体デフォルト

最小例:

plugins:
    device_plugins:
        config_file: "config/device_plugins.yaml"
        auto_register: true

device_plugins:
    default_device: "gpu"
    priority_list: ["gpu", "cpu", "jetson", "loihi", "edgetpu", "ibm_quantum", "ibm_neurochip"]

IBM Runtime を使う場合の任意環境変数:

export QISKIT_IBM_TOKEN=your_token
export QISKIT_IBM_CHANNEL=ibm_quantum
export QISKIT_IBM_INSTANCE=your_hub_group_project
export QISKIT_IBM_BACKEND=ibmq_qasm_simulator

IBM NeuroChip を NorthPole プロファイルで利用する例:

plugin = IBMNeuroChipPlugin(
    config={
        "target_chip": "northpole",
        "runtime_candidates": ["ibm_northpole", "northpole", "northpole_sdk"],
        "enable_simulator": True,
    }
)
plugin.initialize()
spikes_out = plugin.run_northpole(spikes, steps=2)

G-QuAT runtime を利用する例:

plugin = GQuATPlugin(
    config={
        "runtime_candidates": ["g_quat", "gquat", "aist_g_quat"],
        "runtime_api_preference": ["run_g_quat", "execute", "run"],
        "enable_simulator": True,
    }
)
plugin.initialize()
spikes_out = plugin.run_g_quat(spikes, steps=2)

NorthPole runtime 連携時の API 契約:

• 実行アダプタ実装: evospikenet/plugins/builtin/device_backends/northpole_runtime_adapter.py

• ランタイム候補モジュールは以下のいずれかを提供します。

  • モジュール関数: run_northpole(spikes, steps=...) / run(spikes, steps=...) / execute(spikes, steps=...)
  • クラス: NorthPoleRuntime / Runtime / NorthPoleClient / Client
  • ビルダー関数: build_runtime(config=...)
• 戻り値は torch.Tensor または dict (spikes / output / result / data) を想定します。

get_capabilities() で確認できる NorthPole 実行状態:

• runtime_bound: 実行可能ランタイム API にバインド済みか
• runtime_api: 実際に選択された API 名 (run_northpole / run / execute)
• runtime_error: 構造化エラー情報（code / phase / message / detail）
• runtime_error_message: 互換用途の短縮エラーメッセージ

実運用向けの追加設定キー:

• runtime_api_preference: 実行 API の優先順位（例: ["execute", "run_northpole"]）
• runtime_class_candidates: インスタンス化対象クラス名の優先順位
• runtime_output_key_preference: dict 戻り値から出力テンソルを抽出するキー優先順位
• runtime_init_kwargs: ランタイムクラス初期化時に渡す引数
• runtime_build_kwargs: build_runtime(...) 呼び出し時に渡す追加引数
• runtime_call_kwargs: 実行 API 呼び出し時に渡す追加引数

例:

plugin = IBMNeuroChipPlugin(
    config={
        "target_chip": "northpole",
        "runtime_candidates": ["ibm_northpole"],
        "runtime_api_preference": ["execute", "run_northpole"],
        "runtime_init_kwargs": {"device_id": 0},
        "runtime_call_kwargs": {"steps": 8, "batch_mode": True},
        "enable_simulator": True,
    }
)

PluginFactory への登録

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

factory = PluginFactory()
plugin = CustomDevicePlugin(config={"target": "cpu", "precision": "fp32"})
plugin.initialize()
plugin.activate()
factory.register_plugin(plugin)

resolved = factory.get_plugin(PluginType.DEVICE, "custom_device")

推奨構成

• config_schema で入力型を明示する
• get_capabilities() で実行可能機能を返す
• 依存がない環境ではフォールバック経路を用意する
• convert_format() は拡張子を強制して出力形式を固定する
• Runtime 系プラグインでは Sampler/Estimator の戻り値を標準化する
• 実回路経路とローカル fallback 経路の両方をテストする

テスト指針

最低限のユニットテスト例: - メタデータと PluginType.DEVICE の一致 - initialize/activate/deactivate のライフサイクル - get_capabilities() のキー整合 - 依存非導入時のフォールバック動作

既存テスト参照: - tests/unit/test_ibm_quantum_plugin.py - tests/unit/test_ibm_neurochip_plugin.py - tests/unit/test_plugins.py - tests/unit/test_plugin_phase_roadmap.py

CI 補足

• optional dependency matrix では ibm_quantum_runtime プロファイルで mock/import 契約を検証します。
• optional dependency matrix の northpole_mock プロファイルでは、NorthPole adapter の単体/統合テストに加えて ibm_neurochip_northpole_mock_e2e.py を実行します。
• optional dependency matrix の g_quat_mock プロファイルでは、test_g_quat_plugin.py と g_quat_mock_e2e.py を実行します。
• QISKIT_IBM_TOKEN が設定された CI では live connectivity ジョブで実接続確認を行います。