root
851d52ed8d
All checks were successful
构建并部署 AI Agent 服务 / deploy (push) Successful in 5m37s
- 创建 backend/app/README.md 主文档 - 整理已实现功能（带 ✅ 标记） - 列出待实现功能（带 🚧 标记） - 删除 agent_subgraphs/ 下的旧 README 文件
266 lines
8.1 KiB
Markdown
266 lines
8.1 KiB
Markdown
# 后端模块 (backend/app/)
|
||
|
||
## 项目概览
|
||
这是一个基于 LangGraph 的个人助手系统，提供对话、工具调用、记忆管理和 RAG 检索功能。
|
||
|
||
---
|
||
|
||
## 📂 目录结构
|
||
|
||
```
|
||
backend/app/
|
||
├── agent/ # Agent 服务层
|
||
│ ├── service.py # AIAgentService - 主服务类
|
||
│ ├── llm_factory.py # LLM 工厂 - 多模型创建
|
||
│ ├── rag_initializer.py # RAG 工具初始化
|
||
│ ├── history.py # 对话历史管理
|
||
│ └── prompts.py # 提示词模板
|
||
├── agent_subgraphs/ # 子图模块（规划中，仅 README）
|
||
├── graph/ # LangGraph 图构建
|
||
│ ├── graph_builder.py # 图构建器
|
||
│ ├── graph_tools.py # 工具定义
|
||
│ ├── state.py # 状态定义
|
||
│ ├── retrieve_memory.py # 记忆检索节点
|
||
│ └── visualize_graph.py # 图可视化
|
||
├── memory/ # 记忆模块
|
||
│ └── mem0_client.py # Mem0 客户端
|
||
├── model_services/ # 模型服务（嵌入、重排等）⭐ 新增
|
||
│ ├── __init__.py
|
||
│ ├── README.md
|
||
│ ├── base.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 工具
|
||
│ ├── reranker.py # 重排器（将弃用，用 model_services）
|
||
│ ├── query_transform.py # 查询转换
|
||
│ └── fusion.py # 结果融合
|
||
├── utils/ # 工具函数
|
||
├── __init__.py
|
||
├── backend.py # FastAPI 后端入口
|
||
├── config.py # 配置管理
|
||
└── logger.py # 日志模块
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 已实现功能
|
||
|
||
### 1. Agent 服务 (agent/)
|
||
- **AIAgentService** - 主服务类
|
||
- 接收外部 checkpointer，管理图生命周期
|
||
- 支持多模型动态切换
|
||
- 提供流式和非流式接口
|
||
- **LLMFactory** - LLM 工厂
|
||
- 支持智谱 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 - 抓取网页
|
||
|
||
### 3. 节点实现 (nodes/)
|
||
- **llm_call** - LLM 调用节点
|
||
- **tool_call** - 工具调用节点
|
||
- **router** - 路由节点（should_continue）
|
||
- **summarize** - 记忆摘要节点
|
||
- **finalize** - 最终响应节点
|
||
- **memory_trigger** - 记忆触发节点
|
||
|
||
### 4. 记忆管理 (memory/)
|
||
- **Mem0Client** - Mem0 记忆客户端
|
||
- 异步初始化和连接测试
|
||
- 支持记忆检索和添加
|
||
- 可集成到 LangGraph 中
|
||
|
||
### 5. 模型服务 (model_services/) - ⭐ 新增
|
||
- **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/)
|
||
- **RAGPipeline** - RAG 流水线
|
||
- 查询改写 → 并行检索 → RRF 融合 → 重排 → 返回结果
|
||
- **ParentDocumentRetriever** - 父文档检索器（基于 rag_core）
|
||
- **查询转换** - MultiQueryGenerator
|
||
- **结果融合** - Reciprocal Rank Fusion
|
||
|
||
### 7. 配置管理 (config.py)
|
||
- 集中管理环境变量
|
||
- 支持智谱 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
|
||
- 数据库和 Qdrant 配置
|
||
|
||
---
|
||
|
||
## 🚧 待实现功能
|
||
|
||
### 1. agent_subgraphs/ - 子图模块
|
||
- **通讯录子图**
|
||
- 联系人 CRUD
|
||
- 邮件读取与审核
|
||
- 外发邮件
|
||
- 智能嗅探
|
||
- **智能词典子图**
|
||
- 翻译、查词
|
||
- 每日一词
|
||
- 专业名词提炼
|
||
- 生词本管理
|
||
- **研究分析子图**
|
||
- 联网搜索
|
||
- 报告生成
|
||
- 引用溯源
|
||
- 可视化图表
|
||
|
||
### 2. 公共工具层 (agent_subgraphs/common/)
|
||
- **意图理解工具** - 标准化意图分类和信息提取
|
||
- **人工审核工具** - LangGraph interrupt + 状态持久化
|
||
- **格式化输出工具** - Jinja2 模板 + Markdown
|
||
- **检查点持久化工具** - LangGraph CheckpointSaver
|
||
- **条件路由工具** - 标准化路由机制
|
||
- **LLM 调用工具** - 统一接口 + 重试 + Token 计数 + 降级
|
||
- **数据库工具** - SQLAlchemy 会话管理 + 标准 CRUD
|
||
- **状态基类工具** - TypedDict 类型安全的状态基类
|
||
|
||
### 3. 其他待完善
|
||
- 更完善的错误处理和日志
|
||
- 监控和指标收集
|
||
- API 文档完善
|
||
- 单元测试和集成测试
|
||
|
||
---
|
||
|
||
## 🛠️ 技术栈
|
||
|
||
| 层级 | 组件 | 技术选型 |
|
||
|------|------|---------|
|
||
| Agent 框架 | 工作流编排 | LangGraph + LangChain |
|
||
| LLM 服务 | 模型调用 | 智谱 AI / DeepSeek / 本地模型 (llama.cpp/vLLM) |
|
||
| Embedding | 向量嵌入 | 本地 llama.cpp / 智谱 AI |
|
||
| Rerank | 重排序 | 本地 llama.cpp / 智谱 AI |
|
||
| 向量数据库 | 语义检索 | Qdrant |
|
||
| 关系数据库 | 结构化存储 | PostgreSQL |
|
||
| 后端框架 | API 服务 | FastAPI + Uvicorn |
|
||
| 记忆服务 | 长期记忆 | Mem0 |
|
||
|
||
---
|
||
|
||
## 📝 使用指南
|
||
|
||
### 快速开始
|
||
|
||
1. **配置环境变量**
|
||
复制 `.env` 文件并配置：
|
||
- 数据库配置（PostgreSQL）
|
||
- Qdrant 配置
|
||
- LLM 配置（智谱/DeepSeek/本地）
|
||
- 嵌入和重排服务配置
|
||
|
||
2. **启动后端**
|
||
```bash
|
||
cd backend
|
||
python -m app.backend
|
||
```
|
||
|
||
3. **API 接口**
|
||
- POST /chat - 非流式对话
|
||
- POST /chat/stream - 流式对话
|
||
|
||
### 配置说明
|
||
|
||
#### 必需配置
|
||
```env
|
||
# 数据库
|
||
DB_HOST=your_db_host
|
||
DB_PORT=5432
|
||
DB_USER=your_db_user
|
||
DB_PASSWORD=your_db_password
|
||
DB_NAME=langgraph_db
|
||
|
||
# Qdrant
|
||
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
|
||
```
|
||
|
||
#### 可选配置
|
||
```env
|
||
# 本地模型服务
|
||
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
|
||
|
||
# 智谱其他配置
|
||
ZHIPU_EMBEDDING_MODEL=embedding-3
|
||
ZHIPU_RERANK_MODEL=rerank-2
|
||
```
|
||
|
||
### 使用模型服务
|
||
|
||
#### 嵌入服务
|
||
```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
|
||
|
||
# 自动选择可用服务
|
||
reranker = get_rerank_service()
|
||
|
||
# 使用
|
||
from langchain_core.documents import Document
|
||
docs = [Document(page_content="...")]
|
||
sorted_docs = reranker.compress_documents(docs, "query", top_n=5)
|
||
```
|