Be Student Project

🚀 Insight Stack

統一された軽量スタックで、以下の機能を提供します。

• MCPゲートウェイ (FastAPI)：データベースをバックエンドに持つツールと、プロセス内のローカルLLM (llama-cpp-python を介した llama.cpp) を公開します。
• Insightバックエンド (FastAPI)：異常スコアリング (LSTM - AE) を提供し、MCPツールを介してオペレーター向けの説明を行います。
• MySQL：センサースキーマ用 (読み取り専用のLLMユーザープロビジョニング付き)。
• OPC UAシミュレーター (オプション)：ストリーミング値を生成します。

📐 システムアーキテクチャ

graph TD
    Sim["Simulator<br/>(OPC UA)"] -->|Stream Data| Backend[Insight Backend]
    Backend -->|Store Metrics| DB[(MySQL)]
    Backend -->|Request Context| MCP[MCP Server]
    MCP -->|Query| DB
    MCP -->|Inference| LLM["LLM<br/>(llama.cpp)"]
    HMI[WebIQ HMI] -->|Visualize| Backend
    HMI -->|Ask Questions| MCP

📦 モジュール

このリポジトリは以下のモジュールに整理されており、それぞれ独自のドキュメントがあります。

• Insight Backend：異常検出と説明のための主要なバックエンドサービス。
• MCP Server：LLMとシステムデータを橋渡しするModel Context Protocolサーバー。
• Simulator：データ生成用のOPC UA生産機械シミュレーター。
• WebIQ LLM MCP：WebIQ HMI用の統合コンポーネント。
• Shared：共有の設定とリソース。

📚 リファレンスとガイド

• Configuration：環境変数と設定。
• Troubleshooting：一般的な問題の解決策。
• API Reference：Insight BackendのAPIドキュメント。
• GPU Prerequisites：GPUアクセラレーションの要件。
• ML Training & Dataset Generation：履歴データの生成とトレーニングの手順。

🚀 クイックスタート

1. 前提条件の確認

DockerとDocker Composeがインストールされていることを確認してください。

Windowsユーザー：.ps1 スクリプトが実行できない場合は、実行ポリシーを設定する必要があるかもしれません。PowerShellで以下のコマンドを実行してください。

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

設定： サンプルの環境ファイルをコピーします。

cp .env.example .env

GPUサポートを有効にするには、GPU Prerequisites ガイドを参照してください。

2. データとモデルのブートストラップ

オプションA：スマートスクリプト (推奨) 自動的にデータを生成し、モデルをトレーニングし (利用可能な場合はGPUを検出)、孤立したコンテナの警告を回避します。 Linux/Mac/Git Bash:

./bootstrap.sh

Windows PowerShell:

./bootstrap.ps1

オプションB：手動のDocker Compose フラグを明示的に定義したい場合は手動で実行します。

docker compose -f compose.bootstrap.yml up --build

GPUトレーニングの場合:

docker compose -f compose.bootstrap.yml -f compose.bootstrap.gpu.yml up --build

3. スタックの起動

オプションA：スマートスクリプト (推奨) 自動的にGPUを検出し、シミュレーターを含みます。 Linux/Mac:

./start.sh

Windows:

./start.ps1

オプションB：手動のDocker Compose

docker compose -f compose.yml -f compose.sim.yml up -d --build

GPU推論サポートの場合:

docker compose -f compose.yml -f compose.gpu.yml -f compose.sim.yml up -d --build

💻 ローカル開発

開発用にコンポーネントをローカルで (Dockerを使用せずに) 実行するには、以下の手順を行います。

1. Python環境： 仮想環境の使用をおすすめします。

   python -m venv .venv
   # Windows:
   .venv\Scripts\activate
   # Linux/Mac:
   source .venv/bin/activate
   

2. 依存関係のインストール：

   pip install -r requirements.txt
   # またはサブモジュールの特定の要件
   pip install -r mcp-server/requirements.txt
   pip install -r insight-backend/requirements.txt
   

🛠️ 開発ツールと検証

LLMツールの使用検証

curlを使用してMCPサーバーツールを検証できます。

• ツールの一覧表示:

  curl -s -X POST http://localhost:8090/mcp \
    -H 'Content-Type: application/json' -H 'MCP-Protocol-Version: 2025-06-18' \
    -d '{"jsonrpc":"2.0","id":"list-1","method":"tools/list"}'
  

パフォーマンスプロファイル

MCPサーバーは、llama.cppの推論に統一されたパフォーマンスプロファイルシステム (cpu_only または gpu_accel) を使用します。システムは利用可能なハードウェアを自動的に検出します。

詳細な設定オプションについては、MCP Server Documentation を参照してください。