コンテンツにスキップ

環境変数運用方針 (EvoSpikeNet)

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

このドキュメントは、EvoSpikeNet リポジトリで使用する運用上重要な環境変数の意味と、各環境（CI／開発／ステージング／本番）での推奨設定を定めます。

目的: - モック/スタブの誤使用を防ぐ - データ出所（mock vs real）を明確にし、本番での欺瞞的データ混入を防止する - CI と本番で一貫した運用手順を提供する

対象の環境変数

EVOSPIKENET_ALLOW_STUBS

  • 説明: プロセス内のスタブ/モック実装（例: in-memory Zenoh スタブ、CARLA mock 等）を明示的に許可するフラグ。
  • 受け取り値: 0|1, false|true, no|yes, off|on（大文字小文字不問）
  • デフォルト: 0（無効）
  • 動作: 1 の場合、コードは依存ライブラリが存在しないときに"mock を用いて正常に起動する"ことを許容します。0 の場合は mock を許可せず、多くの統合ポイントは接続失敗で停止します。
  • 強制禁止: EVOSPIKENET_ENV/ENV が prod|production|staging のとき、EVOSPIKENET_ALLOW_STUBS=1 を検出すると起動時に例外で停止（fail-closed）。

推奨設定

  • CI（ユニットテスト）: 1（ユニットテストでスタブを使用するため）
  • 開発ローカル: 1（開発効率のため許可）
  • ステージング: 0（本番に近い検証を行うため非許可を推奨）
  • 本番: 0（必ず無効）

運用注意

  • 本番イメージ・本番デプロイ前に EVOSPIKENET_ALLOW_STUBS が 0 であることをデプロイ前チェックリストで確認してください。
  • 1 を本番で誤って有効化すると、依存サービスの不在を隠してしまい重大な運用リスクになります。

EVOSPIKENET_ALLOW_ROS_STUBS

  • 説明: ROS2 連携の mock ルートを明示的に許可するフラグ（embodied PLA のロボット I/F）。
  • 受け取り値: 0|1, false|true, no|yes, off|on
  • デフォルト: EVOSPIKENET_ENV/ENV が prod|production|staging 以外なら許可、それ以外は非許可。
  • 動作:
  • 1: mock 経路を許可（開発/CI 向け）。
  • prod|production|staging で 1 を検出した場合は例外で停止（fail-closed）。

推奨設定

  • CI（ユニットテスト）: 1
  • 開発ローカル: 1
  • ステージング: 0
  • 本番: 0

EVOSPIKENET_DATA_STRICT_REAL

  • 説明: データ起源の厳格性を強制するフラグ。1 の場合、source_type が mock のデータを受け取ったコンポーネントは例外を投げる/エラーとして扱います。
  • 受け取り値: 0|1, false|true, no|yes, off|on
  • デフォルト: 0（無効）

推奨設定

  • CI（ユニットテスト）: 0（ユニットテストはモックデータを利用するため）
  • 開発ローカル: 0（ローカル開発はモックを多用）
  • ステージング: 1（本番近似の検証を行うため推奨）
  • 本番: 1（必須。モック混入を防止）

運用注意

  • EVOSPIKENET_DATA_STRICT_REAL=1 を有効にすると、テストジョブでは失敗しうるため、CI のテストマトリクスで "mock 許可ジョブ" と "strict 実データ検証ジョブ" を分けて実行することを推奨します。

EVOSPIKENET_FAIL_ON_COMM_FALLBACK

  • 説明: 通信層で real Zenoh backend が利用できない場合の動作を制御します。
  • 受け取り値: 0|1, false|true, no|yes, off|on
  • デフォルト: 0（無効）
  • 動作:
  • 1: 通信 fallback（SDK relay / in-memory stub）を許可せず fail-closed で例外停止。
  • 0: EVOSPIKENET_ALLOW_STUBS の条件下で fallback を許可。

推奨設定

  • CI（ユニットテスト）: 0
  • 開発ローカル: 0
  • ステージング: 1
  • 本番: 1

