Skip to main content

概述

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

智能路由的工作原理

1. 工具索引

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

2. 语义搜索

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

3. 智能过滤

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

4. 工具执行

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

前置条件

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

必需组件

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

使用智能路由

智能路由端点

通过特殊的 $smart 端点访问智能路由:

分组范围的智能路由

智能路由支持分组范围的搜索,允许您将工具发现限制在特定分组内的服务器:
将您的 AI 客户端连接到特定分组的智能路由端点:
此端点只会搜索属于 “production” 分组的服务器中的工具。优势:
  • 聚焦结果:只返回相关服务器的工具
  • 更好的性能:减少搜索空间以加快查询速度
  • 环境隔离:将开发、预发布和生产工具分开
  • 访问控制:根据用户权限限制工具发现
当使用 $smart/{group} 时:
  1. 系统识别指定的分组
  2. 获取属于该分组的所有服务器
  3. 将工具搜索过滤到仅限那些服务器
  4. 返回限定在该分组服务器范围内的结果
如果分组不存在或没有服务器,搜索将不返回任何结果。

固定工具

$smart/{group} 端点只列出元工具,因此即使是模型几乎每次会话都会调用的工具,也要先经过一次 search_tools 往返。在分组的服务器条目上固定这些工具后,端点会在元工具旁列出它们的完整定义:
在控制台中编辑分组,展开服务器,然后点击已选工具旁的图钉图标。仅在启用智能路由时显示该图标。
  • 固定使用不带前缀的工具名,与 tools 选择相同。只有分组已选择且已启用的工具才会生效,其余固定会被忽略。
  • 固定工具的列出方式与直接的 /mcp/{group} 端点完全相同(使用服务器的对外名称和自定义描述),并可直接按该名称调用。它仍保留在搜索索引中,search_tools、describe_tool 和 call_tool 照常可用。
  • 全局 $smart 端点没有分组,从不列出固定工具。没有固定工具的分组与之前一样只列出元工具。
  • 如果固定工具列出的名称与元工具名称(search_tools、describe_tool、call_tool,例如别名 describe + 分隔符 _ + 工具 tool)相同,则在任何模式下都不会列出:对这些名称的调用始终交给元工具处理。
  • 分组显示的智能路由占用包含其固定工具的定义成本。
  • 在控制台中或通过 PUT /api/groups/:id/server-configs/:serverName/tools 取消选择某个工具时,也会移除它的固定。
  • 在 $smart/{group} 上,对声明支持 MCP Apps 的客户端,固定工具会保留其 MCP Apps 元数据(_meta.ui),因此其小部件可以渲染,该服务器的 ui:// 资源和仅限 Apps 的辅助工具也可从小部件访问;不支持 MCP Apps 的客户端仍会去除这些元数据。只有固定工具才带有小部件:通过 search_tools 和 call_tool 调用的工具没有可供宿主关联小部件的独立描述,因此请固定需要小部件的工具。全局 $smart 端点始终不是 MCP Apps 路由。
通过 call_tool 调用时,所有工具共享客户端的同一个审批决定。固定工具以自己的名称列出,逐个审批工具的客户端会对其应用单独的规则——固定会写入数据的工具前请先确认这一点。

渐进式披露模式

渐进式披露是一个优化功能,可以减少使用智能路由时的 Token 消耗。启用后,工具发现工作流从 2 步变为 3 步。
默认情况下,智能路由在 search_tools 结果中返回完整的工具信息,包括完整的参数模式。当处理具有复杂输入模式的工具时,这会消耗大量 Token。渐进式披露 改变了这种行为:
  • search_tools 只返回工具名称和描述(最少信息)
  • 新的 describe_tool 端点按需提供完整的参数模式
  • call_tool 像以前一样执行工具
这种方法特别适用于:
  • 处理具有复杂模式的大量工具
  • Token 使用优化很重要的场景
  • AI 客户端需要浏览多个工具后再选择
通过设置页面或环境变量启用渐进式披露:通过设置界面:
  1. 导航到 设置 → 智能路由
  2. 启用”渐进式披露”开关
  3. 更改立即生效
