docs: 更新主 README.md，添加模型服务层和子图系统说明

README.md

@@ -29,16 +29,22 @@
 - 🌐 **网页抓取**：提取网页正文内容
 - 🔍 **知识库检索（RAG）**：基于向量数据库的智能问答
 - 🔄 **多模型切换**：前端可选择不同大语言模型
+- 📇 **通讯录管理**：子图模块，联系人 CRUD、邮件处理
+- 📖 **智能词典**：子图模块，翻译、生词本、专业术语提取
+- 📰 **资讯分析**：子图模块，资讯获取、内容分析、格式化展示
 
 ### 技术特性
 
 - ✅ **持久化记忆**：PostgreSQL 存储对话历史，重启不丢失
-- ✅ **高可用架构**：模型自动降级，确保服务稳定
+- ✅ **高可用架构**：模型服务自动降级，确保服务稳定
 - ✅ **前后端分离**：FastAPI 后端 + Streamlit 前端
 - ✅ **Docker 部署**：一键启动所有服务
 - ✅ **远程服务架构**：PostgreSQL 和 Qdrant 部署在远程服务器
 - ✅ **流式响应**：SSE 流式输出，提升用户体验
 - ✅ **模块化设计**：清晰的代码分层，易于扩展和维护
+- ✅ **模型服务层**：统一的 Embedding、Rerank、Chat 服务接口，支持自动降级
+- ✅ **子图系统**：模块化的子图架构，共享公共工具（意图理解、人工审核、格式化输出）
+- ✅ **React 模式**：循环推理 + 超时重试 + 结构化错误处理
 
 ---
 
@@ -51,8 +57,14 @@
 | **LLM 服务** | 云端模型 | 智谱 AI (glm-4.7-flash) | v4.7 | 快速响应，适合日常对话 |
 | | | DeepSeek (deepseek-reasoner) | v3 | 深度推理，适合复杂问题 |
 | | 本地模型 | Gemma-4-E4B-it | v4 | 本地部署，保护隐私 |
+| **模型服务层** | Chat 服务 | chat_services.py | - | 统一的生成式大模型接口 |
+| | Embedding 服务 | embedding_services.py | - | 统一的嵌入模型接口 |
+| | Rerank 服务 | rerank_services.py | - | 统一的重排序接口 |
+| | 服务基类 | base.py | - | BaseServiceProvider + FallbackServiceChain + SingletonServiceManager |
 | **Embedding** | 向量嵌入 | llama.cpp server | latest | 本地 embedding 服务，支持多种模型 |
 | **Agent 框架** | 工作流编排 | LangGraph + LangChain | latest | 状态机驱动的智能体工作流 |
+| **子图系统** | 模块化子图 | agent_subgraphs/ | - | 通讯录、词典、资讯分析等子图 |
+| | 公共工具 | common/ | - | 状态基类、意图理解、格式化输出、人工审核 |
 | **向量数据库** | 向量检索 | Qdrant | v1.12+ | 高性能向量相似度检索（远程服务器） |
 | **后端框架** | API 服务 | FastAPI + Uvicorn | v0.115+ | RESTful API + WebSocket + SSE 流式输出 |
 | **前端框架** | Web 界面 | Streamlit | v1.40+ | 交互式对话界面，组件化设计 |
@@ -66,39 +78,54 @@
 graph TB
     User[用户浏览器] -->|HTTP/SSE| Frontend[Streamlit 前端 :8501]
     Frontend -->|REST API| Backend[FastAPI 后端 :8083]
-    
+
     Backend --> AgentService[AIAgentService]
-    
+    Backend --> SubgraphAPI[子图 API 端点]
-    AgentService -->|模型路由| LLMFactory[LLM Factory]
+
-    LLMFactory -->|创建| Zhipu[智谱 GLM-4.7]
+    AgentService -->|模型路由| ChatServices[模型服务层 chat_services]
-    LLMFactory -->|创建| DeepSeek[DeepSeek Reasoner]
+    ChatServices -->|自动降级| FallbackChain[FallbackServiceChain]
-    LLMFactory -->|创建| LocalGemma[本地 Gemma-4]
+    FallbackChain -->|创建| Zhipu[智谱 GLM-4.7]
-    
+    FallbackChain -->|创建| DeepSeek[DeepSeek Reasoner]
+    FallbackChain -->|创建| LocalGemma[本地 Gemma-4]
+
     AgentService -->|初始化| LangGraph[LangGraph 工作流引擎]
