ailine/REACT_MODE_SUMMARY.md

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	集成混合路由到主图

配置项

# 构建图时可选择
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()	获取所有可用的生成式大模型服务（用于多模型切换）

使用方法

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()	获取重排模型服务（自动降级）

---

🚀 快速使用

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）