使用说明

智能意图路由器

一个复杂的AI请求路由系统，结合了 FastAPI+AI代理+MCP 在统一的架构中。该系统具有一个智能AI代理，可以协调请求路由、用于现代REST端点的FastAPI和用于高级工具功能的模型上下文协议（MCP）。它智能地对用户意图进行分类，检测语言，并使用基于规则或AI代理驱动的编排将请求路由到最合适的语言模型。

🚀 特性

核心路由智能

AI代理编排：使用LLM推理做出上下文感知路由决策的智能AI代理
双路由模式：基于规则的路由和AI代理驱动的编排，以实现最大的灵活性
意图分类：自动将用户请求分类（代码、数学、翻译、创意写作、一般）
语言检测：支持多语言输入和自动语言检测
动态LLM选择：根据意图、语言和上下文将请求路由到最佳模型

高级架构堆栈

FastAPI基金会：具有异步支持和自动文档的现代REST API框架
AI代理核心：基于LLM的智能编排器，对路由决策进行推理
MCP集成：用于高级工具功能和动态发现的模型上下文协议
实时模型发现：从LM Studio实时动态获取可用模型
会话管理：具有上下文感知响应的持续聊天会话

用户体验

对话历史：所有对话都存储在MongoDB中，以便跨会话持久化
上下文感知响应：智能上下文检索可保持对话流和相关性
web界面：基于Streamlit的现代聊天界面，带有markdown渲染
与跨平台支持：VS为Windows、macOS和Linux编写任务和启动配置
LM工作室集成：与LM Studio无缝集成，用于本地模型托管

🏗️ 建筑

FastAPI+AI代理+MCP 建筑

Smart Intent Router实现了尖端技术 三层架构:

🌐 FastAPI层（端口8000）

现代REST API基础：

高性能异步HTTP端点
WebSocket支持实时通信
实时流媒体的服务器发送事件（SSE）
自动OpenAPI文档
CORS支持跨源请求

🤖 AI代理层

智能编排核心：

LLM驱动的推理 用于路由决策
情境感知分析 用户请求和对话历史记录
动态工具发现 能力评估
自适应路由策略 基于模型性能和可用性
多步骤编排 适用于复杂的路由场景

🔧 MCP层（端口3001）

先进的工具生态系统：

标准化工具接口的模型上下文协议
动态工具和资源发现
高级对话上下文管理
LM Studio中的实时模型发现
可扩展插件架构

组件

Smart Intent Router由两个主要组件组成：

1. web客户端 (`web-client/`)

基于Streamlit的聊天界面 具有实时消息功能
Markdown渲染 对代码块进行语法高亮显示
会话管理 有持续的对话记录
REST API客户端 用于与FastAPI端点通信
双路由支持 -可以使用基于规则和AI驱动的路由

2. 服务器 (`smart-intent-router-server/`)

统一的 FastAPI+AI代理+MCP 服务器架构：

🌐 FastAPI REST层：

核心路由: /route_request （基于规则）， /route_request_ai （AI代理驱动）
会话管理：对话和消息的CRUD操作
会话管理：用户会话创建和跟踪
实时通信：WebSocket和SSE端点
健康监测：系统状态和型号可用性

🤖 AI代理层：

智能编排器：具有推理能力的LLM驱动的路由决策
上下文分析：深入了解对话流程和用户意图
动态战略选择：根据请求复杂性调整路由方法
多模型协调：为复杂任务编排多个专业模型
学习与适应：改进基于交互模式的路由决策

🔧 MCP工具层：

工具生态系统: send_to_llm, classify_intent, detect_language
模型管理: get_models_from_lm_studio, get_orchestrator_model
动态发现：实时工具和资源枚举
上下文管理：对话历史和上下文检索

核心组件：

