- 删除过时文档：REACT_PLAN.md、backend/docs/HYBRID_ROUTER.md - 更新 REACT_MODE_SUMMARY.md：加入新的混合路由架构 - 更新 README.md：加入混合路由、双模型服务等新特性 - 更新 backend/app/README.md：加入 hybrid_router.py - 更新 backend/app/model_services/README.md：加入 get_chat_service/get_small_llm_service - 更新 .gitignore：允许 REACT_MODE_SUMMARY.md 上传 - 新增 backend/test/test_hybrid_router.py：测试脚本
This commit is contained in:
1
.gitignore
vendored
1
.gitignore
vendored
@@ -26,6 +26,7 @@
|
||||
!.gitignore
|
||||
!README.md
|
||||
!QUICKSTART.md
|
||||
!REACT_MODE_SUMMARY.md
|
||||
!LICENSE
|
||||
!requirement.txt
|
||||
!.env.docker
|
||||
|
||||
149
REACT_MODE_SUMMARY.md
Normal file
149
REACT_MODE_SUMMARY.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# React 模式架构总结
|
||||
|
||||
---
|
||||
|
||||
## ✅ 当前架构：混合路由 + React 循环
|
||||
|
||||
本项目采用 **两层混合架构**：
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 第一层：前置混合路由（低延迟） │
|
||||
│ ├─ 规则快速分流（无 LLM） │
|
||||
│ ├─ 轻量级意图分类（smallLLM） │
|
||||
│ └─ 快速路径（fast_chitchat, fast_rag, fast_tool） │
|
||||
└───────────────────────┬─────────────────────────────────────┘
|
||||
↓（自动升级：失败时）
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 第二层：完整 React 循环（兜底，复杂任务处理） │
|
||||
│ └─ 推理 → 行动 → 观察（最多 40 步） │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 第一层：前置混合路由（新）
|
||||
|
||||
### 核心功能
|
||||
|
||||
| 功能 | 说明 |
|
||||
|------|------|
|
||||
| 规则快速分流 | 无 LLM，毫秒级响应，用于问候、感谢、子图关键词等 |
|
||||
| 轻量级意图分类 | 使用 smallLLM，压缩到 4 类：chitchat, knowledge, tool, complex |
|
||||
| 快速路径 | 三个快速处理节点：fast_chitchat, fast_rag, fast_tool |
|
||||
| 自动升级 | 快速路径失败时，自动回到完整 React 循环 |
|
||||
| SSE 事件增强 | intent_classified, path_decision, fast_path_*, escalation |
|
||||
|
||||
### 快速流程图
|
||||
|
||||
```
|
||||
START
|
||||
↓
|
||||
init_state
|
||||
↓
|
||||
hybrid_router (前置路由) ←────────────┐
|
||||
↓ │
|
||||
├─ 规则分流 → fast_chitchat →────────┤
|
||||
│ ↓ │
|
||||
├─ 模型分类 → fast_rag →────────────┤
|
||||
│ ↓ │
|
||||
├─ fast_tool →────────┤
|
||||
│ ↓ │
|
||||
└─ react_loop →────────┤
|
||||
↓ │
|
||||
检查成功/升级? ──────────┘
|
||||
↓ ↓
|
||||
finalize react_reason
|
||||
```
|
||||
|
||||
### 关键文件
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `backend/app/main_graph/nodes/hybrid_router.py` | 混合路由完整实现 |
|
||||
| `backend/app/model_services/chat_services.py` | get_chat_service() + get_small_llm_service() |
|
||||
| `backend/app/main_graph/utils/main_graph_builder.py` | 集成混合路由到主图 |
|
||||
|
||||
### 配置项
|
||||
|
||||
```python
|
||||
# 构建图时可选择
|
||||
graph = build_react_main_graph(use_hybrid_router=True) # 启用混合路由（默认）
|
||||
graph = build_react_main_graph(use_hybrid_router=False) # 禁用，纯 React 循环
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 第二层：完整 React 循环（保留）
|
||||
|
||||
### 核心特性
|
||||
|
||||
| 特性 | 说明 |
|
||||
|------|------|
|
||||
| 循环推理 | 每轮推理判断下一步，最多 40 步 |
|
||||
| 结构化错误 | ErrorRecord + ErrorSeverity |
|
||||
| 超时重试 | RAG 最多 2 次，子图最多 1 次 |
|
||||
| 子图集成 | contact, dictionary, news_analysis |
|
||||
| RAG 检索 | 支持重检索（re_retrieve） |
|
||||
|
||||
### 流程图
|
||||
|
||||
```
|
||||
react_reason (推理) ←──────────────────┐
|
||||
↓ │
|
||||
条件路由 │
|
||||
├─→ rag_retrieve (带重试) →──────────┤
|
||||
├─→ contact_subgraph →───────────────┤
|
||||
├─→ dictionary_subgraph →────────────┤
|
||||
├─→ news_analysis_subgraph →─────────┤
|
||||
├─→ handle_error → (重试或降级) →────┤
|
||||
└─→ finalize
|
||||
↓
|
||||
END
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 关键文件清单
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `backend/app/main_graph/utils/main_graph_builder.py` | 主图构建（支持混合路由开关） |
|
||||
| `backend/app/main_graph/nodes/react_nodes.py` | React 循环节点 |
|
||||
| `backend/app/main_graph/nodes/hybrid_router.py` | 混合路由节点（新） |
|
||||
| `backend/app/main_graph/nodes/rag_nodes.py` | RAG 检索节点 |
|
||||
| `backend/app/main_graph/utils/retry_utils.py` | 超时重试工具 |
|
||||
| `backend/app/main_graph/state.py` | 主状态 |
|
||||
| `backend/app/core/intent.py` | React 模式意图推理器 |
|
||||
| `backend/app/model_services/chat_services.py` | 双模型服务（llm + smallLLM） |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速使用
|
||||
|
||||
```python
|
||||
from backend.app.main_graph.utils.main_graph_builder import build_react_main_graph
|
||||
|
||||
# 构建图（默认启用混合路由）
|
||||
graph = build_react_main_graph(use_hybrid_router=True)
|
||||
compiled_graph = graph.compile()
|
||||
|
||||
# 调用
|
||||
result = compiled_graph.invoke({"user_query": "你好", "user_id": "test"})
|
||||
print(result.final_result)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎉 完整特性总结
|
||||
|
||||
✅ 双模型服务 (llm + smallLLM)
|
||||
✅ 前置混合路由（规则快速分流 + 轻量级意图分类）
|
||||
✅ 三个快速路径（fast_chitchat, fast_rag, fast_tool）
|
||||
✅ 自动升级机制（快速路径失败 → 完整 React 循环）
|
||||
✅ SSE 事件增强（intent_classified, path_decision, fast_path_*, escalation）
|
||||
✅ 完整 React 循环（最多 40 步）
|
||||
✅ 结构化错误处理
|
||||
✅ 超时和重试策略
|
||||
✅ 子图集成（contact, dictionary, news_analysis）
|
||||
✅ 向后兼容（use_hybrid_router=True/False）
|
||||
@@ -45,6 +45,10 @@
|
||||
- ✅ **子图系统**：模块化的子图架构，共享公共工具（意图理解、人工审核、格式化输出）
|
||||
- ✅ **公共工具库**：联网搜索、可视化图表等通用工具，所有子图和主图均可使用
|
||||
- ✅ **React 模式** ⭐：Reasoning → Acting → Observing 循环，LLM 先思考再行动，支持多次工具调用
|
||||
- ✅ **混合路由架构** ⭐⭐：前置快速路由（规则分流 + 轻量级意图分类）+ 完整 React 循环（兜底）
|
||||
- ✅ **双模型服务** ⭐：get_chat_service()（大模型）+ get_small_llm_service()（轻量级模型）
|
||||
- ✅ **自动升级机制**：快速路径失败时，自动回到完整 React 循环
|
||||
- ✅ **向后兼容**：可通过 use_hybrid_router=True/False 切换混合路由/纯 React 模式
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -36,6 +36,7 @@ app/
|
||||
│ ├── nodes/ # 主图节点
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── react_nodes.py # React 模式节点（推理、路由）
|
||||
│ │ ├── hybrid_router.py # ⭐ 混合路由节点（前置快速路由 + 自动升级）
|
||||
│ │ ├── llm_call.py # LLM 调用节点
|
||||
│ │ ├── retrieve_memory.py # 记忆检索节点
|
||||
│ │ ├── memory_trigger.py # 记忆触发节点
|
||||
@@ -52,7 +53,7 @@ app/
|
||||
│ │
|
||||
│ └── utils/ # 主图工具函数
|
||||
│ ├── __init__.py
|
||||
│ ├── main_graph_builder.py # 主图构建器
|
||||
│ ├── main_graph_builder.py # 主图构建器（支持混合路由开关）
|
||||
│ ├── retry_utils.py # 重试工具
|
||||
│ ├── rag_initializer.py # RAG 初始化工具
|
||||
│ └── visualize_graph.py # 图可视化工具
|
||||
|
||||
@@ -1,31 +1,85 @@
|
||||
"""
|
||||
模型服务模块（model_services）
|
||||
|
||||
提供统一的嵌入和重排模型服务获取接口，支持自动降级：
|
||||
1. 优先使用本地 llama.cpp 服务
|
||||
2. 本地服务不可用时，自动降级到智谱 API 服务
|
||||
提供统一的嵌入、重排和生成式大模型服务获取接口，支持自动降级。
|
||||
|
||||
使用方法：
|
||||
---
|
||||
|
||||
from app.model_services import get_embedding_service, get_rerank_service, BaseReranker
|
||||
## 📚 生成式大模型服务（Chat）
|
||||
|
||||
### 双模型服务
|
||||
| 函数 | 说明 |
|
||||
|------|------|
|
||||
| `get_chat_service()` | 获取大模型服务（用于复杂推理、生成） |
|
||||
| `get_small_llm_service()` | 获取轻量级模型服务（用于简单意图分类、快速问答） |
|
||||
| `get_all_chat_services()` | 获取所有可用的生成式大模型服务（用于多模型切换） |
|
||||
|
||||
### 使用方法
|
||||
|
||||
```python
|
||||
from app.model_services import get_chat_service, get_small_llm_service
|
||||
|
||||
# 获取大模型服务（复杂任务）
|
||||
llm = get_chat_service()
|
||||
response = llm.invoke("什么是 LangGraph?")
|
||||
|
||||
# 获取轻量级模型服务（简单任务）
|
||||
small_llm = get_small_llm_service()
|
||||
response = small_llm.invoke("分类用户意图：'你好'")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 嵌入模型服务（Embedding）
|
||||
|
||||
| 函数 | 说明 |
|
||||
|------|------|
|
||||
| `get_embedding_service()` | 获取嵌入模型服务（自动降级） |
|
||||
|
||||
### 使用方法
|
||||
|
||||
```python
|
||||
from app.model_services import get_embedding_service
|
||||
|
||||
# 获取嵌入服务（LangChain 兼容的 Embeddings）
|
||||
embeddings = get_embedding_service()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 重排模型服务（Rerank）
|
||||
|
||||
| 函数 | 说明 |
|
||||
|------|------|
|
||||
| `get_rerank_service()` | 获取重排模型服务（自动降级） |
|
||||
|
||||
### 使用方法
|
||||
|
||||
```python
|
||||
from app.model_services import get_rerank_service
|
||||
|
||||
# 获取重排服务
|
||||
reranker = get_rerank_service()
|
||||
sorted_docs = reranker.compress_documents(documents, query, top_n=5)
|
||||
```
|
||||
|
||||
环境变量配置：
|
||||
---
|
||||
|
||||
## 🔧 环境变量配置
|
||||
|
||||
```env
|
||||
# 智谱 API 配置
|
||||
ZHIPUAI_API_KEY=your_api_key
|
||||
ZHIPUAI_API_KEY=***
|
||||
ZHIPU_EMBEDDING_MODEL=embedding-3 # 可选：embedding-2、embedding-3
|
||||
ZHIPU_RERANK_MODEL=rerank-2 # 可选：rerank-1、rerank-2
|
||||
ZHIPU_API_BASE=https://open.bigmodel.cn/api/paas/v4
|
||||
|
||||
# DeepSeek API 配置（用于大模型）
|
||||
DEEPSEEK_API_KEY=***
|
||||
|
||||
# 本地 llama.cpp 服务配置（原有配置保持不变）
|
||||
LLAMACPP_EMBEDDING_URL=http://localhost:port/v1
|
||||
LLAMACPP_RERANKER_URL=http://localhost:port/v1
|
||||
LLAMACPP_API_KEY=your_api_key
|
||||
LLAMACPP_API_KEY=***
|
||||
```
|
||||
"""
|
||||
|
||||
@@ -1,269 +0,0 @@
|
||||
# 混合 Agent 路由架构文档
|
||||
|
||||
## 架构概述
|
||||
|
||||
```
|
||||
+-----------------+
|
||||
| 用户输入 |
|
||||
+--------+--------+
|
||||
|
|
||||
v
|
||||
+-----------------+
|
||||
| 意图分类器 |
|
||||
+--------+--------+
|
||||
|
|
||||
+----------------+-----------------+
|
||||
| | |
|
||||
v v v
|
||||
+---------+ +---------+ +----------------+
|
||||
| 知识查询 | | 工具操作 | | 复杂任务 |
|
||||
+----+----+ +----+----+ +-------+--------+
|
||||
| | |
|
||||
v v v
|
||||
+-----------+ +------------+ +---------------+
|
||||
| 快速 RAG | | 快速工具 | | React 循环 |
|
||||
+-----+-----+ +-----+------+ +-------+-------+
|
||||
| | |
|
||||
+----------------+-----------------+
|
||||
|
|
||||
v
|
||||
+-------------+
|
||||
| 最终答案 |
|
||||
+-------------+
|
||||
```
|
||||
|
||||
## 意图类型
|
||||
|
||||
| 类型 | 说明 | 示例 | 路径 |
|
||||
|------|------|------|------|
|
||||
| `knowledge` | 知识查询 | "公司报销政策是什么？" | 快速 RAG |
|
||||
| `realtime` | 实时数据查询 | "查一下订单 123 的状态" | 快速工具 |
|
||||
| `action` | 执行操作 | "帮我申请退款" | 快速工具 |
|
||||
| `chitchat` | 闲聊 | "你好" | 直接回答 |
|
||||
| `clarify` | 需要澄清 | "我想查点东西..." | 澄清反问 |
|
||||
| `mixed` | 复杂任务 | "查订单+退款政策+写邮件" | React 循环 |
|
||||
|
||||
## 路由规则
|
||||
|
||||
```
|
||||
置信度 < 0.6 → React 循环（安全模式）
|
||||
|
||||
置信度 >= 0.6
|
||||
├─ knowledge → 快速 RAG
|
||||
├─ realtime → 快速工具
|
||||
├─ action → 快速工具
|
||||
├─ chitchat → 直接回答
|
||||
├─ clarify → 澄清反问
|
||||
└─ mixed → React 循环
|
||||
```
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
backend/app/agent/
|
||||
├── intent_classifier.py # 意图分类器
|
||||
├── hybrid_router.py # 混合路由实现
|
||||
└── service.py # Agent 服务（已更新）
|
||||
```
|
||||
|
||||
## SSE 事件
|
||||
|
||||
### 新增事件
|
||||
|
||||
| 事件 | 说明 | 数据结构 |
|
||||
|------|------|---------|
|
||||
| `intent_classified` | 意图分类完成 | `{type: "intent_classified", intent: string, confidence: float, reasoning: string}` |
|
||||
| `path_decision` | 路径决策完成 | `{type: "path_decision", path: "fast|react_loop", intent: string}` |
|
||||
|
||||
### 完整事件流
|
||||
|
||||
```
|
||||
用户消息
|
||||
↓
|
||||
intent_classified (新!)
|
||||
↓
|
||||
path_decision (新!)
|
||||
↓
|
||||
[node_start] llm_call
|
||||
↓
|
||||
[reasoning] 思考过程
|
||||
↓
|
||||
[tool_call_start] 工具调用开始
|
||||
↓
|
||||
[tool_call_end] 工具调用结束
|
||||
↓
|
||||
[llm_token] 最终回答
|
||||
↓
|
||||
[human_review_request] 人工审核（如有）
|
||||
↓
|
||||
[done]
|
||||
```
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 快速路径示例
|
||||
|
||||
```python
|
||||
# 输入
|
||||
用户: "你好"
|
||||
|
||||
# 响应
|
||||
intent_classified: {
|
||||
intent: "chitchat",
|
||||
confidence: 0.95,
|
||||
reasoning: "简单寒暄"
|
||||
}
|
||||
path_decision: {
|
||||
path: "fast",
|
||||
intent: "chitchat"
|
||||
}
|
||||
llm_token: "你"...
|
||||
llm_token: "好"...
|
||||
```
|
||||
|
||||
### React 循环示例
|
||||
|
||||
```python
|
||||
# 输入
|
||||
用户: "帮我查订单，然后生成邮件"
|
||||
|
||||
# 响应
|
||||
intent_classified: {
|
||||
intent: "mixed",
|
||||
confidence: 0.92,
|
||||
reasoning: "需要查询订单、生成邮件，多步骤任务"
|
||||
}
|
||||
path_decision: {
|
||||
path: "react_loop",
|
||||
intent: "mixed"
|
||||
}
|
||||
node_start: llm_call
|
||||
reasoning: "我需要先查询订单..."
|
||||
tool_call_start: get_order
|
||||
tool_call_end: 结果
|
||||
...
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 初始化意图分类器
|
||||
|
||||
```python
|
||||
from app.agent.intent_classifier import get_intent_classifier
|
||||
|
||||
classifier = get_intent_classifier()
|
||||
|
||||
# 分类意图
|
||||
result = await classifier.classify("公司报销政策是什么？")
|
||||
print(f"意图: {result.intent_type}")
|
||||
print(f"置信度: {result.confidence}")
|
||||
print(f"推理: {result.reasoning}")
|
||||
```
|
||||
|
||||
### 2. 使用混合路由
|
||||
|
||||
```python
|
||||
from app.agent.hybrid_router import HybridRouter
|
||||
from app.agent.intent_classifier import get_intent_classifier
|
||||
|
||||
classifier = get_intent_classifier()
|
||||
router = HybridRouter(
|
||||
intent_classifier=classifier,
|
||||
rag_pipeline=None, # 传入 RAG
|
||||
tool_registry={}, # 传入工具
|
||||
react_graph=None # 传入 Graph
|
||||
)
|
||||
|
||||
# 路由决策
|
||||
decision = await router.route("你好")
|
||||
print(f"决策: {decision.action}")
|
||||
|
||||
# 执行
|
||||
result = await router.execute(decision, "你好", "thread_123")
|
||||
```
|
||||
|
||||
## 配置选项
|
||||
|
||||
### 置信度阈值
|
||||
|
||||
```python
|
||||
# 修改 backend/app/agent/hybrid_router.py 中的 _make_decision 方法
|
||||
if confidence < 0.6: # 修改这个值
|
||||
# 走 React 循环
|
||||
```
|
||||
|
||||
### 添加新的意图类型
|
||||
|
||||
1. 在 `IntentType` 枚举中添加新类型
|
||||
2. 在 `routing_map` 中添加路由规则
|
||||
3. 在 `_build_examples` 中添加示例
|
||||
|
||||
## 核心优势
|
||||
|
||||
1. **性能优化** - 简单问题走快速路径
|
||||
2. **用户体验** - 响应速度快
|
||||
3. **灵活扩展** - 易于添加新意图
|
||||
4. **安全可靠** - 低置信度走完整循环
|
||||
5. **可观测性** - 前端显示路径决策
|
||||
|
||||
## 测试建议
|
||||
|
||||
### 测试用例
|
||||
|
||||
```python
|
||||
test_cases = [
|
||||
# 知识查询
|
||||
("公司报销政策是什么？", "knowledge"),
|
||||
|
||||
# 实时查询
|
||||
("查一下订单 123 的状态", "realtime"),
|
||||
|
||||
# 执行操作
|
||||
("帮我申请退款", "action"),
|
||||
|
||||
# 闲聊
|
||||
("你好", "chitchat"),
|
||||
|
||||
# 澄清
|
||||
("我想查点东西...", "clarify"),
|
||||
|
||||
# 复杂任务
|
||||
("查订单+退款政策+写邮件", "mixed"),
|
||||
]
|
||||
|
||||
for query, expected_intent in test_cases:
|
||||
result = await classifier.classify(query)
|
||||
print(f"{query} → {result.intent_type}")
|
||||
```
|
||||
|
||||
## 扩展指南
|
||||
|
||||
### 添加新的快速路径
|
||||
|
||||
```python
|
||||
# 在 HybridRouter 中添加
|
||||
async def _execute_custom_path(self, user_input: str) -> str:
|
||||
# 自定义路径逻辑
|
||||
pass
|
||||
```
|
||||
|
||||
### 添加缓存层
|
||||
|
||||
```python
|
||||
# 在 IntentClassifier 中添加缓存
|
||||
from functools import lru_cache
|
||||
|
||||
class IntentClassifier:
|
||||
@lru_cache(maxsize=1000)
|
||||
async def classify_cached(self, user_input: str):
|
||||
# 缓存分类结果
|
||||
pass
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. 确保降级策略合理
|
||||
2. 监控意图分类准确率
|
||||
3. 根据实际情况调整置信度阈值
|
||||
4. 前端需要处理新的 SSE 事件
|
||||
5. 保持向后兼容
|
||||
Reference in New Issue
Block a user