Smart Intent Router

智能意图路由器

一个复杂的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 整合

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

1. FastAPI服务器 （端口8000）-REST API基础
2. AI代理核心 -智能推理和编排
3. 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. 基于规则的路由 （传统）

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

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

2. AI代理驱动路由 新

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

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

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**

git clone https://github.com/vika4433/smart-intent-router.git cd smart-intent-router

2. **设置Python环境**

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

   注意：安装python 3.11.2

1. **在LM Studio中下载和配置模型**

   - 从下载LM Studio [lmstudio.ai](https://lmstudio.ai)
   - 安装并打开LM Studio
   - 从模型存储库下载您喜欢的模型：
     - 用于编码：Qwen2.5编码器、CodeLlama或类似产品
     - 一般任务：Llama 3.2、Mistral或类似型号
     - 数学：WizardMath或专门的数学模型
   - 启动LM Studio本地服务器：
     - 转到LM Studio中的“本地服务器”选项卡
     - 加载您下载的模型
     - 点击“启动服务器”（默认端口：1234）
   - **重要**：请注意LM Studio中显示的确切型号名称——您需要这些名称进行配置

1. **设置MongoDB**

   - 在本地安装MongoDB或使用MongoDB Atlas
   - 对于本地安装： `brew install mongodb-community` （macOS）或遵循 [MongoDB安装指南](https://docs.mongodb.com/manual/installation/)
   - 启动MongoDB服务（默认连接： `mongodb://localhost:27017`)

1. **配置系统**

   - 编辑 `config/smart_intent_router_config.yaml` 使用您的设置：
     - 更新 `model_name` LM Studio中具有精确名称的字段
     - 验证端点（默认值： `http://localhost:1234/v1/chat/completions`)
     - 设置模型权重：值越高（例如2.0）=优先级越高
     - 为每个模型配置支持的意图和语言
     - 如果需要，更新数据库连接字符串

1. **运行系统**

   该系统现在同时运行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

1. **访问应用程序**

   - **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）