コンテンツにスキップ

EvoSpikeNet SDK & Frontend API Key Configuration

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

実装ノート（アーティファクト）: トレーニングスクリプトが出力する artifact_manifest.json と推奨CLIフラグについては docs/implementation/ARTIFACT_MANIFESTS.md を参照してください。

このドキュメントでは、EvoSpikeNet の SDK とフロントエンドが API にアクセスする際の API キー設定方法を詳細に説明します。

環境変数 (推奨)

  • EVOSPIKENET_API_KEY — 単一の API キーを設定します。バックエンドや SDK 実行プロセスにこの環境変数を設定すると、SDK の認証ヘッダー X-API-Key が自動的に使用されます。
  • EVOSPIKENET_API_KEYS — カンマ区切りで複数のキーを設定できます。SDK はこの変数の先頭キーをデフォルトとして使用します。

Linux / macOS の例:

export EVOSPIKENET_API_KEY=dev-key-1
# または
export EVOSPIKENET_API_KEYS=dev-key-1,dev-key-2

Docker Compose の場合、docker-compose.yml に環境変数を追加してください。

分散脳 + ASR/Whisper 構成（2026-04-20 追記）

分散ノード環境では、SDK側のメソッド追加は不要で、サーバー側環境変数でASR経路を制御します。

  • VIDEO_ANALYSIS_ASR_BACKEND=asr_fallback|whisper_real
  • VIDEO_ANALYSIS_WHISPER_MODEL=tiny|base|small|...
  • VIDEO_ANALYSIS_WHISPER_DEVICE=cpu|cuda
  • VIDEO_ANALYSIS_ASR_PREPROCESS=1|0

docker-compose.distributed.yml を使う場合の例:

VIDEO_ANALYSIS_ASR_BACKEND=whisper_real \
VIDEO_ANALYSIS_WHISPER_MODEL=base \
docker compose -f docker-compose.distributed.yml up -d

SDKクライアントは従来どおり EvoSpikeNetAPIClient(base_url=...) を利用し、 接続先ノード（例: http://localhost:8001）を切り替えて実行します。

SDK (Python) での利用例

evospikenet.sdk.EvoSpikeNetAPIClient を直接使う場合、コンストラクタで api_key を与えることができます（推奨）。

<!-- from evospikenet.sdk import EvoSpikeNetAPIClient -->

client = EvoSpikeNetAPIClient(base_url='http://api:8000', api_key='dev-key-1')
# または環境変数を使う場合、コンストラクタに api_key を渡さなくても OK
client = EvoSpikeNetAPIClient(base_url='http://api:8000')

SDK のマルチパートアップロードやファイル操作は SDK 内で X-API-Key をヘッダーに付与します。

フロントエンド (Dash) のサーバー側 API 呼び出し

このリポジトリのフロントエンドには、サーバー側で API を呼ぶための共通ヘルパー frontend/pages/api_client.py を追加しました。

  • 起動時に EVOSPIKENET_API_KEY / EVOSPIKENET_API_KEYS からキーを読み取ります。
  • ランタイムで API キーを変更するために set_api_key(key) を呼び出すと、サーバープロセス内のセッションヘッダーが更新されます。

フロントエンド UI から API キーを適用するには: 1. フロントエンドの Settings ページに Runtime API Key 欄を追加しました。 2. キーを入力して Apply API Key を押すと、Dash サーバー内で api_client.set_api_key() が呼ばれ、以降のサーバー側 API 呼び出しは新しい X-API-Key を使います。 3. 同時に config/settings.json に security.api_key として保存されます（開発用途の利便性のため）。

注意: この保存はプレーンテキストで行われます。運用環境ではキー管理（Vault など）を検討してください。

フロントエンドのブラウザ側 API 呼び出し

  • 本リポジトリの Dash フロントエンドはサーバーサイドで API 呼び出しを行う設計です。ブラウザから直接 API を叩く場合は、ブラウザ側JavaScriptから X-API-Key を送信する必要があります。これを実装する予定であれば、CORS とブラウザ安全性を設計してください。

ローカルでの手順サンプル

  1. 環境変数を設定して Docker を起動:
export EVOSPIKENET_API_KEY=dev-key-1
docker compose up --build
  1. または、アプリ起動後に Dash の Settings ページで API キーを入力して Apply API Key を押す。

トラブルシューティング

  • API が 401 Missing API key を返す場合:
  • サーバー側（バックエンド）とフロントエンド（Dash サーバー）の両方で X-API-Key が設定されているか確認してください。

  • docker-compose.yml に EVOSPIKENET_API_KEYS を設定し、API コンテナを再起動してください。

  • フロントエンドの一覧が空のままの場合:

  • Dash サーバー側のログを確認し、API 呼び出し時に X-API-Key ヘッダーが付与されているか確認します。

参考: 既存の変更点

  • frontend/pages/api_client.py に get/post/download/delete/set_api_key/get_api_key を実装しました。
  • フロントエンドの複数ページは api_client を使うように更新済みです。
  • frontend/pages/settings.py にてランタイムAPIキーの入力欄と適用ボタンを追加しました。

AEG-Comm通信最適化設定 ⭐ NEW (2026-01-23)

AEG-Commは分散脳シミュレーションにおける通信を最適化する機能です。SDKを通じて設定を行うことができます。

環境変数設定

# AEG-Comm有効化
export EVOSPIKENET_AEG_COMM_ENABLED=true

# エネルギー閾値設定
export EVOSPIKENET_AEG_ENERGY_THRESHOLD=10.0

# 重要モダリティ設定（カンマ区切り）
export EVOSPIKENET_AEG_CRITICAL_MODALITIES=force,safety,text

# 強制変更閾値
export EVOSPIKENET_AEG_FORCE_CHANGE_THRESHOLD=10.0

SDKでの設定例

<!-- TODO: update or remove - import faileNetAPIClient -->

client = EvoSpikeNetAPIClient()

# AEG-Comm設定
config_result = client.set_aeg_comm_config(
    node_id="brain_node_1",
    enable_comm=True,
    energy_threshold=10.0,
    critical_modalities=["force", "safety", "text"],
    force_change_threshold=10.0
)

# 通信統計取得
stats = client.get_communication_stats(node_id="brain_node_1")
print(f"通信削減率: {stats['reduction_rate']}%")

分散脳シミュレーション設定

分散脳シミュレーション実行時にAEG-Commを有効化するには、設定ファイルに以下を追加：

# config/settings.yaml
distributed_brain:
  enable_aeg_comm: true
  aeg_config:
    energy_threshold: 10.0
    critical_modalities: ["force", "safety"]
    force_change_threshold: 10.0

このドキュメントを README に追記したり、運用手順書に統合することを推奨します。