-    
+
     LangGraph -->|节点1| RetrieveMemory[记忆检索]
     LangGraph -->|节点2| MemoryTrigger[记忆触发]
-    LangGraph -->|节点3| LLMCall[LLM 调用]
+    LangGraph -->|节点3| LLMCall[LLM 调用 (React 模式)]
     LangGraph -->|节点4| ToolNode[工具执行]
     LangGraph -->|节点5| Summarize[记忆摘要]
     LangGraph -->|节点6| Finalize[最终处理]
-    
+
     ToolNode -->|调用| Tools[工具集合]
     Tools -->|天气| WeatherTool[天气查询]
     Tools -->|文件| FileTool[文件读取]
     Tools -->|网页| WebTool[网页抓取]
     Tools -->|RAG| RAGTool[知识库检索]
-    
+
     RAGTool -->|检索| Qdrant[(Qdrant 向量库)]
-    RAGTool -->|重排序| CrossEncoder[Cross-Encoder]
+    RAGTool -->|重排序| RerankService[rerank_services]
-    
+    RAGTool -->|嵌入| EmbeddingService[embedding_services]
+
     RetrieveMemory -->|存储| PostgreSQL[(PostgreSQL)]
     Summarize -->|存储| PostgreSQL
-    
+
+    SubgraphAPI -->|路由| Subgraphs[子图系统 agent_subgraphs]
+    Subgraphs --> Contact[通讯录子图]
+    Subgraphs --> Dictionary[词典子图]
+    Subgraphs --> NewsAnalysis[资讯分析子图]
+    Subgraphs --> Common[公共工具 common/]
+    Common --> Intent[意图理解 (React)]
+    Common --> HumanReview[人工审核]
+    Common --> Formatter[格式化输出]
+    Common --> StateBase[状态基类]
+
     style User fill:#e1f5ff
     style Frontend fill:#fff4e1
     style Backend fill:#e8f5e9
+    style ChatServices fill:#c8e6c9
     style LangGraph fill:#f3e5f5
