> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcphub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 智能路由

> 使用向量语义搜索的 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 theme={null}
    SMART_ROUTING_PROGRESSIVE_DISCLOSURE=true
    ```
  </Accordion>

  <Accordion title="在 search_tools 中包含服务器描述">
    默认情况下，`search_tools` 只会在工具描述中列出服务器名称。若要同时显示服务器描述（或上游返回的 instructions），请设置：

    ```bash theme={null}
    SMART_ROUTING_SERVER_DESCRIPTION_MODE=full
    ```

    使用 `names`（默认值）可保持原来的紧凑列表。
  </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 theme={null}
    {
      "tools": [
        {
          "name": "read_file",
          "description": "读取文件内容",
          "inputSchema": {
            "type": "object",
            "properties": {
              "path": { "type": "string", "description": "要读取的文件路径" },
              "encoding": { "type": "string", "default": "utf-8" }
            },
            "required": ["path"]
          }
        }
      ]
    }
    ```

    **渐进式披露模式 search\_tools 响应：**

    ```json theme={null}
    {
      "tools": [
        {
          "name": "read_file",
          "description": "读取文件内容"
        }
      ],
      "metadata": {
        "progressiveDisclosure": true,
        "guideline": "使用 describe_tool 获取完整的参数模式后再调用。"
      }
    }
    ```

    **describe\_tool 响应：**

    ```json theme={null}
    {
      "tool": {
        "name": "read_file",
        "description": "读取文件内容",
        "inputSchema": {
          "type": "object",
          "properties": {
            "path": { "type": "string", "description": "要读取的文件路径" },
            "encoding": { "type": "string", "default": "utf-8" }
          },
          "required": ["path"]
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## 故障排除

<AccordionGroup>
  <Accordion title="数据库连接问题">
    **症状：**

    * 智能路由不可用
    * 数据库连接错误
    * 嵌入存储失败

    **解决方案：**

    1. 验证 PostgreSQL 是否正在运行
    2. 检查 DB\_URL 格式
    3. 确保安装了 pgvector 扩展
    4. 手动测试连接：

    ```bash theme={null}
    psql $DB_URL -c "SELECT 1;"
    ```
  </Accordion>

  <Accordion title="嵌入服务问题">
    **症状：**

    * 工具索引失败
    * 查询处理错误
    * API 速率限制错误

    **解决方案：**

    1. 验证 API 密钥有效性
    2. 检查网络连接
    3. 监控速率限制
    4. 测试嵌入服务：

    ```bash theme={null}
    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 theme={null}
    # 重新索引所有工具
    curl -X POST http://localhost:3000/api/smart-routing/reindex \
      -H "Authorization: Bearer YOUR_JWT_TOKEN"
    ```
  </Accordion>

  <Accordion title="性能问题">
    **症状：**

    * 查询响应缓慢
    * 数据库负载高
    * 内存使用激增

    **解决方案：**

    1. 优化数据库配置
    2. 增加缓存大小
    3. 减少批处理大小
    4. 监控系统资源

    ```bash theme={null}
    # 检查系统性能
    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>