From 01762970af732d2df601d6bd3165799dff7f2d01 Mon Sep 17 00:00:00 2001 From: root <953994191@qq.com> Date: Fri, 1 May 2026 23:45:08 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20README=EF=BC=9A=E6=B7=BB?= =?UTF-8?q?=E5=8A=A0=E5=AE=8C=E6=95=B4=E7=9A=84=20React=20=E6=A8=A1?= =?UTF-8?q?=E5=BC=8F=E6=9E=B6=E6=9E=84=E8=AF=B4=E6=98=8E=E5=92=8C=E6=B5=81?= =?UTF-8?q?=E7=A8=8B=E5=9B=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend/app/README.md | 186 +++++++++++++++++++++++++++++++++++------- 1 file changed, 158 insertions(+), 28 deletions(-) diff --git a/backend/app/README.md b/backend/app/README.md index f9053c7..2ebdea6 100644 --- a/backend/app/README.md +++ b/backend/app/README.md @@ -23,26 +23,27 @@ app/ │ ├── agent/ # ⭐ Agent 服务层 │ ├── __init__.py -│ ├── service.py # AIAgentService - 核心服务类 +│ ├── agent_service.py # AIAgentService - 核心服务类 │ ├── history.py # 历史查询服务 │ └── prompts.py # 提示词模板 │ ├── main_graph/ # ⭐ 主图 - LangGraph 主流程 │ ├── __init__.py -│ ├── state.py # 主图状态定义 -│ ├── graph_builder.py # 主图构建器 +│ ├── state.py # 主图状态定义（MainGraphState） +│ ├── graph.py # 图组件重导出 +│ ├── config.py # 流配置 │ │ │ ├── nodes/ # 主图节点 │ │ ├── __init__.py -│ │ ├── router.py # 路由决策节点 -│ │ ├── llm_call.py # LLM 调用节点（React 模式） -│ │ ├── tool_call.py # 工具执行节点 +│ │ ├── react_nodes.py # React 模式节点（推理、路由） +│ │ ├── llm_call.py # LLM 调用节点 │ │ ├── retrieve_memory.py # 记忆检索节点 +│ │ ├── memory_trigger.py # 记忆触发节点 │ │ ├── summarize.py # 记忆摘要节点 │ │ ├── finalize.py # 最终处理节点 -│ │ ├── memory_trigger.py # 记忆触发节点 │ │ ├── rag_nodes.py # RAG 相关节点 -│ │ └── react_nodes.py # React 模式节点 +│ │ ├── web_search_node.py # 联网搜索节点 +│ │ └── error_handling_node.py # 错误处理节点 │ │ │ ├── tools/ # 主图工具 │ │ ├── __init__.py @@ -51,8 +52,8 @@ app/ │ │ │ └── utils/ # 主图工具函数 │ ├── __init__.py +│ ├── main_graph_builder.py # 主图构建器 │ ├── retry_utils.py # 重试工具 -│ ├── subgraph_builder.py # 子图构建器 │ ├── rag_initializer.py # RAG 初始化工具 │ └── visualize_graph.py # 图可视化工具 │ @@ -82,7 +83,8 @@ app/ │ ├── model_services/ # 模型服务层 │ ├── __init__.py -│ ├── base.py # 基类：BaseServiceProvider, FallbackServiceChain, SingletonServiceManager +│ ├── README.md # 模型服务文档 +│ ├── base.py # 基类：BaseServiceProvider, FallbackServiceChain │ ├── chat_services.py # 生成式大模型服务 │ ├── embedding_services.py # 嵌入模型服务 │ └── rerank_services.py # 重排序服务 @@ -136,23 +138,42 @@ app/ | 文件 | 说明 | |------|------| -| `service.py` | `AIAgentService` 类，管理模型、图、工具，提供 `process_message` 和 `process_message_stream` 方法 | +| `agent_service.py` | `AIAgentService` 类，管理模型、图、工具，提供 `process_message` 和 `process_message_stream` 方法 | | `history.py` | 历史对话查询服务 | | `prompts.py` | 系统提示词模板 | --- -### 3. `main_graph/` - 主图 +### 3. `main_graph/` - 主图（React 模式） -LangGraph 的主流程，处理普通对话和工具调用： +LangGraph 的主流程，采用 React 模式（Reasoning + Acting）： | 目录/文件 | 说明 | |----------|------| -| `state.py` | 主图状态定义，包含消息、RAG 上下文、错误记录等 | -| `graph_builder.py` | 构建主图的类，定义节点和边 | -| `nodes/` | 所有节点实现（router, llm_call, tool_call 等） | -| `tools/` | 图的工具定义（天气、文件、网页、RAG 等） | -| `utils/` | 辅助函数（重试、子图构建、初始化等） | +| `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` | 完成 | 发送完成事件 | --- @@ -174,7 +195,7 @@ LangGraph 的主流程，处理普通对话和工具调用： | 文件 | 说明 | |------|------| -| `base.py` | `BaseServiceProvider`（基类）、`FallbackServiceChain`（降级链）、`SingletonServiceManager`（单例管理） | +| `base.py` | `BaseServiceProvider`（基类）、`FallbackServiceChain`（降级链） | | `chat_services.py` | 生成式大模型服务（智谱、DeepSeek、本地） | | `embedding_services.py` | 嵌入模型服务 | | `rerank_services.py` | 重排序服务 | @@ -196,19 +217,65 @@ LangGraph 的主流程，处理普通对话和工具调用： --- -## 🔄 数据流 +## 🔄 完整流程图 + +``` +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/service.py (AIAgentService) - ├─> model_services/ (获取模型) - ├─> main_graph/ (执行主图) - │ ├─> nodes/ (执行节点) - │ ├─> tools/ (调用工具) - │ └─> rag/ (RAG 检索) - └─> subgraphs/ (可选：调用子图) - └─> core/ (共享工具) + └─> agent/agent_service.py (AIAgentService) + ├─> model_services/ (获取模型 - 支持降级链) + ├─> main_graph/utils/main_graph_builder.py (构建主图) + └─> graph.astream() (执行图流) + ├─> nodes/ (执行节点) + ├─> tools/ (调用工具) + ├─> rag/ (RAG 检索) + ├─> subgraphs/ (可选：调用子图) + └─> memory/ (记忆检索和存储) ``` --- @@ -227,3 +294,66 @@ 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] +```