ailine/backend/docs/HYBRID_ROUTER.md

混合 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

完整事件流

用户消息
  ↓
intent_classified  (新!)
  ↓
path_decision      (新!)
  ↓
[node_start] llm_call
  ↓
[reasoning] 思考过程
  ↓
[tool_call_start] 工具调用开始
  ↓
[tool_call_end] 工具调用结束
  ↓
[llm_token] 最终回答
  ↓
[human_review_request] 人工审核（如有）
  ↓
[done]

使用示例

快速路径示例

# 输入
用户: "你好"

# 响应
intent_classified: {
  intent: "chitchat",
  confidence: 0.95,
  reasoning: "简单寒暄"
}
path_decision: {
  path: "fast",
  intent: "chitchat"
}
llm_token: "你"...
llm_token: "好"...

React 循环示例

# 输入
用户: "帮我查订单，然后生成邮件"

# 响应
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. 初始化意图分类器

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. 使用混合路由

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")

配置选项

置信度阈值

# 修改 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. 可观测性 - 前端显示路径决策

测试建议

测试用例

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}")

扩展指南

添加新的快速路径

# 在 HybridRouter 中添加
async def _execute_custom_path(self, user_input: str) -> str:
    # 自定义路径逻辑
    pass

添加缓存层

# 在 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. 保持向后兼容