mirror of
https://github.com/samanhappy/mcphub.git
synced 2026-01-11 09:07:01 -05:00
532 lines
13 KiB
Plaintext
532 lines
13 KiB
Plaintext
---
|
||
title: '智能路由'
|
||
description: '使用向量语义搜索的 AI 工具发现系统'
|
||
---
|
||
|
||
## 概述
|
||
|
||
智能路由是 MCPHub 的智能工具发现系统，它使用向量语义搜索来自动找到与任何给定任务最相关的工具。AI 客户端无需手动指定使用哪些工具，只需描述他们想要完成的任务，智能路由就会识别并提供对最合适工具的访问。
|
||
|
||
## 智能路由的工作原理
|
||
|
||
### 1. 工具索引
|
||
|
||
当服务器启动时，智能路由会自动：
|
||
|
||
- 从 MCP 服务器发现所有可用工具
|
||
- 提取工具元数据（名称、描述、参数）
|
||
- 将工具信息转换为向量嵌入
|
||
- 使用 pgvector 将嵌入存储在 PostgreSQL 中
|
||
|
||
### 2. 语义搜索
|
||
|
||
当进行查询时：
|
||
|
||
- 用户查询被转换为向量嵌入
|
||
- 相似性搜索使用余弦相似度找到匹配的工具
|
||
- 动态阈值过滤掉不相关的结果
|
||
- 结果按相关性得分排序
|
||
|
||
### 3. 智能过滤
|
||
|
||
智能路由应用多个过滤器：
|
||
|
||
- **相关性阈值**：只返回高于相似性阈值的工具
|
||
- **上下文感知**：考虑对话上下文
|
||
- **工具可用性**：确保工具当前可访问
|
||
- **权限过滤**：尊重用户访问权限
|
||
|
||
### 4. 工具执行
|
||
|
||
找到的工具可以直接执行：
|
||
|
||
- 参数验证确保正确的工具使用
|
||
- 错误处理提供有用的反馈
|
||
- 响应格式保持一致性
|
||
- 日志记录跟踪工具使用情况进行分析
|
||
|
||
## 前置条件
|
||
|
||
智能路由需要比基础 MCPHub 使用更多的设置：
|
||
|
||
### 必需组件
|
||
|
||
1. **带有 pgvector 的 PostgreSQL**：用于嵌入存储的向量数据库
|
||
2. **嵌入服务**：OpenAI API 或兼容服务
|
||
3. **环境配置**：正确的配置变量
|
||
|
||
## 使用智能路由
|
||
|
||
### 智能路由端点
|
||
|
||
通过特殊的 `$smart` 端点访问智能路由：
|
||
|
||
<Tabs>
|
||
<Tab title="HTTP MCP">
|
||
```
|
||
# 搜索所有服务器
|
||
http://localhost:3000/mcp/$smart
|
||
|
||
# 在特定分组内搜索
|
||
http://localhost:3000/mcp/$smart/{group}
|
||
```
|
||
</Tab>
|
||
|
||
<Tab title="SSE (Legacy)">
|
||
```
|
||
# 搜索所有服务器
|
||
http://localhost:3000/sse/$smart
|
||
|
||
# 在特定分组内搜索
|
||
http://localhost:3000/sse/$smart/{group}
|
||
```
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
### 分组范围的智能路由
|
||
|
||
智能路由支持分组范围的搜索，允许您将工具发现限制在特定分组内的服务器：
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="使用分组范围的智能路由">
|
||
将您的 AI 客户端连接到特定分组的智能路由端点：
|
||
|
||
```
|
||
http://localhost:3000/mcp/$smart/production
|
||
```
|
||
|
||
此端点只会搜索属于 "production" 分组的服务器中的工具。
|
||
|
||
**优势：**
|
||
- **聚焦结果**：只返回相关服务器的工具
|
||
- **更好的性能**：减少搜索空间以加快查询速度
|
||
- **环境隔离**：将开发、预发布和生产工具分开
|
||
- **访问控制**：根据用户权限限制工具发现
|
||
</Accordion>
|
||
|
||
<Accordion title="工作原理">
|
||
当使用 `$smart/{group}` 时：
|
||
|
||
1. 系统识别指定的分组
|
||
2. 获取属于该分组的所有服务器
|
||
3. 将工具搜索过滤到仅限那些服务器
|
||
4. 返回限定在该分组服务器范围内的结果
|
||
|
||
如果分组不存在或没有服务器，搜索将不返回任何结果。
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
|
||
### 渐进式披露模式
|
||
|
||
渐进式披露是一个优化功能，可以减少使用智能路由时的 Token 消耗。启用后，工具发现工作流从 2 步变为 3 步。
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="什么是渐进式披露？">
|
||
默认情况下，智能路由在 `search_tools` 结果中返回完整的工具信息，包括完整的参数模式。当处理具有复杂输入模式的工具时，这会消耗大量 Token。
|
||
|
||
**渐进式披露** 改变了这种行为：
|
||
- `search_tools` 只返回工具名称和描述（最少信息）
|
||
- 新的 `describe_tool` 端点按需提供完整的参数模式
|
||
- `call_tool` 像以前一样执行工具
|
||
|
||
这种方法特别适用于：
|
||
- 处理具有复杂模式的大量工具
|
||
- Token 使用优化很重要的场景
|
||
- AI 客户端需要浏览多个工具后再选择
|
||
</Accordion>
|
||
|
||
<Accordion title="启用渐进式披露">
|
||
通过设置页面或环境变量启用渐进式披露：
|
||
|
||
**通过设置界面：**
|
||
1. 导航到 设置 → 智能路由
|
||
2. 启用"渐进式披露"开关
|
||
3. 更改立即生效
|
||
|
||
**通过环境变量：**
|
||
```bash
|
||
SMART_ROUTING_PROGRESSIVE_DISCLOSURE=true
|
||
```
|
||
</Accordion>
|
||
|
||
<Accordion title="标准模式（默认）">
|
||
当渐进式披露**禁用**（默认）时，智能路由提供两个工具：
|
||
|
||
**工作流：** `search_tools` → `call_tool`
|
||
|
||
| 工具 | 用途 |
|
||
|------|------|
|
||
| `search_tools` | 按查询查找工具，返回包含 `inputSchema` 的完整工具信息 |
|
||
| `call_tool` | 使用提供的参数执行工具 |
|
||
|
||
这种模式更简单，但由于搜索结果中包含完整模式，会使用更多 Token。
|
||
</Accordion>
|
||
|
||
<Accordion title="渐进式披露模式">
|
||
当渐进式披露**启用**时，智能路由提供三个工具：
|
||
|
||
**工作流：** `search_tools` → `describe_tool` → `call_tool`
|
||
|
||
| 工具 | 用途 |
|
||
|------|------|
|
||
| `search_tools` | 按查询查找工具，只返回名称和描述 |
|
||
| `describe_tool` | 获取特定工具的完整模式（新增） |
|
||
| `call_tool` | 使用提供的参数执行工具 |
|
||
|
||
**示例工作流：**
|
||
1. AI 使用查询 "文件操作" 调用 `search_tools`
|
||
2. 结果显示工具名称和描述（最少 Token）
|
||
3. AI 为特定工具调用 `describe_tool` 获取完整的 `inputSchema`
|
||
4. AI 使用正确的参数调用 `call_tool`
|
||
|
||
这种模式通过仅在需要时获取完整模式来减少 Token 使用。
|
||
</Accordion>
|
||
|
||
<Accordion title="响应格式对比">
|
||
**标准模式 search_tools 响应：**
|
||
```json
|
||
{
|
||
"tools": [
|
||
{
|
||
"name": "read_file",
|
||
"description": "读取文件内容",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"path": { "type": "string", "description": "要读取的文件路径" },
|
||
"encoding": { "type": "string", "default": "utf-8" }
|
||
},
|
||
"required": ["path"]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**渐进式披露模式 search_tools 响应：**
|
||
```json
|
||
{
|
||
"tools": [
|
||
{
|
||
"name": "read_file",
|
||
"description": "读取文件内容"
|
||
}
|
||
],
|
||
"metadata": {
|
||
"progressiveDisclosure": true,
|
||
"guideline": "使用 describe_tool 获取完整的参数模式后再调用。"
|
||
}
|
||
}
|
||
```
|
||
|
||
**describe_tool 响应：**
|
||
```json
|
||
{
|
||
"tool": {
|
||
"name": "read_file",
|
||
"description": "读取文件内容",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"path": { "type": "string", "description": "要读取的文件路径" },
|
||
"encoding": { "type": "string", "default": "utf-8" }
|
||
},
|
||
"required": ["path"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
|
||
{/* ## 性能优化
|
||
|
||
### 嵌入缓存
|
||
|
||
智能路由缓存嵌入以提高性能：
|
||
|
||
```bash
|
||
# 配置缓存设置
|
||
EMBEDDING_CACHE_TTL=3600 # 缓存 1 小时
|
||
EMBEDDING_CACHE_SIZE=10000 # 最多缓存 10k 个嵌入
|
||
EMBEDDING_CACHE_CLEANUP=300 # 每 5 分钟清理一次
|
||
```
|
||
|
||
### 批处理
|
||
|
||
工具批量索引以提高效率：
|
||
|
||
```bash
|
||
# 嵌入生成的批大小
|
||
EMBEDDING_BATCH_SIZE=100
|
||
|
||
# 并发嵌入请求
|
||
EMBEDDING_CONCURRENCY=5
|
||
|
||
# 索引更新频率
|
||
INDEX_UPDATE_INTERVAL=3600 # 每小时重新索引
|
||
```
|
||
|
||
### 数据库优化
|
||
|
||
为向量操作优化 PostgreSQL：
|
||
|
||
```sql
|
||
-- 创建索引以获得更好的性能
|
||
CREATE INDEX ON tool_embeddings USING hnsw (embedding vector_cosine_ops);
|
||
|
||
-- 调整 PostgreSQL 设置
|
||
ALTER SYSTEM SET shared_preload_libraries = 'vector';
|
||
ALTER SYSTEM SET max_connections = 200;
|
||
ALTER SYSTEM SET shared_buffers = '256MB';
|
||
ALTER SYSTEM SET effective_cache_size = '1GB';
|
||
```
|
||
|
||
## 监控和分析
|
||
|
||
### 智能路由指标
|
||
|
||
监控智能路由性能：
|
||
|
||
```bash
|
||
# 获取智能路由统计信息
|
||
curl http://localhost:3000/api/smart-routing/stats \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||
```
|
||
|
||
响应包括：
|
||
|
||
- 查询计数和频率
|
||
- 平均响应时间
|
||
- 嵌入缓存命中率
|
||
- 最受欢迎的工具
|
||
- 查询模式
|
||
|
||
### 工具使用分析
|
||
|
||
跟踪哪些工具被发现和使用：
|
||
|
||
```bash
|
||
# 获取工具使用分析
|
||
curl http://localhost:3000/api/smart-routing/analytics \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||
```
|
||
|
||
指标包括：
|
||
|
||
- 工具发现率
|
||
- 执行成功率
|
||
- 用户满意度评分
|
||
- 查询到执行的转换率
|
||
|
||
### 性能监控
|
||
|
||
监控系统性能：
|
||
|
||
```bash
|
||
# 数据库性能
|
||
curl http://localhost:3000/api/smart-routing/db-stats \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||
|
||
# 嵌入服务状态
|
||
curl http://localhost:3000/api/smart-routing/embedding-stats \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||
```
|
||
|
||
## 高级功能
|
||
|
||
### 自定义嵌入
|
||
|
||
使用自定义嵌入模型：
|
||
|
||
```bash
|
||
# Hugging Face 模型
|
||
EMBEDDING_SERVICE=huggingface
|
||
HUGGINGFACE_MODEL=sentence-transformers/all-MiniLM-L6-v2
|
||
HUGGINGFACE_API_KEY=your_api_key
|
||
|
||
# 本地嵌入服务
|
||
EMBEDDING_SERVICE=local
|
||
EMBEDDING_SERVICE_URL=http://localhost:8080/embeddings
|
||
```
|
||
|
||
### 查询增强
|
||
|
||
增强查询以获得更好的结果：
|
||
|
||
```json
|
||
{
|
||
"queryEnhancement": {
|
||
"enabled": true,
|
||
"expandAcronyms": true,
|
||
"addSynonyms": true,
|
||
"contextualExpansion": true
|
||
}
|
||
}
|
||
```
|
||
|
||
### 结果过滤
|
||
|
||
基于条件过滤结果：
|
||
|
||
```json
|
||
{
|
||
"resultFiltering": {
|
||
"minRelevanceScore": 0.7,
|
||
"maxResults": 10,
|
||
"preferredServers": ["fetch", "playwright"],
|
||
"excludeServers": ["deprecated-server"]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 反馈学习
|
||
|
||
基于用户反馈改进结果：
|
||
|
||
```bash
|
||
# 对搜索结果提供反馈
|
||
curl -X POST http://localhost:3000/api/smart-routing/feedback \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-d '{
|
||
"queryId": "search-123",
|
||
"toolName": "fetch_html",
|
||
"rating": 5,
|
||
"successful": true,
|
||
"comments": "完美适合这个任务的工具"
|
||
}'
|
||
``` */}
|
||
|
||
## 故障排除
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="数据库连接问题">
|
||
**症状：**
|
||
- 智能路由不可用
|
||
- 数据库连接错误
|
||
- 嵌入存储失败
|
||
|
||
**解决方案：**
|
||
1. 验证 PostgreSQL 是否正在运行
|
||
2. 检查 DB_URL 格式
|
||
3. 确保安装了 pgvector 扩展
|
||
4. 手动测试连接：
|
||
```bash
|
||
psql $DB_URL -c "SELECT 1;"
|
||
```
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="嵌入服务问题">
|
||
**症状：**
|
||
- 工具索引失败
|
||
- 查询处理错误
|
||
- API 速率限制错误
|
||
|
||
**解决方案：**
|
||
1. 验证 API 密钥有效性
|
||
2. 检查网络连接
|
||
3. 监控速率限制
|
||
4. 测试嵌入服务：
|
||
```bash
|
||
curl -X POST https://api.openai.com/v1/embeddings \
|
||
-H "Authorization: Bearer $OPENAI_API_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"input": "test", "model": "text-embedding-3-small"}'
|
||
```
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="搜索结果不佳">
|
||
**症状：**
|
||
- 返回不相关的工具
|
||
- 相关性得分低
|
||
- 缺少预期的工具
|
||
|
||
**解决方案：**
|
||
1. 调整相似性阈值
|
||
2. 使用更好的描述重新索引工具
|
||
3. 使用更具体的查询
|
||
4. 检查工具元数据质量
|
||
```bash
|
||
# 重新索引所有工具
|
||
curl -X POST http://localhost:3000/api/smart-routing/reindex \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||
```
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="性能问题">
|
||
**症状：**
|
||
- 查询响应缓慢
|
||
- 数据库负载高
|
||
- 内存使用激增
|
||
|
||
**解决方案：**
|
||
1. 优化数据库配置
|
||
2. 增加缓存大小
|
||
3. 减少批处理大小
|
||
4. 监控系统资源
|
||
```bash
|
||
# 检查系统性能
|
||
curl http://localhost:3000/api/smart-routing/performance \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||
```
|
||
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
|
||
## 最佳实践
|
||
|
||
### 查询编写
|
||
|
||
<Tip>
|
||
**要具体描述**：在查询中使用具体、描述性的语言以获得更好的工具匹配。
|
||
</Tip>
|
||
|
||
<Tip>
|
||
**包含上下文**：提供有关您的任务或领域的相关上下文以获得更准确的结果。
|
||
</Tip>
|
||
|
||
<Tip>**使用自然语言**：像向人类描述任务一样编写查询。</Tip>
|
||
|
||
### 工具描述
|
||
|
||
<Warning>
|
||
**质量元数据**：确保 MCP 服务器提供高质量的工具描述和元数据。
|
||
</Warning>
|
||
|
||
<Warning>**定期更新**：随着功能的发展保持工具描述的最新状态。</Warning>
|
||
|
||
<Warning>
|
||
**一致的命名**：在工具和服务器中使用一致的命名约定。
|
||
</Warning>
|
||
|
||
### 系统维护
|
||
|
||
<Info>**定期重新索引**：定期重新索引工具以确保嵌入质量。</Info>
|
||
|
||
<Info>**监控性能**：跟踪查询模式并根据使用情况进行优化。</Info>
|
||
|
||
<Info>
|
||
**更新模型**：随着新嵌入模型的出现，考虑更新到更新的模型。
|
||
</Info>
|
||
|
||
## 下一步
|
||
|
||
<CardGroup cols={2}>
|
||
<Card title="身份验证" icon="shield" href="/zh/features/authentication">
|
||
用户管理和访问控制
|
||
</Card>
|
||
<Card title="监控" icon="chart-line" href="/zh/features/monitoring">
|
||
系统监控和分析
|
||
</Card>
|
||
<Card title="API 参考" icon="code" href="/zh/api-reference/smart-routing">
|
||
完整的智能路由 API 文档
|
||
</Card>
|
||
<Card title="配置" icon="cog" href="/zh/configuration/environment-variables">
|
||
高级配置选项
|
||
</Card>
|
||
</CardGroup>
|