230 lines
8.0 KiB
Markdown
230 lines
8.0 KiB
Markdown
# Backend App - 后端应用目录
|
||
|
||
本目录包含 AI Agent 系统的所有后端代码，采用模块化设计，层级清晰。
|
||
|
||
---
|
||
|
||
## 📁 目录结构
|
||
|
||
```
|
||
app/
|
||
├── __init__.py # 应用初始化
|
||
├── backend.py # FastAPI 主入口，包含 API 端点
|
||
├── config.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. `core/` - 核心模块
|
||
|
||
这是整个系统的基础，被主图和所有子图共享：
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `state_base.py` | 所有子图状态的基类，定义通用字段和方法 |
|
||
| `intent.py` | React 模式的意图理解，用于解析用户意图 |
|
||
| `intent_classifier.py` | 意图分类器，用于混合路由 |
|
||
| `formatter.py` | 输出格式化工具，用于统一美化子图输出 |
|
||
| `human_review.py` | 人工审核节点，需要人工确认的操作 |
|
||
|
||
---
|
||
|
||
### 2. `agent/` - Agent 服务层
|
||
|
||
对外提供服务的核心层：
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `service.py` | `AIAgentService` 类，管理模型、图、工具，提供 `process_message` 和 `process_message_stream` 方法 |
|
||
| `history.py` | 历史对话查询服务 |
|
||
| `prompts.py` | 系统提示词模板 |
|
||
|
||
---
|
||
|
||
### 3. `main_graph/` - 主图
|
||
|
||
LangGraph 的主流程，处理普通对话和工具调用：
|
||
|
||
| 目录/文件 | 说明 |
|
||
|----------|------|
|
||
| `state.py` | 主图状态定义，包含消息、RAG 上下文、错误记录等 |
|
||
| `graph_builder.py` | 构建主图的类，定义节点和边 |
|
||
| `nodes/` | 所有节点实现（router, llm_call, tool_call 等） |
|
||
| `tools/` | 图的工具定义（天气、文件、网页、RAG 等） |
|
||
| `utils/` | 辅助函数（重试、子图构建、初始化等） |
|
||
|
||
---
|
||
|
||
### 4. `subgraphs/` - 子图模块
|
||
|
||
三个独立的子图，每个子图都有完整的 `state.py`、`nodes.py`、`graph.py`：
|
||
|
||
| 子图 | 功能 |
|
||
|------|------|
|
||
| `contact/` | 通讯录管理：CRUD、邮件处理、智能嗅探 |
|
||
| `dictionary/` | 词典：查词、翻译、生词本、专业术语提取 |
|
||
| `news_analysis/` | 资讯分析：获取资讯、内容分析、格式化展示 |
|
||
|
||
---
|
||
|
||
### 5. `model_services/` - 模型服务层
|
||
|
||
统一的模型服务接口，支持自动降级：
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `base.py` | `BaseServiceProvider`（基类）、`FallbackServiceChain`（降级链）、`SingletonServiceManager`（单例管理） |
|
||
| `chat_services.py` | 生成式大模型服务（智谱、DeepSeek、本地） |
|
||
| `embedding_services.py` | 嵌入模型服务 |
|
||
| `rerank_services.py` | 重排序服务 |
|
||
|
||
---
|
||
|
||
### 6. `rag/` - RAG 模块
|
||
|
||
知识库检索相关：
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `retriever.py` | 向量检索器 |
|
||
| `rerank.py` | 重排序业务逻辑 |
|
||
| `pipeline.py` | RAG 流水线 |
|
||
| `fusion.py` | RAG-Fusion 多路召回融合 |
|
||
| `tools.py` | 封装为 LangChain Tool 的 RAG 工具 |
|
||
| `evaluate.py` | RAG 评估工具 |
|
||
|
||
---
|
||
|
||
## 🔄 数据流
|
||
|
||
```
|
||
用户请求
|
||
└─> backend.py (FastAPI)
|
||
└─> agent/service.py (AIAgentService)
|
||
├─> model_services/ (获取模型)
|
||
├─> main_graph/ (执行主图)
|
||
│ ├─> nodes/ (执行节点)
|
||
│ ├─> tools/ (调用工具)
|
||
│ └─> rag/ (RAG 检索)
|
||
└─> subgraphs/ (可选：调用子图)
|
||
└─> core/ (共享工具)
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 启动方式
|
||
|
||
FastAPI 应用入口是 `backend.py`，可以通过以下方式启动：
|
||
|
||
```bash
|
||
# 方式 1：直接运行
|
||
cd backend && python -m app.backend
|
||
|
||
# 方式 2：Uvicorn
|
||
uvicorn app.backend:app --reload --host 0.0.0.0 --port 8079
|
||
|
||
# 方式 3：Docker
|
||
docker compose up
|
||
```
|