层级	组件	技术选型	说明
Agent 框架	工作流编排	LangGraph + LangChain	状态机驱动的智能体工作流
后端框架	API 服务	FastAPI + Uvicorn	RESTful API + SSE 流式输出
前端框架	Web 界面	Streamlit	交互式对话界面
关系数据库	持久化存储	PostgreSQL	对话记忆持久化（远程服务器）
向量数据库	向量检索	Qdrant	高性能向量相似度检索（远程服务器）
容器化	服务编排	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)

2. 系统全景图

展示系统各组件之间的高层交互关系，隐藏执行细节。

graph TB
    subgraph UserLayer["👤 用户层"]
        Browser["浏览器"]
        Streamlit["Streamlit 前端<br/>:8501"]
    end

    subgraph AppLayer["⚙️ 应用服务层"]
        FastAPI["FastAPI 后端<br/>:8079"]
        Agent["AIAgentService<br/>（智能体协调）"]
    end

    subgraph EngineLayer["🧠 智能体引擎"]
        LangGraph["LangGraph 工作流引擎<br/>路由 / React / 工具调用"]
    end

    subgraph ServicesLayer["🧩 领域服务"]
        RAG["RAG 检索服务"]
        Tools["工具集<br/>（搜索、通讯录、词典等）"]
    end

    subgraph ModelLayer["🤖 模型层"]
        LLM["LLM 服务<br/>（多模型降级链）"]
        Embedding["Embedding 服务<br/>:18001"]
        Rerank["Rerank 服务<br/>:18002"]
    end

    subgraph DataLayer["💾 数据层"]
        Qdrant["Qdrant 向量库"]
        PostgreSQL["PostgreSQL"]
    end

    Browser --> Streamlit
    Streamlit --> FastAPI
    FastAPI --> Agent
    Agent --> LangGraph
    LangGraph --> RAG
    LangGraph --> Tools
    LangGraph --> LLM
    RAG --> Embedding
    RAG --> Rerank
    RAG --> Qdrant
    Agent --> PostgreSQL
    LangGraph --> PostgreSQL

    style UserLayer fill:#e1f5ff
    style AppLayer fill:#fff4e1
    style EngineLayer fill:#ffe0b2
    style ServicesLayer fill:#e8f5e9
    style ModelLayer fill:#f3e5f5
    style DataLayer fill:#ffebee

3. 智能体引擎（主图）

3.1 核心流程

graph TB
    Start([开始]) --> Retrieve["检索长期记忆"]
    Retrieve --> Trigger["记忆触发"]
    Trigger --> Init["初始化状态"]
    Init --> Route{"混合路由<br/>hybrid_router"}
    
    Route -->|闲聊/简单问答| Fast["⚡ 快速路径<br/>（fast_*）"]
    Route -->|知识检索| FastRAG["⚡ 快速 RAG"]
    Route -->|工具调用| FastTool["⚡ 快速工具"]
    Route -->|复杂任务| React["🔄 React 循环"]
    
    React --> Reason["推理"]
    Reason --> Action["选择行动"]
    Action -->|需要检索| RAGNode["RAG 检索"]
    Action -->|搜索| Web["联网搜索"]
    Action -->|通讯录| Contact["通讯录子图"]
    Action -->|词典| Dict["词典子图"]
    Action -->|资讯| News["资讯子图"]
    Action -->|LLM| LLMCall["LLM 生成"]
    
    RAGNode --> Observe["观察结果"]
    Web --> Observe
    Contact --> Observe
    Dict --> Observe
    News --> Observe
    LLMCall --> Observe
    Observe -->|未完成| Reason
    Observe -->|完成| Final["生成最终回复"]
    
    Fast --> Final
    FastRAG --> Final
    FastTool --> Final
    Final --> End([结束])

    style Route fill:#fff3e0,stroke:#ff9800,stroke-width:3px
    style React fill:#f3e5f5,stroke:#7e57c2,stroke-width:2px

3.2 路由策略

闲聊 / 简单问答 → fast_chitchat：直接调用 LLM 生成回复
知识检索 → fast_rag：RAG 检索后生成回复
工具调用 → fast_tool：直接执行原子工具操作
复杂任务 → React 循环：推理 → 行动 → 观察的多轮迭代

3.3 React 循环详解

当任务需要多步推理时，引擎进入 React 循环：

推理：LLM 分析当前状态，决定下一步行动
行动：执行工具调用（RAG 检索、联网搜索、子图操作等）
观察：收集行动结果，更新状态
若任务未完成，回到步骤 1；否则退出循环，生成最终回复