EVOSPIKENET_ALLOW_COMPAT_FALLBACKS

  • 説明: compatibility API (/datasets, /images, /audio, /state, /training) の synthetic fallback 応答を許可します。
  • 受け取り値: 0|1, false|true, no|yes, off|on
  • デフォルト: 開発系環境では 1、production/staging 判定時は 0。
  • 動作: 0 の場合は 503 と compat_fallback_disabled を返却。

推奨設定

  • CI（ユニットテスト）: 1
  • 開発ローカル: 1
  • ステージング: 0
  • 本番: 0

EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS

  • 説明: 動画解析で transcript/narrative を生成できない場合のプレースホルダ応答を許可します。
  • 受け取り値: 0|1, false|true, no|yes, off|on
  • デフォルト: 開発系環境では 1、production/staging 判定時は 0。
  • 動作:
  • 1: transcript/narrative の synthetic 応答を返す。
  • 0: ジョブを failed として終了（fail-closed）。

推奨設定

  • CI（ユニットテスト）: 1
  • 開発ローカル: 1
  • ステージング: 0
  • 本番: 0

VIDEO_ANALYSIS_FAIL_CLOSED

  • 説明: 動画解析バックエンドのフォールバックを許可するかどうかを制御します。
  • 受け取り値: 0|1, false|true, no|yes, off|on
  • デフォルト: EVOSPIKENET_PROFILE/EVOSPIKENET_ENV/ENV が prod|production|release|staging|stage の場合は 1（strict）、それ以外は 0。
  • 動作:
  • 1: real backend が利用できない場合は例外で停止（fail-closed）。
  • 0: real backend 不在時に stub/fallback へ退避。

運用注意

  • real backend を使う場合は依存とモデル配置を事前に検証してください。
  • /diagnostics の診断エンドポイントでフォールバック使用状況を確認できます（video analysis サーバー）。

EVOSPIKENET_ALLOW_DUMMY_SERVICES

  • 説明: import 失敗時に有効化される dummy service 代替実装を許可します。
  • 受け取り値: 0|1, false|true, no|yes, off|on
  • デフォルト: 開発系環境では 1、production/staging 判定時は 0。
  • 動作: 0 の場合、dummy 実装は synthetic 応答を返さず例外を送出します。

推奨設定

  • CI（ユニットテスト）: 1
  • 開発ローカル: 1
  • ステージング: 0
  • 本番: 0

RAG_V2_NER_BACKEND / RAG_V2_NER_MODEL

  • 説明: RAG v2 前処理で使用する NER バックエンドとモデル。
  • 受け取り値:
  • RAG_V2_NER_BACKEND: transformers|regex
  • RAG_V2_NER_MODEL: Transformers NER モデル名（例: tner/roberta-large-japanese-char-luw-ner）
  • デフォルト:
  • RAG_V2_NER_BACKEND=transformers
  • RAG_V2_NER_MODEL=tner/roberta-large-japanese-char-luw-ner
  • 動作:
  • 本番系（production/staging）で transformers 初期化失敗時は fail-closed。
  • 非本番では regex へフォールバック可能。

RAG_V2_PREPROCESSING_WARMUP / RAG_V2_PREPROCESSING_WARMUP_STRICT

  • 説明: RAG v2 前処理（Sudachi/NER/QueryExpander）を起動時にウォームアップし、健全性を事前検証する。
  • 受け取り値: 0|1, false|true, no|yes, off|on
  • デフォルト:
  • RAG_V2_PREPROCESSING_WARMUP=1
  • RAG_V2_PREPROCESSING_WARMUP_STRICT: 本番系は 1、非本番は 0
  • 動作:
  • strict 有効時、前処理の準備不足で起動を fail-closed。

RAG_V2_SUDACHI_VERSION / RAG_V2_SUDACHI_DICT_VERSION / RAG_V2_SUDACHI_DICT_DIST_NAMES

  • 説明: Sudachi バージョン整合性チェックの期待値と辞書配布名候補。
  • デフォルト:
  • RAG_V2_SUDACHI_VERSION=0.7.5
  • RAG_V2_SUDACHI_DICT_VERSION=20240716
  • RAG_V2_SUDACHI_DICT_DIST_NAMES=sudachidict_small,sudachipy-dict-small
  • 動作:
  • 本番系で不一致時は fail-closed。
  • 非本番は警告ログで継続。

