root
b647150814
All checks were successful
构建并部署 AI Agent 服务 / deploy (push) Successful in 5m42s
- 删除冗余文档：backend/app/README.md、backend/app/model_services/README.md - 保留重要深度文档：backend/app/rag/README.md（RAG 模块详细说明） - 更新 REACT_MODE_SUMMARY.md：加入模型服务层的关键内容
183 lines
6.7 KiB
Markdown
183 lines
6.7 KiB
Markdown
# 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） |
|
||
|
||
---
|
||
|
||
## 🛠️ 模型服务层
|
||
|
||
### 生成式大模型服务（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("分类用户意图：'你好'")
|
||
```
|
||
|
||
### 嵌入与重排模型服务
|
||
|
||
| 函数 | 说明 |
|
||
|------|------|
|
||
| `get_embedding_service()` | 获取嵌入模型服务（自动降级） |
|
||
| `get_rerank_service()` | 获取重排模型服务（自动降级） |
|
||
|
||
---
|
||
|
||
## 🚀 快速使用
|
||
|
||
```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）
|