AI Agent - 智能助手系统
一个基于 LangGraph + FastAPI 的智能对话助手，支持多模型切换、联网搜索、可视化图表、以及多个专业子图模块（通讯录、词典、资讯分析）等功能。
📑 目录导航
- 核心功能 - 面向用户的功能和技术特性
- 技术架构 - 技术栈、系统架构图、工作流流程图
- 核心算法与实现原理 - LangGraph 工作流、多模型路由、SSE 流式响应
- 快速开始 - Docker 和本地部署指南
- 使用指南 - 基础对话、工具调用、多模型切换
- 开发指南 - 添加工具、添加模型、Docker 部署
- 实现指南与最佳实践 - 性能优化、扩展开发、部署实践
- 环境配置 - 配置文件、环境变量
- 故障排查 - 常见问题
🎯 核心功能
面向用户的功能
- 💬 智能对话：支持多轮对话，自动记忆上下文
- 🌐 联网搜索：免费使用 DuckDuckGo 搜索，无需 API Key，支持引用溯源
- 📊 可视化图表：支持 Mermaid 图表和 matplotlib 图表生成
- 🔄 多模型切换：前端可选择不同大语言模型
- 📇 通讯录管理：子图模块，联系人 CRUD、邮件处理
- 📖 智能词典：子图模块，翻译、生词本、专业术语提取
- 📰 资讯分析：子图模块，资讯获取、内容分析、格式化展示
技术特性
- ✅ 持久化记忆：PostgreSQL 存储对话历史，重启不丢失
- ✅ 高可用架构：模型服务自动降级，确保服务稳定
- ✅ 前后端分离：FastAPI 后端 + Streamlit 前端
- ✅ Docker 部署：一键启动所有服务
- ✅ 远程服务架构：PostgreSQL 和 Qdrant 部署在远程服务器
- ✅ 流式响应：SSE 流式输出，提升用户体验
- ✅ 模块化设计：清晰的代码分层，易于扩展和维护
- ✅ 模型服务层：统一的 Embedding、Rerank、Chat 服务接口，支持自动降级
- ✅ 子图系统：模块化的子图架构，共享公共工具（意图理解、人工审核、格式化输出）
- ✅ 公共工具库：联网搜索、可视化图表等通用工具，所有子图和主图均可使用
- ✅ React 模式 ⭐：Reasoning → Acting → Observing 循环，LLM 先思考再行动，支持多次工具调用
- ✅ 混合路由架构 ⭐⭐：前置快速路由（规则分流 + 轻量级意图分类）+ 完整 React 循环（兜底）
- ✅ 双模型服务 ⭐：get_chat_service()（大模型）+ get_small_llm_service()（轻量级模型）
- ✅ 自动升级机制：快速路径失败时，自动回到完整 React 循环
- ✅ 向后兼容：可通过 use_hybrid_router=True/False 切换混合路由/纯 React 模式
🏗️ 技术架构
技术栈总览
| 层级 | 组件 | 技术选型 | 说明 |
|---|---|---|---|
| Agent 框架 | 工作流编排 | LangGraph + LangChain | 状态机驱动的智能体工作流 |
| 主图系统 | 主流程 | main_graph/ | 混合路由 + React 循环 + 工具执行 |
| 子图系统 | 模块化子图 | subgraphs/ | 通讯录、词典、资讯分析等子图 |
| 核心工具 | core/ | 意图理解、格式化输出、人工审核、联网搜索、可视化图表 | |
| 向量数据库 | 向量检索 | Qdrant | 高性能向量相似度检索（远程服务器） |
| 后端框架 | API 服务 | FastAPI + Uvicorn | RESTful API + SSE 流式输出 |
| 前端框架 | Web 界面 | Streamlit | 交互式对话界面 |
| 关系数据库 | 持久化存储 | PostgreSQL | 对话记忆持久化（远程服务器） |
| 容器化 | 服务编排 | Docker + Docker Compose | 一键部署所有服务 |
| CI/CD | 自动化部署 | Gitea Workflows | 代码推送自动构建部署 |
| LLM 服务 | 云端模型 | 智谱 AI (glm-4-plus) | 快速响应，适合日常对话 |
| DeepSeek (deepseek-chat-v3) | 深度推理，适合复杂问题 | ||
| OpenAI (gpt-4o-mini) | 通用对话 | ||
| 本地模型 | Qwen3.5-9B.Q4_K_M | 本地部署 GGUF 格式 | |
| 模型服务层 | Chat 服务 | chat_services.py | 统一的生成式大模型接口 |
| Embedding 服务 | embedding_services.py | 统一的嵌入模型接口 | |
| Rerank 服务 | rerank_services.py | 统一的重排序接口 | |
| Embedding | 向量嵌入 | llama.cpp server | 本地 embedding 服务 (:18001) |
系统架构流程图
graph TB
User[用户浏览器] -->|HTTP/SSE| Frontend[Streamlit 前端 :8501]
Frontend -->|REST API| Backend[FastAPI 后端 :8079]
Backend --> AgentService[AIAgentService]
AgentService -->|初始化| LangGraph[LangGraph 工作流引擎]
LangGraph -->|阶段1| RetrieveMemory[记忆检索 retrieve_memory]
LangGraph -->|阶段2| MemoryTrigger[记忆触发 memory_trigger]
LangGraph -->|阶段3| InitState[初始化状态 init_state]
LangGraph -->|阶段4| HybridRouter[⭐ 混合路由 hybrid_router]
LangGraph -->|阶段5| ReactLoop[React 循环 react_loop]
LangGraph -->|阶段6| FastPath[快速路径 fast_*]
LangGraph -->|阶段7| LLMCall[LLM 调用 llm_call]
LangGraph -->|阶段8| Summarize[记忆摘要 summarize]
LangGraph -->|阶段9| Finalize[最终处理 finalize]
HybridRouter -->|闲聊| FastChitchat[fast_chitchat]
HybridRouter -->|知识查询| FastRAG[fast_rag]
HybridRouter -->|工具调用| FastTool[fast_tool]
HybridRouter -->|复杂任务| ReactLoop
ReactLoop -->|推理| ReactReason[react_reason 推理节点]
ReactLoop -->|RAG检索| RAGRetrieve[rag_retrieve]
ReactLoop -->|联网搜索| WebSearch[web_search]
ReactLoop -->|通讯录| ContactSubgraph[contact_subgraph]
ReactLoop -->|词典| DictionarySubgraph[dictionary_subgraph]
ReactLoop -->|资讯分析| NewsSubgraph[news_analysis_subgraph]
ReactLoop -->|错误处理| HandleError[handle_error]
RAGRetrieve -->|向量检索| Qdrant[Qdrant向量库]
RAGRetrieve -->|重排序| RerankService[Rerank服务]
RAGRetrieve -->|嵌入| EmbeddingService[Embedding服务]
AgentService -->|模型路由| ChatServices[模型服务层 chat_services]
ChatServices -->|自动降级| FallbackChain[FallbackServiceChain]
FallbackChain -->|创建| Zhipu[智谱 GLM-4]
FallbackChain -->|创建| DeepSeek[DeepSeek V3]
FallbackChain -->|创建| OpenAI[OpenAI GPT-4o]
FallbackChain -->|创建| LocalQwen[本地 Qwen3.5-9B]
RetrieveMemory -->|存储/读取| PostgreSQL[PostgreSQL]
Summarize -->|存储| PostgreSQL
style User fill:#e1f5ff
style Frontend fill:#fff4e1
style Backend fill:#e8f5e9
style HybridRouter fill:#fff3e0,stroke:#ff9800,stroke-width:3px
style ReactLoop fill:#f3e5f5
style FastPath fill:#e3f2fd
style LangGraph fill:#c8e6c9
style ChatServices fill:#c8e6c9
style PostgreSQL fill:#ffebee
style Qdrant fill:#ffebee
主图与子图架构
graph TB
subgraph "主图 MainGraph"
StartMain[START]
RetrieveMemory[记忆检索]
MemoryTrigger[记忆触发]
InitState[初始化状态]
HybridRouter[⭐ 混合路由<br>规则分流 + LLM意图分类]
FastChitchat[fast_chitchat<br>闲聊快速路径]
FastRAG[fast_rag<br>RAG快速路径]
FastTool[fast_tool<br>工具快速路径]
ReactReason[react_reason<br>React推理节点]
LLMCall[llm_call<br>LLM调用节点]
FinalMain[最终响应]
EndMain[END]
StartMain -->|用户输入| RetrieveMemory
RetrieveMemory --> MemoryTrigger
MemoryTrigger --> InitState
InitState --> HybridRouter
HybridRouter -->|闲聊| FastChitchat
HybridRouter -->|知识查询| FastRAG
HybridRouter -->|工具调用| FastTool
HybridRouter -->|复杂任务| ReactReason
FastChitchat -->|成功| LLMCall
FastChitchat -->|失败| ReactReason
FastRAG -->|成功| LLMCall
FastRAG -->|失败| ReactReason
FastTool -->|成功| LLMCall
FastTool -->|失败| ReactReason
ReactReason -->|rag_retrieve| RAGRetrieve[RAG检索]
ReactReason -->|web_search| WebSearchNode[联网搜索]
ReactReason -->|contact_subgraph| ContactNode[通讯录子图]
ReactReason -->|dictionary_subgraph| DictNode[词典子图]
ReactReason -->|news_analysis_subgraph| NewsNode[资讯子图]
ReactReason -->|llm_call| LLMCall
RAGRetrieve --> ReactReason
WebSearchNode --> ReactReason
ContactNode --> ReactReason
DictNode --> ReactReason
NewsNode --> ReactReason
LLMCall --> FinalMain
FinalMain --> EndMain
end
subgraph "通讯录子图 ContactSubgraph"
StartContact[START]
IntentContact[parse_intent<br>解析意图]
ListContacts[list_contacts<br>列出联系人]
AddContact[add_contact<br>添加联系人]
ListEmails[list_emails<br>列出邮件]
GenEmail[generate_email_draft<br>生成邮件草稿]
HumanReview[human_review<br>人工审核]
SendEmail[send_email<br>发送邮件]
SniffContact[sniff_contacts<br>智能嗅探]
FormatContact[format_result<br>格式化输出]
EndContact[END]
StartContact --> IntentContact
IntentContact -->|list| ListContacts
IntentContact -->|add| AddContact
IntentContact -->|list_emails| ListEmails
IntentContact -->|generate_email| GenEmail
IntentContact -->|sniff| SniffContact
ListContacts --> FormatContact
AddContact --> FormatContact
ListEmails --> FormatContact
SniffContact --> FormatContact
GenEmail --> HumanReview
HumanReview -->|approve| SendEmail
HumanReview -->|reject| FormatContact
SendEmail --> FormatContact
FormatContact --> EndContact
end
subgraph "词典子图 DictionarySubgraph"
StartDict[START]
IntentDict[parse_intent<br>解析意图]
QueryWord[query_word<br>查询单词]
Translate[translate_text<br>翻译文本]
ExtractTerms[extract_terms<br>提取专业术语]
DailyWord[get_daily_word<br>每日一词]
LookupWord[lookup_word_book<br>查询生词本]
AddToWord[add_to_word_book<br>添加到生词本]
FormatDict[format_result<br>格式化输出]
EndDict[END]
StartDict --> IntentDict
IntentDict -->|query| QueryWord
IntentDict -->|translate| Translate
IntentDict -->|extract| ExtractTerms
IntentDict -->|daily| DailyWord
IntentDict -->|lookup| LookupWord
IntentDict -->|add| AddToWord
QueryWord --> FormatDict
Translate --> FormatDict
ExtractTerms --> FormatDict
DailyWord --> FormatDict
LookupWord --> FormatDict
AddToWord --> FormatDict
FormatDict --> EndDict
end
subgraph "资讯分析子图 NewsSubgraph"
StartNews[START]
IntentNews[parse_intent<br>解析意图]
QueryNews[query_news<br>查询资讯]
AnalyzeUrl[analyze_url<br>分析链接]
ExtractKeywords[extract_keywords<br>提取关键词]
GenReport[generate_report<br>生成报告]
FormatNews[format_result<br>格式化输出]
EndNews[END]
StartNews --> IntentNews
IntentNews -->|query| QueryNews
IntentNews -->|analyze| AnalyzeUrl
IntentNews -->|keywords| ExtractKeywords
IntentNews -->|report| GenReport
QueryNews --> FormatNews
AnalyzeUrl --> FormatNews
ExtractKeywords --> FormatNews
GenReport --> FormatNews
FormatNews --> EndNews
end
ReactReason -.->|调用<br>状态传递| StartContact
ReactReason -.->|调用<br>状态传递| StartDict
ReactReason -.->|调用<br>状态传递| StartNews
style HybridRouter fill:#fff3e0,stroke:#ff9800,stroke-width:3px
style ReactReason fill:#e8eaf6
---
### 索引工作流（离线构建）
```mermaid
flowchart TB
subgraph 文档输入
A1[文档源]
A2[PDF/DOCX/TXT/Markdown]
end
subgraph 文档加载
B1[rag_indexer/loaders.py]
B2[UnstructuredLoader]
B3[PyMuPDFLoader]
B4[TextLoader]
end
subgraph 文本切分
C1[rag_indexer/splitters.py]
C2[RecursiveCharacterTextSplitter<br/>按分隔符递归切分]
C3[SemanticChunker<br/>基于语义相似度]
C4[ParentChildSplitter<br/>父子块切分]
end
subgraph 嵌入生成
D1[Embedding 生成]
D2[稠密向量<br/>Qwen3-Embedding-0.6B<br/>llama.cpp server:18001]
D3[稀疏向量 BM25<br/>FastEmbed]
end
subgraph 向量存储
E1[Qdrant Vector Store]
E2[稠密向量索引<br/>HNSW 算法]
E3[稀疏向量索引<br/>BM25]
E4[rag_core/vector_store.py]
end
A1 --> A2
A2 --> B1
B1 --> B2
B2 --> C1
C1 --> C2
C1 --> C3
C1 --> C4
C2 --> D1
C3 --> D1
C4 --> D1
D1 --> D2
D1 --> D3
D2 --> E1
D3 --> E1
E1 --> E2
E1 --> E3
style A1 fill:#e3f2fd
style B1 fill:#fff3e0
style C1 fill:#f3e5f5
style D1 fill:#e8f5e9
style E1 fill:#ffebee
技术组件说明：
| 组件 | 技术选型 | 说明 |
|---|---|---|
| 文档加载 | Unstructured / PyMuPDF / TextLoader | 支持多种文档格式 |
| 文本切分 | RecursiveCharacterTextSplitter | 按分隔符递归切分，默认 500 字符 |
| 语义切分 | SemanticChunker | 基于 Embedding 相似度自动切分 |
| 父子块切分 | ParentChildSplitter | 大块存储上下文，小块用于检索 |
| 稠密嵌入 | Qwen3-Embedding-0.6B-Q8_0 | llama.cpp server (:18001) |
| 稀疏嵌入 | FastEmbed BM25 | 本地计算，无需额外服务 |
| 向量存储 | Qdrant | HNSW 索引，高性能 ANN 检索 |
检索工作流（在线查询）
flowchart TB
subgraph 查询输入
Q1[用户查询]
Q2[Query: "公司报销流程是什么？"]
end
subgraph 查询处理
R1[查询改写 MultiQuery]
R2[rag_indexer/splitters.py]
R3[使用 chat_services 生成多角度查询]
end
subgraph 混合检索
S1[并行检索]
S2[稠密向量检索<br/>Embedding → 向量相似度]
S3[稀疏 BM25 检索<br/>词频统计]
S4[rag_core/sparse_embedder.py]
end
subgraph 结果融合
F1[RRF 融合]
F2[rag_indexer/fusion.py]
F3[RRF(d) = Σ 1/(k + rank)]
F4[Qdrant Fusion API<br/>服务端融合]
end
subgraph 重排序
P1[Cross-Encoder 重排]
P2[bge-reranker-v2-m3]
P3[rerank_services.py<br/>llama.cpp server:18002]
P4[Query-Document 交互编码]
end
subgraph LLM 生成
G1[LLM 生成回答]
G2[chat_services.py]
G3[Context + 生成回答]
end
Q1 --> Q2
Q2 --> R1
R1 --> R2
R2 --> S1
S1 --> S2
S1 --> S3
S2 --> F1
S3 --> F1
F1 --> P1
P1 --> P2
P2 --> G1
G1 --> G2
G2 --> G3
style Q1 fill:#e3f2fd
style R1 fill:#fff3e0
style S1 fill:#f3e5f5
style F1 fill:#e8f5e9
style P1 fill:#ffebee
style G1 fill:#e1f5ff
技术组件说明：
| 阶段 | 技术选型 | 说明 |
|---|---|---|
| 查询改写 | MultiQuery | 使用 LLM 生成 3-5 个多角度查询 |
| 稠密检索 | Qwen3-Embedding | 向量相似度计算，余弦相似度 |
| 稀疏检索 | FastEmbed BM25 | 词频 TF-IDF 统计 |
| 结果融合 | Qdrant Fusion API | 服务端 RRF 融合，无需传输数据 |
| 重排序 | bge-reranker-v2-m3 | Cross-Encoder 交互编码，精度更高 |
| LLM 生成 | chat_services | 统一的大模型服务接口 |
数据流向图
用户请求
│
├─→ 前端 Streamlit
│ │
│ ├─→ 发送 HTTP POST /api/chat
│ │
│ └─→ 接收 SSE 流式响应
│
└─→ 后端 FastAPI
│
├─→ AIAgentService.achat()
│ │
│ ├─→ 初始化 LangGraph 状态
│ │ ├─→ messages: 对话历史
│ │ ├─→ user_id: 用户标识
│ │ └─→ metadata: 元数据
│ │
│ └─→ 执行工作流（混合路由 + React 循环）
│ ├─→ retrieve_memory: 从 PostgreSQL 检索历史
│ ├─→ memory_trigger: 判断是否触发记忆
│ ├─→ init_state: 初始化状态
│ ├─→ hybrid_router: 混合路由决策
│ │ ├─→ fast_chitchat: 闲聊快速路径
│ │ ├─→ fast_rag: RAG 快速路径
│ │ ├─→ fast_tool: 工具快速路径
│ │ └─→ react_loop: React 循环（兜底）
│ │
│ ├─→ React 循环（react_reason 节点）
│ │ ├─→ rag_retrieve: RAG 检索
│ │ ├─→ web_search: 联网搜索
│ │ ├─→ contact_subgraph: 通讯录子图
│ │ ├─→ dictionary_subgraph: 词典子图
│ │ ├─→ news_analysis_subgraph: 资讯子图
│ │ └─→ llm_call: LLM 调用
│ │
│ ├─→ summarize: 生成对话摘要（如需要）
│ └─→ finalize: 格式化最终响应
│
└─→ 持久化存储
├─→ PostgreSQL: 对话历史和摘要
└─→ Qdrant: RAG 向量索引
项目结构
Agent1/
├── backend/
│ ├── app/
│ │ ├── __init__.py
│ │ ├── config.py # 配置管理
│ │ ├── logger.py # 日志工具
│ │ ├── backend.py # FastAPI 后端应用（含子图 API）
│ │ ├── README.md # 后端目录文档
│ │ │
│ │ ├── core/ # ⭐ 核心模块 - 基类和通用工具
│ │ │ ├── __init__.py
│ │ │ ├── state_base.py # 子图状态基类
│ │ │ ├── intent.py # 意图理解（React 模式）
│ │ │ ├── intent_classifier.py # 意图分类器
│ │ │ ├── formatter.py # 格式化输出工具
│ │ │ ├── human_review.py # 人工审核节点
│ │ │ ├── web_search.py # ⭐ 联网搜索工具（DuckDuckGo）
│ │ │ └── visualization.py # ⭐ 可视化图表工具（Mermaid + matplotlib）
│ │ │
│ │ ├── agent/ # ⭐ Agent 服务层
│ │ │ ├── __init__.py
│ │ │ ├── agent_service.py # Agent 服务核心（使用 chat_services）
│ │ │ ├── history.py # 历史查询服务
│ │ │ └── prompts.py # 提示词模板
│ │ │
│ │ ├── main_graph/ # ⭐ 主图 - LangGraph 主流程（混合路由 + React 循环）
│ │ │ ├── __init__.py
│ │ │ ├── state.py # 主图状态定义 MainGraphState
│ │ │ ├── graph.py # LangGraph 组件导出
│ │ │ ├── config.py # 主图配置
│ │ │ ├── nodes/ # 主图节点
│ │ │ │ ├── __init__.py
│ │ │ │ ├── _utils.py # 节点公共工具
│ │ │ │ ├── reasoning.py # React 推理节点
│ │ │ │ ├── hybrid_router.py # 混合路由节点
│ │ │ │ ├── fast_paths.py # 快速路径节点
│ │ │ │ ├── llm_call.py # LLM 调用节点
│ │ │ │ ├── routing.py # 路由决策（init_state, route_by_reasoning）
│ │ │ │ ├── rag_nodes.py # RAG 检索节点
│ │ │ │ ├── web_search.py # 联网搜索节点
│ │ │ │ ├── retrieve_memory.py # 记忆检索节点
│ │ │ │ ├── memory_trigger.py # 记忆触发节点
│ │ │ │ ├── summarize.py # 记忆摘要节点
│ │ │ │ ├── finalize.py # 最终处理节点
│ │ │ │ ├── tool_call.py # 工具执行节点
│ │ │ │ └── error_handling.py # 错误处理节点
│ │ │ ├── tools/ # 主图工具
│ │ │ │ ├── __init__.py
│ │ │ │ ├── common_tools.py # 通用工具
│ │ │ │ ├── subgraph_tools.py # 子图调用工具
│ │ │ │ └── graph_tools.py # 图工具
│ │ │ └── utils/ # 主图工具函数
│ │ │ ├── __init__.py
│ │ │ ├── main_graph_builder.py # 主图构建器
│ │ │ ├── rag_initializer.py # RAG 初始化
│ │ │ └── retry_utils.py # 重试工具
│ │ │
│ │ ├── subgraphs/ # ⭐ 子图模块
│ │ │ ├── __init__.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
│ │ │
│ │ ├── model_services/ # 模型服务层
│ │ │ ├── __init__.py
│ │ │ ├── base.py # 基类：BaseServiceProvider, FallbackServiceChain, SingletonServiceManager
│ │ │ ├── chat_services.py # 生成式大模型服务
│ │ │ ├── embedding_services.py # 嵌入模型服务
│ │ │ └── rerank_services.py # 重排序服务
│ │ │
│ │ ├── mcp/ # MCP 模块
│ │ │ ├── __init__.py
│ │ │ ├── mcp_manager.py # MCP 管理器
│ │ │ ├── mcp_client.py # MCP 客户端
│ │ │ ├── adapters/ # MCP 适配器
│ │ │ │ ├── __init__.py
│ │ │ │ ├── base_adapter.py
│ │ │ │ ├── contact_adapter.py
│ │ │ │ ├── dictionary_adapter.py
│ │ │ │ └── news_adapter.py
│ │ │ └── mcp_example.py
│ │ │
│ │ ├── memory/ # 记忆模块
│ │ │ ├── __init__.py
│ │ │ └── mem0_client.py # Mem0 客户端封装
│ │ │
│ │ ├── rag/ # RAG 模块
│ │ │ ├── __init__.py
│ │ │ ├── retriever.py # 检索器
│ │ │ ├── rerank.py # 重排序业务逻辑（使用 rerank_services）
│ │ │ ├── query_transform.py # 查询转换
│ │ │ ├── pipeline.py # RAG 流水线
│ │ │ ├── fusion.py # RAG-Fusion
│ │ │ ├── tools.py # RAG 工具
│ │ │ └── evaluate.py # RAG 评估
│ │ │
│ │ ├── db/ # 数据库模块
│ │ │ ├── __init__.py
│ │ │ ├── base.py # 数据库基类
│ │ │ ├── models.py # 数据模型
│ │ │ └── init_db.py # 数据库初始化
│ │ │
│ │ └── utils/ # 工具模块
│ │ ├── __init__.py
│ │ └── logging.py # 日志工具
│ └── rag_core/ # ⭐ RAG 核心库（统一组件）
│ ├── __init__.py
│ ├── config.py # RAG 配置
│ ├── client.py # RAG 核心客户端
│ ├── embedders.py # 嵌入模型
│ ├── sparse_embedder.py # BM25 稀疏嵌入
│ ├── vector_store.py # 向量存储（Dense + Sparse）
│ └── doc_store.py # 文档存储
├── frontend/
│ ├── run.py # 前端启动脚本
│ ├── requirements.txt
│ └── src/
│ ├── __init__.py
│ ├── frontend_main.py # Streamlit 主入口
│ ├── api_client.py # API 客户端（含子图调用）
│ ├── config.py # 前端配置
│ ├── state.py # 状态管理
│ ├── logger.py # 日志
│ ├── utils.py # 工具函数
│ └── components/
│ ├── __init__.py
│ ├── sidebar.py # 侧边栏组件
│ ├── chat_area.py # 聊天区域组件
│ └── info_panel.py # 信息面板组件
├── rag_indexer/
│ ├── __init__.py
│ ├── cli.py # 命令行入口
│ ├── index_builder.py # 索引构建器
│ ├── loaders.py # 文档加载器
│ ├── splitters.py # 文本切分器
│ └── test/ # 测试脚本
├── docker/
│ ├── docker-compose.yml # Docker 服务编排
│ ├── backend/
│ │ └── Dockerfile # 后端镜像构建
│ ├── frontend/
│ │ └── Dockerfile # 前端镜像构建
│ └── models/ # spaCy 模型文件
├── scripts/
│ └── start.sh # 启动脚本
├── test/ # 测试目录
│ ├── test_backend.py
│ ├── test_rag.py
│ ├── test_qdrant.py
│ └── test_rag_indexer_result.py
├── .gitea/
│ └── workflows/
│ └── deploy.yml # CI/CD 自动化部署
├── requirement.txt # Python 依赖
├── .env.docker # Docker 环境变量模板
├── .gitignore
├── LICENSE
├── QUICKSTART.md # 快速开始指南
└── user_docs/ # 用户文档目录
🧠 核心算法与实现原理
1. RAG 检索算法
项目采用稠密 + 稀疏混合检索架构，结合 RRF 融合和 Cross-Encoder 重排序，实现高精度知识库问答。
核心特性：
- 三种文本切分策略：递归字符切分、语义切分、父子块切分
- 稠密向量检索（Embedding）+ 稀疏 BM25 检索
- RRF 融合算法实现多检索源结果合并
- Cross-Encoder 重排序提升相关性
详细文档：
LangGraph 工作流详细流程
1. 混合路由 + React 循环架构 ⭐⭐
设计理念：混合路由（Hybrid Router）作为前置决策，快速路径处理简单任务，React 循环作为复杂任务的兜底方案。
┌─────────────────────────────────────────────────────────────────────────────┐
│ 主图执行流程 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 阶段1: 记忆检索 (retrieve_memory) │ │
│ │ - 从 PostgreSQL 检索用户历史对话 │ │
│ │ - 生成 memory_context 供后续使用 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 阶段2: 记忆触发 (memory_trigger) │ │
│ │ - 判断是否需要激活记忆上下文 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 阶段3: 初始化状态 (init_state) │ │
│ │ - 初始化 MainGraphState │ │
│ │ - 设置 user_query、messages 等 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 阶段4: 混合路由 (hybrid_router) ⭐ │ │
│ │ - 规则分流：闲聊关键词、子图关键词（<5ms） │ │
│ │ - LLM 分类：使用轻量级模型进行意图分类（chitchat/knowledge/tool） │ │
│ │ - 输出决策：fast_chitchat / fast_rag / fast_tool / react_loop │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────┼──────────────────────┐ │
│ ↓ ↓ ↓ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │快速路径 │ │快速路径 │ │快速路径 │ │
│ │fast_* │ │fast_rag │ │fast_tool│ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ │ ┌────────────────┘ ┌──────────────┘ │
│ │ │ │ │
│ ↓ ↓ ↓ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 阶段5: React 循环 (react_reason) │ │
│ │ - 调用 app/core/intent.py 的 react_reason_async() │ │
│ │ - 使用 app/model_services/ 获取 chat 服务 │ │
│ │ - 推理下一步动作（rag_retrieve/web_search/子图/llm_call） │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ React 循环内节点 │ │
│ │ rag_retrieve → react_reason（回到推理） │ │
│ │ web_search → react_reason（回到推理） │ │
│ │ contact_subgraph → react_reason（回到推理） │ │
│ │ dictionary_subgraph → react_reason（回到推理） │ │
│ │ news_analysis_subgraph → react_reason（回到推理） │ │
│ │ handle_error → react_reason（错误处理后继续推理） │ │
│ │ llm_call → 退出循环，进入完成阶段 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 阶段6: LLM 调用 (llm_call) │ │
│ │ - 调用主 LLM 生成最终回答 │ │
│ │ - 使用 llm.bind_tools(tools) 绑定工具 │ │
│ │ - 支持流式输出到前端 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 阶段7: 记忆摘要 (summarize) / 最终处理 (finalize) │ │
│ │ - 对话轮数 >= 5 时触发摘要 │ │
│ │ - 保存对话到 PostgreSQL │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
2. React 推理循环详解
React 推理循环使用 app/core/intent.py 中的 react_reason_async() 函数：
┌─────────────────────────────────────────────────────────────────┐
│ React 推理循环 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ 1. Reasoning (推理) - react_reason 节点 │ │
│ │ - 调用 react_reason_async() │ │
│ │ - 传入上下文：retrieved_docs、reasoning_history、 │ │
│ │ previous_actions、messages、errors │ │
│ │ - LLM 决定下一步 action │ │
│ │ - 记录到 reasoning_history │ │
│ └───────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ 2. Acting (行动) │ │
│ │ - rag_retrieve: RAG 检索 │ │
│ │ - web_search: 联网搜索 │ │
│ │ - contact_subgraph: 通讯录子图 │ │
│ │ - dictionary_subgraph: 词典子图 │ │
│ │ - news_analysis_subgraph: 资讯分析子图 │ │
│ │ - handle_error: 错误处理 │ │
│ └───────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ 3. Observing (观察) / 循环 │ │
│ │ - 工具结果返回给 react_reason │ │
│ │ - 再次推理下一步 │ │
│ │ - 最多 10 次循环 (max_steps=10) │ │
│ │ - 或直到推理决定 llm_call │ │
│ └───────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ 4. 退出条件 │ │
│ │ - action == llm_call: 退出循环，进入 llm_call 节点 │ │
│ │ - max_steps 达到: 强制退出到 llm_call │ │
│ │ - 错误累积过多: 进入 handle_error │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
关键实现点：
react_reason_async()- 在app/core/intent.py中，使用 chat_services 获取 LLM 进行推理route_by_reasoning- 路由函数，根据推理结果决定下一步节点- 循环边 - 工具节点执行后回到 react_reason 继续推理
- 自动升级 - 快速路径失败时，回到 react_reason 继续推理
2.2 状态机设计
# 核心状态定义
class MainGraphState(TypedDict):
messages: Annotated[list, add_messages] # 对话历史（自动合并）
user_id: str # 用户标识
user_query: str # 用户查询
memory_context: str # 检索到的记忆上下文
memory_triggered: bool # 记忆是否触发
should_summarize: bool # 是否需要生成摘要
retrieved_docs: list # RAG 检索到的文档
reasoning_history: list # React 推理历史
previous_actions: list # 之前的动作
errors: list # 错误列表
current_step: int # 当前步骤
max_steps: int # 最大步骤数
llm_override: str # LLM 覆盖
final_response: str # 最终响应
状态流转规则：
初始状态 → retrieve_memory → memory_trigger → init_state → hybrid_router
↓
┌───────────────────────────┼───────────────────────────┐
↓ ↓ ↓
fast_chitchat fast_rag fast_tool
↓ ↓ ↓
[成功→llm_call / 失败→react_reason] [成功→llm_call / 失败→react_reason] [成功→llm_call / 失败→react_reason]
↓
┌───────────────────────────────────────────────┘
↓
react_reason
↓
┌──────────────┼──────────────┬──────────────┬──────────────┬──────────────┬──────────────┐
↓ ↓ ↓ ↓ ↓ ↓ ↓
rag_retrieve web_search contact_subgraph dictionary_subgraph news_analysis_subgraph handle_error llm_call
↓ ↓ ↓ ↓ ↓ ↓ ↓
react_reason ←────────┴──────────────┴──────────────┴──────────────┴──────────────┴──────────────┘
↓
llm_call
↓
summarize
↓
finalize
2.3 记忆管理算法
记忆检索策略：
1. 向量检索：将用户查询 Embedding，在 PostgreSQL 中检索相似对话
2. 时间衰减：近期对话权重更高（可选）
3. 相关性过滤：仅返回相似度 > 阈值的记忆
4. 上下文窗口：限制记忆长度，避免超出 LLM 上下文限制
摘要生成策略：
触发条件：
- 对话轮数超过阈值（默认 10 轮）
- 记忆上下文长度超过限制
摘要生成：
1. 提取最近 N 轮对话
2. 调用 LLM 生成摘要
3. 保存摘要到 PostgreSQL
4. 清理旧对话记录
摘要格式：
"用户在 {时间} 讨论了 {主题}，关键信息：{要点}"
3. 多模型路由算法
模型选择逻辑：
┌─────────────────────────────────────────────┐
│ 用户选择模型 │
└──────────────────┬──────────────────────────┘
│
┌──────────┼──────────┬──────────┐
↓ ↓ ↓ ↓
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│ zhipu│ │deep │ │openai│ │local │
└──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘
│ │ │ │
↓ ↓ ↓ ↓
ChatZhipu ChatOpenAI ChatOpenAI ChatOpenAI
(官方SDK) (DeepSeek) (OpenAI) (llama.cpp/Qwen)
│ │ │ │
└─────────┴─────────┴─────────┘
↓
┌────────────────┐
│ 统一接口输出 │
│ (BaseChatModel)│
└────────────────┘
高可用降级策略：
1. 优先使用用户选择的模型
2. 如果模型不可用（API 错误、超时等）：
- 尝试切换到备用模型
- 记录错误日志
- 返回降级提示给用户
3. 健康检查：定期检查各模型服务状态
4. SSE 流式响应算法
流式输出流程：
┌─────────────────────────────────────────────┐
│ LLM 生成 Token │
└──────────────────┬──────────────────────────┘
│
↓
┌─────────────────────────────────────────────┐
│ 事件格式化 │
│ data: {"content": "你", "type": "content"} │
│ data: {"content": "好", "type": "content"} │
│ data: {"content": "！", "type": "content"} │
│ data: {"done": true, "type": "end"} │
└──────────────────┬──────────────────────────┘
│
↓
┌─────────────────────────────────────────────┐
│ HTTP Response Stream │
│ Content-Type: text/event-stream │
│ Cache-Control: no-cache │
│ Connection: keep-alive │
└─────────────────────────────────────────────┘
实现要点：
- 使用
asyncio.Queue缓冲 Token - 生产者：LLM 异步生成 Token 放入队列
- 消费者：FastAPI
EventSourceResponse从队列读取并推送 - 超时保护：30 秒无输出自动断开
📚 RAG 系统完整架构
离线索引构建 vs 在线检索生成
RAG 系统分为两个独立但协同的阶段：
┌──────────────────────────────────────────────────────────────────┐
│ RAG 系统双阶段架构 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ 阶段一：离线索引构建 (rag_indexer) │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 文档加载 → 文本切分 → Embedding → 向量存储 │ │
│ │ PDF/DOCX/TXT 递归/语义/父子块 llama.cpp Qdrant │ │
│ └────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 阶段二：在线检索生成 (backend/app/rag) │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 用户查询 → 查询改写 → 多路检索 → RRF 融合 → 重排序 │ │
│ │ MultiQuery Dense+Sparse Cross-Encoder │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ LLM 生成回答 │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
RAG 演进路线 (Roadmap)
Level 1: 基础向量搜索 (Basic Similarity Search)
核心算法: 近似最近邻搜索 (ANN, 常用 HNSW 算法)
算法原理：
用户问题 → Embedding 模型 → 向量表示
↓
计算与库中向量的余弦相似度
↓
取距离最近的 K 个块返回
优缺点：
✅ 速度极快（毫秒级）
❌ 只能捕捉"语义相似"，专有名词匹配差
实现代码：
from app.rag.retriever import create_base_retriever
retriever = create_base_retriever(
collection_name="rag_documents",
embeddings=embeddings,
search_kwargs={"k": 20}
)
docs = retriever.invoke("什么是 RAG？")
Level 2: 混合检索与重排序 (Hybrid Search + Reranker)
1. 基础召回（混合检索）
算法原理：
稠密向量检索（语义相似）+ BM25 稀疏检索（关键词匹配）
↓
两路结果并行获取，等待融合
实现代码：
from app.rag.retriever import create_hybrid_retriever
retriever = create_hybrid_retriever(
collection_name="rag_documents",
embeddings=embeddings,
dense_k=10,
sparse_k=10,
score_threshold=0.3
)
2. 二次精排（Cross-Encoder）
算法原理：
不同于双塔模型（分别算向量再求距离）
交叉编码器将"问题 + 文档"拼接后整体输入 Transformer
由模型直接输出 0~1 的相关性得分，精度极高
实现代码：
from app.rag.reranker import LLaMaCPPReranker
reranker = LLaMaCPPReranker(
base_url="http://127.0.0.1:8083",
api_key="your-api-key",
top_n=5
)
sorted_docs = reranker.compress_documents(documents, query)
Level 3: RAG-Fusion (多路改写与倒数排名融合)
1. 多路查询改写
算法原理：
克服用户初始提问词不达意或视角受限的问题
通过 LLM 将单一问题改写为多个不同角度的查询
实现代码：
from app.rag.query_transform import MultiQueryGenerator
generator = MultiQueryGenerator(llm=llm, num_queries=3)
queries = await generator.agenerate("如何申请项目资金？")
# 返回：["如何申请项目资金？", "项目资金申请流程是什么？", "申请项目经费需要哪些步骤？"]
2. 倒数排名融合（RRF）
算法原理：
RRF (Reciprocal Rank Fusion) 是一种无需评分归一化的融合算法
公式：RRF_score(d) = Σ 1/(k + rank_q(d))
有效避免某一极端检索结果主导全局
实现代码：
from app.rag.fusion import reciprocal_rank_fusion
# 多个查询的检索结果
doc_lists = [result1, result2, result3]
fused_docs = reciprocal_rank_fusion(doc_lists, k=60)
Level 4: Agentic RAG / Self-RAG (智能体与自我反思)
核心原理：
基于 LangGraph 的 ReAct (Reasoning and Acting) 状态机路由
大模型并非每次都去死板地执行检索，而是先判断问题：
"这是闲聊？还是需要查知识库？"
工作流程：
┌──────────┐ ┌──────────────┐ ┌──────────┐ ┌────────┐
│ User │────>│ LangGraph │────>│ RAG_Tool │────>│ Qdrant │
│ │ │ Agent │ │ │ │ │
│ "公司报 │ │ 思考: 这是 │ │ ToolCall │ │ RAG- │
│ 销流程？"│ │ 内部规章问题 │ │ search_ │ │ Fusion │
│ │ │ 需要查资料 │ │ knowledge│ │ & 混合 │
│ │<────│ 资料充分， │<────│ 返回最相 │<────│ 检索 │
│ "根据知 │ │ 开始撰写回答 │ │ 关5条规定 │ │ Cross- │
│ 识库规定 │ │ │ │ │ │ Encoder│
│ ..." │ │ │ │ │ │ 重排 │
└────────── └────────────── └──────────┘ └────────┘
实现代码：
from app.rag.tools import search_knowledge_base
from app.main_graph.utils.main_graph_builder import MainGraphBuilder
# 构建图
builder = MainGraphBuilder()
graph = builder.build_graph().compile(checkpointer=checkpointer)
Level 5: GraphRAG 集成 (基于图和关系的 RAG)
核心原理：
结合知识图谱的结构化关系和向量检索的语义相似度
解决跨文档复杂关系推理问题
实现代码：
from langchain_community.graphs import Neo4jGraph
from langchain_experimental.graph_transformers import LLMGraphTransformer
# 实体关系抽取
transformer = LLMGraphTransformer(llm=local_llm)
graph_documents = transformer.convert_to_graph_documents(documents)
# 存储到图数据库
graph = Neo4jGraph(url="bolt://localhost:7687")
graph.add_graph_documents(graph_documents)
检索策略对比
| 策略 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 基础向量检索 | 速度快，语义理解好 | 专有名词匹配差 | 通用问答 |
| 混合检索 | 语义 + 关键词匹配 | 需要配置稀疏向量 | 专业术语查询 |
| 多路改写 + RRF | 搜索面广，结果稳定 | 延迟略高 | 复杂问题 |
| 重排序 | 精度高 | 依赖额外模型 | 最终精排 |
| Agentic RAG | 智能决策，灵活 | 实现复杂 | 生产环境 |
| GraphRAG | 关系推理能力强 | 需要图数据库 | 知识密集型场景 |
切分策略对比
| 策略 | 原理 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|---|
| 递归字符 | 按分隔符递归切分 | 速度快，实现简单 | 可能截断语义 | 简单文档 |
| 语义切分 | 基于句子相似度阈值 | 语义连贯性好 | 需要 Embedding 模型 | 专业文档 |
| 父子块 | 大块存储+小块检索 | 检索精准+上下文完整 | 存储复杂度高 | 生产环境 |
🧩 子图系统架构
设计理念
子图系统采用模块化设计，每个子图是一个独立的 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) │
└───────────────────────────────────────────────────────────────────┘
子图架构总览
graph TB
subgraph "主图 MainGraph"
MainState[主图 MainState<br>用户输入 + 上下文]
IntentRouter[意图分类器<br>intent.py]
MainLLM[主 LLM 节点<br>普通对话]
end
subgraph "通讯录子图 ContactSubgraph"
ContactState[ContactState<br>联系人状态]
ContactNodes[内部节点<br>parse_intent<br>add_contact<br>list_contacts<br>generate_draft<br>human_review<br>should_continue]
ContactDB[(PostgreSQL 联系人)]
end
subgraph "词典子图 DictionarySubgraph"
DictState[DictionaryState<br>词典状态]
DictNodes[内部节点<br>translate<br>lookup_word<br>extract_terms<br>daily_word<br>lookup_word_book<br>add_to_word_book]
DictDB[(PostgreSQL 生词本)]
end
subgraph "资讯分析子图 NewsSubgraph"
NewsState[NewsAnalysisState<br>资讯状态]
NewsNodes[内部节点<br>query_news<br>analyze_url<br>extract_keywords<br>generate_report]
NewsQdrant[(Qdrant 向量检索)]
end
MainState -->|用户查询| IntentRouter
IntentRouter -->|contact| ContactState
IntentRouter -->|dictionary| DictState
IntentRouter -->|news| NewsState
IntentRouter -->|chat| MainLLM
ContactState -->|调用| ContactNodes
ContactNodes -->|读写| ContactDB
ContactNodes -->|返回结果| MainState
DictState -->|调用| DictNodes
DictNodes -->|读写| DictDB
DictNodes -->|返回结果| MainState
NewsState -->|调用| NewsNodes
NewsNodes -->|检索| NewsQdrant
NewsNodes -->|返回结果| MainState
style MainState fill:#e3f2fd
style IntentRouter fill:#ffe0b2
style ContactState fill:#c8e6c9
style DictState fill:#e1bee7
style NewsState fill:#ffcdd2
状态传送机制
sequenceDiagram
participant User as 用户
participant Frontend as 前端
participant Backend as 后端 API
participant Main as 主图
participant Intent as 意图分类器
participant Subgraph as 子图
participant DB as 数据库
User->>Frontend: 输入查询
Frontend->>Backend: POST /subgraph/{type}/{action}
Backend->>Main: 初始化 MainState
Main->>Intent: 调用意图分类
Intent-->>Main: 返回子图类型 (contact/dictionary/news/chat)
alt 是子图请求
Main->>Subgraph: 传递状态
activate Subgraph
Subgraph->>Subgraph: 解析意图 (parse_intent)
Subgraph->>DB: 读取/写入数据
DB-->>Subgraph: 返回数据
Subgraph->>Subgraph: 执行业务逻辑
Subgraph->>Subgraph: 格式化结果 (format_result)
Subgraph-->>Main: 返回结果状态
deactivate Subgraph
else 是普通对话
Main->>Main: 调用主 LLM
end
Main->>Main: 合并状态
Main-->>Backend: 返回最终结果
Backend-->>Frontend: JSON 响应
Frontend-->>User: 显示结果
核心工具说明
1. state_base.py - 状态基类
提供类型安全的状态基类，所有子图状态继承此类。
2. intent.py - 意图理解（React 模式）
智能决策节点，判断是否需要调用 RAG、是否需要重新检索、是否需要调用工具。
# 核心功能
- 意图分类：闲聊 / 查询 / 任务
- RAG 决策：是否需要检索知识库
- 检索策略：是否需要多路检索 / 是否需要重新检索
3. formatter.py - 格式化输出工具
使用 Jinja2 模板提供美观的 Markdown 格式化输出。
4. human_review.py - 人工审核节点
使用 LangGraph 的 interrupt 机制实现人工审核流程，支持：
- 确定 / 取消 / 继续 三种操作
- 状态持久化
- 异步等待
子图开发指南
创建新子图的步骤
- 创建子图目录
mkdir backend/app/subgraphs/my_subgraph
- 创建状态定义 (state.py)
from typing_extensions import TypedDict
from ..core.state_base import BaseSubgraphState
class MySubgraphState(BaseSubgraphState):
\"\"\"
我的子图状态
\"\"\"
my_field: str
my_list: list[str]
- 实现节点 (nodes.py)
from langgraph.graph import StateGraph
from .state import MySubgraphState
def my_node(state: MySubgraphState) -> MySubgraphState:
\"\"\"
我的节点
\"\"\"
# 实现逻辑
return state
- 构建图 (graph.py)
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()
- 添加 API 客户端 (api_client.py)（可选） 用于与外部 API 交互。
已实现的子图
1. 通讯录子图 (contact/)
详细流程图：
stateDiagram-v2
[*] --> parse_intent: 开始
parse_intent --> list_contacts: action=list
parse_intent --> add_contact: action=add
parse_intent --> list_emails: action=list_emails
parse_intent --> generate_email_draft: action=generate_email
parse_intent --> sniff_contacts: action=sniff
list_contacts --> format_result: 返回联系人列表
add_contact --> format_result: 添加成功
list_emails --> format_result: 返回邮件列表
sniff_contacts --> format_result: 嗅探完成
generate_email_draft --> human_review: 生成草稿
human_review --> send_email: action=approve
human_review --> format_result: action=reject
send_email --> format_result: 邮件已发送
format_result --> [*]: 格式化输出
note right of parse_intent
解析用户意图
支持的操作：
- list: 列出联系人
- add: 添加联系人
- list_emails: 列出邮件
- generate_email: 生成邮件草稿
- sniff: 智能嗅探
end note
note right of human_review
人工审核节点
使用 LangGraph interrupt
支持三种操作：
- approve: 审核通过，发送邮件
- reject: 审核拒绝，返回结果
- modify: 审核修改，编辑内容
end note
功能列表：
- 联系人 CRUD（增删改查）
- 邮件读取与审核
- 外发邮件
- 智能嗅探
- 精美格式化展示
API 端点：
GET /subgraph/contact/{action}
参数:
- action: list | add | list_emails | generate_email | sniff
- query: 查询内容
- user_id: 用户 ID
2. 词典子图 (dictionary/)
详细流程图：
stateDiagram-v2
[*] --> parse_intent: 开始
parse_intent --> query_word: action=query
parse_intent --> translate_text: action=translate
parse_intent --> extract_terms: action=extract
parse_intent --> get_daily_word: action=daily
parse_intent --> lookup_word_book: action=lookup
parse_intent --> add_to_word_book: action=add
query_word --> format_result: 查询单词
translate_text --> format_result: 翻译文本
extract_terms --> format_result: 提取专业术语
get_daily_word --> format_result: 每日一词
lookup_word_book --> format_result: 查询生词本
add_to_word_book --> format_result: 添加到生词本
format_result --> [*]: 格式化输出
note right of parse_intent
解析用户意图
支持的操作：
- query: 查询单词
- translate: 翻译文本
- extract: 提取专业术语
- daily: 每日一词
- lookup: 查询生词本
- add: 添加到生词本
end note
功能列表：
- 翻译、查词
- 每日一词
- 专业名词提炼
- 生词本管理
- 精美格式化展示
API 端点：
GET /subgraph/dictionary/{action}
参数:
- action: query | translate | extract | daily | lookup | add
- query: 查询内容
- user_id: 用户 ID
3. 资讯分析子图 (news_analysis/)
详细流程图：
stateDiagram-v2
[*] --> parse_intent: 开始
parse_intent --> query_news: action=query
parse_intent --> analyze_url: action=analyze
parse_intent --> extract_keywords: action=keywords
parse_intent --> generate_report: action=report
query_news --> format_result: 查询资讯
analyze_url --> format_result: 分析链接
extract_keywords --> format_result: 提取关键词
generate_report --> format_result: 生成报告
format_result --> [*]: 格式化输出
note right of parse_intent
解析用户意图
支持的操作：
- query: 查询资讯
- analyze: 分析链接
- keywords: 提取关键词
- report: 生成报告
end note
功能列表：
- 资讯查询
- 链接分析
- 关键词提取
- 报告生成
- 精美格式化展示
API 端点：
GET /subgraph/news/{action}
参数:
- action: query | analyze | keywords | report
- query: 查询内容
- user_id: 用户 ID
4. 研究分析子图 (research/) - 未实现
以下功能尚未实现：
- 联网搜索
- 报告生成（资讯分析子图已提供基础报告生成）
- 引用溯源
- 可视化图表
🚀 快速开始
详细启动指南请查看 QUICKSTART.md
方式一：Docker Compose（推荐）
# 1. 配置环境变量
cp .env.docker .env
# 编辑 .env 文件，填入真实的 API Key
# 2. 启动所有服务
docker compose -f docker/docker-compose.yml up -d --build
# 3. 访问应用
# 前端: http://127.0.0.1:8501
# 后端 API: http://127.0.0.1:8083
方式二：本地开发模式
# 1. 安装依赖
pip install -r requirement.txt
# 2. 配置环境变量
cp .env.docker .env
# 编辑 .env，根据本地/远程环境调整配置
# 3. 启动后端
python backend/app/backend.py
# 4. 启动前端（新终端）
streamlit run frontend/src/frontend_main.py
# 或者使用启动脚本（推荐）
./scripts/start.sh both
📖 使用指南
基础对话
直接在聊天框输入问题即可：
你好，请介绍一下自己
帮我写一个 Python 脚本
主要功能
| 功能 | 说明 | 示例提问 |
|---|---|---|
| 🧠 混合路由智能分流 | 自动判断任务类型，选择最佳路径 | 自然对话即可 |
| ⚡ 快速路径 | 闲聊、RAG查询、工具调用可走快速路径 | "你好"、"什么是 RAG" |
| 🔄 React 推理循环 | 复杂任务走完整的思考-行动-观察循环 | "帮我分析一下这个文档" |
| 🌐 联网搜索 | 免费 DuckDuckGo 搜索 | "今天北京天气怎么样？" |
| 📚 RAG 知识库检索 | 检索本地知识库 | "如何配置系统？" |
| 📇 通讯录管理 | 联系人 CRUD、邮件处理 | "帮我查看一下张三的联系方式" |
| 📖 智能词典 | 翻译、生词本、专业术语提取 | "帮我翻译这句话" |
| 📰 资讯分析 | 资讯获取、内容分析 | "帮我分析一下这篇新闻" |
| 📊 可视化图表 | 支持 Mermaid 图表生成 | "帮我画一个流程图" |
多模型切换
-
在左侧边栏选择模型：
- 智谱 GLM-4：在线服务，速度快
- DeepSeek V3：深度推理模型
- OpenAI GPT-4o-mini：通用对话模型
- 本地 Qwen3.5-9B：本地部署，隐私性好
-
可随时切换，甚至在同一会话中
-
点击 "🔄 新会话" 清空当前对话
🔧 开发指南
添加新工具
在 backend/app/main_graph/tools/common_tools.py 中添加新的 @tool 装饰函数：
from langchain_core.tools import tool
from typing import Optional
@tool
def my_new_tool(param: str) -> str:
"""
工具描述（会显示给 LLM）
Args:
param: 参数说明
Returns:
返回值说明
"""
# 实现逻辑
return result
然后在 backend/app/main_graph/tools/graph_tools.py 的 AVAILABLE_TOOLS 列表中注册。
添加新模型
在 backend/app/model_services/chat_services.py 中添加新的服务提供者：
class NewModelChatProvider(BaseServiceProvider[BaseChatModel]):
"""
新模型服务提供者
"""
def __init__(self, model: str = "new-model-name"):
super().__init__("new_model_chat")
self._model = model
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
然后在 CHAT_PROVIDERS 字典中注册：
CHAT_PROVIDERS: Dict[str, Callable[[], BaseServiceProvider[BaseChatModel]]] = {
"local": lambda: LocalChatProvider(),
"zhipu": lambda: ZhipuChatProvider(),
"deepseek": lambda: DeepSeekChatProvider(),
"openai": lambda: OpenAIChatProvider(),
"new_model": lambda: NewModelChatProvider(), # 新增
}
添加新的子图
1. 创建子图目录结构
在 backend/app/subgraphs/ 下创建新的子图目录：
backend/app/subgraphs/
└── my_subgraph/
├── __init__.py
├── state.py # 子图状态定义
├── nodes.py # 子图节点实现
├── graph.py # 子图构建
└── api_client.py # 外部 API 客户端（可选）
2. 定义子图状态
在 state.py 中定义：
from typing import TypedDict, Annotated, Literal
from langgraph.graph.message import add_messages
class MySubgraphState(TypedDict):
"""子图状态"""
messages: Annotated[list, add_messages]
user_id: str
query: str
result: str
step: Literal["init", "process", "format", "end"]
3. 实现子图节点
在 nodes.py 中实现节点函数：
from .state import MySubgraphState
def process_query(state: MySubgraphState) -> MySubgraphState:
"""处理查询"""
query = state["query"]
# 处理逻辑
return {
"step": "format",
"result": "处理结果"
}
def format_output(state: MySubgraphState) -> MySubgraphState:
"""格式化输出"""
result = state["result"]
return {
"step": "end",
"result": f"格式化后的结果: {result}"
}
4. 构建子图
在 graph.py 中构建：
from langgraph.graph import StateGraph, END
from .state import MySubgraphState
from .nodes import process_query, format_output
def create_my_subgraph() -> StateGraph:
"""创建子图"""
graph = StateGraph(MySubgraphState)
graph.add_node("process_query", process_query)
graph.add_node("format_output", format_output)
graph.set_entry_point("process_query")
graph.add_edge("process_query", "format_output")
graph.add_edge("format_output", END)
return graph
5. 在主图中注册子图工具
在 backend/app/main_graph/tools/subgraph_tools.py 中添加子图调用工具：
@tool
async def my_subgraph_tool(query: str) -> str:
"""
我的子图工具描述
Args:
query: 用户查询
Returns:
子图执行结果
"""
# 调用子图逻辑
return result
6. 在 React Reason 中添加路由
在 backend/app/core/intent.py 的 react_reason_async 函数中添加对子图工具的支持。
Docker 部署
项目包含完整的 Docker 配置：
- docker-compose.yml：服务编排（Backend + Frontend，连接远程数据库）
- docker/Dockerfile.backend：后端镜像构建
- docker/Dockerfile.frontend：前端镜像构建
- .gitea/workflows/deploy.yml：CI/CD 自动化部署
详见 QUICKSTART.md 的 Docker 部署章节。
⚙️ 环境配置
配置文件说明
项目采用两层环境配置文件体系：
| 文件 | 用途 | 是否提交 Git |
|---|---|---|
.env.docker |
Docker 部署模板 | ✅ 是 |
.env |
实际使用的配置 | ❌ 否（已忽略） |
使用方法：
- 本地开发：
cp .env.docker .env，修改为本地服务地址 - Docker 部署：
cp .env.docker .env，使用远程服务器地址
重要配置（必需）
| 变量名 | 说明 | 示例值 |
|---|---|---|
ZHIPUAI_API_KEY |
智谱AI API密钥 | your-api-key |
DEEPSEEK_API_KEY |
DeepSeek API密钥 | your-api-key |
LLAMACPP_API_KEY |
llama.cpp API密钥 | your-api-key |
VLLM_BASE_URL |
主 LLM 服务地址 | http://127.0.0.1:18000/v1 |
LLAMACPP_EMBEDDING_URL |
Embedding 服务地址 | http://127.0.0.1:18001/v1 |
LLAMACPP_RERANKER_URL |
Rerank 服务地址 | http://127.0.0.1:18002/v1 |
DB_HOST |
PostgreSQL 主机 | 115.190.121.151 |
DB_PORT |
PostgreSQL 端口 | 5432 |
DB_USER |
PostgreSQL 用户名 | postgres |
DB_PASSWORD |
PostgreSQL 密码 | your-password |
DB_NAME |
PostgreSQL 数据库名 | langgraph_db |
QDRANT_URL |
Qdrant 向量数据库地址 | http://115.190.121.151:6333 |
QDRANT_API_KEY |
Qdrant API 密钥 | your-api-key |
其他配置（有默认值）
| 变量名 | 说明 | 默认值 |
|---|---|---|
BACKEND_PORT |
后端服务端口 | 8079 |
API_URL |
前端调用后端地址 | http://backend:8079/chat |
MEMORY_SUMMARIZE_INTERVAL |
对话摘要生成间隔 | 10 |
ENABLE_GRAPH_TRACE |
是否启用图追踪 | true |
FASTEMBED_CACHE_PATH |
FastEmbed 缓存路径 | /app/fastembed_cache |
RAG_COLLECTION_NAME |
RAG 集合名称 | rag_documents |
RAG_STRATEGY |
RAG 切分策略 | parent-child |
RAG_STORAGE_TYPE |
RAG 存储类型 | postgres |
LOG_LEVEL |
日志级别 | DEBUG |
DEBUG |
调试模式 | true |
注意事项
- ⚠️ 不要硬编码敏感信息：所有 API Key 必须通过环境变量配置
- ⚠️ 远程服务依赖：确保可以访问远程 PostgreSQL (115.190.121.151:5432) 和 Qdrant (115.190.121.151:6333)
- ⚠️ 修改后重启：修改
.env后，Docker 部署需要执行docker compose down && docker compose up -d --build
🔍 故障排查
常见问题
Q: 无法连接远程数据库？
# 测试 PostgreSQL
psql -h 115.190.121.151 -U postgres -d langgraph_db -c "SELECT version();"
# 测试 Qdrant
curl http://115.190.121.151:6333/collections
Q: 后端启动失败？
- 确认端口 8079 未被占用
- 检查
.env中的 API Key 是否正确 - 查看启动日志确认模型初始化成功
Q: 模型切换后无响应？
- 检查所选模型的配置是否正确
- 确认 llama.cpp 服务是否运行（如使用本地模型）
- 尝试切换到另一个模型
Q: 混合路由异常？
- 检查
ENABLE_GRAPH_TRACE=true查看详细执行流程 - 确认快速路径工具是否正确注册
- 查看 React Reason 节点的输出
更多问题排查请查看 QUICKSTART.md
📝 许可证
本项目采用 MIT 许可证。详见 LICENSE 文件。
🤝 贡献
欢迎提交 Issue 和 Pull Request！