AI代理编排器 (mcp_server/server.py)
- LLM驱动的推理引擎 用于智能路由决策
- 情境感知分析 会话历史和用户意图
- 动态能力评估 可用模型和工具
- 多步骤编排 适用于复杂的路由场景
- 可配置的推理提示 通过 ai_router.system_prompt
- 自动工具和资源发现 对于MCP客户
- 自适应路由策略 基于模型性能和可用性
意图分类器 (intent_classifier/)
- 分析用户消息以确定意图类型
- 支持： code, math, translation, creative writing, general
- 使用基于关键字的分类和LLM回退
- 后续问题的上下文感知分类
语言检测器 (language_detector/)
- 自动检测用户输入的语言
- 支持多种语言的多语言路由
LLM选择器 (llm_selector/)
- 根据意图、语言和上下文动态选择最佳模型
- 可配置的模型映射和回退策略
- 实时模型可用性验证
实时模型发现 (lm_studio_proxy/)
- 直接从LM Studio获取可用型号 /v1/models 端点
- 将实时数据与配置元数据相结合
- LM Studio不可用时智能回退到配置
- 增强的模型验证和健康监测
会话管理器 (utils/conversation_manager.py)
- 管理持久聊天会话和对话历史记录
- 上下文感知消息过滤和令牌计数
- 使用对话摘要进行智能上下文检索

支持组件：

会话管理器 (utils/session_manager.py)
- 用户会话管理和跟踪
- 会话过期和清理
LM工作室代理 (lm_studio_proxy/)
- 用于LM Studio API集成的HTTP客户端
- 本地模型推理的请求/响应处理
- 实时模型发现和可用性检查
响应处理器 (response_handler/)
- 处理和格式化LLM响应
- 处理不同的响应类型和错误情况

FastAPI+AI代理+MCP 整合

该系统作为 统一服务器 具有三个集成层：

FastAPI服务器 （端口8000）-REST API基础
AI代理核心 -智能推理和编排
MCP服务器 （端口3001）-先进的工具生态系统

这种架构的好处:

🧠 智能：AI代理为路由决策提供类似人类的推理
🚀 演出：FastAPI提供高性能REST端点
🔧 可扩展性：MCP支持丰富的工具生态系统和动态功能
🔒 安全：公共API和内部AI推理之间的明确分离
📱 兼容性：Web客户端使用REST，AI系统使用MCP，代理协调两者
🎯 精确度：AI代理随着时间的推移学习和调整路由策略

💾 对话历史管理

智能意图路由器自动 在MongoDB中保存所有对话历史记录，确保您的聊天会话在应用程序重新启动时得到保留，并提供无缝的对话连续性。

主要特点：

永久存储：所有消息、用户会话和对话元数据都存储在MongoDB中
会话连续性：即使在重新启动应用程序后，也要在中断的地方继续对话
上下文保护：该系统维护对话上下文，以进行更连贯的多回合对话
自动管理：无需手动干预-对话会自动保存和检索

数据库集合：

conversations：存储对话元数据和消息历史记录
sessions：管理用户会话数据和跟踪
messages：带有时间戳和元数据的单个消息存储

隐私和数据管理：

默认情况下，对话数据存储在MongoDB实例的本地
使用 delete_messages MCP工具，用于在需要时清除对话历史记录
如果需要，在MongoDB中配置保留策略以进行自动数据清理

📋 配置架构

系统通过以下方式配置 config/smart_intent_router_config.yaml。这是一个可自定义的模板，您可以根据可用型号、支持的语言和特定要求进行修改。

配置参数

意图分类

intents：支持的意图类别数组（例如。， code, math, translation, creative_writing, general)
用户可以根据自己的用例添加或修改意图类型

语言支持

languages：支持的语言代码数组（例如。， en, es, fr, de, ru)
添加语言代码以支持多语言

模型配置

每个模型 models 数组需要：

model_name：LM Studio中显示的确切型号名称
endpoint：API端点URL（通常为 http://localhost:1234/v1/chat/completions)
context_length：模型的最大令牌限制
weight：模型选择的优先级值（较高=较高优先级）
supported_intents：此模型可以处理的意图数组
supported_languages：此模型支持的语言数组
enabled：用于启用/禁用模型的布尔值
is_orchestrator：布尔值标记为编排器模型（用于AI驱动的路由）

编排器模型选择

模型可以被指定为AI驱动路由的编排器：

