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 服务器文档。