Be Student Project

🚀 Insight Stack

Insight Stack 是一個統一的輕量級堆棧，主要用於以下方面：

• MCP 網關（基於 FastAPI）：提供基於數據庫的工具，同時在進程中集成本地大語言模型（通過 llama-cpp-python 調用 llama.cpp）。
• Insight 後端（基於 FastAPI）：提供異常評分（採用 LSTM - AE 算法），並通過 MCP 工具為操作員提供解釋。
• MySQL：用於存儲傳感器模式（為大語言模型用戶提供只讀權限）。
• OPC UA 模擬器（可選）：用於生成流式數據。

🚀 快速開始

1. 前提檢查

確保你已經安裝了 Docker 和 Docker Compose。

⚠️ 重要提示

Windows 用戶：如果你無法運行 .ps1 腳本，可能需要設置執行策略。在 PowerShell 中運行以下命令：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

配置： 複製示例環境文件：

cp .env.example .env

若要啟用 GPU 支持，請參考 GPU 前提條件 指南。

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

✨ 主要特性

• 提供統一的輕量級架構，集成了 MCP 網關、Insight 後端、MySQL 數據庫和可選的 OPC UA 模擬器。
• 利用 FastAPI 構建後端服務，實現高效的 API 接口。
• 採用 LSTM - AE 算法進行異常評分，並通過 MCP 工具為操作員提供解釋。
• 支持本地大語言模型（llama.cpp），可在進程中進行推理。
• 提供智能腳本和手動 Docker Compose 兩種方式進行數據引導、模型訓練和堆棧啟動。

📦 安裝指南

本地開發

若要在本地（不使用 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

💻 使用示例

驗證大語言模型工具使用

你可以使用 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"}'

📚 詳細文檔

系統架構

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 後端：用於異常檢測和解釋的主要後端服務。
• MCP 服務器：連接大語言模型和系統數據的模型上下文協議服務器。
• 模擬器：用於生成數據的 OPC UA 生產機器模擬器。
• WebIQ 大語言模型 MCP：WebIQ 人機界面的集成組件。
• 共享：共享配置和資源。

參考與指南

• 配置：環境變量和設置。
• 故障排除：常見問題的解決方案。
• API 參考：Insight 後端的 API 文檔。
• GPU 前提條件：GPU 加速的要求。
• 機器學習訓練與數據集生成：生成歷史數據和訓練的說明。

開發工具與驗證

性能配置文件

MCP 服務器使用統一的性能配置文件系統（cpu_only 或 gpu_accel）進行 llama.cpp 推理。系統會自動檢測可用硬件。

詳細的配置選項請參考 MCP 服務器文檔。