refactor: 单图方案重构 + 动态模型选择 + chat_services优化
All checks were successful
构建并部署 AI Agent 服务 / deploy (push) Successful in 12m9s

## 核心改动

### 1. 单图方案重构
- 删除了多图(self.graphs),改为单图(self.graph)
- 新增 MainGraphState.current_model 字段用于运行时注入模型
- llm_call 节点改为动态选择模型(create_dynamic_llm_call_node)

### 2. chat_services 优化
- 添加 _cached_services 缓存,避免重复初始化
- 新增 get_cached_chat_services() 函数,用于单图注入
- 新增 _check_http_service_available() 统一HTTP探测逻辑
- 减少重复代码,LocalVLLMChatProvider和LocalSmallModelProvider共用探测方法

### 3. AIAgentService 重构
- initialize() 只构建一次图,传入 chat_services 字典
- 新增 _resolve_model() 模型回退逻辑
- 新增 _build_invocation() 统一构建调用参数
- process_message() 和 process_message_stream() 改为注入 current_model
- 流式处理代码拆分,增加可读性

### 4. 新增和删除文件
- 新增:backend/app/main_graph/main_graph_builder.py(图构建)
- 新增:backend/app/main_graph/subgraph_wrapper.py(子图封装)
- 新增:tools/test/test_tavily_search.py(测试)
- 删除:backend/app/main_graph/graph.py(旧图)
- 删除:backend/app/main_graph/utils/main_graph_builder.py(旧构建器)
- 删除:backend/app/main_graph/utils/__init__.py

### 5. 其他更新
- README.md:新增模型服务使用情况详解章节
- backend/app/model_services/__init__.py:新增 get_cached_chat_services 导出

## 方案优势

- 内存优化:N张图 → 1张图
- 灵活性:运行时动态选择模型,支持同会话不同模型
- 性能:模型服务缓存,初始化仅一次
- 可维护性:减少重复代码,统一HTTP探测逻辑
This commit is contained in:
2026-05-05 17:30:55 +08:00
parent 8b5fbbd395
commit b5c15ef445
25 changed files with 1225 additions and 830 deletions

205
README.md
View File

