228 lines
8.0 KiB
Markdown
228 lines
8.0 KiB
Markdown
# MCP (Model Context Protocol) 实现文档
|
||
|
||
## 概述
|
||
|
||
本文档介绍了在youfool-devops-gd系统中实现的真正的MCP (Model Context Protocol) 版本。与原有的硬编码数据库查询不同，MCP版本允许LLM动态调用工具来获取数据，提供更灵活和可扩展的AI回答服务。
|
||
|
||
## 架构对比
|
||
|
||
### 原有流程（硬编码版本）
|
||
```
|
||
用户请求 → AIAnswerController → AIAnswerService.generateAnswer() →
|
||
直接数据库查询 (repair表、repair_handle表、ai_knowledge_base表) →
|
||
构建预处理的prompt → qwenChatService.chatCompletion() → 返回AI回答
|
||
```
|
||
|
||
### MCP流程（动态工具调用版本）
|
||
```
|
||
用户请求 → AIAnswerMCPController → AIAnswerServiceMCP.generateAnswerWithMCP() →
|
||
QwenChatService.chatCompletionWithMCP() →
|
||
LLM动态调用MCP工具 (repair_query, repair_feedback_query, similarity_search) →
|
||
MCPServer.executeTool() → 返回AI回答 + 工具使用记录
|
||
```
|
||
|
||
## 核心组件
|
||
|
||
### 1. MCPServer
|
||
- **位置**: `com.chinaweal.youfool.devops.ai.mcp.MCPServer`
|
||
- **功能**: 提供MCP工具的注册、管理和执行
|
||
- **支持的工具**:
|
||
- `repair_query`: 根据工单ID查询工单详细信息
|
||
- `repair_feedback_query`: 查询工单的feedback步骤处理结果
|
||
- `similarity_search`: 基于文本内容进行向量相似度检索
|
||
- `knowledge_query`: 在知识库中精确匹配记录
|
||
|
||
### 2. AIAnswerServiceMCP
|
||
- **位置**: `com.chinaweal.youfool.devops.ai.service.AIAnswerServiceMCP`
|
||
- **功能**: 提供基于MCP的AI回答生成服务
|
||
- **特点**:
|
||
- 支持动态工具调用
|
||
- 包含完整的错误处理和降级机制
|
||
- 提供流式和非流式两种模式
|
||
|
||
### 3. QwenChatService（扩展）
|
||
- **功能扩展**: 增加了MCP工具调用支持
|
||
- **新方法**:
|
||
- `chatCompletionWithMCP()`: 支持MCP的聊天完成
|
||
- `streamChatCompletionWithMCP()`: 支持MCP的流式聊天完成
|
||
- `processMCPToolCalls()`: 处理MCP工具调用逻辑
|
||
|
||
### 4. AIAnswerMCPController
|
||
- **位置**: `com.chinaweal.youfool.devops.ai.controller.AIAnswerMCPController`
|
||
- **功能**: 提供MCP版本的REST API接口
|
||
- **端点**:
|
||
- `GET /api/ai/mcp/tools`: 获取可用的MCP工具列表
|
||
- `POST /api/ai/mcp/answer`: 生成AI回答(MCP版本)
|
||
- `POST /api/ai/mcp/answer/stream`: 生成AI回答流式输出(MCP版本)
|
||
- `POST /api/ai/mcp/compare`: 比较MCP版本与原版本结果
|
||
- `GET /api/ai/mcp/test/{toolName}`: 测试MCP工具调用
|
||
|
||
## 配置说明
|
||
|
||
在 `application.yml` 中添加了以下MCP配置：
|
||
|
||
```yaml
|
||
ai:
|
||
mcp:
|
||
enabled: true # 是否启用MCP服务
|
||
server-name: youfool-devops-mcp # MCP服务器名称
|
||
version: 1.0.0 # MCP版本
|
||
tool-timeout: 30000 # 工具执行超时时间（毫秒）
|
||
log-tool-calls: true # 是否记录工具调用日志
|
||
cache:
|
||
enabled: true # 工具调用结果缓存
|
||
ttl: 300000 # 5分钟缓存
|
||
tools:
|
||
repair-query:
|
||
enabled: true
|
||
description: "查询工单详细信息"
|
||
repair-feedback-query:
|
||
enabled: true
|
||
description: "查询工单feedback处理结果"
|
||
similarity-search:
|
||
enabled: true
|
||
description: "基于文本相似度搜索"
|
||
default-top-k: 5
|
||
default-threshold: 0.7
|
||
knowledge-query:
|
||
enabled: true
|
||
description: "知识库精确查询"
|
||
```
|
||
|
||
## 工具详细说明
|
||
|
||
### 1. repair_query
|
||
- **功能**: 根据工单ID查询工单详细信息
|
||
- **输入参数**:
|
||
- `repairId` (string): 工单ID
|
||
- **返回数据**: 工单基本信息（ID、标题、业务模块、问题类型、优先级、故障描述等）
|
||
|
||
### 2. repair_feedback_query
|
||
- **功能**: 查询工单的feedback步骤处理结果
|
||
- **输入参数**:
|
||
- `repairId` (string): 工单ID
|
||
- **返回数据**: feedback记录列表，包括处理结果、处理人、处理时间等
|
||
|
||
### 3. similarity_search
|
||
- **功能**: 基于文本内容进行向量相似度检索
|
||
- **输入参数**:
|
||
- `queryText` (string): 查询文本
|
||
- `topK` (integer, 可选): 返回前K个结果，默认5
|
||
- `threshold` (number, 可选): 相似度阈值，默认0.7
|
||
- **返回数据**: 相似工单列表，包括相似度分数、解决方案等
|
||
|
||
### 4. knowledge_query
|
||
- **功能**: 在知识库中精确匹配记录
|
||
- **输入参数**:
|
||
- `kbId` (string, 可选): 知识库ID
|
||
- `sourceRepairId` (string, 可选): 源工单ID
|
||
- **返回数据**: 匹配的知识库记录
|
||
|
||
## 使用示例
|
||
|
||
### 1. 获取可用工具
|
||
```bash
|
||
GET /api/ai/mcp/tools
|
||
```
|
||
|
||
### 2. 生成MCP版本AI回答
|
||
```bash
|
||
POST /api/ai/mcp/answer
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"repairId": "R12345",
|
||
"sessionId": "session-123",
|
||
"language": "Chinese",
|
||
"answerStyle": "professional",
|
||
"includeSimilarCases": true,
|
||
"includeHistory": true
|
||
}
|
||
```
|
||
|
||
### 3. 测试特定工具
|
||
```bash
|
||
GET /api/ai/mcp/test/repair_query?repairId=R12345
|
||
GET /api/ai/mcp/test/similarity_search?queryText=数据库连接失败
|
||
```
|
||
|
||
## 工作流程
|
||
|
||
### MCP工具调用流程
|
||
|
||
1. **请求分析**: 系统分析用户请求，提取工单ID
|
||
2. **工单查询**: 调用 `repair_query` 获取工单基本信息
|
||
3. **反馈查询**: 调用 `repair_feedback_query` 获取处理反馈
|
||
4. **相似度检索**: 如果没有meaningful feedback，调用 `similarity_search` 查找相似案例
|
||
5. **结果整合**: 将所有工具调用结果整合到LLM prompt中
|
||
6. **AI生成**: LLM基于整合后的信息生成回答
|
||
|
||
### 处理优先级
|
||
|
||
1. **最高优先级**: feedback处理结果（经过验证的解决方案）
|
||
2. **中等优先级**: 相似案例的解决方案
|
||
3. **最低优先级**: 通用建议和指导
|
||
|
||
## 优势对比
|
||
|
||
### MCP版本优势
|
||
|
||
1. **动态性**: LLM可以根据需要动态调用不同工具
|
||
2. **可扩展性**: 易于添加新的工具和功能
|
||
3. **透明性**: 记录了具体使用了哪些工具
|
||
4. **一致性**: 确保与原版本获得相同的数据源
|
||
5. **可维护性**: 工具调用逻辑独立，便于测试和维护
|
||
|
||
### 原版本问题
|
||
|
||
1. **硬编码**: 数据查询逻辑固化在代码中
|
||
2. **不灵活**: 无法根据具体需求调整查询策略
|
||
3. **难扩展**: 添加新数据源需要修改核心代码
|
||
4. **不透明**: 无法了解具体使用了哪些数据源
|
||
|
||
## 一致性保证
|
||
|
||
MCP版本通过以下措施确保与原版本结果的一致性：
|
||
|
||
1. **相同数据源**: 使用完全相同的数据库表和查询逻辑
|
||
2. **相同算法**: 向量相似度计算使用相同的算法
|
||
3. **相同优先级**: 保持feedback > 相似案例 > 通用建议的优先级
|
||
4. **质量对比**: 提供比较接口可以验证两个版本的结果差异
|
||
|
||
## 监控和调试
|
||
|
||
### 日志记录
|
||
- 所有MCP工具调用都有详细的日志记录
|
||
- 包括调用参数、返回结果、执行时间等信息
|
||
|
||
### 性能监控
|
||
- 记录每个工具的执行时间
|
||
- 统计工具调用成功率
|
||
- 监控整体处理时间
|
||
|
||
### 测试接口
|
||
- 提供独立的工具测试接口
|
||
- 支持对比测试原版本和MCP版本的结果
|
||
|
||
## 部署说明
|
||
|
||
1. **配置启用**: 在 `application.yml` 中设置 `ai.mcp.enabled: true`
|
||
2. **依赖检查**: 确保所有MCP相关的Bean都能正常注入
|
||
3. **功能验证**: 使用测试接口验证各个工具的功能
|
||
4. **对比测试**: 使用对比接口验证结果一致性
|
||
|
||
## 注意事项
|
||
|
||
1. **条件启用**: MCP服务需要通过配置启用，默认情况下与原版本共存
|
||
2. **API隔离**: MCP版本使用独立的API端点，不影响原有功能
|
||
3. **降级机制**: 如果MCP工具调用失败，会降级到原始请求处理
|
||
4. **性能考虑**: MCP版本由于增加了工具调用，处理时间可能略长
|
||
|
||
## 未来扩展
|
||
|
||
1. **更多工具**: 可以轻松添加新的MCP工具
|
||
2. **缓存优化**: 可以添加更智能的缓存策略
|
||
3. **工具链**: 支持工具之间的依赖和链式调用
|
||
4. **自适应**: 根据历史表现自动选择最佳工具组合
|
||
|
||
这个MCP实现为youfool-devops-gd系统提供了一个现代化、可扩展的AI回答服务架构，既保证了与原有流程的一致性，又为未来的功能扩展奠定了基础。 |