RAG_V2_QUERY_EXPANDER_BACKEND / RAG_V2_QUERY_EXPANDER_STRICT / RAG_V2_QUERY_EXPANDER_LM_BACKEND

  • 説明: QueryExpander の実行バックエンドと厳格モード。
  • 受け取り値:
  • RAG_V2_QUERY_EXPANDER_BACKEND: rule|llm|hybrid
  • RAG_V2_QUERY_EXPANDER_STRICT: 0|1 等
  • RAG_V2_QUERY_EXPANDER_LM_BACKEND: 既定 evospikenet_lm
  • デフォルト:
  • RAG_V2_QUERY_EXPANDER_BACKEND=rule
  • RAG_V2_QUERY_EXPANDER_STRICT: 本番系は 1、非本番は 0
  • 動作:
  • llm/hybrid では JSON スキーマ（{"expansions": [...]}）を前提に解析。
  • strict 時は不正JSON/推論失敗で例外。

RAG_V2_QUERY_EXPANDER_QUALITY_GUARD / RAG_V2_QUERY_EXPANDER_MIN_DIVERSITY / RAG_V2_QUERY_EXPANDER_MAX_REDUNDANCY / RAG_V2_QUERY_EXPANDER_GUARD_HISTORY_SIZE

  • 説明: Query Expansion 品質ガードと履歴監視設定。
  • デフォルト:
  • RAG_V2_QUERY_EXPANDER_QUALITY_GUARD=1
  • RAG_V2_QUERY_EXPANDER_MIN_DIVERSITY=0.35
  • RAG_V2_QUERY_EXPANDER_MAX_REDUNDANCY=0.7
  • RAG_V2_QUERY_EXPANDER_GUARD_HISTORY_SIZE=20
  • 動作:
  • 品質しきい値未達時、llm/hybrid から rule に自動フォールバック。
  • 履歴はリングバッファ保持。query_hash と品質スナップショットを含む。
  • GET /api/v2/rag/preprocessing/health と POST /api/v2/rag/search の debug_info で監視可能。

EVOSPIKENET_PTP_DEVICE

  • 説明: EEG 時刻同期で使用する PTP ハードウェアクロックのデバイスパス（例: /dev/ptp0）。
  • 受け取り値: デバイスパス文字列
  • デフォルト: 未設定時は /dev/ptp0..3 を自動探索。

運用注意

  • デバイスが未配備の場合は NTP フォールバックに退避します。

EVOSPIKENET_PTP_NTP_SAMPLES

  • 説明: PTP フォールバック時に取得する NTP サンプル数。
  • 受け取り値: 1〜10
  • デフォルト: 3

EVOSPIKENET_MTLS_REQUIRED / EVOSPIKENET_ALLOWED_CERTS / EVOSPIKENET_ALLOWED_CERT_FINGERPRINTS

  • 説明: mTLS の必須化と許可証明書（PEM/フィンガープリント）を制御します。
  • 受け取り値:
  • EVOSPIKENET_MTLS_REQUIRED: 0|1, false|true, no|yes, off|on
  • EVOSPIKENET_ALLOWED_CERTS: PEM 文字列のカンマ区切り
  • EVOSPIKENET_ALLOWED_CERT_FINGERPRINTS: SHA256 フィンガープリントのカンマ区切り

運用注意

  • TLS 終端プロキシは以下の順序でクライアント証明書ヘッダを転送してください: X-Forwarded-Client-Cert -> X-SSL-Client-Cert -> X-Client-Cert
  • 検証結果ヘッダとして X-SSL-Client-Verify または X-Client-Verify を付与してください。