is_orchestrator: true：将模型标记为能够进行智能路由决策
AI路由器系统提示：编排器应如何表现的可配置说明
自动选择：系统会自动选择第一个启用的编排器模型
回退策略：如果没有可用的编排器，则退回到基于规则的路由

模型选择逻辑

系统支持多种路由策略：

1. 基于规则的路由（传统）

当多个模型可用于相同的意图和语言时：

基于重量的选择：最高的型号 weight 自动选择值
回退命令：如果权重相等，则按配置顺序对模型进行优先级排序
默认处理：回落到 default_model 如果找不到合适的匹配

2. AI代理驱动路由新

使用智能AI代理做出复杂的路由决策：

AI代理选择：自动选择第一个启用的型号 is_orchestrator: true
基于推理的决策：AI代理使用LLM推理分析对话上下文、意图复杂性和模型能力
动态工具发现：代理可以实时发现和利用可用的工具和模型
多步骤编排：可以将复杂的请求分解为多个路由步骤
自适应学习：根据交互模式和结果改进路由策略
智能回退：如果没有可用的编排器代理，则退回到基于规则的路由

3. 实时模型发现

系统现在可以直接从LM Studio获取可用模型：

现场模特列表：查询LM工作室 /v1/models 当前加载模型的端点
配置丰富：将实时数据与配置元数据相结合
智能回退：当LM Studio不可用时，使用基于配置的模型列表
健康监测：跟踪LM Studio连接和型号可用性状态

系统模板

system_templates：每种意图类型的自定义系统消息
提供特定于上下文的提示，以获得更好的响应

AI路由器配置

ai_router.system_prompt：AI驱动路由的系统提示
定义编排LLM的行为和使用工具/资源的方式
可定制的模型选择和工具使用说明

数据库设置

MongoDB配置 用于持久存储
可配置的数据库和集合名称
本地或远程MongoDB实例的连接字符串

AI代理行为的AI路由器配置

ai_router： system_prompt：| 你是一名智能人工智能代理ORCHESTRATOR。你的工作是分析用户请求并根据最合适的专家模型做出智能路由决策。

AI AGENT REASONING PROCESS:
1. Analyze user intent and conversation context
2. Assess available models and their capabilities  
3. Make intelligent routing decision based on reasoning
4. Execute routing via function calls:
   - classify_intent(message="user's exact message")
   - detect_language(prompt="user's exact message") 
   - get_models()
   - send_to_llm(model_name="selected_model", user_message="user's exact message")

system_templates： code：“你是一名编程助理…”#根据你的需求进行定制

为每个意图添加模板


#### Intent Templates
- **`system_templates`**: Custom system messages for each intent type
- Provides context-specific prompting for better responses

#### AI Router Configuration
- **`ai_router.system_prompt`**: System prompt for AI-driven routing
- Defines how the orchestrating LLM should behave and use tools/resources
- Customizable instructions for model selection and tool usage

#### Database Settings
- **MongoDB configuration** for persistent storage
- Configurable database and collection names
- Connection string for local or remote MongoDB instances

## 🛠️ API Reference

### FastAPI REST Endpoints (Port 8000)

#### Core Routing
- **`POST /route_request`** - Rule-based request routing
- **`POST /route_request_ai`** - AI-driven intelligent routing with orchestrator model

#### Conversation Management
- **`POST /conversations`** - Create new conversation
- **`GET /conversations/{user_id}`** - Get user's conversations
- **`GET /conversations/{conversation_id}/messages`** - Get conversation messages
- **`DELETE /conversations/{conversation_id}`** - Delete conversation
- **`DELETE /conversations/{conversation_id}/messages`** - Clear conversation messages

#### Session Management
- **`POST /sessions`** - Create new user session
- **`GET /sessions/{session_id}`** - Check session status

#### Real-time Communication
- **`GET /stream_response/{conversation_id}`** - Server-Sent Events streaming
- **`WebSocket /ws/{conversation_id}`** - Bidirectional real-time communication

#### System Health
- **`GET /health`** - System health check with model availability

### MCP Tools (Port 3001)

