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，可以通过以下方式启动：

# 方式 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

8.0 KiB Raw Blame History Unescape Escape

Backend App - 后端应用目录

📁 目录结构

📖 模块详解

1. core/ - 核心模块

2. agent/ - Agent 服务层

3. main_graph/ - 主图

4. subgraphs/ - 子图模块

5. model_services/ - 模型服务层

6. rag/ - RAG 模块