diff --git a/README.md b/README.md index 606bd23..c3a6920 100644 --- a/README.md +++ b/README.md @@ -63,8 +63,9 @@ | | 服务基类 | base.py | - | BaseServiceProvider + FallbackServiceChain + SingletonServiceManager | | **Embedding** | 向量嵌入 | llama.cpp server | latest | 本地 embedding 服务，支持多种模型 | | **Agent 框架** | 工作流编排 | LangGraph + LangChain | latest | 状态机驱动的智能体工作流 | -| **子图系统** | 模块化子图 | agent_subgraphs/ | - | 通讯录、词典、资讯分析等子图 | -| | 公共工具 | common/ | - | 状态基类、意图理解、格式化输出、人工审核 | +| **子图系统** | 模块化子图 | subgraphs/ | - | 通讯录、词典、资讯分析等子图 | +| | 核心工具 | core/ | - | 状态基类、意图理解、格式化输出、人工审核 | +| **主图系统** | 主流程 | main_graph/ | - | 主图节点、工具、构建器 | | **向量数据库** | 向量检索 | Qdrant | v1.12+ | 高性能向量相似度检索（远程服务器） | | **后端框架** | API 服务 | FastAPI + Uvicorn | v0.115+ | RESTful API + WebSocket + SSE 流式输出 | | **前端框架** | Web 界面 | Streamlit | v1.40+ | 交互式对话界面，组件化设计 | @@ -110,15 +111,15 @@ graph TB RetrieveMemory -->|存储| PostgreSQL[(PostgreSQL)] Summarize -->|存储| PostgreSQL - SubgraphAPI -->|路由| Subgraphs[子图系统 agent_subgraphs] + SubgraphAPI -->|路由| Subgraphs[子图系统 subgraphs] Subgraphs --> Contact[通讯录子图] Subgraphs --> Dictionary[词典子图] Subgraphs --> NewsAnalysis[资讯分析子图] - Subgraphs --> Common[公共工具 common/] - Common --> Intent[意图理解 (React)] - Common --> HumanReview[人工审核] - Common --> Formatter[格式化输出] - Common --> StateBase[状态基类] + Subgraphs --> Core[核心工具 core/] + Core --> Intent[意图理解 (React)] + Core --> HumanReview[人工审核] + Core --> Formatter[格式化输出] + Core --> StateBase[状态基类] Contact -->|数据库| ContactDB[(PostgreSQL 联系人)] Dictionary -->|数据库| DictionaryDB[(PostgreSQL 生词本)] @@ -354,53 +355,50 @@ Agent1/ │ │ ├── config.py # 配置管理 │ │ ├── logger.py # 日志工具 │ │ ├── backend.py # FastAPI 后端应用（含子图 API） -│ │ ├── agent/ +│ │ ├── README.md # 后端目录文档 +│ │ │ +│ │ ├── core/ # ⭐ 核心模块 - 基类和通用工具 +│ │ │ ├── __init__.py +│ │ │ ├── state_base.py # 子图状态基类 +│ │ │ ├── intent.py # 意图理解（React 模式） +│ │ │ ├── intent_classifier.py # 意图分类器 +│ │ │ ├── formatter.py # 格式化输出工具 +│ │ │ └── human_review.py # 人工审核节点 +│ │ │ +│ │ ├── agent/ # ⭐ Agent 服务层 │ │ │ ├── __init__.py │ │ │ ├── service.py # Agent 服务核心（使用 chat_services） │ │ │ ├── history.py # 历史查询服务 -│ │ │ ├── prompts.py # 提示模板 -│ │ │ └── rag_initializer.py # RAG 工具初始化 -│ │ ├── model_services/ # 模型服务层（新增） -│ │ │ ├── __init__.py -│ │ │ ├── base.py # 基类：BaseServiceProvider, FallbackServiceChain, SingletonServiceManager -│ │ │ ├── chat_services.py # 生成式大模型服务（替代 llm_factory） -│ │ │ ├── embedding_services.py # 嵌入模型服务 -│ │ │ └── rerank_services.py # 重排序服务 -│ │ ├── graph/ +│ │ │ └── prompts.py # 提示词模板 +│ │ │ +│ │ ├── main_graph/ # ⭐ 主图 - LangGraph 主流程 │ │ │ ├── __init__.py +│ │ │ ├── state.py # 主图状态定义 │ │ │ ├── graph_builder.py # LangGraph 图构建器 -│ │ │ ├── graph_tools.py # 工具定义 -│ │ │ ├── state.py # 状态定义 -│ │ │ ├── rag_nodes.py # RAG 集成节点 -│ │ │ └── retrieve_memory.py # 记忆检索 -│ │ ├── nodes/ +│ │ │ ├── nodes/ # 主图节点 +│ │ │ │ ├── __init__.py +│ │ │ │ ├── router.py # 路由决策 +│ │ │ │ ├── llm_call.py # LLM 调用节点（React 模式） +│ │ │ │ ├── tool_call.py # 工具执行节点 +│ │ │ │ ├── retrieve_memory.py # 记忆检索节点 +│ │ │ │ ├── summarize.py # 记忆存储节点 +│ │ │ │ ├── finalize.py # 最终处理节点 +│ │ │ │ ├── memory_trigger.py # 记忆触发节点 +│ │ │ │ ├── rag_nodes.py # RAG 集成节点 +│ │ │ │ └── react_nodes.py # React 模式节点 +│ │ │ ├── tools/ # 主图工具 +│ │ │ │ ├── __init__.py +│ │ │ │ ├── graph_tools.py # 工具定义 +│ │ │ │ └── subgraph_tools.py # 子图调用工具 +│ │ │ └── utils/ # 主图工具函数 +│ │ │ ├── __init__.py +│ │ │ ├── retry_utils.py # 重试工具 +│ │ │ ├── subgraph_builder.py # 子图构建器 +│ │ │ ├── rag_initializer.py # RAG 初始化工具 +│ │ │ └── visualize_graph.py # 图可视化工具 +│ │ │ +│ │ ├── subgraphs/ # ⭐ 子图模块 │ │ │ ├── __init__.py -│ │ │ ├── router.py # 路由决策 -│ │ │ ├── llm_call.py # LLM 调用节点（React 模式） -│ │ │ ├── tool_call.py # 工具执行节点 -│ │ │ ├── retrieve_memory.py # 记忆检索节点 -│ │ │ ├── summarize.py # 记忆存储节点 -│ │ │ ├── finalize.py # 最终处理节点 -│ │ │ └── memory_trigger.py # 记忆触发节点 -│ │ ├── memory/ -│ │ │ ├── __init__.py -│ │ │ └── mem0_client.py # Mem0 客户端封装 -│ │ ├── rag/ -│ │ │ ├── __init__.py -│ │ │ ├── retriever.py # 检索器 -│ │ │ ├── rerank.py # 重排序业务逻辑（使用 rerank_services） -│ │ │ ├── query_transform.py # 查询转换 -│ │ │ ├── pipeline.py # RAG 流水线 -│ │ │ ├── fusion.py # RAG-Fusion -│ │ │ └── tools.py # RAG 工具 -│ │ ├── agent_subgraphs/ # 子图模块（新增） -│ │ │ ├── __init__.py -│ │ │ ├── README.md # 子图文档 -│ │ │ ├── common/ # 公共工具 -│ │ │ │ ├── state_base.py # 状态基类 -│ │ │ │ ├── intent.py # 意图理解（React 模式） -│ │ │ │ ├── formatter.py # 格式化输出工具 -│ │ │ │ └── human_review.py # 人工审核节点 │ │ │ ├── contact/ # 通讯录子图 │ │ │ │ ├── state.py # 状态定义 │ │ │ │ ├── nodes.py # 节点实现 @@ -413,14 +411,41 @@ Agent1/ │ │ │ │ ├── graph.py # 图构建 │ │ │ │ ├── api_client.py # API 客户端 │ │ │ │ └── __init__.py -│ │ │ ├── news_analysis/ # 资讯分析子图 -│ │ │ │ ├── state.py # 状态定义 -│ │ │ │ ├── nodes.py # 节点实现 -│ │ │ │ ├── graph.py # 图构建 -│ │ │ │ ├── api_client.py # API 客户端 -│ │ │ │ └── __init__.py -│ │ │ └── research/ # 研究分析子图（规划中） -│ │ └── utils/ +│ │ │ └── news_analysis/ # 资讯分析子图 +│ │ │ ├── state.py # 状态定义 +│ │ │ ├── nodes.py # 节点实现 +│ │ │ ├── graph.py # 图构建 +│ │ │ ├── api_client.py # API 客户端 +│ │ │ └── __init__.py +│ │ │ +│ │ ├── model_services/ # 模型服务层 +│ │ │ ├── __init__.py +│ │ │ ├── base.py # 基类：BaseServiceProvider, FallbackServiceChain, SingletonServiceManager +│ │ │ ├── chat_services.py # 生成式大模型服务 +│ │ │ ├── embedding_services.py # 嵌入模型服务 +│ │ │ └── rerank_services.py # 重排序服务 +│ │ │ +│ │ ├── memory/ # 记忆模块 +│ │ │ ├── __init__.py +│ │ │ └── mem0_client.py # Mem0 客户端封装 +│ │ │ +│ │ ├── rag/ # RAG 模块 +│ │ │ ├── __init__.py +│ │ │ ├── retriever.py # 检索器 +│ │ │ ├── rerank.py # 重排序业务逻辑（使用 rerank_services） +│ │ │ ├── query_transform.py # 查询转换 +│ │ │ ├── pipeline.py # RAG 流水线 +│ │ │ ├── fusion.py # RAG-Fusion +│ │ │ ├── tools.py # RAG 工具 +│ │ │ └── evaluate.py # RAG 评估 +│ │ │ +│ │ ├── db/ # 数据库模块 +│ │ │ ├── __init__.py +│ │ │ ├── base.py # 数据库基类 +│ │ │ ├── models.py # 数据模型 +│ │ │ └── init_db.py # 数据库初始化 +│ │ │ +│ │ └── utils/ # 工具模块 │ │ └── __init__.py │ └── rag_core/ │ ├── __init__.py @@ -739,8 +764,8 @@ python scripts/evaluate_rag.py 4. **可以多次循环** - LLM 可以调用多个工具，或者同一个工具多次 **实际代码位置**： -- `backend/app/graph/graph_builder.py` 第 79 行：`builder.add_edge("tool_node", "llm_call")` -- `backend/app/nodes/router.py`：`should_continue` 函数检查 `last_message.tool_calls` +- `backend/app/main_graph/graph_builder.py` 第 79 行：`builder.add_edge("tool_node", "llm_call")` +- `backend/app/main_graph/nodes/router.py`：`should_continue` 函数检查 `last_message.tool_calls` #### 2.2 状态机设计 @@ -1207,7 +1232,7 @@ sequenceDiagram --- -### 公共工具说明 +### 核心工具说明 #### 1. state_base.py - 状态基类 提供类型安全的状态基类，所有子图状态继承此类。 @@ -1239,13 +1264,13 @@ sequenceDiagram 1. **创建子图目录** ```bash -mkdir backend/app/agent_subgraphs/my_subgraph +mkdir backend/app/subgraphs/my_subgraph ``` 2. **创建状态定义 (state.py)** ```python from typing_extensions import TypedDict -from ..common.state_base import BaseSubgraphState +from ..core.state_base import BaseSubgraphState class MySubgraphState(BaseSubgraphState): \"\"\" @@ -1545,7 +1570,7 @@ streamlit run frontend/src/frontend_main.py ### 添加新工具 -在 [backend/app/graph/graph_tools.py](file:///home/huang/Study/AIProject/Agent1/backend/app/graph/graph_tools.py) 中添加新的 `@tool` 装饰函数： +在 [backend/app/main_graph/tools/graph_tools.py](file:///home/huang/Study/AIProject/Agent1/backend/app/main_graph/tools/graph_tools.py) 中添加新的 `@tool` 装饰函数： ```python @tool @@ -1863,7 +1888,7 @@ curl -X POST http://localhost:6333/collections/my_docs/actions \ #### 3.1 添加自定义工具 ```python -# 在 backend/app/graph/graph_tools.py 中添加 +# 在 backend/app/main_graph/tools/graph_tools.py 中添加 from langchain_core.tools import tool from typing import Optional diff --git a/backend/app/README.md b/backend/app/README.md index 9b07a70..f9053c7 100644 --- a/backend/app/README.md +++ b/backend/app/README.md @@ -1,356 +1,229 @@ -# 后端模块 (backend/app/) +# Backend App - 后端应用目录 -这是一个基于 LangGraph 的个人助手系统，提供对话、工具调用、记忆管理、RAG 检索和子图功能。 +本目录包含 AI Agent 系统的所有后端代码，采用模块化设计，层级清晰。 --- -## 📂 目录结构 +## 📁 目录结构 ``` -backend/app/ -├── agent/ # Agent 服务层 -│ ├── service.py # AIAgentService - 主服务类 -│ ├── rag_initializer.py # RAG 工具初始化 -│ ├── history.py # 对话历史管理 -│ └── prompts.py # 提示词模板 -├── agent_subgraphs/ # 子图模块 ✅ 已实现 -│ ├── common/ # 公共工具 -│ │ ├── state_base.py # 状态基类 -│ │ ├── intent.py # 意图理解（React 模式） -│ │ ├── formatter.py # 格式化输出工具 -│ │ └── human_review.py # 人工审核节点 -│ ├── contact/ # 通讯录子图 -│ ├── dictionary/ # 词典子图 -│ ├── news_analysis/ # 资讯分析子图 -│ ├── research/ # 研究分析子图（规划中） -│ └── README.md -├── graph/ # LangGraph 主图构建 -│ ├── graph_builder.py # 图构建器 -│ ├── graph_tools.py # 工具定义 -│ ├── state.py # 状态定义 -│ ├── retrieve_memory.py # 记忆检索节点 -│ ├── rag_nodes.py # RAG 集成节点 -│ └── visualize_graph.py # 图可视化 -├── memory/ # 记忆模块 -│ └── mem0_client.py # Mem0 客户端 -├── model_services/ # 模型服务层 ✅ 已重构 -│ ├── __init__.py -│ ├── base.py # 基类和降级机制 -│ ├── chat_services.py # 生成式大模型服务 -│ ├── embedding_services.py # 嵌入服务 -│ └── rerank_services.py # 重排服务 -├── nodes/ # LangGraph 节点实现 -│ ├── llm_call.py # LLM 调用节点 -│ ├── tool_call.py # 工具调用节点 -│ ├── router.py # 路由节点 -│ ├── summarize.py # 摘要节点 -│ ├── finalize.py # 最终节点 -│ └── memory_trigger.py # 记忆触发节点 -├── rag/ # RAG 检索模块 ✅ 已重构 -│ ├── pipeline.py # RAG 流水线 -│ ├── tools.py # RAG 工具 -│ ├── rerank.py # 重排业务逻辑 -│ ├── retriever.py # 检索器 -│ ├── query_transform.py # 查询转换 -│ └── fusion.py # 结果融合 -├── utils/ # 工具函数 -├── __init__.py -├── backend.py # FastAPI 后端入口 +app/ +├── __init__.py # 应用初始化 +├── backend.py # FastAPI 主入口，包含 API 端点 ├── config.py # 配置管理 -└── logger.py # 日志模块 +├── logger.py # 日志工具 +│ +├── core/ # ⭐ 核心模块 - 基类和通用工具 +│ ├── __init__.py +│ ├── state_base.py # 子图状态基类 +│ ├── intent.py # 意图理解（React 模式） +│ ├── intent_classifier.py # 意图分类器 +│ ├── formatter.py # 格式化输出工具 +│ └── human_review.py # 人工审核节点 +│ +├── agent/ # ⭐ Agent 服务层 +│ ├── __init__.py +│ ├── service.py # AIAgentService - 核心服务类 +│ ├── history.py # 历史查询服务 +│ └── prompts.py # 提示词模板 +│ +├── main_graph/ # ⭐ 主图 - LangGraph 主流程 +│ ├── __init__.py +│ ├── state.py # 主图状态定义 +│ ├── graph_builder.py # 主图构建器 +│ │ +│ ├── nodes/ # 主图节点 +│ │ ├── __init__.py +│ │ ├── router.py # 路由决策节点 +│ │ ├── llm_call.py # LLM 调用节点（React 模式） +│ │ ├── tool_call.py # 工具执行节点 +│ │ ├── retrieve_memory.py # 记忆检索节点 +│ │ ├── summarize.py # 记忆摘要节点 +│ │ ├── finalize.py # 最终处理节点 +│ │ ├── memory_trigger.py # 记忆触发节点 +│ │ ├── rag_nodes.py # RAG 相关节点 +│ │ └── react_nodes.py # React 模式节点 +│ │ +│ ├── tools/ # 主图工具 +│ │ ├── __init__.py +│ │ ├── graph_tools.py # 图工具定义 +│ │ └── subgraph_tools.py # 子图调用工具 +│ │ +│ └── utils/ # 主图工具函数 +│ ├── __init__.py +│ ├── retry_utils.py # 重试工具 +│ ├── subgraph_builder.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 +│ ├── base.py # 基类：BaseServiceProvider, FallbackServiceChain, SingletonServiceManager +│ ├── 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. Agent 服务 (agent/) -- **AIAgentService** - 主服务类 - - 接收外部 checkpointer，管理图生命周期 - - 支持多模型动态切换 - - 提供流式和非流式接口 -- **多模型支持** - 通过 chat_services - - 智谱 AI (glm-4.7-flash) - - DeepSeek (deepseek-reasoner) - - 本地模型 (vLLM/llama.cpp) -- **对话历史** - 基于 LangGraph 状态持久化 +### 1. `core/` - 核心模块 -### 2. LangGraph 主图 (graph/) -- **GraphBuilder** - 图构建器 - - 模块化节点创建，依赖注入 - - 支持 Mem0 客户端集成 -- **状态管理** - - MessagesState - 对话状态（消息、token、时间、摘要轮数） - - GraphContext - 执行上下文（用户 ID） -- **工具定义** - - get_current_temperature - 示例温度工具 - - read_local_file - 读取本地文件 - - read_pdf_summary - 读取 PDF - - read_excel_as_markdown - 读取 Excel - - fetch_webpage_content - 抓取网页 -- **React 模式** - 循环推理 + 超时重试 + 结构化错误处理 +这是整个系统的基础，被主图和所有子图共享： -### 3. 节点实现 (nodes/) -- **llm_call** - LLM 调用节点 -- **tool_call** - 工具调用节点 -- **router** - 路由节点（should_continue） -- **summarize** - 记忆摘要节点 -- **finalize** - 最终响应节点 -- **memory_trigger** - 记忆触发节点 - -### 4. 记忆管理 (memory/) -- **Mem0Client** - Mem0 记忆客户端 - - 异步初始化和连接测试 - - 支持记忆检索和添加 - - 可集成到 LangGraph 中 - -### 5. 模型服务层 (model_services/) -架构：纯服务层 + 业务逻辑分离 - -#### 5.1 基类与公共机制 (base.py) -- **BaseServiceProvider** - 服务提供者基类 - - 统一接口：is_available() 和 get_service() -- **FallbackServiceChain** - 链式降级机制 - - 优先尝试主服务，失败自动尝试备用服务 -- **SingletonServiceManager** - 单例管理器 - - 全局单例，避免重复创建 - -#### 5.2 生成式大模型 (chat_services.py) -- **LocalVLLMChatProvider** - 本地 VLLM 服务（gemma-4-E4B-it） -- **ZhipuChatProvider** - 智谱 AI 服务（glm-4.7-flash） -- **DeepSeekChatProvider** - DeepSeek 服务（deepseek-reasoner） -- **get_chat_service()** - 默认服务（自动降级） -- **get_all_chat_services()** - 获取所有可用模型 - -#### 5.3 嵌入服务 (embedding_services.py) -- **LocalLlamaCppEmbeddingProvider** - 本地 llama.cpp 嵌入 -- **ZhipuEmbeddingProvider** - 智谱 AI 嵌入 -- **get_embedding_service()** - 统一接口，自动降级 - -#### 5.4 重排服务 (rerank_services.py) -- **LocalLlamaCppRerankProvider** - 本地 llama.cpp 重排 -- **ZhipuRerankProvider** - 智谱 AI 重排 -- **get_rerank_service()** - 统一接口，自动降级 - -### 6. RAG 检索模块 (rag/) -架构：业务逻辑层 + 服务层分离 - -- **RAGPipeline** - RAG 流水线 - - 查询改写 → 并行检索 → RRF 融合 → 重排 → 返回结果 -- **DocumentReranker** - 重排业务逻辑（rag/rerank.py） -- **ParentDocumentRetriever** - 父文档检索器 -- **查询转换** - MultiQueryGenerator -- **结果融合** - Reciprocal Rank Fusion - -### 7. 子图模块 (agent_subgraphs/) ✅ 已实现 - -#### 7.1 公共工具 (common/) -- **state_base.py** - TypedDict 类型安全的状态基类 -- **intent.py** - 意图理解（React 模式）- 是否调用 RAG、是否重新检索 -- **formatter.py** - 格式化输出工具（Jinja2 + Markdown） -- **human_review.py** - 人工审核节点（LangGraph interrupt） - -#### 7.2 通讯录子图 (contact/) -- 联系人管理（CRUD） -- 邮件读取与审核 -- 外发邮件 -- 智能嗅探 -- API 客户端 -- 精美格式化展示 - -#### 7.3 词典子图 (dictionary/) -- 翻译、查词 -- 每日一词 -- 专业名词提炼 -- 生词本管理 -- API 客户端 -- 精美格式化展示 - -#### 7.4 资讯分析子图 (news_analysis/) -- 资讯获取 -- 内容分析 -- API 客户端 -- 精美格式化展示 - -#### 7.5 研究分析子图 (research/) -- 规划中 - -### 8. FastAPI 后端 (backend.py) -- POST /chat - 非流式对话 -- POST /chat/stream - 流式对话 -- 子图 API 端点 -- 人工审核交互端点（确定/取消/继续） - -### 9. 配置管理 (config.py) -- 集中管理环境变量 -- 智谱 AI 配置 - - ZHIPUAI_API_KEY - - ZHIPU_EMBEDDING_MODEL（默认 embedding-3） - - ZHIPU_RERANK_MODEL（默认 rerank-2） - - ZHIPU_API_BASE -- DeepSeek 配置 - - DEEPSEEK_API_KEY -- 本地模型配置 - - VLLM_BASE_URL（主 LLM） - - LLAMACPP_EMBEDDING_URL（嵌入） - - LLAMACPP_RERANKER_URL（重排） - - LLM_API_KEY / LLAMACPP_API_KEY -- 数据库和 Qdrant 配置 +| 文件 | 说明 | +|------|------| +| `state_base.py` | 所有子图状态的基类，定义通用字段和方法 | +| `intent.py` | React 模式的意图理解，用于解析用户意图 | +| `intent_classifier.py` | 意图分类器，用于混合路由 | +| `formatter.py` | 输出格式化工具，用于统一美化子图输出 | +| `human_review.py` | 人工审核节点，需要人工确认的操作 | --- -## 🚧 待完善功能 +### 2. `agent/` - Agent 服务层 -### 1. 子图模块 -- **research/** - 研究分析子图（联网搜索、报告生成、引用溯源、可视化） +对外提供服务的核心层： -### 2. 其他 -- 更完善的错误处理和日志 -- 监控和指标收集 -- API 文档完善（OpenAPI/Swagger） -- 单元测试和集成测试 +| 文件 | 说明 | +|------|------| +| `service.py` | `AIAgentService` 类，管理模型、图、工具，提供 `process_message` 和 `process_message_stream` 方法 | +| `history.py` | 历史对话查询服务 | +| `prompts.py` | 系统提示词模板 | --- -## 🛠️ 技术栈 +### 3. `main_graph/` - 主图 -| 层级 | 组件 | 技术选型 | -|------|------|---------| -| Agent 框架 | 工作流编排 | LangGraph + LangChain | -| LLM 服务 | 模型调用 | 智谱 AI / DeepSeek / 本地模型 (llama.cpp/vLLM) | -| Embedding | 向量嵌入 | 本地 llama.cpp / 智谱 AI | -| Rerank | 重排序 | 本地 llama.cpp / 智谱 AI | -| 向量数据库 | 语义检索 | Qdrant | -| 关系数据库 | 结构化存储 | PostgreSQL | -| 后端框架 | API 服务 | FastAPI + Uvicorn | -| 记忆服务 | 长期记忆 | Mem0 | +LangGraph 的主流程，处理普通对话和工具调用： + +| 目录/文件 | 说明 | +|----------|------| +| `state.py` | 主图状态定义，包含消息、RAG 上下文、错误记录等 | +| `graph_builder.py` | 构建主图的类，定义节点和边 | +| `nodes/` | 所有节点实现（router, llm_call, tool_call 等） | +| `tools/` | 图的工具定义（天气、文件、网页、RAG 等） | +| `utils/` | 辅助函数（重试、子图构建、初始化等） | --- -## 📝 使用指南 +### 4. `subgraphs/` - 子图模块 -### 快速开始 +三个独立的子图，每个子图都有完整的 `state.py`、`nodes.py`、`graph.py`： -1. **配置环境变量** - 复制 `.env` 文件并配置： - - 数据库配置（PostgreSQL） - - Qdrant 配置 - - LLM 配置（智谱/DeepSeek/本地） - - 嵌入和重排服务配置 +| 子图 | 功能 | +|------|------| +| `contact/` | 通讯录管理：CRUD、邮件处理、智能嗅探 | +| `dictionary/` | 词典：查词、翻译、生词本、专业术语提取 | +| `news_analysis/` | 资讯分析：获取资讯、内容分析、格式化展示 | -2. **启动后端** - ```bash - cd backend - python -m app.backend - ``` +--- -3. **API 接口** - - POST /chat - 非流式对话 - - POST /chat/stream - 流式对话 +### 5. `model_services/` - 模型服务层 -### 配置说明 +统一的模型服务接口，支持自动降级： -#### 必需配置 -```env -# 数据库 -DB_HOST=your_db_host -DB_PORT=5432 -DB_USER=your_db_user -DB_PASSWORD=*** -DB_NAME=langgraph_db +| 文件 | 说明 | +|------|------| +| `base.py` | `BaseServiceProvider`（基类）、`FallbackServiceChain`（降级链）、`SingletonServiceManager`（单例管理） | +| `chat_services.py` | 生成式大模型服务（智谱、DeepSeek、本地） | +| `embedding_services.py` | 嵌入模型服务 | +| `rerank_services.py` | 重排序服务 | -# Qdrant -QDRANT_URL=http://your_qdrant_host:6333 -QDRANT_API_KEY=your_qdrant_api_key +--- + +### 6. `rag/` - RAG 模块 + +知识库检索相关： + +| 文件 | 说明 | +|------|------| +| `retriever.py` | 向量检索器 | +| `rerank.py` | 重排序业务逻辑 | +| `pipeline.py` | RAG 流水线 | +| `fusion.py` | RAG-Fusion 多路召回融合 | +| `tools.py` | 封装为 LangChain Tool 的 RAG 工具 | +| `evaluate.py` | RAG 评估工具 | + +--- + +## 🔄 数据流 -# 至少配置一个 LLM -ZHIPUAI_API_KEY=*** -DEEPSEEK_API_KEY=*** ``` - -#### 可选配置 -```env -# 本地模型服务 -VLLM_BASE_URL=http://localhost:8000/v1 -LLAMACPP_EMBEDDING_URL=http://localhost:8001/v1 -LLAMACPP_RERANKER_URL=http://localhost:8002/v1 -LLM_API_KEY=*** -LLAMACPP_API_KEY=*** - -# 智谱其他配置 -ZHIPU_EMBEDDING_MODEL=embedding-3 -ZHIPU_RERANK_MODEL=rerank-2 -``` - -### 使用模型服务 - -#### 生成式大模型 -```python -from app.model_services import get_chat_service, get_all_chat_services - -# 自动选择可用服务（优先本地，降级智谱，再降级 DeepSeek） -llm = get_chat_service() - -# 获取所有可用模型（用于多模型切换） -all_llms = get_all_chat_services() # Dict[str, BaseChatModel] -``` - -#### 嵌入服务 -```python -from app.model_services import get_embedding_service - -# 自动选择可用服务（优先本地，降级智谱） -embeddings = get_embedding_service() - -# 使用 -vector = embeddings.embed_query("hello") -``` - -#### 重排服务 -```python -from app.model_services import get_rerank_service -from app.rag.rerank import create_document_reranker - -# 获取原始重排服务（仅计算分数） -rerank_service = get_rerank_service() -scores = rerank_service.compute_scores("query", ["doc1", "doc2"]) - -# 使用业务逻辑层（完整的文档重排） -reranker = create_document_reranker() -sorted_docs = reranker.compress_documents(docs, "query", top_n=5) +用户请求 + └─> backend.py (FastAPI) + └─> agent/service.py (AIAgentService) + ├─> model_services/ (获取模型) + ├─> main_graph/ (执行主图) + │ ├─> nodes/ (执行节点) + │ ├─> tools/ (调用工具) + │ └─> rag/ (RAG 检索) + └─> subgraphs/ (可选：调用子图) + └─> core/ (共享工具) ``` --- -## 📁 架构说明 +## 🚀 启动方式 -### 模型服务层架构 -``` -model_services/ -├── base.py # 基类：BaseServiceProvider, FallbackServiceChain, SingletonServiceManager -├── chat_services.py # 生成式大模型（纯服务层） -├── embedding_services.py # 嵌入服务（纯服务层） -└── rerank_services.py # 重排服务（纯服务层） +FastAPI 应用入口是 `backend.py`，可以通过以下方式启动： -业务逻辑层 -├── rag/rerank.py # 重排业务逻辑（使用 model_services） -└── agent/service.py # Agent 服务（使用 model_services） -``` +```bash +# 方式 1：直接运行 +cd backend && python -m app.backend -### 子图架构 -``` -agent_subgraphs/ -├── common/ # 公共工具（所有子图共享） -│ ├── state_base.py # 状态基类 -│ ├── intent.py # 意图理解 -│ ├── formatter.py # 格式化输出 -│ └── human_review.py # 人工审核 -├── contact/ # 每个子图独立目录 -│ ├── state.py # 状态定义 -│ ├── nodes.py # 节点实现 -│ ├── graph.py # 图构建 -│ ├── api_client.py # API 客户端 -│ └── __init__.py -└── dictionary/ - └── (同 contact) +# 方式 2：Uvicorn +uvicorn app.backend:app --reload --host 0.0.0.0 --port 8079 + +# 方式 3：Docker +docker compose up ```