diff --git a/REACT_MODE_SUMMARY.md b/REACT_MODE_SUMMARY.md index f912de7..255dafe 100644 --- a/REACT_MODE_SUMMARY.md +++ b/REACT_MODE_SUMMARY.md @@ -104,7 +104,7 @@ END --- -## 📁 关键文件清单 +## 📦 关键文件清单 | 文件 | 说明 | |------|------| @@ -119,6 +119,39 @@ END --- +## 🛠️ 模型服务层 + +### 生成式大模型服务（Chat） + +| 函数 | 说明 | +|------|------| +| `get_chat_service()` | 获取大模型服务（用于复杂推理、生成） | +| `get_small_llm_service()` | 获取轻量级模型服务（用于简单意图分类、快速问答） | +| `get_all_chat_services()` | 获取所有可用的生成式大模型服务（用于多模型切换） | + +### 使用方法 + +```python +from app.model_services import get_chat_service, get_small_llm_service + +# 获取大模型服务（复杂任务） +llm = get_chat_service() +response = llm.invoke("什么是 LangGraph?") + +# 获取轻量级模型服务（简单任务） +small_llm = get_small_llm_service() +response = small_llm.invoke("分类用户意图：'你好'") +``` + +### 嵌入与重排模型服务 + +| 函数 | 说明 | +|------|------| +| `get_embedding_service()` | 获取嵌入模型服务（自动降级） | +| `get_rerank_service()` | 获取重排模型服务（自动降级） | + +--- + ## 🚀 快速使用 ```python diff --git a/backend/app/README.md b/backend/app/README.md deleted file mode 100644 index eedbbf9..0000000 --- a/backend/app/README.md +++ /dev/null @@ -1,360 +0,0 @@ -# Backend App - 后端应用目录 - -本目录包含 AI Agent 系统的所有后端代码，采用模块化设计，层级清晰。 - ---- - -## 📁 目录结构 - -``` -app/ -├── __init__.py # 应用初始化 -├── backend.py # FastAPI 主入口，包含 API 端点 -├── config.py # 配置管理 -├── logger.py # 日志工具 -│ -├── core/ # ⭐ 核心模块 - 基类和通用工具 -│ ├── __init__.py -│ ├── state_base.py # 子图状态基类 -│ ├── intent.py # 意图理解（React 模式） -│ ├── intent_classifier.py # 意图分类器 -│ ├── formatter.py # 格式化输出工具 -│ └── human_review.py # 人工审核节点 -│ -├── agent/ # ⭐ Agent 服务层 -│ ├── __init__.py -│ ├── agent_service.py # AIAgentService - 核心服务类 -│ ├── history.py # 历史查询服务 -│ └── prompts.py # 提示词模板 -│ -├── main_graph/ # ⭐ 主图 - LangGraph 主流程 -│ ├── __init__.py -│ ├── state.py # 主图状态定义（MainGraphState） -│ ├── graph.py # 图组件重导出 -│ ├── config.py # 流配置 -│ │ -│ ├── nodes/ # 主图节点 -│ │ ├── __init__.py -│ │ ├── react_nodes.py # React 模式节点（推理、路由） -│ │ ├── hybrid_router.py # ⭐ 混合路由节点（前置快速路由 + 自动升级） -│ │ ├── llm_call.py # LLM 调用节点 -│ │ ├── retrieve_memory.py # 记忆检索节点 -│ │ ├── memory_trigger.py # 记忆触发节点 -│ │ ├── summarize.py # 记忆摘要节点 -│ │ ├── finalize.py # 最终处理节点 -│ │ ├── rag_nodes.py # RAG 相关节点 -│ │ ├── web_search_node.py # 联网搜索节点 -│ │ └── error_handling_node.py # 错误处理节点 -│ │ -│ ├── tools/ # 主图工具 -│ │ ├── __init__.py -│ │ ├── graph_tools.py # 图工具定义 -│ │ └── subgraph_tools.py # 子图调用工具 -│ │ -│ └── utils/ # 主图工具函数 -│ ├── __init__.py -│ ├── main_graph_builder.py # 主图构建器（支持混合路由开关） -│ ├── retry_utils.py # 重试工具 -│ ├── rag_initializer.py # RAG 初始化工具 -│ └── visualize_graph.py # 图可视化工具 -│ -├── subgraphs/ # ⭐ 子图模块 -│ ├── __init__.py -│ │ -│ ├── contact/ # 通讯录子图 -│ │ ├── __init__.py -│ │ ├── state.py # 状态定义 -│ │ ├── nodes.py # 节点实现 -│ │ ├── graph.py # 图构建 -│ │ └── api_client.py # API 客户端 -│ │ -│ ├── dictionary/ # 词典子图 -│ │ ├── __init__.py -│ │ ├── state.py # 状态定义 -│ │ ├── nodes.py # 节点实现 -│ │ ├── graph.py # 图构建 -│ │ └── api_client.py # API 客户端 -│ │ -│ └── news_analysis/ # 资讯分析子图 -│ ├── __init__.py -│ ├── state.py # 状态定义 -│ ├── nodes.py # 节点实现 -│ ├── graph.py # 图构建 -│ └── api_client.py # API 客户端 -│ -├── model_services/ # 模型服务层 -│ ├── __init__.py -│ ├── README.md # 模型服务文档 -│ ├── base.py # 基类：BaseServiceProvider, FallbackServiceChain -│ ├── chat_services.py # 生成式大模型服务 -│ ├── embedding_services.py # 嵌入模型服务 -│ └── rerank_services.py # 重排序服务 -│ -├── rag/ # RAG 模块 -│ ├── __init__.py -│ ├── retriever.py # 检索器 -│ ├── rerank.py # 重排序业务逻辑 -│ ├── query_transform.py # 查询转换 -│ ├── pipeline.py # RAG 流水线 -│ ├── fusion.py # RAG-Fusion -│ ├── tools.py # RAG 工具 -│ └── evaluate.py # RAG 评估 -│ -├── memory/ # 记忆模块 -│ ├── __init__.py -│ └── mem0_client.py # Mem0 客户端封装 -│ -├── db/ # 数据库模块 -│ ├── __init__.py -│ ├── base.py # 数据库基类 -│ ├── models.py # 数据模型 -│ └── init_db.py # 数据库初始化 -│ -└── utils/ # 工具模块 - ├── __init__.py - └── logging.py # 日志工具 -``` - ---- - -## 📖 模块详解 - -### 1. `core/` - 核心模块 - -这是整个系统的基础，被主图和所有子图共享： - -| 文件 | 说明 | -|------|------| -| `state_base.py` | 所有子图状态的基类，定义通用字段和方法 | -| `intent.py` | React 模式的意图理解，用于解析用户意图 | -| `intent_classifier.py` | 意图分类器，用于混合路由 | -| `formatter.py` | 输出格式化工具，用于统一美化子图输出 | -| `human_review.py` | 人工审核节点，需要人工确认的操作 | - ---- - -### 2. `agent/` - Agent 服务层 - -对外提供服务的核心层： - -| 文件 | 说明 | -|------|------| -| `agent_service.py` | `AIAgentService` 类，管理模型、图、工具，提供 `process_message` 和 `process_message_stream` 方法 | -| `history.py` | 历史对话查询服务 | -| `prompts.py` | 系统提示词模板 | - ---- - -### 3. `main_graph/` - 主图（React 模式） - -LangGraph 的主流程，采用 React 模式（Reasoning + Acting）： - -| 目录/文件 | 说明 | -|----------|------| -| `state.py` | 主图状态定义（MainGraphState），整合所有旧状态字段 | -| `graph.py` | StateGraph, START, END 等组件重导出 | -| `config.py` | 流写入器配置 | -| `nodes/` | 所有节点实现 | -| `tools/` | 图的工具定义 | -| `utils/main_graph_builder.py` | 主图构建器 - 构建完整的 React 模式图 | - -#### 🔄 主图节点说明 - -| 节点 | 类型 | 说明 | -|------|------|------| -| `retrieve_memory` | 记忆 | 从 Mem0 检索相关长期记忆 | -| `memory_trigger` | 记忆 | 检测记忆指令，主动触发存储 | -| `init_state` | React | 初始化状态 | -| `react_reason` | React | 推理节点，理解意图并决策下一步 | -| `rag_retrieve` | 工具 | RAG 检索 | -| `web_search` | 工具 | 联网搜索 | -| `contact_subgraph` | 子图 | 调用通讯录子图 | -| `dictionary_subgraph` | 子图 | 调用词典子图 | -| `news_analysis_subgraph` | 子图 | 调用资讯分析子图 | -| `handle_error` | 错误 | 错误处理和重试 | -| `llm_call` | 模型 | 调用大模型生成回复 | -| `summarize` | 记忆 | 对话总结，提交 Mem0 存储 | -| `finalize` | 完成 | 发送完成事件 | - ---- - -### 4. `subgraphs/` - 子图模块 - -三个独立的子图，每个子图都有完整的 `state.py`、`nodes.py`、`graph.py`： - -| 子图 | 功能 | -|------|------| -| `contact/` | 通讯录管理：CRUD、邮件处理、智能嗅探 | -| `dictionary/` | 词典：查词、翻译、生词本、专业术语提取 | -| `news_analysis/` | 资讯分析：获取资讯、内容分析、格式化展示 | - ---- - -### 5. `model_services/` - 模型服务层 - -统一的模型服务接口，支持自动降级： - -| 文件 | 说明 | -|------|------| -| `base.py` | `BaseServiceProvider`（基类）、`FallbackServiceChain`（降级链） | -| `chat_services.py` | 生成式大模型服务（智谱、DeepSeek、本地） | -| `embedding_services.py` | 嵌入模型服务 | -| `rerank_services.py` | 重排序服务 | - ---- - -### 6. `rag/` - RAG 模块 - -知识库检索相关： - -| 文件 | 说明 | -|------|------| -| `retriever.py` | 向量检索器 | -| `rerank.py` | 重排序业务逻辑 | -| `pipeline.py` | RAG 流水线 | -| `fusion.py` | RAG-Fusion 多路召回融合 | -| `tools.py` | 封装为 LangChain Tool 的 RAG 工具 | -| `evaluate.py` | RAG 评估工具 | - ---- - -## 🔄 完整流程图 - -``` -START - ↓ -retrieve_memory (从Mem0检索长期记忆) - ↓ -memory_trigger (记忆触发器 - 检测记忆指令) - ↓ -init_state (初始化状态) - ↓ -react_reason (推理节点 - 理解意图并决策) ←───────────┐ - ↓ │ -route_by_reasoning (条件路由) │ - ↓ │ -┌─────────────────────────────────────────────────┐ │ -│ 分支选择： │ │ -│ ├─ rag_retrieve →───────────────────────────┐ │ │ -│ ├─ web_search →─────────────────────────────┤ │ │ -│ ├─ contact_subgraph →───────────────────────┤ │ │ -│ ├─ dictionary_subgraph →────────────────────┤ │ │ -│ ├─ news_analysis_subgraph →─────────────────┤ │ │ -│ ├─ handle_error →───────────────────────────┤ │ │ -│ └─ llm_call →────────────────────────────────┘ │ │ -└─────────────────────────────────────────────────┘ │ - ↓ │ - (回到 react_reason) ──────────────────┘ - ↓ - (无工具调用) - ↓ - llm_call (直接生成回复) - ↓ -┌─────────────────────────────────────────────────┐ -│ 检查：需要总结吗？(turns_since_last_summary >=5?) │ -│ ├─ 是 → summarize (提交Mem0存储) │ -│ └─ 否 → (跳过) │ -└─────────────────────────────────────────────────┘ - ↓ - finalize (发送完成事件) - ↓ - END -``` - ---- - -## 📊 数据流 - -``` -用户请求 - └─> backend.py (FastAPI) - └─> agent/agent_service.py (AIAgentService) - ├─> model_services/ (获取模型 - 支持降级链) - ├─> main_graph/utils/main_graph_builder.py (构建主图) - └─> graph.astream() (执行图流) - ├─> nodes/ (执行节点) - ├─> tools/ (调用工具) - ├─> rag/ (RAG 检索) - ├─> subgraphs/ (可选：调用子图) - └─> memory/ (记忆检索和存储) -``` - ---- - -## 🚀 启动方式 - -FastAPI 应用入口是 `backend.py`，可以通过以下方式启动： - -```bash -# 方式 1：直接运行 -cd backend && python -m app.backend - -# 方式 2：Uvicorn -uvicorn app.backend:app --reload --host 0.0.0.0 --port 8079 - -# 方式 3：Docker -docker compose up -``` - ---- - -## 📝 状态系统 - -### MainGraphState - -所有节点统一使用 `MainGraphState`（dataclass），包含以下字段： - -```python -@dataclass -class MainGraphState: - # 消息和记忆 - messages: Annotated[Sequence[BaseMessage], add_messages] - llm_calls: int - memory_context: str - system_prompt: str - turns_since_last_summary: int - - # LLM 输出 - last_token_usage: Dict[str, Any] - last_elapsed_time: float - - # 用户信息 - user_query: str - user_id: str - - # React 推理 - reasoning_step: int - max_steps: int - last_action: str - reasoning_history: List[Dict[str, Any]] - - # RAG 相关 - rag_context: str - rag_retrieved: bool - rag_docs: List[Dict[str, Any]] - - # 搜索相关 - web_search_results: List[str] - - # 错误处理 - errors: List[ErrorRecord] - current_error: Optional[ErrorRecord] - retry_action: Optional[str] - - # 子图结果 - news_result: Optional[Dict[str, Any]] - dictionary_result: Optional[Dict[str, Any]] - contact_result: Optional[Dict[str, Any]] - - # 执行状态 - current_action: CurrentAction - current_phase: str - error_message: str - final_result: str - success: bool - - # 元数据 - start_time: Optional[str] - end_time: Optional[str] - debug_info: Dict[str, Any] -``` diff --git a/backend/app/model_services/README.md b/backend/app/model_services/README.md deleted file mode 100644 index 221516b..0000000 --- a/backend/app/model_services/README.md +++ /dev/null @@ -1,85 +0,0 @@ -""" -模型服务模块（model_services） - -提供统一的嵌入、重排和生成式大模型服务获取接口，支持自动降级。 - ---- - -## 📚 生成式大模型服务（Chat） - -### 双模型服务 -| 函数 | 说明 | -|------|------| -| `get_chat_service()` | 获取大模型服务（用于复杂推理、生成） | -| `get_small_llm_service()` | 获取轻量级模型服务（用于简单意图分类、快速问答） | -| `get_all_chat_services()` | 获取所有可用的生成式大模型服务（用于多模型切换） | - -### 使用方法 - -```python -from app.model_services import get_chat_service, get_small_llm_service - -# 获取大模型服务（复杂任务） -llm = get_chat_service() -response = llm.invoke("什么是 LangGraph?") - -# 获取轻量级模型服务（简单任务） -small_llm = get_small_llm_service() -response = small_llm.invoke("分类用户意图：'你好'") -``` - ---- - -## 📚 嵌入模型服务（Embedding） - -| 函数 | 说明 | -|------|------| -| `get_embedding_service()` | 获取嵌入模型服务（自动降级） | - -### 使用方法 - -```python -from app.model_services import get_embedding_service - -# 获取嵌入服务（LangChain 兼容的 Embeddings） -embeddings = get_embedding_service() -``` - ---- - -## 📚 重排模型服务（Rerank） - -| 函数 | 说明 | -|------|------| -| `get_rerank_service()` | 获取重排模型服务（自动降级） | - -### 使用方法 - -```python -from app.model_services import get_rerank_service - -# 获取重排服务 -reranker = get_rerank_service() -sorted_docs = reranker.compress_documents(documents, query, top_n=5) -``` - ---- - -## 🔧 环境变量配置 - -```env -# 智谱 API 配置 -ZHIPUAI_API_KEY=*** -ZHIPU_EMBEDDING_MODEL=embedding-3 # 可选：embedding-2、embedding-3 -ZHIPU_RERANK_MODEL=rerank-2 # 可选：rerank-1、rerank-2 -ZHIPU_API_BASE=https://open.bigmodel.cn/api/paas/v4 - -# DeepSeek API 配置（用于大模型） -DEEPSEEK_API_KEY=*** - -# 本地 llama.cpp 服务配置（原有配置保持不变） -LLAMACPP_EMBEDDING_URL=http://localhost:port/v1 -LLAMACPP_RERANKER_URL=http://localhost:port/v1 -LLAMACPP_API_KEY=*** -``` -"""