4. 子图系统

每个子图都是独立的模块化工作流，由主图的 React 循环按需调用。

4.1 通讯录子图

支持联系人管理、邮件草稿生成与人工审核发送。

graph LR
    Start([START]) --> Intent["parse_intent"]
    Intent --> List["list_contacts"]
    Intent --> Add["add_contact"]
    Intent --> EmailList["list_emails"]
    Intent --> GenEmail["generate_email_draft"]
    Intent --> Sniff["sniff_contacts"]
    GenEmail --> Human["human_review"]
    Human --> Send["send_email"]
    Send --> Format["format_result"]
    List --> Format
    Add --> Format
    EmailList --> Format
    Sniff --> Format
    Format --> End([END])

4.2 词典子图

支持单词查询、翻译、术语提取、每日单词、单词本管理。

graph LR
    Start([START]) --> Intent["parse_intent"]
    Intent --> Query["query_word"]
    Intent --> Trans["translate_text"]
    Intent --> Terms["extract_terms"]
    Intent --> Daily["get_daily_word"]
    Intent --> Lookup["lookup_word_book"]
    Intent --> AddWord["add_to_word_book"]
    Query --> Format["format_result"]
    Trans --> Format
    Terms --> Format
    Daily --> Format
    Lookup --> Format
    AddWord --> Format
    Format --> End([END])

4.3 资讯分析子图

支持新闻检索、URL 分析、关键词提取与报告生成。

graph LR
    Start([START]) --> Intent["parse_intent"]
    Intent --> QueryNews["query_news"]
    Intent --> AnalyzeUrl["analyze_url"]
    Intent --> Keywords["extract_keywords"]
    Intent --> Report["generate_report"]
    QueryNews --> Format["format_result"]
    AnalyzeUrl --> Format
    Keywords --> Format
    Report --> Format
    Format --> End([END])

5. RAG 系统

5.1 离线索引

文档导入、切分、嵌入生成到存入向量库的完整流程。

flowchart TB
    subgraph Input["文档输入"]
        DocSource["文档源<br/>PDF/DOCX/TXT/Markdown"]
    end

    subgraph Load["文档加载"]
        Loader["Unstructured / PyMuPDF / TextLoader"]
    end

    subgraph Split["文本切分"]
        Recursive["RecursiveCharacterTextSplitter<br/>按分隔符递归切分"]
        Semantic["SemanticChunker<br/>基于语义相似度"]
        ParentChild["ParentChildSplitter<br/>父子块切分"]
    end

    subgraph Embed["嵌入生成"]
        Dense["稠密向量<br/>Qwen3-Embedding-0.6B"]
        Sparse["稀疏向量 BM25<br/>FastEmbed"]
    end

    subgraph Store["向量存储"]
        QdrantStore["Qdrant<br/>HNSW 索引 + 稀疏索引"]
    end

    DocSource --> Loader
    Loader --> Recursive
    Loader --> Semantic
    Loader --> ParentChild
    Recursive --> Dense
    Semantic --> Dense
    ParentChild --> Dense
    Recursive --> Sparse
    Semantic --> Sparse
    ParentChild --> Sparse
    Dense --> QdrantStore
    Sparse --> QdrantStore

    style Input fill:#e3f2fd
    style Load fill:#fff3e0
    style Split fill:#f3e5f5
    style Embed fill:#e8f5e9
    style Store 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 检索

5.2 在线检索

用户查询经过改写、混合检索、融合、重排序，最终由 LLM 生成回答。

flowchart TB
    subgraph Input["查询输入"]
        Query["用户查询"]
    end

    subgraph Processing["查询处理"]
        Rewrite["查询改写<br/>（LLM 生成多角度查询）"]
    end

    subgraph Retrieval["混合检索"]
        Parallel["并行检索"]
        DenseRet["稠密向量检索"]
        SparseRet["稀疏 BM25 检索"]
    end

    subgraph Fusion["结果融合"]
        RRF["RRF 融合<br/>（Qdrant 服务端融合）"]
    end

    subgraph Rerank["重排序"]
        CrossEncoder["Cross-Encoder 重排<br/>bge-reranker-v2-m3"]
    end

    subgraph Generation["生成"]
        LLMGen["LLM 生成回答"]
    end

    Query --> Rewrite --> Parallel
    Parallel --> DenseRet
    Parallel --> SparseRet
    DenseRet --> RRF
    SparseRet --> RRF
    RRF --> CrossEncoder --> LLMGen

    style Input fill:#e3f2fd
    style Processing fill:#fff3e0
    style Retrieval fill:#f3e5f5
    style Fusion fill:#e8f5e9
    style Rerank fill:#ffebee
    style Generation fill:#fff3e0

