--- title: '智能路由' description: '使用向量语义搜索的 AI 工具发现系统' --- ## 概述 智能路由是 MCPHub 的智能工具发现系统，它使用向量语义搜索来自动找到与任何给定任务最相关的工具。AI 客户端无需手动指定使用哪些工具，只需描述他们想要完成的任务，智能路由就会识别并提供对最合适工具的访问。 ## 智能路由的工作原理 ### 1. 工具索引 当服务器启动时，智能路由会自动： - 从 MCP 服务器发现所有可用工具 - 提取工具元数据（名称、描述、参数） - 将工具信息转换为向量嵌入 - 使用 pgvector 将嵌入存储在 PostgreSQL 中 ### 2. 语义搜索 当进行查询时： - 用户查询被转换为向量嵌入 - 相似性搜索使用余弦相似度找到匹配的工具 - 动态阈值过滤掉不相关的结果 - 结果按相关性得分排序 ### 3. 智能过滤 智能路由应用多个过滤器： - **相关性阈值**：只返回高于相似性阈值的工具 - **上下文感知**：考虑对话上下文 - **工具可用性**：确保工具当前可访问 - **权限过滤**：尊重用户访问权限 ### 4. 工具执行 找到的工具可以直接执行： - 参数验证确保正确的工具使用 - 错误处理提供有用的反馈 - 响应格式保持一致性 - 日志记录跟踪工具使用情况进行分析 ## 前置条件 智能路由需要比基础 MCPHub 使用更多的设置： ### 必需组件 1. **带有 pgvector 的 PostgreSQL**：用于嵌入存储的向量数据库 2. **嵌入服务**：OpenAI API 或兼容服务 3. **环境配置**：正确的配置变量 ## 使用智能路由 ### 智能路由端点 通过特殊的 `$smart` 端点访问智能路由： ``` # 搜索所有服务器 http://localhost:3000/mcp/$smart # 在特定分组内搜索 http://localhost:3000/mcp/$smart/{group} ``` ``` # 搜索所有服务器 http://localhost:3000/sse/$smart # 在特定分组内搜索 http://localhost:3000/sse/$smart/{group} ``` ### 分组范围的智能路由 智能路由支持分组范围的搜索，允许您将工具发现限制在特定分组内的服务器： 将您的 AI 客户端连接到特定分组的智能路由端点： ``` http://localhost:3000/mcp/$smart/production ``` 此端点只会搜索属于 "production" 分组的服务器中的工具。 **优势：** - **聚焦结果**：只返回相关服务器的工具 - **更好的性能**：减少搜索空间以加快查询速度 - **环境隔离**：将开发、预发布和生产工具分开 - **访问控制**：根据用户权限限制工具发现 当使用 `$smart/{group}` 时： 1. 系统识别指定的分组 2. 获取属于该分组的所有服务器 3. 将工具搜索过滤到仅限那些服务器 4. 返回限定在该分组服务器范围内的结果 如果分组不存在或没有服务器，搜索将不返回任何结果。 ### 渐进式披露模式 渐进式披露是一个优化功能，可以减少使用智能路由时的 Token 消耗。启用后，工具发现工作流从 2 步变为 3 步。 默认情况下，智能路由在 `search_tools` 结果中返回完整的工具信息，包括完整的参数模式。当处理具有复杂输入模式的工具时，这会消耗大量 Token。 **渐进式披露** 改变了这种行为： - `search_tools` 只返回工具名称和描述（最少信息） - 新的 `describe_tool` 端点按需提供完整的参数模式 - `call_tool` 像以前一样执行工具 这种方法特别适用于： - 处理具有复杂模式的大量工具 - Token 使用优化很重要的场景 - AI 客户端需要浏览多个工具后再选择 通过设置页面或环境变量启用渐进式披露： **通过设置界面：** 1. 导航到 设置 → 智能路由 2. 启用"渐进式披露"开关 3. 更改立即生效 **通过环境变量：** ```bash SMART_ROUTING_PROGRESSIVE_DISCLOSURE=true ``` 当渐进式披露**禁用**（默认）时，智能路由提供两个工具： **工作流：** `search_tools` → `call_tool` | 工具 | 用途 | |------|------| | `search_tools` | 按查询查找工具，返回包含 `inputSchema` 的完整工具信息 | | `call_tool` | 使用提供的参数执行工具 | 这种模式更简单，但由于搜索结果中包含完整模式，会使用更多 Token。 当渐进式披露**启用**时，智能路由提供三个工具： **工作流：** `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 使用。 **标准模式 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"] } } } ``` {/* ## 性能优化 ### 嵌入缓存 智能路由缓存嵌入以提高性能： ```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": "完美适合这个任务的工具" }' ``` */} ## 故障排除 **症状：** - 智能路由不可用 - 数据库连接错误 - 嵌入存储失败 **解决方案：** 1. 验证 PostgreSQL 是否正在运行 2. 检查 DB_URL 格式 3. 确保安装了 pgvector 扩展 4. 手动测试连接： ```bash psql $DB_URL -c "SELECT 1;" ``` **症状：** - 工具索引失败 - 查询处理错误 - 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"}' ``` **症状：** - 返回不相关的工具 - 相关性得分低 - 缺少预期的工具 **解决方案：** 1. 调整相似性阈值 2. 使用更好的描述重新索引工具 3. 使用更具体的查询 4. 检查工具元数据质量 ```bash # 重新索引所有工具 curl -X POST http://localhost:3000/api/smart-routing/reindex \ -H "Authorization: Bearer YOUR_JWT_TOKEN" ``` **症状：** - 查询响应缓慢 - 数据库负载高 - 内存使用激增 **解决方案：** 1. 优化数据库配置 2. 增加缓存大小 3. 减少批处理大小 4. 监控系统资源 ```bash # 检查系统性能 curl http://localhost:3000/api/smart-routing/performance \ -H "Authorization: Bearer YOUR_JWT_TOKEN" ``` ## 最佳实践 ### 查询编写 **要具体描述**：在查询中使用具体、描述性的语言以获得更好的工具匹配。 **包含上下文**：提供有关您的任务或领域的相关上下文以获得更准确的结果。 **使用自然语言**：像向人类描述任务一样编写查询。 ### 工具描述 **质量元数据**：确保 MCP 服务器提供高质量的工具描述和元数据。 **定期更新**：随着功能的发展保持工具描述的最新状态。 **一致的命名**：在工具和服务器中使用一致的命名约定。 ### 系统维护 **定期重新索引**：定期重新索引工具以确保嵌入质量。 **监控性能**：跟踪查询模式并根据使用情况进行优化。 **更新模型**：随着新嵌入模型的出现，考虑更新到更新的模型。 ## 下一步 用户管理和访问控制 系统监控和分析 完整的智能路由 API 文档 高级配置选项