root
53fbfb4741
All checks were successful
构建并部署 AI Agent 服务 / deploy (push) Successful in 6m41s
- 删除过时文档：REACT_PLAN.md、backend/docs/HYBRID_ROUTER.md - 更新 REACT_MODE_SUMMARY.md：加入新的混合路由架构 - 更新 README.md：加入混合路由、双模型服务等新特性 - 更新 backend/app/README.md：加入 hybrid_router.py - 更新 backend/app/model_services/README.md：加入 get_chat_service/get_small_llm_service - 更新 .gitignore：允许 REACT_MODE_SUMMARY.md 上传 - 新增 backend/test/test_hybrid_router.py：测试脚本
13 KiB
13 KiB
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，可以通过以下方式启动：
# 方式 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），包含以下字段：
@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]