root/ailine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新目录结构文档，适配重构后的目录
Some checks failed
构建并部署 AI Agent 服务 / deploy (push) Failing after 11m7s
Details

Browse Source
This commit is contained in:
root
2026-04-29 13:04:10 +08:00
parent ef5113bffb
commit dc26771614
2 changed files with 275 additions and 377 deletions
Download Patch File Download Diff File Expand all files Collapse all files

153
README.md
View File

@@ -63,8 +63,9 @@
| | 服务基类 | base.py | - | BaseServiceProvider + FallbackServiceChain + SingletonServiceManager | | | 服务基类 | base.py | - | BaseServiceProvider + FallbackServiceChain + SingletonServiceManager |
| **Embedding** | 向量嵌入 | llama.cpp server | latest | 本地 embedding 服务，支持多种模型 | | **Embedding** | 向量嵌入 | llama.cpp server | latest | 本地 embedding 服务，支持多种模型 |
| **Agent 框架** | 工作流编排 | LangGraph + LangChain | latest | 状态机驱动的智能体工作流 | | **Agent 框架** | 工作流编排 | LangGraph + LangChain | latest | 状态机驱动的智能体工作流 |
| **子图系统** | 模块化子图 | agent_subgraphs/ | - | 通讯录、词典、资讯分析等子图 | | **子图系统** | 模块化子图 | subgraphs/ | - | 通讯录、词典、资讯分析等子图 |
| | 公共工具 | common/ | - | 状态基类、意图理解、格式化输出、人工审核 | | | 核心工具 | core/ | - | 状态基类、意图理解、格式化输出、人工审核 |
| **主图系统** | 主流程 | main_graph/ | - | 主图节点、工具、构建器 |
| **向量数据库** | 向量检索 | Qdrant | v1.12+ | 高性能向量相似度检索（远程服务器） | | **向量数据库** | 向量检索 | Qdrant | v1.12+ | 高性能向量相似度检索（远程服务器） |
| **后端框架** | API 服务 | FastAPI + Uvicorn | v0.115+ | RESTful API + WebSocket + SSE 流式输出 | | **后端框架** | API 服务 | FastAPI + Uvicorn | v0.115+ | RESTful API + WebSocket + SSE 流式输出 |
| **前端框架** | Web 界面 | Streamlit | v1.40+ | 交互式对话界面，组件化设计 | | **前端框架** | Web 界面 | Streamlit | v1.40+ | 交互式对话界面，组件化设计 |
@@ -110,15 +111,15 @@ graph TB
RetrieveMemory -->|存储| PostgreSQL[(PostgreSQL)] RetrieveMemory -->|存储| PostgreSQL[(PostgreSQL)]
Summarize -->|存储| PostgreSQL Summarize -->|存储| PostgreSQL
SubgraphAPI -->|路由| Subgraphs[子图系统 agent_subgraphs] SubgraphAPI -->|路由| Subgraphs[子图系统 subgraphs]
Subgraphs --> Contact[通讯录子图] Subgraphs --> Contact[通讯录子图]
Subgraphs --> Dictionary[词典子图] Subgraphs --> Dictionary[词典子图]
Subgraphs --> NewsAnalysis[资讯分析子图] Subgraphs --> NewsAnalysis[资讯分析子图]
Subgraphs --> Common[公共工具 common/] Subgraphs --> Core[核心工具 core/]
Common --> Intent[意图理解 (React)] Core --> Intent[意图理解 (React)]
Common --> HumanReview[人工审核] Core --> HumanReview[人工审核]
Common --> Formatter[格式化输出] Core --> Formatter[格式化输出]
Common --> StateBase[状态基类] Core --> StateBase[状态基类]
Contact -->|数据库| ContactDB[(PostgreSQL 联系人)] Contact -->|数据库| ContactDB[(PostgreSQL 联系人)]
Dictionary -->|数据库| DictionaryDB[(PostgreSQL 生词本)] Dictionary -->|数据库| DictionaryDB[(PostgreSQL 生词本)]
@@ -354,53 +355,50 @@ Agent1/
│ │ ├── config.py # 配置管理 │ │ ├── config.py # 配置管理
│ │ ├── logger.py # 日志工具 │ │ ├── logger.py # 日志工具
│ │ ├── backend.py # FastAPI 后端应用（含子图 API） │ │ ├── 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 │ │ │ ├── __init__.py
│ │ │ ├── service.py # Agent 服务核心（使用 chat_services） │ │ │ ├── service.py # Agent 服务核心（使用 chat_services）
│ │ │ ├── history.py # 历史查询服务 │ │ │ ├── history.py # 历史查询服务
│ │ │ ├── prompts.py # 提示模板 │ │ │ └── prompts.py # 提示词模板
│ │ │ └── rag_initializer.py # RAG 工具初始化 │ │ │
│ │ ├── model_services/ # 模型服务层（新增） │ │ ├── main_graph/ # ⭐ 主图 - LangGraph 主流程
│ │ │ ├── __init__.py
│ │ │ ├── base.py # 基类：BaseServiceProvider, FallbackServiceChain, SingletonServiceManager
│ │ │ ├── chat_services.py # 生成式大模型服务（替代 llm_factory）
│ │ │ ├── embedding_services.py # 嵌入模型服务
│ │ │ └── rerank_services.py # 重排序服务
│ │ ├── graph/
│ │ │ ├── __init__.py │ │ │ ├── __init__.py
│ │ │ ├── state.py # 主图状态定义
│ │ │ ├── graph_builder.py # LangGraph 图构建器 │ │ │ ├── graph_builder.py # LangGraph 图构建器
│ │ │ ├── graph_tools.py # 工具定义 │ │ │ ├── nodes/ # 主图节点
│ │ │ ├── state.py # 状态定义 │ │ │ │ ├── __init__.py
│ │ │ ├── rag_nodes.py # RAG 集成节点 │ │ │ │ ├── router.py # 路由决策
│ │ │ └── retrieve_memory.py # 记忆检索 │ │ │ │ ├── llm_call.py # LLM 调用节点（React 模式）
│ │ ├── nodes/ │ │ │ │ ├── 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 │ │ │ ├── __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/ # 通讯录子图 │ │ │ ├── contact/ # 通讯录子图
│ │ │ │ ├── state.py # 状态定义 │ │ │ │ ├── state.py # 状态定义
│ │ │ │ ├── nodes.py # 节点实现 │ │ │ │ ├── nodes.py # 节点实现
@@ -413,14 +411,41 @@ Agent1/
│ │ │ │ ├── graph.py # 图构建 │ │ │ │ ├── graph.py # 图构建
│ │ │ │ ├── api_client.py # API 客户端 │ │ │ │ ├── api_client.py # API 客户端
│ │ │ │ └── __init__.py │ │ │ │ └── __init__.py
│ │ │ ├── news_analysis/ # 资讯分析子图 │ │ │ └── news_analysis/ # 资讯分析子图
│ │ │ │ ├── state.py # 状态定义 │ │ │ ├── state.py # 状态定义
│ │ │ │ ├── nodes.py # 节点实现 │ │ │ ├── nodes.py # 节点实现
│ │ │ │ ├── graph.py # 图构建 │ │ │ ├── graph.py # 图构建
│ │ │ │ ├── api_client.py # API 客户端 │ │ │ ├── api_client.py # API 客户端
│ │ │ │ └── __init__.py │ │ │ └── __init__.py
│ │ │ └── research/ # 研究分析子图（规划中） │ │ │
│ │ └── utils/ │ │ ├── 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 │ │ └── __init__.py
│ └── rag_core/ │ └── rag_core/
│ ├── __init__.py │ ├── __init__.py
@@ -739,8 +764,8 @@ python scripts/evaluate_rag.py
4. **可以多次循环** - LLM 可以调用多个工具，或者同一个工具多次 4. **可以多次循环** - LLM 可以调用多个工具，或者同一个工具多次
**实际代码位置**： **实际代码位置**：
- `backend/app/graph/graph_builder.py` 第 79 行：`builder.add_edge("tool_node", "llm_call")` - `backend/app/main_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/nodes/router.py`：`should_continue` 函数检查 `last_message.tool_calls`
#### 2.2 状态机设计 #### 2.2 状态机设计
@@ -1207,7 +1232,7 @@ sequenceDiagram
--- ---
### 公共工具说明 ### 核心工具说明
#### 1. state_base.py - 状态基类 #### 1. state_base.py - 状态基类
提供类型安全的状态基类，所有子图状态继承此类。 提供类型安全的状态基类，所有子图状态继承此类。
@@ -1239,13 +1264,13 @@ sequenceDiagram
1. **创建子图目录** 1. **创建子图目录**
```bash ```bash
mkdir backend/app/agent_subgraphs/my_subgraph mkdir backend/app/subgraphs/my_subgraph
``` ```
2. **创建状态定义 (state.py)** 2. **创建状态定义 (state.py)**
```python ```python
from typing_extensions import TypedDict from typing_extensions import TypedDict
from ..common.state_base import BaseSubgraphState from ..core.state_base import BaseSubgraphState
class MySubgraphState(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 ```python
@tool @tool
@@ -1863,7 +1888,7 @@ curl -X POST http://localhost:6333/collections/my_docs/actions \
#### 3.1 添加自定义工具 #### 3.1 添加自定义工具
```python ```python
# 在 backend/app/graph/graph_tools.py 中添加 # 在 backend/app/main_graph/tools/graph_tools.py 中添加
from langchain_core.tools import tool from langchain_core.tools import tool
from typing import Optional from typing import Optional

499
backend/app/README.md
View File

@@ -1,356 +1,229 @@
# 后端模块 (backend/app/) # Backend App - 后端应用目录
这是一个基于 LangGraph 的个人助手系统，提供对话、工具调用、记忆管理、RAG 检索和子图功能。 本目录包含 AI Agent 系统的所有后端代码，采用模块化设计，层级清晰。
--- ---
## 📂 目录结构 ## 📁 目录结构
``` ```
backend/app/ app/
├── agent/ # Agent 服务层 ├── __init__.py # 应用初始化
│ ├── service.py # AIAgentService - 主服务类 ├── backend.py # FastAPI 主入口，包含 API 端点
│ ├── 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 后端入口
├── config.py # 配置管理 ├── 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/) ### 1. `core/` - 核心模块
- **AIAgentService** - 主服务类
- 接收外部 checkpointer，管理图生命周期
- 支持多模型动态切换
- 提供流式和非流式接口
- **多模型支持** - 通过 chat_services
- 智谱 AI (glm-4.7-flash)
- DeepSeek (deepseek-reasoner)
- 本地模型 (vLLM/llama.cpp)
- **对话历史** - 基于 LangGraph 状态持久化
### 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** - 工具调用节点 | `state_base.py` | 所有子图状态的基类，定义通用字段和方法 |
- **router** - 路由节点（should_continue） | `intent.py` | React 模式的意图理解，用于解析用户意图 |
- **summarize** - 记忆摘要节点 | `intent_classifier.py` | 意图分类器，用于混合路由 |
- **finalize** - 最终响应节点 | `formatter.py` | 输出格式化工具，用于统一美化子图输出 |
- **memory_trigger** - 记忆触发节点 | `human_review.py` | 人工审核节点，需要人工确认的操作 |
### 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 配置
--- ---
## 🚧 待完善功能 ### 2. `agent/` - Agent 服务层
### 1. 子图模块 对外提供服务的核心层：
- **research/** - 研究分析子图（联网搜索、报告生成、引用溯源、可视化）
### 2. 其他 | 文件 | 说明 |
- 更完善的错误处理和日志 |------|------|
- 监控和指标收集 | `service.py` | `AIAgentService` 类，管理模型、图、工具，提供 `process_message` 和 `process_message_stream` 方法 |
- API 文档完善（OpenAPI/Swagger） | `history.py` | 历史对话查询服务 |
- 单元测试和集成测试 | `prompts.py` | 系统提示词模板 |
--- ---
## 🛠️ 技术栈 ### 3. `main_graph/` - 主图
| 层级 | 组件 | 技术选型 | LangGraph 的主流程，处理普通对话和工具调用：
|------|------|---------|
| Agent 框架 | 工作流编排 | LangGraph + LangChain | | 目录/文件 | 说明 |
| LLM 服务 | 模型调用 | 智谱 AI / DeepSeek / 本地模型 (llama.cpp/vLLM) | |----------|------|
| Embedding | 向量嵌入 | 本地 llama.cpp / 智谱 AI | | `state.py` | 主图状态定义，包含消息、RAG 上下文、错误记录等 |
| Rerank | 重排序 | 本地 llama.cpp / 智谱 AI | | `graph_builder.py` | 构建主图的类，定义节点和边 |
| 向量数据库 | 语义检索 | Qdrant | | `nodes/` | 所有节点实现（router, llm_call, tool_call 等） |
| 关系数据库 | 结构化存储 | PostgreSQL | | `tools/` | 图的工具定义（天气、文件、网页、RAG 等） |
| 后端框架 | API 服务 | FastAPI + Uvicorn | | `utils/` | 辅助函数（重试、子图构建、初始化等） |
| 记忆服务 | 长期记忆 | Mem0 |
--- ---
## 📝 使用指南 ### 4. `subgraphs/` - 子图模块
### 快速开始 三个独立的子图，每个子图都有完整的 `state.py`、`nodes.py`、`graph.py`：
1. **配置环境变量** | 子图 | 功能 |
复制 `.env` 文件并配置： |------|------|
- 数据库配置（PostgreSQL） | `contact/` | 通讯录管理：CRUD、邮件处理、智能嗅探 |
- Qdrant 配置 | `dictionary/` | 词典：查词、翻译、生词本、专业术语提取 |
- LLM 配置（智谱/DeepSeek/本地） | `news_analysis/` | 资讯分析：获取资讯、内容分析、格式化展示 |
- 嵌入和重排服务配置
2. **启动后端** ---
```bash
cd backend
python -m app.backend
```
3. **API 接口** ### 5. `model_services/` - 模型服务层
- POST /chat - 非流式对话
- POST /chat/stream - 流式对话
### 配置说明 统一的模型服务接口，支持自动降级：
#### 必需配置 | 文件 | 说明 |
```env |------|------|
# 数据库 | `base.py` | `BaseServiceProvider`（基类）、`FallbackServiceChain`（降级链）、`SingletonServiceManager`（单例管理） |
DB_HOST=your_db_host | `chat_services.py` | 生成式大模型服务（智谱、DeepSeek、本地） |
DB_PORT=5432 | `embedding_services.py` | 嵌入模型服务 |
DB_USER=your_db_user | `rerank_services.py` | 重排序服务 |
DB_PASSWORD=***
DB_NAME=langgraph_db
# 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=***
``` ```
用户请求
#### 可选配置 └─> backend.py (FastAPI)
```env └─> agent/service.py (AIAgentService)
# 本地模型服务 ├─> model_services/ (获取模型)
VLLM_BASE_URL=http://localhost:8000/v1 ├─> main_graph/ (执行主图)
LLAMACPP_EMBEDDING_URL=http://localhost:8001/v1 │ ├─> nodes/ (执行节点)
LLAMACPP_RERANKER_URL=http://localhost:8002/v1 │ ├─> tools/ (调用工具)
LLM_API_KEY=*** │ └─> rag/ (RAG 检索)
LLAMACPP_API_KEY=*** └─> subgraphs/ (可选：调用子图)
└─> core/ (共享工具)
# 智谱其他配置
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)
``` ```
--- ---
## 📁 架构说明 ## 🚀 启动方式
### 模型服务层架构 FastAPI 应用入口是 `backend.py`，可以通过以下方式启动：
```
model_services/
├── base.py # 基类：BaseServiceProvider, FallbackServiceChain, SingletonServiceManager
├── chat_services.py # 生成式大模型（纯服务层）
├── embedding_services.py # 嵌入服务（纯服务层）
└── rerank_services.py # 重排服务（纯服务层）
业务逻辑层 ```bash
├── rag/rerank.py # 重排业务逻辑（使用 model_services） # 方式 1：直接运行
└── agent/service.py # Agent 服务（使用 model_services） cd backend && python -m app.backend
```
### 子图架构 # 方式 2：Uvicorn
``` uvicorn app.backend:app --reload --host 0.0.0.0 --port 8079
agent_subgraphs/
├── common/ # 公共工具（所有子图共享） # 方式 3：Docker
│ ├── state_base.py # 状态基类 docker compose up
│ ├── intent.py # 意图理解
│ ├── formatter.py # 格式化输出
│ └── human_review.py # 人工审核
├── contact/ # 每个子图独立目录
│ ├── state.py # 状态定义
│ ├── nodes.py # 节点实现
│ ├── graph.py # 图构建
│ ├── api_client.py # API 客户端
│ └── __init__.py
└── dictionary/
└── (同 contact)
``` ```