mcphub/docs/zh/features/smart-routing.mdx

---
title: '智能路由'
description: '使用向量语义搜索的 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
    ```
  </Tab>

  <Tab title="SSE (Legacy)">
    ```
    http://localhost:3000/sse/$smart
    ```
  </Tab>
</Tabs>

{/* ## 性能优化

### 嵌入缓存

智能路由缓存嵌入以提高性能：

```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": "完美适合这个任务的工具"
  }'
``` */}

## 故障排除

<AccordionGroup>
  <Accordion title="数据库连接问题">
    **症状：**
    - 智能路由不可用
    - 数据库连接错误
    - 嵌入存储失败

    **解决方案：**
    1. 验证 PostgreSQL 是否正在运行
    2. 检查 DATABASE_URL 格式
    3. 确保安装了 pgvector 扩展
    4. 手动测试连接：
    ```bash
    psql $DATABASE_URL -c "SELECT 1;"
    ```

  </Accordion>

  <Accordion title="嵌入服务问题">
    **症状：**
    - 工具索引失败
    - 查询处理错误
    - 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"}'
    ```

  </Accordion>

  <Accordion title="搜索结果不佳">
    **症状：**
    - 返回不相关的工具
    - 相关性得分低
    - 缺少预期的工具

    **解决方案：**
    1. 调整相似性阈值
    2. 使用更好的描述重新索引工具
    3. 使用更具体的查询
    4. 检查工具元数据质量
    ```bash
    # 重新索引所有工具
    curl -X POST http://localhost:3000/api/smart-routing/reindex \
      -H "Authorization: Bearer YOUR_JWT_TOKEN"
    ```

  </Accordion>

  <Accordion title="性能问题">
    **症状：**
    - 查询响应缓慢
    - 数据库负载高
    - 内存使用激增

    **解决方案：**
    1. 优化数据库配置
    2. 增加缓存大小
    3. 减少批处理大小
    4. 监控系统资源
    ```bash
    # 检查系统性能
    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>