- 删除冗余文档：backend/app/README.md、backend/app/model_services/README.md - 保留重要深度文档：backend/app/rag/README.md（RAG 模块详细说明） - 更新 REACT_MODE_SUMMARY.md：加入模型服务层的关键内容
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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]
|
||||
```
|
||||
@@ -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=***
|
||||
```
|
||||
"""
|
||||
Reference in New Issue
Block a user