#### AI Orchestration Tools
- **`send_to_llm`** - Direct LLM communication
- **`classify_intent`** - Intent classification with conversation context
- **`detect_language`** - Language detection
- **`get_models_from_lm_studio`** - Real-time model discovery from LM Studio
- **`get_models_from_config`** - Get models from configuration
- **`get_orchestrator_model`** - Get designated orchestrator model
- **`route_request_ai`** - AI-driven routing orchestration

#### System Management Tools
- **`health_check`** - Internal health monitoring with LM Studio connectivity
- **`get_conversation_context`** - Retrieve conversation context for AI

#### Legacy Tools (Maintained for Compatibility)
- **`route_request`** - Rule-based routing
- **`create_session`** - Create new user session
- **`create_conversation`** - Create new conversation
- **`get_conversations`** - Retrieve user conversations
- **`get_messages`** - Retrieve conversation messages
- **`delete_messages`** - Clear conversation history

## 🚦 Getting Started

### Prerequisites
- Python 3.8+
- MongoDB (local or remote)
- LM Studio (for local model hosting)

### Setup Steps

1. **Clone the repository**
   ```bash
   git clone https://github.com/vika4433/smart-intent-router.git
   cd smart-intent-router

设置Python环境

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

注意：安装python 3.11.2

在LM Studio中下载和配置模型
- 从下载LM Studio lmstudio.ai
- 安装并打开LM Studio
- 从模型存储库下载您喜欢的模型：
  - 用于编码：Qwen2.5编码器、CodeLlama或类似产品
  - 一般任务：Llama 3.2、Mistral或类似型号
  - 数学：WizardMath或专门的数学模型
- 启动LM Studio本地服务器：
  - 转到LM Studio中的“本地服务器”选项卡
  - 加载您下载的模型
  - 点击“启动服务器”（默认端口：1234）
- 重要：请注意LM Studio中显示的确切型号名称——您需要这些名称进行配置
设置MongoDB
- 在本地安装MongoDB或使用MongoDB Atlas
- 对于本地安装： brew install mongodb-community （macOS）或遵循 MongoDB安装指南
- 启动MongoDB服务（默认连接： mongodb://localhost:27017)
配置系统
- 编辑 config/smart_intent_router_config.yaml 使用您的设置：
  - 更新 model_name LM Studio中具有精确名称的字段
  - 验证端点（默认值： http://localhost:1234/v1/chat/completions)
  - 设置模型权重：值越高（例如2.0）=优先级越高
  - 为每个模型配置支持的意图和语言
  - 如果需要，更新数据库连接字符串
运行系统

该系统现在同时运行FastAPI和MCP服务器。您可以通过多种方式启动它们：

选项A：使用VS代码（推荐）
- 在VS Code中打开项目
- 使用“运行服务器和Web客户端”复合启动配置
- 这将自动启动服务器和web客户端
选项B：手动启动
```
# Start the hybrid server (FastAPI + MCP)
cd smart-intent-router-server
python src/mcp_server/server.py

# In another terminal, start the web client
cd web-client
streamlit run src/app.py
```
选项C：使用终端脚本
```
# Start server
./scripts/start_server.sh

