基于 LangGraph ReAct Agent 的工业设备智能诊断平台。系统通过 SSE 流式交互，将大语言模型与数据库查询、SHAP 可解释性分析、知识库检索、可视化图表生成等工具深度集成，实现从数据采集到诊断报告的端到端自动化。
核心能力：
- 故障诊断：子 Agent 自动完成 数据查询 → ML API 推理 → SHAP 分析 → 可视化图表 → 诊断报告 全流程
- 数据可视化：通过 Python 代码执行生成 matplotlib/seaborn 图表，前端实时渲染
- 双格式报告：Markdown 技术报告 + HTML 交互式报告（ECharts 图表 + KPI 卡片）
- 知识库增强：FAISS 向量检索设备手册和故障码，配合网络搜索补充最新标准
- 对话持久化：PostgreSQL 存储完整对话状态，支持多轮上下文和历史回溯
- 身份适配：根据用户身份（游客/管理员）动态调整响应的专业程度
┌─────────────────┐ SSE/REST ┌──────────────────────────────────────┐
│ Vue 3 Frontend │ ◄───────────────► │ FastAPI (app.py) │
│ :9005 │ │ :8000 │
└─────────────────┘ │ │
│ ┌─────────────────────────────────┐ │
│ │ LangGraph ReAct Agent │ │
│ │ │ │
│ │ Middleware Pipeline: │ │
│ │ TodoList → DynamicPrompt → │ │
│ │ Summarization │ │
│ │ │ │
│ │ Tools (9个): │ │
│ │ ┌─────────┐ ┌──────────┐ │ │
│ │ │ SQL查询 │ │ 数据提取 │ │ │
│ │ │ 知识库 │ │ 图表生成 │ │ │
│ │ │ 报告生成 │ │ 网络搜索 │ │ │
│ │ │ 时间工具 │ │ 子Agent │ │ │
│ │ └─────────┘ └──────────┘ │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │MySQL │ │PgSQL │ │FAISS │ │
│ │业务数据│ │会话状态│ │知识库 │ │
│ └──────┘ └──────┘ └──────┘ │
└──────────────────────────────────────┘
SSE 事件流：start → token(逐字输出) → tool_start/tool_end(工具调用) → complete
.
├── app.py # FastAPI 入口：lifespan、路由、CORS、静态文件（256行）
├── streaming.py # SSE 流式事件生成器
├── config.py # 集中配置（环境变量 + 默认值）
├── utils.py # 通用工具函数（JSON 序列化、todo 解析）
├── middleware.py # 中间件组装（TodoList + DynamicPrompt + Summarization）
├── knowledge_base.py # FAISS 知识库（创建/加载/检索）
├── html_template.html # HTML 报告模板（ECharts + KPI 卡片）
│
├── tools/ # 工具模块（可替换）
│ ├── __init__.py # 导出 tools 列表（9个工具）
│ ├── data_tools.py # extract_data + fig_inter（数据提取与可视化）
│ ├── sql_tools.py # sql_inter + DCMA toolkit（SQL 查询）
│ ├── kb_tools.py # query_knowledge_base（知识库检索）
│ ├── report_tools.py # save_report + save_html_report（报告生成）
│ ├── utility_tools.py # get_time + search_tool（通用工具）
│ └── subagent/ # 故障解释子 Agent
│ ├── agent.py # 子 Agent 工厂（独立 LangGraph 实例）
│ ├── system_prompt.py# SHAP 分析专用提示词
│ └── api_tool.py # ML API 调用 + 子 Agent 图表生成
│
├── prompts/ # 提示词模块（可替换）
│ ├── system_prompt.py # 系统提示词（诊断流程、工具使用规范）
│ └── dynamic_prompt.py # Context + @dynamic_prompt（身份感知）
│
├── tests/ # 测试套件（76个特征测试）
├── agent_fronted/ # 前端 Vue 3 项目
│ ├── public/
│ │ ├── images/ # 运行时生成的图表（fig_inter 输出）
│ │ └── reports/ # 运行时生成的报告（save_report 输出）
│ └── src/
├── pdfs/ # 知识库 PDF 源文档
└── faiss_db/ # FAISS 向量索引（运行时生成）
模块职责划分：
| 可替换模块 | 说明 |
|---|---|
tools/ |
领域工具——替换为你的数据查询、API 调用、可视化逻辑 |
prompts/ |
系统提示词——替换为你的工作流程和角色设定 |
config.py |
配置常量——修改数据库名、API 地址、Agent 参数 |
middleware.py |
中间件组合——调整摘要策略、上下文管理 |
| 核心模块（通常不改） | 说明 |
|---|---|
app.py |
FastAPI 路由、lifespan、Agent 创建 |
streaming.py |
SSE token 级流式输出 |
utils.py |
JSON 序列化、todo 解析等通用函数 |
| 层级 | 技术 | 版本 |
|---|---|---|
| Web 框架 | FastAPI + Uvicorn | 0.121.0 / 0.38.0 |
| AI 框架 | LangChain + LangGraph | 1.0.3 / 1.0.5 |
| LLM | OpenAI 兼容 API（ModelScope / 智谱等） | — |
| 向量嵌入 | Ollama (qwen3-embedding:8b) | — |
| 向量检索 | FAISS | — |
| 业务数据库 | MySQL + PyMySQL + SQLAlchemy | — |
| 状态持久化 | PostgreSQL + psycopg | — |
| 可视化 | Matplotlib + Seaborn | — |
| 前端 | Vue 3 + TypeScript + Vite + Element Plus | 3.5 / 7.1 |
| 报告 | ECharts (HTML) + Markdown | — |
- Python 3.12+
- Node.js 16+
- MySQL
- PostgreSQL
- （可选）Ollama 服务（知识库向量嵌入，模型
qwen3-embedding:8b）
git clone https://gitee.com/yxhn05/fault-diagnosis.git
cd fault-diagnosis
# 创建虚拟环境
python3.12 -m venv .venv
source .venv/bin/activate # Linux/macOS (bash/zsh)
# .venv/bin/python app.py # 如果 activate 不兼容你的 shell，直接用完整路径
# 安装依赖
pip install -r requirements.txt创建 .env 文件：
# LLM 模型配置（OpenAI 兼容接口）
OPENAI_API_KEY=your_api_key
OPENAI_BASE_URL=https://api-inference.modelscope.cn/v1
MODEL_NAME=ZhipuAI/GLM-5
# 搜索工具
TAVILY_API_KEY=your_tavily_key
# MySQL（业务数据）
HOST=127.0.0.1
USER=root
MYSQL_PW=your_password
DB_NAME=fault_diagnosis
PORT=3306
# PostgreSQL（对话状态持久化）
POSTGRES_HOST=127.0.0.1
POSTGRES_PORT=5432
POSTGRES_DB=fault_diagnosis
POSTGRES_USER=your_user
POSTGRES_PASSWORD=your_password# PostgreSQL
psql -U your_user -d postgres -c "CREATE DATABASE fault_diagnosis;"
# MySQL
mysql -u root -p -e "CREATE DATABASE fault_diagnosis CHARACTER SET utf8mb4;"
mysql -u root -p -e "CREATE DATABASE dcma CHARACTER SET utf8mb4;"PostgreSQL 的表结构会在首次启动时由
checkpointer.setup()自动创建。
# 后端（终端 1）
.venv/bin/python app.py
# 🚀 服务启动在 http://localhost:8000
# 前端（终端 2）
cd agent_fronted
npm install
npm run dev
# 前端启动在 http://localhost:9005打开浏览器访问 http://localhost:9005。
将设备手册 PDF 放入 pdfs/ 目录，运行：
.venv/bin/python rebuild_kb.py需要 Ollama 服务运行中（默认 http://10.108.13.254:11434，可在 config.py 修改）。
用户：对 J3 机械臂进行故障诊断
系统自动执行：
1. get_time → 获取时间戳
2. write_todos → 规划诊断任务
3. fault_explanation_tool → 子 Agent 完成：
- 查询传感器数据（36通道 × 512条）
- 调用 ML 故障预测 API
- SHAP 可解释性分析
- 生成 2 张分析图表（重要性条形图 + 时序热力图）
4. query_knowledge_base → 查询故障码含义
5. save_report → 生成 Markdown 诊断报告
用户：了解 DCMA 的运行状态
系统自动执行：
1. sql_db_query → 查询 DCMA 数据库
2. save_html_report → 生成 HTML 报告（KPI 卡片 + ECharts 图表）
用户：展示 J3 轴电流数据趋势
系统自动执行：
1. sql_inter → 预览数据
2. extract_data → 导入 DataFrame
3. fig_inter → 生成 matplotlib 图表
| 端点 | 方法 | 说明 |
|---|---|---|
/chat/stream |
GET | SSE 流式聊天（message, thread_id, user_identity） |
/ai/history/{type} |
GET | 获取对话列表 |
/ai/history/{type}/{chat_id} |
GET | 获取对话消息历史 |
/api/todos/{thread_id} |
GET | 获取任务清单 |
/images/* |
Static | 生成的图表文件 |
/reports/* |
Static | 生成的报告文件 |
# 构建前端
cd agent_fronted && npm run build
# 启动后端（4 worker）
gunicorn -w 4 -k uvicorn.workers.UvicornWorker app:app --bind 0.0.0.0:8000Fork 本项目后，替换以下 4 个模块即可搭建你自己领域的 Agent 服务：
# tools/your_tool.py
from pydantic import BaseModel, Field
from langchain_core.tools import tool
class MyToolInput(BaseModel):
query: str = Field(description="查询内容")
@tool(args_schema=MyToolInput)
def my_tool(query: str) -> str:
"""工具描述（中文，作为 LLM 的工具说明）"""
return "结果"在 tools/__init__.py 中注册：
from .your_tool import my_tool
tools = [my_tool, ...]修改 prompts/system_prompt.py 中的 systemprompt 字符串，定义你的角色和工作流程。
调整数据库名、API 地址、Agent 参数等。
根据需要启用/禁用 TodoList、Summarization 等中间件。
核心部分（app.py、streaming.py、utils.py）通常不需要修改。
- 前端重构：Vue 3 前端代码整理，组件化、状态管理优化
- 多模型支持：前端可切换不同 LLM 模型，对比诊断效果
- Docker 部署：提供 docker-compose 一键启动（后端 + MySQL + PostgreSQL + Ollama）
- 多设备支持：扩展传感器数据模型，支持不同类型工业设备接入
- 实时监控：WebSocket 推送设备实时状态，异常自动触发诊断
- 报告模板系统：可视化配置报告布局，支持自定义 KPI 和图表类型
- 权限管理：完善用户角色体系，支持团队协作和审批流程
- 多 Agent 协作：设备诊断 Agent、维护调度 Agent、备件管理 Agent 协同工作
- 预测性维护：基于历史数据训练故障预测模型，从被动诊断转向主动预防
- 知识图谱：构建设备-故障-维修知识图谱，提升诊断的关联推理能力
- 移动端：提供移动端 App，支持现场诊断和离线报告查看