EvoSpikeNet Build & Service Matrix

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

ビルド対象ごとに起動するサービスとボリューム、主な利用方法をまとめました。docker compose は v2 を想定しています。

主要コンポーズファイル

用途	ファイル	主な対象	典型コマンド例
コア開発・デモ	docker-compose.yml	API/Frontend/DB/RAG(任意)	`docker compose up -d api frontend`
Jupyter/開発ツール	docker-compose.yml	notebook/mkdocs/dev	`docker compose up -d notebook`
RAG 最小構成	docker-compose.yml (profile rag)	rag-api/milvus/elasticsearch	`docker compose --profile rag up -d rag-api`
大規模学習 (GPU/CPU)	docker-compose.train.yml	llm-trainer-gpu / llm-trainer-cpu	`docker compose -f docker-compose.train.yml up -d llm-trainer-gpu`
マイクロサービス分割	docker-compose.microservices.yml	gateway/training/inference 等	`docker compose -f docker-compose.microservices.yml up -d gateway`
GPU リソース付与オーバーレイ	docker-compose.gpu.yml	既存サービスへ GPU 割当	`docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d api`
GPU 単独トレーナー	docker-compose.gpu-only.yml	llm-trainer-gpu (単体)	`docker compose -f docker-compose.gpu-only.yml up -d llm-trainer-gpu`
CPU 単独トレーナー	docker-compose.cpu-only.yml	llm-trainer-cpu (単体)	`docker compose -f docker-compose.cpu-only.yml up -d llm-trainer-cpu`
分散ノード実験	docker-compose.distributed.yml	brain-node-1..3 + zenoh-router + model-server(任意)	`docker compose -f docker-compose.distributed.yml up -d`

コア開発スタック（docker-compose.yml）

api: FastAPI サーバ (8000)。依存: postgres, zenoh-router。ボリューム: saved_models, shared_tmp。
frontend: Dash UI (8050/8051)。依存: api, milvus-standalone, elasticsearch, postgres。ボリューム: saved_models, shared_tmp。
dev: 開発用 Dash 実行 (8052→8050, 8080, 8765)。コードホットリロード用途。
notebook: Jupyter Lab (8888)。API/RAG へ接続。ボリューム: saved_models, shared_tmp。
mkdocs: ドキュメントサーバ (8001)。profile full。
rag-api: RAG 用 API (外部 8101 / 内部 8001)。profile rag。ボリューム: rag-system/data。
zenoh-router: 分散ノード用ルーター (7447/tcp+udp, 7446/udp)。
milvus-standalone: ベクタDB (19530, 9091)。依存: etcd, minio。ボリューム: milvus_data。
elasticsearch: ログ/検索用 (9200, 9300)。
postgres: メイン DB (5432)。ボリューム: postgres_data。
etcd/minio: Milvus の依存。

主要ボリューム

milvus_data, milvus_etcd, milvus_minio: RAG/Milvus 永続化。
saved_models: モデル成果物共有 (api/frontend/notebook)。
postgres_data: DB 永続化。
shared_tmp: 一時領域共有。
rag-system/data: RAG データ（rag-api サービスでマウント）。

代表的な起動例

# API + Frontend（開発デフォルト）
docker compose up -d api frontend

# RAG セット（profiling）
docker compose --profile rag up -d rag-api milvus-standalone elasticsearch

# ノートブックのみ
docker compose up -d notebook

大規模学習スタック（docker-compose.train.yml）

llm-trainer-gpu: GPU トレーナー (8000)。ボリューム: ./data, ./saved_models, ./logs, ./config。NVIDIA ランタイム必須。
llm-trainer-cpu: CPU トレーナー (8001→内側 8000)。ボリューム: 同上。
nginx (任意): 8080 で GPU/CPU をリバースプロキシ。

起動例

# GPU トレーナー
docker compose -f docker-compose.train.yml up -d llm-trainer-gpu

# CPU トレーナー
docker compose -f docker-compose.train.yml up -d llm-trainer-cpu

# プロキシ併用
docker compose -f docker-compose.train.yml up -d nginx

GPU/CPU 単独トレーナー（シンプル構成）

docker-compose.gpu-only.yml: llm-trainer-gpu を単体で起動（8000）。環境: CUDA_VISIBLE_DEVICES、TORCH_USE_CUDA_DSA、DEVICE_TYPE=gpu。
docker-compose.cpu-only.yml: llm-trainer-cpu を単体で起動（8001→内側 8000）。環境: OMP_NUM_THREADS/MKL_NUM_THREADS、DEVICE_TYPE=cpu。

