概述
智能路由是 MCPHub 的智能工具发现系统,它使用向量语义搜索来自动找到与任何给定任务最相关的工具。AI 客户端无需手动指定使用哪些工具,只需描述他们想要完成的任务,智能路由就会识别并提供对最合适工具的访问。智能路由的工作原理
1. 工具索引
当服务器启动时,智能路由会自动:- 从 MCP 服务器发现所有可用工具
- 提取工具元数据(名称、描述、参数)
- 将工具信息转换为向量嵌入
- 使用 pgvector 将嵌入存储在 PostgreSQL 中
2. 语义搜索
当进行查询时:- 用户查询被转换为向量嵌入
- 相似性搜索使用余弦相似度找到匹配的工具
- 动态阈值过滤掉不相关的结果
- 结果按相关性得分排序
3. 智能过滤
智能路由应用多个过滤器:- 相关性阈值:只返回高于相似性阈值的工具
- 上下文感知:考虑对话上下文
- 工具可用性:确保工具当前可访问
- 权限过滤:尊重用户访问权限
4. 工具执行
找到的工具可以直接执行:- 参数验证确保正确的工具使用
- 错误处理提供有用的反馈
- 响应格式保持一致性
- 日志记录跟踪工具使用情况进行分析
前置条件
智能路由需要比基础 MCPHub 使用更多的设置:必需组件
- 带有 pgvector 的 PostgreSQL:用于嵌入存储的向量数据库
- 嵌入服务:OpenAI API 或兼容服务
- 环境配置:正确的配置变量
使用智能路由
智能路由端点
通过特殊的$smart 端点访问智能路由:
- HTTP MCP
- SSE (Legacy)
分组范围的智能路由
智能路由支持分组范围的搜索,允许您将工具发现限制在特定分组内的服务器:使用分组范围的智能路由
使用分组范围的智能路由
将您的 AI 客户端连接到特定分组的智能路由端点:此端点只会搜索属于 “production” 分组的服务器中的工具。优势:
- 聚焦结果:只返回相关服务器的工具
- 更好的性能:减少搜索空间以加快查询速度
- 环境隔离:将开发、预发布和生产工具分开
- 访问控制:根据用户权限限制工具发现
工作原理
工作原理
当使用
$smart/{group} 时:- 系统识别指定的分组
- 获取属于该分组的所有服务器
- 将工具搜索过滤到仅限那些服务器
- 返回限定在该分组服务器范围内的结果
固定工具
$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 路由。
渐进式披露模式
渐进式披露是一个优化功能,可以减少使用智能路由时的 Token 消耗。启用后,工具发现工作流从 2 步变为 3 步。什么是渐进式披露?
什么是渐进式披露?
默认情况下,智能路由在
search_tools 结果中返回完整的工具信息,包括完整的参数模式。当处理具有复杂输入模式的工具时,这会消耗大量 Token。渐进式披露 改变了这种行为:search_tools只返回工具名称和描述(最少信息)- 新的
describe_tool端点按需提供完整的参数模式 call_tool像以前一样执行工具
- 处理具有复杂模式的大量工具
- Token 使用优化很重要的场景
- AI 客户端需要浏览多个工具后再选择
启用渐进式披露
启用渐进式披露
通过设置页面或环境变量启用渐进式披露:通过设置界面:
- 导航到 设置 → 智能路由
- 启用”渐进式披露”开关
- 更改立即生效
在 search_tools 中包含服务器描述
在 search_tools 中包含服务器描述
默认情况下,使用
search_tools 只会在工具描述中列出服务器名称。若要同时显示服务器描述(或上游返回的 instructions),请设置:names(默认值)可保持原来的紧凑列表。该列表列出 search_tools 实际搜索的服务器:已启用且已连接或按需启动的服务器。按需启动的服务器未连接时仍会列出,无论是因空闲而关闭还是启动失败,因为 call_tool 会启动它;其他连接失败的服务器在重新连接之前不会列出。上游 instructions 只在连接时获得,因此在 full 模式下,尚未连接过的服务器只显示其配置的描述,或仅显示名称。嵌入任务前缀
嵌入任务前缀
非对称检索模型在训练时对查询和文档使用不同的任务前缀,直接嵌入原始文本时效果明显变差。可在 设置 → 智能路由 中或通过环境变量设置模型所需的前缀:两者默认均为空,即与以前一样嵌入原始文本。前缀按原样使用,请保留末尾空格。修改文档前缀会重新生成所有服务器的工具嵌入;修改查询前缀在下一次搜索时生效。前缀会改变相似度分数(以 EmbeddingGemma 为例,弱匹配下降得比强匹配更多),因此基于原始文本调好的阈值在启用前缀后可能需要重新校准(参见下方的 搜索结果;每个结果都会返回
score)。前缀也计入嵌入的 Token 上限(EMBEDDING_MAX_TOKENS 或模型默认值):前缀会被保留,工具文本会相应提前截断。搜索结果:分数、阈值与 Schema 预算
搜索结果:分数、阈值与 Schema 预算
每个 三者也可以在 设置 → 智能路由 → 搜索结果 中设置,且都不会触发重新嵌入。默认不附带的字段主要供客户端而非模型使用,而且可能很大:上游服务器可能为每个工具附带 base64 格式的
search_tools 结果都带有 score:查询与工具之间的余弦相似度(0-1,保留两位小数),也就是与阈值比较的值。结果按相关性排序,排序时还会考虑工具所在服务器与查询的匹配程度。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示例工作流:
- AI 使用查询 “文件操作” 调用
search_tools - 结果显示工具名称和描述(最少 Token)
- AI 为特定工具调用
describe_tool获取完整的inputSchema - AI 使用正确的参数调用
call_tool
响应格式对比
响应格式对比
标准模式 search_tools 响应:渐进式披露模式 search_tools 响应:describe_tool 响应:
故障排除
数据库连接问题
数据库连接问题
症状:
- 智能路由不可用
- 数据库连接错误
- 嵌入存储失败
- 验证 PostgreSQL 是否正在运行
- 检查 DB_URL 格式
- 确保安装了 pgvector 扩展
- 手动测试连接:
嵌入服务问题
嵌入服务问题
症状:
- 工具索引失败
- 查询处理错误
- API 速率限制错误
- 验证 API 密钥有效性
- 检查网络连接
- 监控速率限制
- 测试嵌入服务:
搜索结果不佳
搜索结果不佳
症状:
- 返回不相关的工具
- 相关性得分低
- 缺少预期的工具
- 调整相似性阈值(
SMART_ROUTING_SIMILARITY_THRESHOLD),可参考每个结果的score选择数值 - 使用更好的描述重新索引工具
- 使用更具体的查询
- 检查工具元数据质量
性能问题
性能问题
症状:
- 查询响应缓慢
- 数据库负载高
- 内存使用激增
- 优化数据库配置
- 增加缓存大小
- 减少批处理大小
- 监控系统资源
密钥已在面板填对,仍然报鉴权失败
密钥已在面板填对,仍然报鉴权失败
症状:
- 工具索引失败,返回鉴权错误(401/403)
- 面板里保存的密钥是有效的,但请求仍被拒绝
- 检查
.env*文件、shell 配置以及容器/服务定义中的OPENAI_API_KEY/AZURE_OPENAI_API_KEY - 移除遗留变量并重启;若提供商或模型也发生变化,请重新索引
- 确认实际生效的密钥是否可用:
最佳实践
查询编写
工具描述
系统维护
定期重新索引:定期重新索引工具以确保嵌入质量。
监控性能:跟踪查询模式并根据使用情况进行优化。
更新模型:随着新嵌入模型的出现,考虑更新到更新的模型。
下一步
身份验证
用户管理和访问控制
监控
系统监控和分析
API 参考
完整的智能路由 API 文档
配置
高级配置选项