diff --git a/articals/assets/sr-conf.png b/articals/assets/sr-conf.png new file mode 100644 index 0000000..421006d Binary files /dev/null and b/articals/assets/sr-conf.png differ diff --git a/articals/assets/sr-dc.png b/articals/assets/sr-dc.png new file mode 100644 index 0000000..bc970b7 Binary files /dev/null and b/articals/assets/sr-dc.png differ diff --git a/articals/assets/sr-map-call.png b/articals/assets/sr-map-call.png new file mode 100644 index 0000000..1e5ed84 Binary files /dev/null and b/articals/assets/sr-map-call.png differ diff --git a/articals/assets/sr-map-result.png b/articals/assets/sr-map-result.png new file mode 100644 index 0000000..fd08e45 Binary files /dev/null and b/articals/assets/sr-map-result.png differ diff --git a/articals/assets/sr-map-search.png b/articals/assets/sr-map-search.png new file mode 100644 index 0000000..96929bd Binary files /dev/null and b/articals/assets/sr-map-search.png differ diff --git a/articals/assets/sr-servers.png b/articals/assets/sr-servers.png new file mode 100644 index 0000000..66830ad Binary files /dev/null and b/articals/assets/sr-servers.png differ diff --git a/articals/assets/sr-time.png b/articals/assets/sr-time.png new file mode 100644 index 0000000..d744b45 Binary files /dev/null and b/articals/assets/sr-time.png differ diff --git a/articals/assets/sr-tools.png b/articals/assets/sr-tools.png new file mode 100644 index 0000000..06619ed Binary files /dev/null and b/articals/assets/sr-tools.png differ diff --git a/articals/assets/sr-web.png b/articals/assets/sr-web.png new file mode 100644 index 0000000..bd2bb15 Binary files /dev/null and b/articals/assets/sr-web.png differ diff --git a/doc/intro.md b/articals/intro.md similarity index 100% rename from doc/intro.md rename to articals/intro.md diff --git a/doc/intro2.md b/articals/intro2.md similarity index 100% rename from doc/intro2.md rename to articals/intro2.md diff --git a/articals/smart-routing.md b/articals/smart-routing.md new file mode 100644 index 0000000..9613fa1 --- /dev/null +++ b/articals/smart-routing.md @@ -0,0 +1,177 @@ +# 无限工具，智能路由：MCPHub 引领 AI 工具使用新范式 + +## 概述 + +在现代 AI 应用中，随着 MCP 服务器数量的快速增长和工具种类的不断丰富，如何从数百个可用工具中快速定位最适合当前任务的工具，成为开发者和 AI 助手面临的一项重要挑战。 + +传统做法要么将所有工具暴露给 AI 助手处理，导致 token 消耗巨大、响应延迟严重；要么依赖开发者手动分组配置，灵活性和智能性不足。 + +MCPHub 推出的智能路由功能，基于向量语义搜索技术，实现了自然语言驱动的工具发现与精准推荐。它让 AI 助手能够像人类专家一样，根据任务描述自动选择最优工具组合，大幅提升了系统效率和用户体验。 + +## 什么是智能路由 + +### 技术原理 + +智能路由是 MCPHub 的核心功能之一。它将每个 MCP 工具的名称和描述嵌入为高维语义向量。当用户发起自然语言任务请求时，系统会将该请求也转换为向量，通过计算相似度，快速返回最相关的工具列表。 + +这一过程摒弃了传统的关键词匹配，具备更强的语义理解能力，能够处理自然语言的模糊性和多样性。 + +### 核心组件 + +- **向量嵌入引擎**：支持如 `text-embedding-3-small`、`bge-m3` 等主流模型，将文本描述转为语义向量。 +- **PostgreSQL + pgvector**：使用开源向量数据库方案，支持高效的向量索引和搜索。 +- **两步工作流分离**： + - `search_tools`：负责语义工具发现 + - `call_tool`：执行实际工具调用逻辑 + +## 为什么需要智能路由 + +### 1. 减少认知负荷 + +- 当工具数量超过 100 个，AI 模型难以处理所有工具上下文。 +- 智能路由通过语义压缩，将候选工具缩小至 5～10 个，提高决策效率。 + +### 2. 显著降低 token 消耗 + +- 传统做法传入全量工具描述，可能消耗上千 token。 +- 使用智能路由，通常可将 token 使用降低 70～90%。 + +### 3. 提升调用准确率 + +- 理解任务语义：如“图片增强”→选择图像处理工具，而不是依赖命名关键词。 +- 上下文感知：考虑输入/输出格式和工具组合能力，匹配更合理的执行链路。 + +## 智能路由配置指南 + +### 1. 启动支持 `pgvector` 的 PostgreSQL 数据库 + +```bash +docker run --name mcphub-postgres \ + -e POSTGRES_DB=mcphub \ + -e POSTGRES_USER=mcphub \ + -e POSTGRES_PASSWORD=your_password \ + -p 5432:5432 \ + -d pgvector/pgvector:pg17 +``` + +如已部署 PostgreSQL，可直接创建数据库并启用 `pgvector` 扩展： + +```sql +CREATE DATABASE mcphub; +CREATE EXTENSION vector; +``` + +### 2. 获取 embedding 模型的 API Key + +前往 OpenAI 或其他提供商获取嵌入模型的 API Key。国内用户推荐使用硅基流动 `bge-m3` 免费模型，没有注册过的用户可以使用我的邀请链接：[https://cloud.siliconflow.cn/i/TQhVYBvA](https://cloud.siliconflow.cn/i/TQhVYBvA)。 + +### 3. 控制台配置 + +![配置](./assets/sr-conf.png) + +在 MCPHub 控制台中，进入「智能路由」配置页面，填写以下信息： + +- **数据库 URL**：`postgresql://mcphub:your_password@localhost:5432/mcphub` +- **OpenAI API Key** ：填写你获取的嵌入模型 API Key +- **OpenAI 基础 URL**：`https://api.siliconflow.cn/v1` +- **嵌入模型**：推荐使用 `BAAI/bge-m3` + +开启「启用智能路由」后系统会自动： + +- 对所有工具生成向量嵌入 +- 构建向量索引 +- 自动监听新增工具，更新索引 + +## 工具定义 + +### search_tools - 工具搜索 + +```ts +{ + "name": "search_tools", + "arguments": { + "query": "help me resize and convert images", + "limit": 10 + } +} +``` + +### call_tool - 工具执行 + +```ts +{ + "name": "call_tool", + "arguments": { + "toolName": "image_resizer", + "arguments": { + "input_path": "/path/to/image.png", + "width": 800, + "height": 600 + } + } +} +``` + +## 演示 + +下面我将通过几个示例来展示如何使用智能路由。 + +首先，我们需要在 mcphub 添加几个不同类型的 MCP 服务器：`amap`、`time-map`、`fetch`。 + +![添加服务器](./assets/sr-servers.png) + +然后我们需要选择一个支持 MCP 的客户端，这里选择国产的 DeepChat，聊天模型选择 `Qwen3-14B`。 + +接着，在 DeepChat 中添加 mcphub 的智能路由端点： + +![添加智能路由](./assets/sr-dc.png) + +添加成功后，就可以在工具中看到 `search_tools` 和 `call_tool` 两个工具了： + +![工具列表](./assets/sr-tools.png) + +### 示例 1：地图导航 + +输入：从北京如何导航到上海。 + +结果： + +![地图导航](./assets/sr-map-result.png) + +可以看到，DeepChat 先调用了 `search_tools` 工具： + +![搜索工具](./assets/sr-map-search.png) + +然后再调用 `call_tool` 查询具体的导航信息： + +![调用工具](./assets/sr-map-call.png) + +### 示例 2：查询时间 + +输入：使用工具查询美国现在的时间是几点 + +结果： + +![查询时间](./assets/sr-time.png) + +需要说明的是，由于不同的模型对工具调用的支持程度不同，可能会出现一些差异。比如在这个例子中，为了提高准确性，我在输入中明确提到了“使用工具”。 + +### 示例 3：查看网页 + +输入：打开 baidu.com 看看有什么 + +结果： + +![查看网页](./assets/sr-web.png) + +可以看到，DeepChat 成功调用了工具，不过由于百度的 robots.txt 限制，无法获取到具体内容。 + +## 结语 + +借助 MCPHub 的智能路由功能，AI 助手能够更高效地处理复杂任务，显著减少不必要的 token 消耗，同时提升工具调用的准确性与灵活性。作为面向未来的 AI 工具发现与调用基础设施，智能路由不仅使 AI 更聪明地选择和组合工具，还为多 Agent 协同提供了清晰、可控且可扩展的底层能力支撑。 + +> MCPHub 只是我一时兴起开发的小项目，没想到收获了这么多关注，非常感谢大家的支持！目前 MCPHub 还有不少地方需要优化和完善，我也专门建了个交流群，感兴趣的可以添加下面的微信。 + +![微信](../assets/wexin.png) + +> 同时，欢迎大家一起参与建设！项目地址为：[https://github.com/samanhappy/mcphub](https://github.com/samanhappy/mcphub)。 diff --git a/doc/smart-routing.md b/doc/smart-routing.md deleted file mode 100644 index 5dcee9e..0000000 --- a/doc/smart-routing.md +++ /dev/null @@ -1,271 +0,0 @@ -# 智能工具发现，精准调用：MCPHub 智能路由重新定义 AI 工具选择 - -## 概述 - -在现代 AI 应用中，随着 MCP 服务器数量的快速增长和工具种类的日益丰富，如何从数百个可用工具中快速找到最适合当前任务的工具，成为了一个日益突出的挑战。传统方式下，AI 助手要么被迫处理所有可用工具的庞大列表，导致 token 消耗激增和响应延迟，要么依赖开发者手动分组，缺乏灵活性和智能化。MCPHub 的智能路由功能基于向量语义搜索技术，实现了自然语言驱动的工具发现与精准推荐，让 AI 助手能够像人类专家一样，根据任务描述智能地选择最合适的工具组合，大幅提升工作效率和用户体验。 - -## 智能路由是什么 - -### 技术原理 - -智能路由是 MCPHub 的核心创新功能，它基于现代向量语义搜索技术，将每个 MCP 工具的描述、参数和功能特征转换为高维向量表示。当用户提出任务需求时，系统将需求同样转换为向量，通过计算向量间的余弦相似度，快速定位最相关的工具集合。这种方法不依赖精确的关键词匹配，而是理解语义层面的相关性，能够处理自然语言的模糊性和多样性。 - -### 核心组件 - -**向量嵌入引擎**：支持 OpenAI text-embedding-3-small、BGE-M3 等多种主流嵌入模型，将工具描述转换为 1536 维或 1024 维向量表示，捕获工具功能的语义特征。 - -**PostgreSQL + pgvector 数据库**：采用业界领先的向量数据库解决方案，支持高效的向量索引和相似度搜索，能够在毫秒级时间内从大量工具中找到最相关的候选。 - -**动态阈值算法**：根据查询复杂度和具体程度自动调整相似度阈值，确保既不遗漏相关工具，也不引入无关噪声。简单查询使用较低阈值（0.2）获得更多样化结果，具体查询使用较高阈值（0.4）确保精确匹配。 - -**两步工作流**：`search_tools` 负责工具发现，`call_tool` 负责工具执行，清晰分离发现和执行逻辑，提供更好的可控性和调试体验。 - -## 为什么要使用智能路由 - -### 1. 解决工具选择的认知负荷 - -- **信息过载问题**：当 MCP 服务器数量超过 10 个、工具总数超过 100 个时，AI 助手面临严重的信息过载，难以在合理时间内做出最优选择。 -- **智能路由优势**：通过语义搜索将候选工具缩减到 5-10 个最相关的选项，让 AI 助手能够专注于理解和使用最合适的工具，而不是被迫处理庞大的工具清单。 - -### 2. 大幅降低 Token 消耗 - -- **传统方式的成本**：向 AI 模型传递完整的工具列表会消耗大量 token，特别是当工具描述详细时，单次请求可能消耗数千 token。 -- **智能路由的效益**：只传递最相关的工具信息，通常可以将工具相关的 token 消耗降低 70-90%，显著减少 API 调用成本，特别是在频繁交互的场景中。 - -### 3. 提升工具使用的准确性 - -- **语义理解能力**：智能路由能够理解"图片处理"、"数据分析"、"文档转换"等抽象概念，将其映射到具体的工具实现，避免了传统关键词匹配的局限性。 -- **上下文感知**：考虑工具的输入输出模式和使用场景，推荐最适合当前任务流程的工具组合。 - -![智能路由工作原理](../assets/smart-routing-flow.png) - -## 如何使用智能路由 - -### 配置智能路由 - -#### 1. 数据库配置 - -智能路由需要 PostgreSQL 数据库支持 pgvector 扩展： - -```bash -# 使用 Docker 快速启动支持 pgvector 的 PostgreSQL -docker run --name mcphub-postgres \ - -e POSTGRES_DB=mcphub \ - -e POSTGRES_USER=mcphub \ - -e POSTGRES_PASSWORD=your_password \ - -p 5432:5432 \ - -d pgvector/pgvector:pg16 -``` - -#### 2. 在 MCPHub 控制台配置智能路由 - -访问 MCPHub 设置页面（http://localhost:3000/settings），在"智能路由配置"部分填写： - -- **数据库 URL**：`postgresql://mcphub:your_password@localhost:5432/mcphub` -- **OpenAI API Key**：您的 OpenAI API 密钥 -- **API Base URL**：可选，默认为 `https://api.openai.com/v1` -- **嵌入模型**：推荐使用 `text-embedding-3-small`（1536 维，性价比最佳） - -![智能路由配置界面](../assets/smart-routing-config.png) - -#### 3. 启用智能路由 - -配置完成后，开启"启用智能路由"开关。系统将自动： - -- 为所有已连接的 MCP 服务器工具生成向量嵌入 -- 建立向量索引以支持快速搜索 -- 在后续新增工具时自动更新向量数据库 - -### 智能工具发现的使用方式 - -启用智能路由后，MCPHub 会自动提供两个核心工具： - -#### search_tools - 智能工具搜索 - -```typescript -// 使用示例 -{ - "name": "search_tools", - "arguments": { - "query": "help me process images and resize them", // 自然语言查询 - "limit": 10 // 返回结果数量 - } -} -``` - -**查询策略建议**： - -- **宽泛查询**：使用较高的 limit（20-30），如"数据处理工具" -- **精确查询**：使用较低的 limit（5-10），如"将 PNG 图片转换为 WebP 格式" -- **分步查询**：复杂任务可以分解为多个具体查询 - -#### call_tool - 精准工具执行 - -```typescript -// 使用示例 -{ - "name": "call_tool", - "arguments": { - "toolName": "image_resize", // 从 search_tools 结果中获取的工具名 - "arguments": { // 根据工具的 inputSchema 提供参数 - "input_path": "/path/to/image.png", - "width": 800, - "height": 600 - } - } -} -``` - -### 实际应用场景演示 - -#### 场景 1：图像处理工作流 - -```markdown -用户请求：我需要批量处理一些产品图片，调整大小并转换格式 - -AI 工作流： - -1. search_tools("image processing batch resize convert format") - → 返回：image_batch_processor, format_converter, image_optimizer -2. call_tool("image_batch_processor", {...}) - → 执行批量图像处理 -``` - -#### 场景 2：数据分析任务 - -```markdown -用户请求：分析这个 CSV 文件的销售数据，生成可视化图表 - -AI 工作流： - -1. search_tools("CSV data analysis visualization charts") - → 返回：csv_analyzer, chart_generator, statistics_calculator -2. call_tool("csv_analyzer", {"file_path": "sales.csv"}) -3. call_tool("chart_generator", {"data": analysis_result}) -``` - -#### 场景 3：文档处理流水线 - -```markdown -用户请求：将 Word 文档转换为 PDF，然后提取其中的文本内容 - -AI 工作流： - -1. search_tools("document conversion Word to PDF") - → 返回：doc_converter, pdf_generator -2. call_tool("doc_converter", {"input": "document.docx", "output_format": "pdf"}) -3. search_tools("PDF text extraction") - → 返回：pdf_text_extractor, ocr_processor -4. call_tool("pdf_text_extractor", {"pdf_path": "document.pdf"}) -``` - -### 高级配置选项 - -#### 多模型支持 - -智能路由支持多种嵌入模型，可根据需求选择： - -```json -{ - "embeddingModel": "text-embedding-3-small", // OpenAI，1536维，平衡性能和成本 - "embeddingModel": "text-embedding-3-large", // OpenAI，3072维，最高精度 - "embeddingModel": "bge-m3" // 开源模型，1024维，支持多语言 -} -``` - -#### 自定义 API 端点 - -支持使用自建的嵌入服务或其他 OpenAI 兼容的 API： - -```json -{ - "openaiApiBaseUrl": "https://your-api-endpoint.com/v1", - "openaiApiKey": "your-custom-api-key" -} -``` - -## 性能优化与最佳实践 - -### 查询优化策略 - -**分层查询**：对于复杂任务，使用从宽泛到具体的查询策略： - -``` -1. 宽泛查询："文档处理工具" (limit: 20) -2. 具体查询："PDF 转 Word 转换器" (limit: 5) -``` - -**上下文相关性**：在查询中包含任务上下文信息： - -``` -好：search_tools("为电商网站批量压缩产品图片") -较好：search_tools("图片压缩工具") -``` - -**动态调整**：根据返回结果质量动态调整查询词和限制数量。 - -### 数据库性能调优 - -**索引优化**：智能路由自动创建最优的向量索引： - -```sql -CREATE INDEX idx_vector_embeddings_embedding -ON vector_embeddings USING ivfflat (embedding vector_cosine_ops) -WITH (lists = 100); -``` - -**内存配置**：对于大规模部署，建议增加 PostgreSQL 内存配置： - -``` -shared_buffers = 256MB -effective_cache_size = 1GB -work_mem = 64MB -``` - -### 监控与调试 - -**相似度阈值监控**：观察搜索结果的相似度分数，调整阈值以获得最佳效果。 - -**查询效果分析**：定期检查常用查询的返回结果，优化工具描述以提高搜索准确性。 - -## 智能路由的技术优势 - -### 语义理解能力 - -与传统的关键词匹配相比，智能路由能够理解： - -- **同义词和近义词**："图片"和"图像"、"转换"和"变换" -- **上下层级概念**："数据可视化"包含"图表生成"、"统计图绘制"等 -- **任务意图推理**："我要做一个数据报告"自动关联数据分析、图表生成、文档创建等工具 - -### 多语言支持 - -智能路由支持中英文混合查询，能够处理： - -``` -search_tools("图片 resize 和 format conversion") -search_tools("将文档转换为 PDF 格式") -search_tools("image processing and 格式转换") -``` - -### 容错能力 - -具备一定的容错能力，能够处理： - -- 拼写错误：自动纠正常见拼写错误 -- 模糊描述：从不完整的描述中推导完整意图 -- 领域术语：理解特定领域的专业术语 - -## 结语 - -MCPHub 的智能路由功能代表着 MCP 生态系统向智能化方向发展的重要一步。通过引入向量语义搜索技术，它不仅解决了工具数量激增带来的选择困难，更为 AI 助手提供了类似人类专家的工具发现和选择能力。 - -随着 MCP 服务器生态的不断丰富，智能路由将成为连接用户需求与丰富工具资源的关键桥梁。它让开发者无需担心工具管理的复杂性，让用户享受到更加智能和高效的 AI 助手体验。 - -未来，我们还将继续优化智能路由的算法，引入更多先进的 AI 技术，如基于强化学习的工具推荐、多模态工具理解等，为 MCP 生态系统注入更强的智能化动力。 - -智能路由不仅仅是一个技术功能，更是 MCPHub 对于"让 AI 工具使用变得简单而智能"这一愿景的具体实现。在这个工具爆炸的时代，智能路由让我们重新定义了 AI 与工具的交互方式。 - -项目地址：https://github.com/samanhappy/mcphub - -![智能路由架构图](../assets/smart-routing-architecture.png) diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.json index 28f662a..49bc2c2 100644 --- a/frontend/src/locales/en.json +++ b/frontend/src/locales/en.json @@ -283,7 +283,7 @@ "systemConfigUpdated": "System configuration updated successfully", "enableSmartRouting": "Enable Smart Routing", "enableSmartRoutingDescription": "Enable smart routing feature to search the most suitable tool based on input (using $smart group name)", - "dbUrl": "PostgreSQL URL (with pgvector support)", + "dbUrl": "PostgreSQL URL (requires pgvector support)", "dbUrlPlaceholder": "e.g. postgresql://user:password@localhost:5432/dbname", "openaiApiBaseUrl": "OpenAI API Base URL", "openaiApiBaseUrlPlaceholder": "https://api.openai.com/v1", diff --git a/frontend/src/locales/zh.json b/frontend/src/locales/zh.json index db1b3d8..a3e74c7 100644 --- a/frontend/src/locales/zh.json +++ b/frontend/src/locales/zh.json @@ -284,7 +284,7 @@ "systemConfigUpdated": "系统配置更新成功", "enableSmartRouting": "启用智能路由", "enableSmartRoutingDescription": "开启智能路由功能，根据输入自动搜索最合适的工具（使用 $smart 分组）", - "dbUrl": "PostgreSQL 连接地址（支持 pgvector）", + "dbUrl": "PostgreSQL 连接地址（必须支持 pgvector）", "dbUrlPlaceholder": "例如: postgresql://user:password@localhost:5432/dbname", "openaiApiBaseUrl": "OpenAI API 基础地址", "openaiApiBaseUrlPlaceholder": "https://api.openai.com/v1",