+    style Subgraphs fill:#fff3e0
     style PostgreSQL fill:#ffebee
     style Qdrant fill:#ffebee
 ```
@@ -174,24 +201,30 @@ Agent1/
 │   │   ├── __init__.py
 │   │   ├── config.py              # 配置管理
 │   │   ├── logger.py              # 日志工具
-│   │   ├── backend.py             # FastAPI 后端应用
+│   │   ├── backend.py             # FastAPI 后端应用（含子图 API）
 │   │   ├── agent/
 │   │   │   ├── __init__.py
-│   │   │   ├── service.py         # Agent 服务核心
+│   │   │   ├── service.py         # Agent 服务核心（使用 chat_services）
-│   │   │   ├── llm_factory.py     # LLM 工厂
 │   │   │   ├── 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/
 │   │   │   ├── __init__.py
 │   │   │   ├── graph_builder.py   # LangGraph 图构建器
 │   │   │   ├── graph_tools.py     # 工具定义
 │   │   │   ├── state.py           # 状态定义
+│   │   │   ├── rag_nodes.py       # RAG 集成节点
 │   │   │   └── retrieve_memory.py # 记忆检索
 │   │   ├── nodes/
 │   │   │   ├── __init__.py
 │   │   │   ├── router.py          # 路由决策
-│   │   │   ├── llm_call.py        # LLM 调用节点
+│   │   │   ├── llm_call.py        # LLM 调用节点（React 模式）
 │   │   │   ├── tool_call.py       # 工具执行节点
 │   │   │   ├── retrieve_memory.py # 记忆检索节点
 │   │   │   ├── summarize.py       # 记忆存储节点
@@ -203,11 +236,38 @@ Agent1/
 │   │   ├── rag/
 │   │   │   ├── __init__.py
 │   │   │   ├── retriever.py       # 检索器
-│   │   │   ├── reranker.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       # 节点实现
+│   │   │   │   ├── graph.py       # 图构建
+│   │   │   │   ├── api_client.py  # API 客户端
+│   │   │   │   └── __init__.py
+│   │   │   ├── dictionary/        # 词典子图
+│   │   │   │   ├── state.py       # 状态定义
+│   │   │   │   ├── nodes.py       # 节点实现
+│   │   │   │   ├── graph.py       # 图构建
+│   │   │   │   ├── api_client.py  # API 客户端
+│   │   │   │   └── __init__.py
+│   │   │   ├── news_analysis/     # 资讯分析子图
+│   │   │   │   ├── state.py       # 状态定义
+│   │   │   │   ├── nodes.py       # 节点实现
+│   │   │   │   ├── graph.py       # 图构建
+│   │   │   │   ├── api_client.py  # API 客户端
+│   │   │   │   └── __init__.py
+│   │   │   └── research/          # 研究分析子图（规划中）
 │   │   └── utils/
 │   │       └── __init__.py
 │   └── rag_core/
@@ -226,7 +286,7 @@ Agent1/
 │   └── src/
 │       ├── __init__.py
 │       ├── frontend_main.py       # Streamlit 主入口
-│       ├── api_client.py          # API 客户端
+│       ├── api_client.py          # API 客户端（含子图调用）
 │       ├── config.py              # 前端配置
 │       ├── state.py               # 状态管理
 │       ├── logger.py              # 日志
@@ -255,7 +315,7 @@ Agent1/
 ├── test/                      # 测试目录
 │   ├── test_backend.py
 │   ├── test_rag.py
-│   ├── test_dqrant.py
+│   ├── test_qdrant.py
 │   └── test_rag_indexer_result.py
 ├── .gitea/
 │   └── workflows/
@@ -785,7 +845,156 @@ RAG 系统分为两个独立但协同的阶段：
 
 ---
 
-## <EFBFBD><EFBFBD> 快速开始
+## 🧩 子图系统架构
+
+### 设计理念
+
+子图系统采用模块化设计，每个子图是一个独立的 LangGraph 工作流，共享公共工具库。
+
+```
+┌───────────────────────────────────────────────────────────────────┐
+│                        子图系统架构                                 │
+├───────────────────────────────────────────────────────────────────┤
+│                                                                   │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │  公共工具库 (common/)                                        │ │
+│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────┐ │ │
+│  │  │ state_base  │ │   intent    │ │ formatter   │ │human │ │ │
+│  │  │   (状态)    │ │  (React)    │ │  (格式化)   │ │review│ │ │
+│  │  └─────────────┘ └─────────────┘ └─────────────┘ └──────┘ │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│                              │                                    │
+│              ┌───────────────┼───────────────┐                   │
+│              ↓               ↓               ↓                   │
+│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐   │
+│  │  通讯录子图     │ │  词典子图       │ │  资讯分析子图   │   │
+│  │  (contact/)    │ │  (dictionary/)  │ │ (news_analysis) │   │
+│  ├─────────────────┤ ├─────────────────┤ ├─────────────────┤   │
+│  │ state.py        │ │ state.py        │ │ state.py        │   │
+│  │ nodes.py        │ │ nodes.py        │ │ nodes.py        │   │
+│  │ graph.py        │ │ graph.py        │ │ graph.py        │   │
+│  │ api_client.py   │ │ api_client.py   │ │ api_client.py   │   │
+│  └─────────────────┘ └─────────────────┘ └─────────────────┘   │
+│                              │                                    │
+│                              ▼                                    │
+│                     FastAPI 子图端点                               │
+│                     (backend/app/backend.py)                       │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+### 公共工具说明
+
+#### 1. state_base.py - 状态基类
+提供类型安全的状态基类，所有子图状态继承此类。
+
+#### 2. intent.py - 意图理解（React 模式）
+智能决策节点，判断是否需要调用 RAG、是否需要重新检索、是否需要调用工具。
+
+```python
+# 核心功能
+- 意图分类：闲聊 / 查询 / 任务
+- RAG 决策：是否需要检索知识库
+- 检索策略：是否需要多路检索 / 是否需要重新检索
+```
+
+#### 3. formatter.py - 格式化输出工具
+使用 Jinja2 模板提供美观的 Markdown 格式化输出。
+
+#### 4. human_review.py - 人工审核节点
+使用 LangGraph 的 interrupt 机制实现人工审核流程，支持：
+- 确定 / 取消 / 继续 三种操作
+- 状态持久化
+- 异步等待
+
+### 子图开发指南
+
+#### 创建新子图的步骤
+
+1. **创建子图目录**
+```bash
+mkdir backend/app/agent_subgraphs/my_subgraph
+```
+
+2. **创建状态定义 (state.py)**
+```python
+from typing_extensions import TypedDict
+from ..common.state_base import BaseSubgraphState
+
+class MySubgraphState(BaseSubgraphState):
+    \"\"\"
+    我的子图状态
+    \"\"\"
+    my_field: str
+    my_list: list[str]
+```
+
+3. **实现节点 (nodes.py)**
+```python
+from langgraph.graph import StateGraph
+from .state import MySubgraphState
+
+def my_node(state: MySubgraphState) -> MySubgraphState:
+    \"\"\"
+    我的节点
+    \"\"\"
+    # 实现逻辑
+    return state
+```
+
+4. **构建图 (graph.py)**
+```python
+from langgraph.graph import StateGraph, END
+from .state import MySubgraphState
+from .nodes import my_node
+
+def build_my_subgraph() -> StateGraph:
+    \"\"\"
+    构建我的子图
+    \"\"\"
+    graph = StateGraph(MySubgraphState)
+
+    graph.add_node("my_node", my_node)
+    graph.set_entry_point("my_node")
+    graph.add_edge("my_node", END)
+
+    return graph.compile()
+```
+
+5. **添加 API 客户端 (api_client.py)**（可选）
+用于与外部 API 交互。
+
+6. **在 backend.py 中添加 API 端点**
+
+### 已实现的子图
+
+#### 1. 通讯录子图 (contact/)
+- 联系人 CRUD
+- 邮件读取与审核
+- 外发邮件
+- 智能嗅探
+- 精美格式化展示
+
+#### 2. 词典子图 (dictionary/)
+- 翻译、查词
+- 每日一词
+- 专业名词提炼
+- 生词本管理
+- 精美格式化展示
+
+#### 3. 资讯分析子图 (news_analysis/)
+- 资讯获取
+- 内容分析
+- 精美格式化展示
+
+#### 4. 研究分析子图 (research/) - 规划中
+- 联网搜索
+- 报告生成
+- 引用溯源
+- 可视化图表
+
+---
+
+## 🚀 快速开始
 
 详细启动指南请查看 [QUICKSTART.md](QUICKSTART.md)
 