@@ -7,15 +7,15 @@
## 📑 目录导航
- [核心功能](#-核心功能) - 面向用户的功能和技术特性
- [使用指南](#-使用指南) - 基础对话、工具调用、多模型切换
- [技术架构](#-技术架构) - 技术栈、系统架构图、工作流流程图
- [模型服务使用情况](#55-模型服务使用情况详解) - 模型选型、Token估算、成本分析
- [核心算法与实现原理](#-核心算法与实现原理) - LangGraph 工作流、多模型路由、SSE 流式响应
- [快速开始](#-快速开始) - Docker 和本地部署指南
- [使用指南](#-使用指南) - 基础对话、工具调用、多模型切换
- [开发指南](#-开发指南) - 添加工具、添加模型、Docker 部署
- [实现指南与最佳实践](#-实现指南与最佳实践) - 性能优化、扩展开发、部署实践
- [环境配置](#-环境配置) - 配置文件、环境变量
- [故障排查](#-故障排查) - 常见问题
---
## 🎯 核心功能
@@ -50,6 +50,48 @@
---
---
## 📖 使用指南
### 基础对话
直接在聊天框输入问题即可:
```
你好,请介绍一下自己
帮我写一个 Python 脚本
```
### 主要功能
| 功能 | 说明 | 示例提问 |
|------|------|---------|
| 🧠 混合路由智能分流 | 自动判断任务类型,选择最佳路径 | 自然对话即可 |
| ⚡ 快速路径 | 闲聊、RAG查询、工具调用可走快速路径 | "你好"、"什么是 RAG" |
| 🔄 React 推理循环 | 复杂任务走完整的思考-行动-观察循环 | "帮我分析一下这个文档" |
| 🌐 联网搜索 | 免费 DuckDuckGo 搜索 | "今天北京天气怎么样?" |
| 📚 RAG 知识库检索 | 检索本地知识库 | "如何配置系统?" |
| 📇 通讯录管理 | 联系人 CRUD、邮件处理 | "帮我查看一下张三的联系方式" |
| 📖 智能词典 | 翻译、生词本、专业术语提取 | "帮我翻译这句话" |
| 📰 资讯分析 | 资讯获取、内容分析 | "帮我分析一下这篇新闻" |
| 📊 可视化图表 | 支持 Mermaid 图表生成 | "帮我画一个流程图" |
### 多模型切换
1. 在左侧边栏选择模型:
- **智谱 GLM-4**:在线服务,速度快
- **DeepSeek V3**:深度推理模型
- **OpenAI GPT-4o-mini**:通用对话模型
- **本地 Qwen3.5-9B**:本地部署,隐私性好
2. 可随时切换,甚至在同一会话中
3. 点击 "🔄 新会话" 清空当前对话
---
## 🏗️ 技术架构
### 1. 技术栈总览
@@ -385,6 +427,126 @@ flowchart TB
---
---
### 5.5. 模型服务使用情况详解
#### 5.5.1. 模型服务架构总览
本项目采用**分层模型策略**,根据任务复杂度选择不同能力和成本的模型:
| 模型类型 | 用途 | 主要来源 | 成本考量 |
|---------|------|---------|---------|
| 小模型 (Small LLM) | 意图分类、路由决策、查询改写 | 本地模型 / DeepSeek小模型 | 低成本,高频率 |
| 大模型 (Main LLM) | 对话生成、推理、工具调用 | 智谱 / DeepSeek / 本地 | 高能力,低频率 |
| Embedding模型 | 文本向量化、语义检索 | 本地 llama.cpp / 智谱API | 批量处理 |
| Rerank模型 | 检索结果重排序 | 硅基流动 / 智谱API | 精准排序 |
| Sparse模型 | BM25稀疏检索 | FastEmbed本地 | 关键词匹配 |
#### 5.5.2. 小模型使用场景及Token估算
**小模型**主要用于高频率、低复杂度的任务:
| 使用场景 | 位置文件 | 用途描述 | 单次Token估算 | 调用频率 |
|---------|---------|---------|-------------|---------|
| 意图分类 (1) | `app/core/intent_classifier.py` | 判断用户意图类型 | ~300输入 + ~50输出 | 每轮对话1次 |
| 意图分类 (2) | `app/main_graph/nodes/hybrid_router.py` | 混合路由决策 | ~200输入 + ~50输出 | 每轮对话1次 |
| 闲聊回复 | `app/main_graph/nodes/fast_paths.py` | 快速回复问候语 | ~50输入 + ~30输出 | 按需调用 |
**Token估算说明**
- 单次意图分类:总计 ~350-600 tokens
- 小模型成本通常是大模型的 1/10 - 1/100
- 每日1000次对话小模型仅消耗 ~350k-600k tokens
#### 5.5.3. 大模型使用场景及Token估算
**大模型**用于核心对话生成和复杂推理:
| 使用场景 | 位置文件 | 用途描述 | 单次Token估算 | 调用频率 |
|---------|---------|---------|-------------|---------|
| RAG查询改写 | `app/main_graph/utils/rag_initializer.py` | 生成多角度查询 | ~100输入 + ~150输出 | RAG调用时 |
| 主对话生成 | `app/main_graph/nodes/llm_call.py` | 用户查询响应 | ~500-2000输入 + ~200-1000输出 | 每轮对话1次 |
| React推理 | `app/main_graph/nodes/reasoning.py` | 任务分解与规划 | ~300-1000输入 + ~100-500输出 | 复杂任务多次 |
| 记忆摘要 | `app/memory/mem0_client.py` | 长期记忆压缩 | ~500-2000输入 + ~200-500输出 | 每N轮对话1次 |
**Token估算说明**
- 普通对话:总计 ~1000-3000 tokens
- RAG查询额外 ~250 tokens
- 复杂多步推理:可能额外增加 500-3000 tokens
- 每日1000次对话大模型预计消耗 1M-3M tokens
#### 5.5.4. Embedding模型使用场景
**Embedding模型**用于语义检索和向量存储:
| 使用场景 | 位置文件 | 用途描述 | 估算 |
|---------|---------|---------|------|
| RAG文档索引 | `rag_indexer/index_builder.py` | 文档分片向量化 | 每个文档片段1次 |
| 在线检索 | `app/rag/retriever.py` | 查询向量化 + 相似度检索 | 每次检索1次 |
| 记忆向量化 | `app/memory/mem0_client.py` | 记忆内容向量化存储 | 每次记忆更新1次 |
**Embedding说明**
- 向量维度1024 (Qwen3-Embedding-0.6B) 或 2048 (智谱 embedding-3)
- 批量处理:建议使用 batch_size=10-20 提高效率
- 本地优先:优先使用 llama.cpp 服务降低API调用成本
#### 5.5.5. Rerank模型使用场景
**Rerank模型**用于检索结果精细化排序:
| 使用场景 | 位置文件 | 用途描述 | 估算 |
|---------|---------|---------|------|
| RAG结果重排 | `app/rag/rerank.py` | 提升检索相关性 | 每次检索调用 |
| 混合检索重排 | `app/rag/retriever.py` | 稀疏+稠密结果融合排序 | 每次检索调用 |
**Rerank说明**
- 通常在 RRF 融合后使用,进一步提升精准度
- 重排数量建议rerank_top_n=3-10
- 成本权衡rerank 会增加额外调用成本,但精度提升明显
#### 5.5.6. 模型服务选型参考对比
为方便不同部署场景选择,提供以下模型选型参考:
| 维度 | 本地优先方案 | 云端优先方案 | 混合方案 |
|------|------------|------------|---------|
| **小模型** | Qwen3.5-9B (本地) | DeepSeek-Chat (API) | 本地+DeepSeek降级 |
| **大模型** | Qwen3.5-9B (本地) | 智谱 GLM-4 / DeepSeek | 本地+云端降级链 |
| **Embedding** | Qwen3-Embedding-0.6B (本地llama.cpp) | 智谱 embedding-2 | 本地优先,智谱降级 |
| **Rerank** | (可选本地) | 硅基流动 bge-reranker-v2-m3 | 硅基流动API |
| **Sparse** | FastEmbed BM25 (本地) | FastEmbed BM25 (本地) | 本地 |
**成本参考对比**每1M tokens仅作示例
| 模型 | 输入成本 | 输出成本 | 适用场景 |
|------|---------|---------|---------|
| **本地模型** | ~0元 | ~0元 | 有GPU机器隐私敏感 |
| **DeepSeek-Chat** | ~¥0.5 | ~¥1.0 | 通用推理,成本适中 |
| **智谱 GLM-4** | ~¥1.0 | ~¥2.0 | 高质量对话 |
| **智谱 embedding-2** | ~¥0.2 | - | 向量嵌入 |
| **硅基流动 Rerank** | ~¥0.3 | - | 精准重排 |
**部署建议**
- **个人/测试**:全云端方案,快速上手
- **小团队**:小模型本地,大模型云端降级
- **企业/隐私敏感**全本地部署或使用私有API
- **生产环境**:核心能力本地+云端降级链,保证高可用
#### 5.5.7. 模型服务降级链路设计
本项目所有模型服务都设计了**自动降级链路**,保证服务高可用:
| 服务类型 | 主服务 | 降级服务 |
|---------|--------|---------|
| 对话生成 | 本地模型 → 智谱GLM-4 → DeepSeek |
| Embedding | 本地llama.cpp → 智谱embedding-2 |
| Rerank | 硅基流动 → 智谱rerank-2 |
降级逻辑实现在 `app/model_services/base.py: FallbackServiceChain`,对上层业务透明。
---
### 6. 模型服务层
#### 6.1 多模型降级链
@@ -1582,45 +1744,6 @@ streamlit run frontend/src/frontend_main.py
---
## 📖 使用指南
### 基础对话
直接在聊天框输入问题即可:
```
你好,请介绍一下自己
帮我写一个 Python 脚本
```
### 主要功能
| 功能 | 说明 | 示例提问 |
|------|------|---------|
| 🧠 混合路由智能分流 | 自动判断任务类型,选择最佳路径 | 自然对话即可 |
| ⚡ 快速路径 | 闲聊、RAG查询、工具调用可走快速路径 | "你好"、"什么是 RAG" |
| 🔄 React 推理循环 | 复杂任务走完整的思考-行动-观察循环 | "帮我分析一下这个文档" |
| 🌐 联网搜索 | 免费 DuckDuckGo 搜索 | "今天北京天气怎么样?" |
| 📚 RAG 知识库检索 | 检索本地知识库 | "如何配置系统?" |
| 📇 通讯录管理 | 联系人 CRUD、邮件处理 | "帮我查看一下张三的联系方式" |
| 📖 智能词典 | 翻译、生词本、专业术语提取 | "帮我翻译这句话" |
| 📰 资讯分析 | 资讯获取、内容分析 | "帮我分析一下这篇新闻" |
| 📊 可视化图表 | 支持 Mermaid 图表生成 | "帮我画一个流程图" |
### 多模型切换
1. 在左侧边栏选择模型:
- **智谱 GLM-4**:在线服务,速度快
- **DeepSeek V3**:深度推理模型
- **OpenAI GPT-4o-mini**:通用对话模型
- **本地 Qwen3.5-9B**:本地部署,隐私性好
2. 可随时切换,甚至在同一会话中
3. 点击 "🔄 新会话" 清空当前对话
---
## 🔧 开发指南
### 添加新工具