- 删除过时文档：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:
@@ -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