起動例

# GPU 単独
docker compose -f docker-compose.gpu-only.yml up -d llm-trainer-gpu

# CPU 単独
docker compose -f docker-compose.cpu-only.yml up -d llm-trainer-cpu

GPU オーバーレイ（既存 compose へ GPU 割当）

docker-compose.gpu.yml: dev/test/prod/frontend など既存サービスに GPU リソースを付与する overlay。ベースは docker-compose.yml と組み合わせて使用。

起動例

# API + Frontend に GPU を割り当てる例
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d api frontend

分散ノード構成（docker-compose.distributed.yml）

brain-node-1..3: それぞれ 8001/8002/8003 で FastAPI を起動、Zenoh peer として接続。
zenoh-router: 分散通信のルーター (7447/tcp+udp, 7446/udp)。
model-server（任意）: 動画/音声解析向けの専用サービス（9002→8000）。Whisper依存を個別イメージで管理。

分散ASR/Whisperの環境変数

VIDEO_ANALYSIS_ASR_BACKEND: asr_fallback（既定）または whisper_real
VIDEO_ANALYSIS_WHISPER_MODEL: Whisperモデルサイズ（例: tiny, base）
VIDEO_ANALYSIS_WHISPER_DEVICE: 実行デバイス（例: cpu, cuda）
VIDEO_ANALYSIS_ASR_PREPROCESS: 前処理ON/OFF（1/0）

起動例

# 分散 3 ノード＋ルーター
docker compose -f docker-compose.distributed.yml up -d

# Whisperを有効化して分散ノードを起動
VIDEO_ANALYSIS_ASR_BACKEND=whisper_real \
VIDEO_ANALYSIS_WHISPER_MODEL=base \
docker compose -f docker-compose.distributed.yml up -d

# 専用model-serverも含めて起動
ENABLE_WHISPER=true \
VIDEO_ANALYSIS_ASR_BACKEND=whisper_real \
docker compose -f docker-compose.distributed.yml up -d model-server brain-node-1 brain-node-2 brain-node-3 zenoh-router

マイクロサービス構成（docker-compose.microservices.yml）

gateway: API ゲートウェイ (8000)。下記サービスへルーティング。
training: 学習サービス (8001)。ボリューム: ./artifacts, ./data。
inference: 推論サービス (8002)。ボリューム: ./artifacts。
model-registry: モデル管理 (8003)。ボリューム: ./model_registry。
monitoring: メトリクス集約 (8004)。
postgres: 共通 DB (5432)。ボリューム: postgres_data。
zenoh-router: 分散通信。

起動例

# 一括起動
docker compose -f docker-compose.microservices.yml up -d

# ゲートウェイのみ
docker compose -f docker-compose.microservices.yml up -d gateway

どのスタックを起動すると何ができるか

api + frontend: コアのダッシュボードと API 実行。SDK 利用、モデルトレーニング呼び出しが可能。
rag-api + milvus + elasticsearch: RAG パイプライン（埋め込み検索、ログ検索）。
notebook: 全サービスに接続した実験環境 (Jupyter)。
llm-trainer-(gpu|cpu): 大規模学習ジョブの単独実行。成果物は saved_models/logs に保存。
microservices stack: ゲートウェイ越しに学習/推論/モデル管理/モニタリングを疎結合で運用。

RAG システムの起動手順（rag-system ディレクトリ連携）

サービス: rag-api（外部 8101 / 内部 8001）、依存: milvus-standalone, elasticsearch。データ: ./rag-system/data を /home/appuser/app/rag-system/data にマウント。
環境変数: EVOSPIKENET_API_KEY / EVOSPIKENET_API_KEYS、MILVUS_HOST=milvus-standalone、ELASTICSEARCH_HOST=elasticsearch。
実行場所: リポジトリルートで docker compose を実行（rag-system へ移動不要）。

起動例

# RAG 依存セット（Milvus/Elasticsearch を含む）
docker compose --profile rag up -d rag-api milvus-standalone elasticsearch

# RAG API のログ確認
docker compose --profile rag logs -f rag-api

# 停止
docker compose --profile rag down

RAG データの場所