通过环境变量:
默认情况下,search_tools 只会在工具描述中列出服务器名称。若要同时显示服务器描述(或上游返回的 instructions),请设置:
使用 names(默认值)可保持原来的紧凑列表。该列表列出 search_tools 实际搜索的服务器:已启用且已连接或按需启动的服务器。按需启动的服务器未连接时仍会列出,无论是因空闲而关闭还是启动失败,因为 call_tool 会启动它;其他连接失败的服务器在重新连接之前不会列出。上游 instructions 只在连接时获得,因此在 full 模式下,尚未连接过的服务器只显示其配置的描述,或仅显示名称。
非对称检索模型在训练时对查询和文档使用不同的任务前缀,直接嵌入原始文本时效果明显变差。可在 设置 → 智能路由 中或通过环境变量设置模型所需的前缀:
两者默认均为空,即与以前一样嵌入原始文本。前缀按原样使用,请保留末尾空格。修改文档前缀会重新生成所有服务器的工具嵌入;修改查询前缀在下一次搜索时生效。前缀会改变相似度分数(以 EmbeddingGemma 为例,弱匹配下降得比强匹配更多),因此基于原始文本调好的阈值在启用前缀后可能需要重新校准(参见下方的 搜索结果;每个结果都会返回 score)。前缀也计入嵌入的 Token 上限(EMBEDDING_MAX_TOKENS 或模型默认值):前缀会被保留,工具文本会相应提前截断。
每个 search_tools 结果都带有 score:查询与工具之间的余弦相似度(0-1,保留两位小数),也就是与阈值比较的值。结果按相关性排序,排序时还会考虑工具所在服务器与查询的匹配程度。
三者也可以在 设置 → 智能路由 → 搜索结果 中设置,且都不会触发重新嵌入。默认不附带的字段主要供客户端而非模型使用,而且可能很大:上游服务器可能为每个工具附带 base64 格式的 icons 或很长的 outputSchema,放在搜索结果里只会消耗 Token。inputSchema 始终返回,并去掉其中的 $schema 键。当没有工具达到阈值时,响应会明确说明,给出阈值并列出已搜索的服务器,让模型可以告诉用户该能力不可用,而不是去调用最接近但无关的工具。
当渐进式披露禁用(默认)时,智能路由提供两个工具:工作流: search_tools → call_tool这种模式更简单,但由于搜索结果中包含完整模式,会使用更多 Token。SMART_ROUTING_FULL_SCHEMA_TOP_N 可以限制这部分开销:只有前 N 个结果带 schema,其余结果通过列出的 describe_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 响应:
渐进式披露模式 search_tools 响应:
describe_tool 响应:

故障排除

症状:
  • 智能路由不可用
  • 数据库连接错误
  • 嵌入存储失败
解决方案:
  1. 验证 PostgreSQL 是否正在运行
  2. 检查 DB_URL 格式
  3. 确保安装了 pgvector 扩展
  4. 手动测试连接:
症状:
  • 工具索引失败
  • 查询处理错误
  • API 速率限制错误
解决方案:
  1. 验证 API 密钥有效性
  2. 检查网络连接
  3. 监控速率限制
  4. 测试嵌入服务:
症状:
  • 返回不相关的工具
  • 相关性得分低
  • 缺少预期的工具
解决方案:
  1. 调整相似性阈值(SMART_ROUTING_SIMILARITY_THRESHOLD),可参考每个结果的 score 选择数值
  2. 使用更好的描述重新索引工具
  3. 使用更具体的查询
  4. 检查工具元数据质量
症状:
  • 查询响应缓慢
  • 数据库负载高
  • 内存使用激增
解决方案:
  1. 优化数据库配置
  2. 增加缓存大小
  3. 减少批处理大小
  4. 监控系统资源
症状:
  • 工具索引失败,返回鉴权错误(401/403)
  • 面板里保存的密钥是有效的,但请求仍被拒绝
原因: 环境变量的优先级高于面板配置,因此你保存的密钥从未被使用(issue #642)。新版本会在对应字段下方显示警告,并指出实际生效的变量名。解决方案:
  1. 检查 .env* 文件、shell 配置以及容器/服务定义中的 OPENAI_API_KEY / AZURE_OPENAI_API_KEY
  2. 移除遗留变量并重启;若提供商或模型也发生变化,请重新索引
  3. 确认实际生效的密钥是否可用:

最佳实践

查询编写

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

工具描述

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

系统维护

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

下一步

身份验证

用户管理和访问控制

监控

系统监控和分析

API 参考

完整的智能路由 API 文档

配置

高级配置选项