EVOSPIKENET_ALERT_SLACK_WEBHOOK_URL / EVOSPIKENET_ALERT_SMTP_* / EVOSPIKENET_ALERT_PAGERDUTY_ROUTING_KEY

  • 説明: 監視アラートの通知チャネル（Slack/SMTP/PagerDuty）を構成します。
  • 受け取り値:
  • Slack: EVOSPIKENET_ALERT_SLACK_WEBHOOK_URL
  • SMTP: EVOSPIKENET_ALERT_SMTP_HOST, EVOSPIKENET_ALERT_SMTP_USER, EVOSPIKENET_ALERT_SMTP_PASS, EVOSPIKENET_ALERT_EMAIL_TO
  • PagerDuty: EVOSPIKENET_ALERT_PAGERDUTY_ROUTING_KEY

運用注意

  • いずれも未設定の場合はログ記録のみとなります。

設定例（.env）

# 例: 本番向け
EVOSPIKENET_ALLOW_STUBS=0
EVOSPIKENET_DATA_STRICT_REAL=1
EVOSPIKENET_FAIL_ON_COMM_FALLBACK=1
EVOSPIKENET_ALLOW_COMPAT_FALLBACKS=0
EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS=0
EVOSPIKENET_ALLOW_DUMMY_SERVICES=0

# 例: CI / 開発向け
EVOSPIKENET_ALLOW_STUBS=1
EVOSPIKENET_DATA_STRICT_REAL=0
EVOSPIKENET_FAIL_ON_COMM_FALLBACK=0
EVOSPIKENET_ALLOW_COMPAT_FALLBACKS=1
EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS=1
EVOSPIKENET_ALLOW_DUMMY_SERVICES=1

Docker Compose での設定例

services:
  api:
    environment:
      - EVOSPIKENET_ALLOW_STUBS=0
      - EVOSPIKENET_DATA_STRICT_REAL=1
      - EVOSPIKENET_FAIL_ON_COMM_FALLBACK=1
      - EVOSPIKENET_ALLOW_COMPAT_FALLBACKS=0
      - EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS=0
      - EVOSPIKENET_ALLOW_DUMMY_SERVICES=0

デプロイ前チェックリスト（推奨）

  • 本番デプロイ前に以下を実行:
  • EVOSPIKENET_ALLOW_STUBS が 0 であることを確認
  • EVOSPIKENET_DATA_STRICT_REAL が 1 であることを確認
  • EVOSPIKENET_FAIL_ON_COMM_FALLBACK が 1 であることを確認
  • EVOSPIKENET_ALLOW_COMPAT_FALLBACKS が 0 であることを確認
  • EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS が 0 であることを確認
  • EVOSPIKENET_ALLOW_DUMMY_SERVICES が 0 であることを確認
  • スモークテストを実行し、外部依存（DB、API、CARLA 等）への接続が成功することを確認

関連コード（実装参照）

  • future_apps/smart_city_infrastructure/src/urban_data_api.py — EVOSPIKENET_DATA_STRICT_REAL を利用
  • future_apps/climate_change_prediction/src/climate_data_api.py — EVOSPIKENET_DATA_STRICT_REAL を利用
  • future_apps/brain_machine_interface/src/services/distributed_connector.py — EVOSPIKENET_ALLOW_STUBS を利用（in-memory stub の許可）
  • EvoSpikeNet-Core/evospikenet/communication.py — EVOSPIKENET_FAIL_ON_COMM_FALLBACK を利用
  • EvoSpikeNet-Core/evospikenet/api_modules/future_apps_compat_api.py — EVOSPIKENET_ALLOW_COMPAT_FALLBACKS を利用
  • EvoSpikeNet-Core/evospikenet/video_scene_service.py — EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS を利用
  • EvoSpikeNet-Core/evospikenet/services/__init__.py — EVOSPIKENET_ALLOW_DUMMY_SERVICES を利用

監査方法

  • リポジトリ全体で設定がどう使われているか確認する:
grep -R "EVOSPIKENET_ALLOW_STUBS\|EVOSPIKENET_DATA_STRICT_REAL\|EVOSPIKENET_FAIL_ON_COMM_FALLBACK\|EVOSPIKENET_ALLOW_COMPAT_FALLBACKS\|EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS\|EVOSPIKENET_ALLOW_DUMMY_SERVICES" -n || true

最後に: この方針はセキュリティと運用健全性を高めるための最低限のガイドラインです。組織の運用ルールや CI/CD ポリシーに合わせて調整してください。