内容
# CPG制造AI助手演示 - 使用Google MCP工具箱和Couchbase集成
一个综合演示，展示了消费品包装（CPG）制造系统，该系统使用 **Couchbase**、**LangGraph** 和 **Google MCP工具箱** 来解决计划外的生产线停机问题，并减少平均故障恢复时间（MTTR）。
## 🌟 主要功能
该演示结合了 **MCP工具箱**、**Couchbase Vector Search** 和 **LangGraph**，提供：
- **🧰 自然语言工具访问** - MCP服务器将`tools.yaml`中的每个SQL查询转换为REST/LLM友好工具，代理可以直接用普通英文调用。
- **🎯 专用多工具代理** - 五个专用LangGraph ReAct代理（故障排除、维护、监控、性能、综合）具有基于路由器的选择；故障排除和综合代理还使用手动语义搜索工具。
- **🔍 语义手动搜索** - 向量嵌入允许操作员为特定问题检索最相关的手动代码段（仅暴露给需要它的代理）。
- **💾 弹性状态和重放** - `langgraph-checkpointer-couchbase` 在Couchbase中持久化每个代理步骤，以便对话可以恢复或稍后审计。
- **⚡ 高吞吐量** - 数据库、嵌入和工具调用之间的连接池、异步I/O和缓存保持低延迟，即使在负载下。
## 🏗️ 架构概述
```mermaid
graph TD
subgraph "API层"
API["FastAPI后端（api.py）"]
end
subgraph "代理编排（LangGraph）"
ManufacturingAgent["顶级图将查询路由到<br/>适当的专用代理进行解析."]
end
subgraph "工具层"
direction TB
Toolbox["MCP工具箱<br/>(基于SQL，通过MCP服务器)"]
ManualSearch["手动搜索工具<br/>(向量搜索)"]
end
subgraph "数据和状态持久化"
CouchbaseDB["Couchbase数据库"]
Checkpointer["AsyncCouchbaseSaver<br/>(LangGraph检查点)"]
end
%% 连接
API -- "发送操作员查询" --> ManufacturingAgent
ManufacturingAgent -- "使用工具" --> Toolbox
ManufacturingAgent -- "使用工具" --> ManualSearch
ManufacturingAgent -- "持久化状态" --> Checkpointer
Toolbox --> CouchbaseDB
ManualSearch --> CouchbaseDB
Checkpointer -- "读写状态" --> CouchbaseDB
%% 样式
classDef api fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
classDef agent fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
classDef tools fill:#fff8e1,stroke:#f57c00,stroke-width:2px
classDef data fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
class API api
class ManufacturingAgent agent
class Toolbox,ManualSearch tools
class CouchbaseDB,Checkpointer data
```
## 🚀 快速开始
### 先决条件
- Python 3.9+
- Couchbase服务器 7.0+
- Google API密钥（用于Gemini和嵌入）
- 名为`manual.pdf`的机器手册PDF文件（可选）
### 1. 安装依赖项
```bash
# 克隆仓库
git clone https://github.com/your-username/genai-rag.git
cd genai-rag
# 安装Python依赖项
pip install -r requirements.txt
```
关键依赖项包括：
- `couchbase==4.4.0` 用于数据库连接
- `langgraph==0.4.7` 用于代理编排
- `langchain-google-genai>=2.1.5` 用于Google AI集成
- `toolbox-langchain==0.2.0` 用于MCP工具箱集成
- `langgraph-checkpointer-couchbase>=1.0.6` 用于状态持久化
### 2. 配置环境
创建`.env`文件：
```bash
# Couchbase配置
COUCHBASE_CONNECTION_STRING=couchbase://localhost
COUCHBASE_USERNAME=Administrator
COUCHBASE_PASSWORD=password
COUCHBASE_BUCKET_NAME=cpg_manufacturing
# AI配置
GOOGLE_API_KEY=your_google_api_key_here
# 应用程序配置
APP_NAME=CPG制造AI助手
DEBUG=true
```
### 3. 初始化系统
```bash
# 运行系统设置
python -m setup.setup_system
```
这将：
- 设置Couchbase数据库集合和索引
- 生成现实的制造样本数据
- 处理机器手册（如果存在`manual.txt`或`manual.pdf`）
- 初始化向量嵌入以进行手动搜索
- 使用AI驱动的相似性检测和智能合并优化警报解决方案
### 4. 启动MCP工具箱
MCP工具箱公开了`tools.yaml`中定义的所有数据库工具。
#### 安装MCP工具箱二进制文件
首先，从GitHub发布页面下载并安装`genai-toolbox`二进制文件：
```bash
# 访问：https://github.com/googleapis/genai-toolbox/releases
# 下载适用于您操作系统的二进制文件并添加到PATH中
```
#### 启动服务器
```bash
# 在端口5000上启动服务器
genai-toolbox --tools-file tools.yaml --port 5000
```
服务器将读取`tools.yaml`，自动注册数据源和REST端点，并开始监听`http://localhost:5000`。
**注意：** 确保二进制文件在您的`$PATH`中，以便您可以从任何文件夹运行`genai-toolbox`。
### 5. 启动后端API
```bash
# 启动FastAPI后端
uvicorn api:app --reload
```
API将在`http://localhost:8000`上可用
### 6. 启动Web界面
```bash
# 启动Streamlit应用程序
streamlit run streamlit_app.py
```
在`http://localhost:8501`上访问应用程序
## 🛠️ 组件架构
### 数据库管理器
`DatabaseManager`类处理所有数据库连接：
```python
from src.db import DatabaseManager
# 自动初始化：
# - 同步Couchbase集群
# - 异步Couchbase集群
# - 带有AsyncCouchbaseSaver的LangGraph检查点
db_manager = DatabaseManager()
await db_manager.initialize()
```
### Couchbase手册检索器
用于机器手册的语义搜索工具：
```python
from src.tools.couchbase_manual_retriever import create_couchbase_manual_tools
# 使用以下方法为手动搜索创建LangChain工具：
# - Google Generative AI嵌入（text-embedding-004）
# - Couchbase向量搜索
# - 语义相似性匹配
manual_tool = create_couchbase_manual_tools(cluster)
```
### 增强型制造代理
基于LangGraph的代理，带有专用工具集：
```python
from src.agents.enhanced_manufacturing_agent import create_manufacturing_agent
# 使用以下方法创建具有路由器节点和专用代理节点的StateGraph工作流：
# 路由器分析查询类型并路由到适当的ReAct代理
# 每个代理都有其领域的专用工具和系统提示
agent = create_manufacturing_agent(
cluster=cluster,
checkpointer=checkpointer,
toolbox_url="http://127.0.0.1:5000"
)
```
## 🧰 MCP工具箱集成
### 可用工具集
该系统包括适用于不同制造场景的专用工具集：
| 工具集 | 代理类型 | 描述 | 用例 |
|---------|-----------|-------------|-----------|
| `troubleshooting` | 故障排除代理 | 问题诊断和解决 | 问题解决，根本原因分析 |
| `maintenance-planning` | 维护代理 | 调度和历史跟踪 | 预防性维护，计划 |
| `production-monitoring` | 监控代理 | 实时生产线状态和警报 | 仪表板概览，状态监控 |
| `performance-analysis` | 性能代理 | 效率和指标分析 | KPI监控，优化 |
| `full-manufacturing-suite` | 综合代理 | 完整工具集访问 | 综合分析 |
### 数据库工具配置
`tools.yaml`文件为以下内容定义了基于SQL的工具：
- **生产线管理**：状态，效率，产量指标
- **机器管理**：详细信息，参数，规格
- **警报管理**：活动警报，关键问题，机器特定警报
- **维护管理**：历史记录，调度，逾期任务
- **性能分析**：生产线效率，设施概览
### 示例代理查询
系统处理复杂的查询，例如：
- **故障排除**：`"MCH_001机器显示高温度警报。我应该检查什么？"``
- **维护**：`"显示我所有逾期的维护任务和即将安排的工作"`
- **监控**：`"所有生产线的当前状态是什么？"``
- **性能**：`"分析LINE_01在过去一周的效率趋势"`
## 📊 数据模型和集合
### Couchbase集合结构
```mermaid
erDiagram
PRODUCTION_LINES ||--o{ MACHINES : contains
MACHINES ||--o{ ALERTS : generates
MACHINES ||--o{ MAINTENANCE : requires
PRODUCTION_LINES ||--o{ METRICS : produces
MANUALS ||--o{ MANUAL_CHUNKS : contains
ALERTS ||--o{ SOLUTIONS : derives
```
### 集合类型
- **production_lines**：生产线状态和配置
- **machines**：机器详细信息，参数和规格
- **alerts**：活动和历史警报，严重程度级别
- **maintenance**：维护记录，计划和历史
- **metrics**：生产指标和性能数据
- **manuals**：处理后的手册内容，带有向量嵌入
- **solutions**：带有向量嵌入的AI优化制造解决方案，用于语义搜索
## 🔧 配置
### 数据库配置
系统使用多集合Couchbase设置：
```python
# config.py
couchbase_collections = {
"manuals": "manuals",
"machines": "machines",
"production_lines": "production_lines",
"alerts": "alerts",
"maintenance": "maintenance",
"metrics": "metrics",
"solutions": "solutions"
}
```
### 代理配置
专用代理的不同系统提示：
- **故障排除代理**：安全无误的错误解决
- **维护代理**：主动维护计划
- **监控代理**：实时生产可见性
- **性能代理**：数据驱动的效率分析
- **综合代理**：全面的制造支持
## 🎯 演示用例
### 1. 智能故障排除
- **挑战**：机器故障导致生产线停机
- **解决方案**：AI分析警报，搜索手册，提供逐步解决方案
- **好处**：将平均故障恢复时间从数小时缩短到数分钟
### 2. 预测性维护
- **挑战**：意外的设备故障
- **解决方案**：AI关联维护计划与历史数据
- **好处**：通过主动维护计划防止故障
### 3. 生产优化
- **挑战**：生产线效率低下
- **解决方案**：AI分析性能趋势并建议改进
- **好处**：提高总体设备效率（OEE）
### 4. 操作员知识支持
- **挑战**：复杂的故障排除程序
- **解决方案**：AI提供相关手册部分的即时访问
- **好处**：为操作员提供专家级指导
## 🧪 运行演示
### 完整的设置过程
```bash
# 1. 安装依赖项
pip install -r requirements.txt
# 2. 初始化数据库并生成样本数据
python -m setup.setup_system
# 3. 启动MCP工具箱（在单独的终端中）
genai-toolbox --tools-file tools.yaml --port 5000
# 4. 启动后端API（在单独的终端中）
uvicorn api:app --reload --host 0.0.0.0 --port 8000
# 5. 启动Web界面（在单独的终端中）
streamlit run streamlit_app.py
# 生成机器状态报告，包含最近24小时的警报
python -m setup.list_machine_alerts
# 生成自定义时间段的报告（例如，过去48小时）
python -m setup.list_machine_alerts 48
```
## 📈 性能指标
系统跟踪综合指标：
- **代理性能**：响应时间和准确率
- **数据库性能**：查询执行时间和连接健康状况
- **工具使用**：MCP工具箱工具执行统计
- **手册搜索**：向量搜索相关性和速度
- **系统健康**：整体可用性和错误率
### 监控仪表板
通过Streamlit界面内置监控：
```python
# 性能指标显示在Web界面中
system_metrics = {
"api_response_time": "< 500ms 平均值",
"database_query_time": "< 100ms 平均值",
"agent_success_rate": "98%",
"manual_search_accuracy": "0.92 平均值",
"system_uptime": "99.5%"
}
```
## 📄 许可证
该项目根据MIT许可证授权 - 参见LICENSE文件了解详情。
## 🙏 致谢
- **Google MCP工具箱团队**：用于强大的数据库集成框架
- **Couchbase**：用于可扩展的NoSQL数据库平台，支持向量搜索
- **LangChain/LangGraph**：用于AI代理编排框架
- **Google AI**：用于Gemini语言模型和嵌入能力
- **Sentence Transformers**：用于额外的嵌入模型支持
## 📚 其他资源
- [Google MCP工具箱文档](https://googleapis.github.io/genai-toolbox/)
- [Couchbase向量搜索文档](https://docs.couchbase.com/server/current/vector-search/vector-search.html)
- [LangGraph文档](https://langchain-ai.github.io/langgraph/)
- [Google AI开发者](https://ai.google.dev/)
- [Streamlit文档](https://docs.streamlit.io/)
---
## 由❤️构建，以实现制造卓越
本演示展示了Google MCP工具箱与Couchbase的强大向量搜索功能相结合，如何通过智能、上下文感知型故障排除助手革新制造运营。该模块化架构确保了可扩展性、可维护性和与企业制造系统的无缝集成。
