From ad345e635d6b14a52558509efa72a630066c7d7c Mon Sep 17 00:00:00 2001 From: root <953994191@qq.com> Date: Sun, 26 Apr 2026 12:09:37 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20backend/app/README?= =?UTF-8?q?.md=EF=BC=8C=E6=8C=89=E6=A8=A1=E5=9D=97=E6=95=B4=E7=90=86?= =?UTF-8?q?=E5=B7=B2=E5=AE=9E=E7=8E=B0=E5=8A=9F=E8=83=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend/app/README.md | 231 +++++++++++++++++++++++++++++------------- 1 file changed, 161 insertions(+), 70 deletions(-) diff --git a/backend/app/README.md b/backend/app/README.md index 32475a7..9b07a70 100644 --- a/backend/app/README.md +++ b/backend/app/README.md @@ -1,7 +1,6 @@ # 后端模块 (backend/app/) -## 项目概览 -这是一个基于 LangGraph 的个人助手系统，提供对话、工具调用、记忆管理和 RAG 检索功能。 +这是一个基于 LangGraph 的个人助手系统，提供对话、工具调用、记忆管理、RAG 检索和子图功能。 --- @@ -11,23 +10,33 @@ backend/app/ ├── agent/ # Agent 服务层 │ ├── service.py # AIAgentService - 主服务类 -│ ├── llm_factory.py # LLM 工厂 - 多模型创建 │ ├── rag_initializer.py # RAG 工具初始化 │ ├── history.py # 对话历史管理 │ └── prompts.py # 提示词模板 -├── agent_subgraphs/ # 子图模块（规划中，仅 README） -├── graph/ # LangGraph 图构建 +├── 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/ # 模型服务（嵌入、重排等）⭐ 新增 +├── model_services/ # 模型服务层 ✅ 已重构 │ ├── __init__.py -│ ├── README.md │ ├── base.py # 基类和降级机制 +│ ├── chat_services.py # 生成式大模型服务 │ ├── embedding_services.py # 嵌入服务 │ └── rerank_services.py # 重排服务 ├── nodes/ # LangGraph 节点实现 @@ -37,10 +46,11 @@ backend/app/ │ ├── summarize.py # 摘要节点 │ ├── finalize.py # 最终节点 │ └── memory_trigger.py # 记忆触发节点 -├── rag/ # RAG 检索模块 +├── rag/ # RAG 检索模块 ✅ 已重构 │ ├── pipeline.py # RAG 流水线 │ ├── tools.py # RAG 工具 -│ ├── reranker.py # 重排器（将弃用，用 model_services） +│ ├── rerank.py # 重排业务逻辑 +│ ├── retriever.py # 检索器 │ ├── query_transform.py # 查询转换 │ └── fusion.py # 结果融合 ├── utils/ # 工具函数 @@ -59,13 +69,13 @@ backend/app/ - 接收外部 checkpointer，管理图生命周期 - 支持多模型动态切换 - 提供流式和非流式接口 -- **LLMFactory** - LLM 工厂 - - 支持智谱 AI (glm-4.7-flash) - - 支持 DeepSeek (deepseek-reasoner) - - 支持本地模型 (vLLM/llama.cpp) +- **多模型支持** - 通过 chat_services + - 智谱 AI (glm-4.7-flash) + - DeepSeek (deepseek-reasoner) + - 本地模型 (vLLM/llama.cpp) - **对话历史** - 基于 LangGraph 状态持久化 -### 2. LangGraph 图 (graph/) +### 2. LangGraph 主图 (graph/) - **GraphBuilder** - 图构建器 - 模块化节点创建，依赖注入 - 支持 Mem0 客户端集成 @@ -78,6 +88,7 @@ backend/app/ - read_pdf_summary - 读取 PDF - read_excel_as_markdown - 读取 Excel - fetch_webpage_content - 抓取网页 +- **React 模式** - 循环推理 + 超时重试 + 结构化错误处理 ### 3. 节点实现 (nodes/) - **llm_call** - LLM 调用节点 @@ -93,78 +104,110 @@ backend/app/ - 支持记忆检索和添加 - 可集成到 LangGraph 中 -### 5. 模型服务 (model_services/) - ⭐ 新增 +### 5. 模型服务层 (model_services/) +架构：纯服务层 + 业务逻辑分离 + +#### 5.1 基类与公共机制 (base.py) - **BaseServiceProvider** - 服务提供者基类 - 统一接口：is_available() 和 get_service() - **FallbackServiceChain** - 链式降级机制 - 优先尝试主服务，失败自动尝试备用服务 - **SingletonServiceManager** - 单例管理器 - 全局单例，避免重复创建 -- **Embedding 服务** - - LocalLlamaCppEmbeddingProvider - 本地 llama.cpp 嵌入 - - ZhipuEmbeddingProvider - 智谱 AI 嵌入 - - get_embedding_service() - 统一接口，自动降级 -- **Rerank 服务** - - LocalLlamaCppRerankProvider - 本地 llama.cpp 重排 - - ZhipuRerankProvider - 智谱 AI 重排 - - get_rerank_service() - 统一接口，自动降级 -### 6. RAG 检索 (rag/) +#### 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 融合 → 重排 → 返回结果 -- **ParentDocumentRetriever** - 父文档检索器（基于 rag_core） +- **DocumentReranker** - 重排业务逻辑（rag/rerank.py） +- **ParentDocumentRetriever** - 父文档检索器 - **查询转换** - MultiQueryGenerator - **结果融合** - Reciprocal Rank Fusion -### 7. 配置管理 (config.py) +### 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 配置 +- 智谱 AI 配置 - ZHIPUAI_API_KEY - ZHIPU_EMBEDDING_MODEL（默认 embedding-3） - ZHIPU_RERANK_MODEL（默认 rerank-2） - ZHIPU_API_BASE -- 支持本地 llama.cpp 配置 - - VLLM_BASE_URL - - LLAMACPP_EMBEDDING_URL - - LLAMACPP_RERANKER_URL - - LLAMACPP_API_KEY +- DeepSeek 配置 + - DEEPSEEK_API_KEY +- 本地模型配置 + - VLLM_BASE_URL（主 LLM） + - LLAMACPP_EMBEDDING_URL（嵌入） + - LLAMACPP_RERANKER_URL（重排） + - LLM_API_KEY / LLAMACPP_API_KEY - 数据库和 Qdrant 配置 --- -## 🚧 待实现功能 +## 🚧 待完善功能 -### 1. agent_subgraphs/ - 子图模块 -- **通讯录子图** - - 联系人 CRUD - - 邮件读取与审核 - - 外发邮件 - - 智能嗅探 -- **智能词典子图** - - 翻译、查词 - - 每日一词 - - 专业名词提炼 - - 生词本管理 -- **研究分析子图** - - 联网搜索 - - 报告生成 - - 引用溯源 - - 可视化图表 +### 1. 子图模块 +- **research/** - 研究分析子图（联网搜索、报告生成、引用溯源、可视化） -### 2. 公共工具层 (agent_subgraphs/common/) -- **意图理解工具** - 标准化意图分类和信息提取 -- **人工审核工具** - LangGraph interrupt + 状态持久化 -- **格式化输出工具** - Jinja2 模板 + Markdown -- **检查点持久化工具** - LangGraph CheckpointSaver -- **条件路由工具** - 标准化路由机制 -- **LLM 调用工具** - 统一接口 + 重试 + Token 计数 + 降级 -- **数据库工具** - SQLAlchemy 会话管理 + 标准 CRUD -- **状态基类工具** - TypedDict 类型安全的状态基类 - -### 3. 其他待完善 +### 2. 其他 - 更完善的错误处理和日志 - 监控和指标收集 -- API 文档完善 +- API 文档完善（OpenAPI/Swagger） - 单元测试和集成测试 --- @@ -213,7 +256,7 @@ backend/app/ DB_HOST=your_db_host DB_PORT=5432 DB_USER=your_db_user -DB_PASSWORD=your_db_password +DB_PASSWORD=*** DB_NAME=langgraph_db # Qdrant @@ -221,8 +264,8 @@ QDRANT_URL=http://your_qdrant_host:6333 QDRANT_API_KEY=your_qdrant_api_key # 至少配置一个 LLM -ZHIPUAI_API_KEY=your_zhipu_key -DEEPSEEK_API_KEY=your_deepseek_key +ZHIPUAI_API_KEY=*** +DEEPSEEK_API_KEY=*** ``` #### 可选配置 @@ -231,7 +274,8 @@ DEEPSEEK_API_KEY=your_deepseek_key VLLM_BASE_URL=http://localhost:8000/v1 LLAMACPP_EMBEDDING_URL=http://localhost:8001/v1 LLAMACPP_RERANKER_URL=http://localhost:8002/v1 -LLAMACPP_API_KEY=your_key +LLM_API_KEY=*** +LLAMACPP_API_KEY=*** # 智谱其他配置 ZHIPU_EMBEDDING_MODEL=embedding-3 @@ -240,6 +284,17 @@ 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 @@ -254,12 +309,48 @@ vector = embeddings.embed_query("hello") #### 重排服务 ```python from app.model_services import get_rerank_service +from app.rag.rerank import create_document_reranker -# 自动选择可用服务 -reranker = get_rerank_service() +# 获取原始重排服务（仅计算分数） +rerank_service = get_rerank_service() +scores = rerank_service.compute_scores("query", ["doc1", "doc2"]) -# 使用 -from langchain_core.documents import Document -docs = [Document(page_content="...")] +# 使用业务逻辑层（完整的文档重排） +reranker = create_document_reranker() sorted_docs = reranker.compress_documents(docs, "query", top_n=5) ``` + +--- + +## 📁 架构说明 + +### 模型服务层架构 +``` +model_services/ +├── base.py # 基类：BaseServiceProvider, FallbackServiceChain, SingletonServiceManager +├── chat_services.py # 生成式大模型（纯服务层） +├── embedding_services.py # 嵌入服务（纯服务层） +└── rerank_services.py # 重排服务（纯服务层） + +业务逻辑层 +├── rag/rerank.py # 重排业务逻辑（使用 model_services） +└── agent/service.py # Agent 服务（使用 model_services） +``` + +### 子图架构 +``` +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) +```