# Start client
./scripts/start_client.sh
```
访问应用程序
- web界面：打开浏览器 http://localhost:8501
- FastAPI服务器：可在 http://localhost:8000
- MCP服务器：可在 http://localhost:3001 （适用于AI代理）
- 开始和你的智能路由器聊天吧！

路由模式

系统支持两种路由模式，您可以在它们之间进行选择：

1. 基于规则的路由 (`/route_request`)

传统意图→ 模型映射
快速且可预测
使用配置规则和模型权重
适用于简单、定义明确的路由场景

2. AI代理驱动路由 (`/route_request_ai`)

使用智能AI代理做出复杂的路由决策
基于推理：AI代理分析上下文并做出类似人类的决策
上下文感知和适应对话流
可以处理复杂的路由场景和多步骤编排
更适合对话式人工智能、模糊请求和从模式中学习

跨平台开发

该项目包括用于无缝开发的VS代码配置视窗, macOS，以及 Linux:

VS代码启动配置

“仅运行FastAPI服务器” -仅启动服务器
“仅运行Web客户端” -仅启动Streamlit客户端
“运行服务器和Web客户端” -两者复合发射

跨平台脚本

视窗：PowerShell脚本(.ps1)
macOS/Linux：Bash脚本(.sh)
自动检测：VS代码任务自动使用正确的脚本

预启动任务

kill-server-if-running -停止任何现有服务器进程
wait-for-server -等待服务器准备就绪
wait-for-server-long -延长复杂启动场景的等待时间

有关详细的设置说明，请参阅 docs/setup_instructions.md

🆕 最近的增强功能

AI代理编排

智能AI代理：使用LLM推理进行复杂路由决策的新AI代理
情境感知分析：深入了解对话流程和用户意图模式
动态工具发现：MCP协议支持实时能力发现
可配置的AI代理：完全可定制的系统提示，用于AI代理推理行为
多步骤编排：AI代理可以将复杂的请求分解为多个路由步骤

实时模型发现

现场模型获取：自动发现当前加载在LM Studio中的模型
健康监测：实时跟踪LM Studio连接和模型可用性
智能回退：需要时，可优雅地降级为基于配置的模型

FastAPI+AI代理+MCP 建筑

统一堆栈：用于REST端点的FastAPI+用于智能推理的AI代理+用于高级工具的MCP
三层集成：明确分离关注点，实现无缝集成
AI优先设计：人工智能代理是路由决策的核心，具有类似人类的推理能力

开发者体验

与跨平台支持：VS代码配置在Windows、macOS和Linux上无缝工作
自动设置：复合启动配置同时启动服务器和客户端
增强测试：用于编排器和配置验证的全面测试套件

📚 文档

安装说明: docs/setup_instructions.md
开发者指南: docs/developer.md
api参考: docs/api_reference.md
架构概述: docs/architecture.md

🔧 技术栈

后端python 快速API （REST端点）， AI 代理 （LLM驱动的推理）， FastMCP （模型上下文协议）
前端：流光灯
数据库：MongoDB
AI模型：LM工作室（本地模特主持）
沟通：REST API、WebSockets、服务器发送事件、MCP协议
智能层：具有LLM推理的AI代理，用于自适应路由决策
实时功能：实时模型发现、流式响应、双向通信
发展：支持跨平台任务的VS代码（Windows/macOS/Linux）

使用说明

智能意图路由器

🚀 特性

核心路由智能

高级架构堆栈

用户体验

🏗️ 建筑

FastAPI+AI代理+MCP 建筑

🌐 FastAPI层 （端口8000）

🤖 AI代理层

🔧 MCP层 （端口3001）

组件

1. web客户端 (web-client/)

2. 服务器 (smart-intent-router-server/)

🌐 FastAPI REST层：

🤖 AI代理层：

🔧 MCP工具层：

核心组件：

支持组件：

FastAPI+AI代理+MCP 整合

💾 对话历史管理

主要特点：

数据库集合：

隐私和数据管理：

📋 配置架构

配置参数

意图分类

语言支持

模型配置

编排器模型选择

模型选择逻辑

1. 基于规则的路由 （传统）

2. AI代理驱动路由 新

3. 实时模型发现

系统模板

AI路由器配置

数据库设置

AI代理行为的AI路由器配置

为每个意图添加模板

路由模式

1. 基于规则的路由 (/route_request)

2. AI代理驱动路由 (/route_request_ai)

跨平台开发

VS代码启动配置

跨平台脚本

预启动任务

🆕 最近的增强功能

AI代理编排

实时模型发现

FastAPI+AI代理+MCP 建筑

开发者体验

📚 文档

🔧 技术栈

相关 MCP

代码索引分析工具

YouTube字幕提取服务

代码运行服务

代码分析服务器

语言服务协议MCP

语言服务器协议模型上下文协议

🌐 FastAPI层（端口8000）

🔧 MCP层（端口3001）

1. web客户端 (`web-client/`)

2. 服务器 (`smart-intent-router-server/`)

1. 基于规则的路由（传统）

2. AI代理驱动路由新

1. 基于规则的路由 (`/route_request`)

2. AI代理驱动路由 (`/route_request_ai`)