@@ -888,32 +1097,98 @@ def my_new_tool(param: str) -> str:
 
 ### 添加新模型
 
-在 [backend/app/agent/llm_factory.py](file:///home/huang/Study/AIProject/Agent1/backend/app/agent/llm_factory.py) 中添加模型创建方法：
+在 [backend/app/model_services/chat_services.py](file:///root/projects/ailine/backend/app/model_services/chat_services.py) 中添加新的服务提供者：
 
 ```python
-@staticmethod
+class NewModelChatProvider(BaseServiceProvider[BaseChatModel]):
-def create_new_model():
+    """
-    api_key = os.getenv("NEW_MODEL_API_KEY")
+    新模型服务提供者
-    return ChatOpenAI(
+    """
-        base_url="https://api.new-model.com/v1",
+
-        api_key=SecretStr(api_key),
+    def __init__(self, model: str = "new-model-name"):
-        model="model-name",
+        super().__init__("new_model_chat")
-        temperature=0.1,
+        self._model = model
-        streaming=True,
+
-    )
+    def is_available(self) -> bool:
+        """
+        检查新模型服务是否可用
+        """
+        if not os.getenv("NEW_MODEL_API_KEY"):
+            logger.warning("NEW_MODEL_API_KEY 未配置")
+            return False
+        logger.info(f"新模型服务配置正确，准备使用: {self._model}")
+        return True
+
+    def get_service(self) -> BaseChatModel:
+        """
+        获取新模型服务
+        """
+        if self._service_instance is None:
+            from langchain_openai import ChatOpenAI
+            from pydantic import SecretStr
+
+            self._service_instance = ChatOpenAI(
+                base_url="https://api.new-model.com/v1",
+                api_key=SecretStr(os.getenv("NEW_MODEL_API_KEY")),
+                model=self._model,
+                temperature=0.1,
+                max_tokens=4096,
+                timeout=60.0,
+                max_retries=2,
+                streaming=True,
+            )
+        return self._service_instance
 ```
 
-然后在 `CREATORS` 字典中注册：
+然后在 `CHAT_PROVIDERS` 字典中注册：
 
 ```python
-CREATORS = {
+CHAT_PROVIDERS: Dict[str, Callable[[], BaseServiceProvider[BaseChatModel]]] = {
-    "local": create_local,
+    "local": lambda: LocalVLLMChatProvider(),
-    "deepseek": create_deepseek,
+    "zhipu": lambda: ZhipuChatProvider(),
-    "zhipu": create_zhipu,
+    "deepseek": lambda: DeepSeekChatProvider(),
-    "new_model": create_new_model,  # 新增
+    "new_model": lambda: NewModelChatProvider(),  # 新增
 }
 ```
 
+### 使用模型服务
+
+#### 生成式大模型
+```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)
+```
+
 ### Docker 部署
 
 项目包含完整的 Docker 配置：
@@ -950,10 +1225,17 @@ CREATORS = {
 | `ZHIPUAI_API_KEY` | 智谱AI API密钥 | `your-api-key` | `your-api-key` |
 | `DEEPSEEK_API_KEY` | DeepSeek API密钥 | `your-api-key` | `your-api-key` |
 | `LLAMACPP_API_KEY` | llama.cpp API 密钥 | `token-abc123` | `token-abc123` |
+| `LLM_API_KEY` | 主 LLM 服务 API 密钥 | `token-abc123` | `token-abc123` |
 | `VLLM_BASE_URL` | LLM 服务地址 | `http://127.0.0.1:8081/v1` | `http://your-server:8081/v1` |
 | `LLAMACPP_EMBEDDING_URL` | Embedding 服务地址 | `http://127.0.0.1:8082/v1` | `http://your-server:8082/v1` |
+| `LLAMACPP_RERANKER_URL` | Rerank 服务地址 | `http://127.0.0.1:8083/v1` | `http://your-server:8083/v1` |
+| `ZHIPU_EMBEDDING_MODEL` | 智谱嵌入模型（可选） | `embedding-3` | `embedding-3` |
+| `ZHIPU_RERANK_MODEL` | 智谱重排模型（可选） | `rerank-2` | `rerank-2` |
+| `ZHIPU_API_BASE` | 智谱 API 基础地址（可选） | `https://open.bigmodel.cn/api/paas/v4` | 同左 |
 | `DB_URI` | PostgreSQL 连接字符串 | `postgresql://...@115.190.121.151:5432/langgraph_db` | 同左 |
 | `QDRANT_URL` | Qdrant 向量数据库地址 | `http://115.190.121.151:6333` | 同左 |
+| `QDRANT_API_KEY` | Qdrant API 密钥 | `your-api-key` | `your-api-key` |
+| `QDRANT_COLLECTION_NAME` | Qdrant 集合名称 | `rag_documents` | `rag_documents` |
 | `LOG_LEVEL` | 日志级别 | `INFO` | `WARNING` |
 | `ENABLE_GRAPH_TRACE` | 是否启用图流转追踪 | `true` | `false` |
 | `MEMORY_SUMMARIZE_INTERVAL` | 对话摘要生成间隔 | `10` | `10` |