永続データ: rag-system/data（ホスト）。ベクタ索引用データやインデックスを保持。
Milvus/Elasticsearch の永続ボリューム: milvus_data, milvus_etcd, milvus_minio（Milvus）、Elasticsearch はコンテナローカル。

distributed_brain 用 LLM 学習ラッパ（フル 30 ランク）

スクリプト: scripts/run_distributed_brain_llm.sh
- 役割: (1) データ収集（RUN_DATA_COLLECTION=1 既定）、(2) train_llm_models.py をランク別に直列実行。
- 主要環境変数: CONFIG(既定: config/training_config.yaml)、CATEGORY(例: full_brain_llm / text_generation)、RANKS(スペース区切りのランクリスト)、GPU(1 で --gpu を付与, 0 で CPU 実行)、RUN_DATA_COLLECTION(0 で収集スキップ)。
実行手順（フル 30 ランク, data collection あり）

export CONFIG=config/training_config.yaml
export CATEGORY=full_brain_llm
export RANKS="0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29"
export GPU=1                 # CPU で走らせる場合は 0
export RUN_DATA_COLLECTION=1 # データ収集を飛ばす場合は 0

./scripts/run_distributed_brain_llm.sh

メモ: - RANKS はスペース区切り必須（カンマ区切り不可）。 - 30 ランクは計算資源を多く消費します。GPU/CPU とストレージの空きに注意してください。

実行前の Python 環境セットアップ (PEP 668 回避)

Homebrew 系のシステム Python では pip install がブロックされるため、仮想環境で実行してください。推奨は Python 3.10/3.11。

# プロジェクトルートで実行
python3 -m venv .venv         # 既存ならスキップ
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
# データ収集も行う場合
python -m pip install -r scripts/requirements-llm-data.txt

# その後にラッパを実行
./scripts/run_distributed_brain_llm.sh

メモ: - --break-system-packages は非推奨。必ず仮想環境で。 - 既存の venv311/ 等がある場合は source venv311/bin/activate でも可。

依存パッケージのバージョン制約 (Ray など)

Ray 2.31.0 など一部パッケージは Python 3.13+ をサポートしません。Python 3.10/3.11 (または 3.12) を使用してください。
macOS Homebrew の python@3.14 では ray==2.31.0 が解決できず、pip が "No matching distribution" を返します。仮想環境を 3.10/3.11 ベースで作り直してください。
pip が Invalid requirement: '#' を出す場合は、pip install -r requirements.txt を実行していることを確認し、pip を最新化してください（python -m pip install --upgrade pip）。

環境変数のポイント

API_URL / RAG_API_URL / EEG_WS_URL: フロントエンドやノートブックからの接続先を指定。
EVOSPIKENET_API_KEY / EVOSPIKENET_API_KEYS: API 認証用キー。
ENABLE_GPU: true にすると GPU 専用パッケージ（bitsandbytes 等）が追加インストールされる。デフォルト false。
BASE_IMAGE: ベースイメージを切り替える。未指定時のデフォルトは ubuntu:22.04（CUDA なし）。

BASE_IMAGE の使い分け

用途	BASE_IMAGE	ENABLE_GPU
CPU ビルド（デフォルト）	`ubuntu:22.04`	`false`
GPU ビルド（CUDA 12.4）	`nvidia/cuda:12.4.1-base-ubuntu22.04`	`true`
GPU ビルド（CUDA 12.1）	`nvidia/cuda:12.1.1-base-ubuntu22.04`	`true`

# CPU ビルド（デフォルト、CUDAなし）
docker build .

# GPU ビルド（CUDAイメージ + bitsandbytes等）
docker build . \
  --build-arg BASE_IMAGE=nvidia/cuda:12.4.1-base-ubuntu22.04 \
  --build-arg ENABLE_GPU=true

注意: docker-compose.yml の base / notebook サービスはデフォルトで nvidia/cuda:12.4.1-base-ubuntu22.04 を使用します。test サービスは ubuntu:22.04 固定です。CPU 環境で docker compose up を使う場合は BASE_IMAGE=ubuntu:22.04 ENABLE_GPU=false docker compose up のように環境変数で上書きしてください。

BuildKit キャッシュについて

Dockerfile は --mount=type=cache を使用した BuildKit キャッシュに対応しています。 2 回目以降のビルドで pip パッケージ（PyTorch 含む）の再ダウンロードが不要になります。

Docker 23.0 未満の場合は BuildKit を明示的に有効化してください：

export DOCKER_BUILDKIT=1
docker build .