技术组件说明：

阶段	技术选型	说明
查询改写	MultiQuery	LLM 生成 3~5 个多角度查询
稠密检索	Qwen3-Embedding	余弦相似度向量检索
稀疏检索	FastEmbed BM25	TF-IDF 词频统计检索
结果融合	Qdrant Fusion API	服务端 RRF 融合，减少数据传输
重排序	bge-reranker-v2-m3	Cross-Encoder 交互编码，精度更高
LLM 生成	chat_services	统一的大模型服务接口

6. 模型服务层

6.1 多模型降级链

当首选模型调用失败时，自动依次尝试备用模型，保证服务可用性。

graph LR
    Start([API 请求]) --> Zhipu["智谱 GLM-4"]
    Zhipu -->|失败| DeepSeek["DeepSeek V3"]
    DeepSeek -->|失败| OpenAI["OpenAI GPT-4o"]
    OpenAI -->|失败| Local["本地 Qwen3.5-9B"]
    Local --> Response([返回响应])
    style Start fill:#e1f5ff
    style Response fill:#c8e6c9

降级策略： 云端模型按优先级依次尝试，最终回退到本地模型，确保无单点故障。

6.2 统一服务接口

所有模型调用均通过以下三个统一接口访问，上层业务不感知具体模型：

chat_services：对话生成
embedding_services：文本向量化
rerank_services：搜索结果重排序

7. 数据存储

存储	用途	访问方式
PostgreSQL	对话历史、长期记忆	远程服务器，SQLAlchemy ORM
Qdrant	文档向量、知识库	远程服务器，gRPC/HTTP API

数据流向图

用户请求
   │
   ├─→ 前端 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 重排序提升相关性

详细文档：

算法原理详见 backend/docs/RAG_ALGORITHM.md
系统架构详见 backend/docs/RAG_ARCHITECTURE.md

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！

README.md Unescape Escape

AI Agent - 智能助手系统

📑 目录导航

🎯 核心功能

面向用户的功能

技术特性

🏗️ 技术架构

1. 技术栈总览

2. 系统全景图

3. 智能体引擎（主图）

3.1 核心流程

3.2 路由策略

3.3 React 循环详解

4. 子图系统

4.1 通讯录子图

4.2 词典子图

4.3 资讯分析子图

5. RAG 系统

5.1 离线索引

5.2 在线检索

6. 模型服务层

6.1 多模型降级链

6.2 统一服务接口

7. 数据存储

数据流向图

项目结构

🧠 核心算法与实现原理

1. RAG 检索算法

LangGraph 工作流详细流程

1. 混合路由 + React 循环架构 ⭐⭐

2. React 推理循环详解

2.2 状态机设计

2.3 记忆管理算法

3. 多模型路由算法

4. SSE 流式响应算法

📚 RAG 系统完整架构

离线索引构建 vs 在线检索生成

RAG 演进路线 (Roadmap)

Level 1: 基础向量搜索 (Basic Similarity Search)

Level 2: 混合检索与重排序 (Hybrid Search + Reranker)

Level 3: RAG-Fusion (多路改写与倒数排名融合)

Level 4: Agentic RAG / Self-RAG (智能体与自我反思)

Level 5: GraphRAG 集成 (基于图和关系的 RAG)

检索策略对比

切分策略对比

🧩 子图系统架构

设计理念

子图架构总览

状态传送机制

核心工具说明

1. state_base.py - 状态基类

2. intent.py - 意图理解（React 模式）

3. formatter.py - 格式化输出工具

4. human_review.py - 人工审核节点

子图开发指南

创建新子图的步骤

已实现的子图

1. 通讯录子图 (contact/)

2. 词典子图 (dictionary/)

3. 资讯分析子图 (news_analysis/)

4. 研究分析子图 (research/) - 未实现

🚀 快速开始

方式一：Docker Compose（推荐）

方式二：本地开发模式

📖 使用指南

基础对话

主要功能

多模型切换

🔧 开发指南

添加新工具

添加新模型

添加新的子图

1. 创建子图目录结构

2. 定义子图状态

3. 实现子图节点

4. 构建子图

5. 在主图中注册子图工具

6. 在 React Reason 中添加路由

Docker 部署

⚙️ 环境配置

README.md