Files

构建并部署 AI Agent 服务 / deploy (push) Successful in 5m37s

Details

- 创建 backend/app/README.md 主文档
- 整理已实现功能（带 ✅ 标记）
- 列出待实现功能（带 🚧 标记）
- 删除 agent_subgraphs/ 下的旧 README 文件

2026-04-24 23:05:03 +08:00

8.1 KiB

Raw Blame History

后端模块 (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

📝 使用指南

快速开始

配置环境变量 复制 .env 文件并配置：
- 数据库配置（PostgreSQL）
- Qdrant 配置
- LLM 配置（智谱/DeepSeek/本地）
- 嵌入和重排服务配置
启动后端
```
cd backend
python -m app.backend
```
API 接口
- POST /chat - 非流式对话
- POST /chat/stream - 流式对话

配置说明

必需配置

# 数据库
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

可选配置

# 本地模型服务
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

使用模型服务

嵌入服务

from app.model_services import get_embedding_service

# 自动选择可用服务（优先本地，降级智谱）
embeddings = get_embedding_service()

# 使用
vector = embeddings.embed_query("hello")

重排服务

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)

8.1 KiB Raw Blame History Unescape Escape

后端模块 (backend/app/)

项目概览

📂 目录结构

✅ 已实现功能

1. Agent 服务 (agent/)

2. LangGraph 图 (graph/)

3. 节点实现 (nodes/)

4. 记忆管理 (memory/)

5. 模型服务 (model_services/) - ⭐ 新增

6. RAG 检索 (rag/)

7. 配置管理 (config.py)

🚧 待实现功能

1. agent_subgraphs/ - 子图模块

2. 公共工具层 (agent_subgraphs/common/)

3. 其他待完善

🛠️ 技术栈

📝 使用指南

快速开始

配置说明

必需配置

可选配置

使用模型服务

嵌入服务

重排服务

8.1 KiB

Raw Blame History