JinDaGe - be-student-project MCP Details

article

README

🚀 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）运行组件进行开发，请按以下步骤操作：

Python 环境：建议使用虚拟环境。

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

安装依赖：

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

be-student-project