Skip to main content

​
概述

智能路由是 MCPHub 的智能工具发现系统，它使用向量语义搜索来自动找到与任何给定任务最相关的工具。AI 客户端无需手动指定使用哪些工具，只需描述他们想要完成的任务，智能路由就会识别并提供对最合适工具的访问。

​
智能路由的工作原理

​
1. 工具索引

当服务器启动时，智能路由会自动：
  • 从 MCP 服务器发现所有可用工具
  • 提取工具元数据（名称、描述、参数）
  • 将工具信息转换为向量嵌入
  • 使用 pgvector 将嵌入存储在 PostgreSQL 中

​
2. 语义搜索

当进行查询时：
  • 用户查询被转换为向量嵌入
  • 相似性搜索使用余弦相似度找到匹配的工具
  • 动态阈值过滤掉不相关的结果
  • 结果按相关性得分排序

​
3. 智能过滤

智能路由应用多个过滤器：
  • 相关性阈值：只返回高于相似性阈值的工具
  • 上下文感知：考虑对话上下文
  • 工具可用性：确保工具当前可访问
  • 权限过滤：尊重用户访问权限

​
4. 工具执行

找到的工具可以直接执行：
  • 参数验证确保正确的工具使用
  • 错误处理提供有用的反馈
  • 响应格式保持一致性
  • 日志记录跟踪工具使用情况进行分析

​
前置条件

智能路由需要比基础 MCPHub 使用更多的设置：

​
必需组件

  1. 带有 pgvector 的 PostgreSQL：用于嵌入存储的向量数据库
  2. 嵌入服务：OpenAI API 或兼容服务
  3. 环境配置：正确的配置变量

​
使用智能路由

​
智能路由端点

通过特殊的 $smart 端点访问智能路由：
  • HTTP MCP
  • SSE (Legacy)
http://localhost:3000/mcp/$smart

​
故障排除

症状：
  • 智能路由不可用
  • 数据库连接错误
  • 嵌入存储失败
解决方案：
  1. 验证 PostgreSQL 是否正在运行
  2. 检查 DATABASE_URL 格式
  3. 确保安装了 pgvector 扩展
  4. 手动测试连接：
psql $DATABASE_URL -c "SELECT 1;"
症状：
  • 工具索引失败
  • 查询处理错误
  • API 速率限制错误
解决方案：
  1. 验证 API 密钥有效性
  2. 检查网络连接
  3. 监控速率限制
  4. 测试嵌入服务：
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. 检查工具元数据质量
# 重新索引所有工具
curl -X POST http://localhost:3000/api/smart-routing/reindex \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
症状：
  • 查询响应缓慢
  • 数据库负载高
  • 内存使用激增
解决方案：
  1. 优化数据库配置
  2. 增加缓存大小
  3. 减少批处理大小
  4. 监控系统资源
# 检查系统性能
curl http://localhost:3000/api/smart-routing/performance \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
最佳实践

​
查询编写

要具体描述：在查询中使用具体、描述性的语言以获得更好的工具匹配。
包含上下文：提供有关您的任务或领域的相关上下文以获得更准确的结果。
使用自然语言：像向人类描述任务一样编写查询。

​
工具描述

质量元数据：确保 MCP 服务器提供高质量的工具描述和元数据。
定期更新：随着功能的发展保持工具描述的最新状态。
一致的命名：在工具和服务器中使用一致的命名约定。

​
系统维护

定期重新索引：定期重新索引工具以确保嵌入质量。
监控性能：跟踪查询模式并根据使用情况进行优化。
更新模型：随着新嵌入模型的出现，考虑更新到更新的模型。

​
下一步

身份验证

用户管理和访问控制

监控

系统监控和分析

API 参考

完整的智能路由 API 文档

配置

高级配置选项
⌘I