| iteration_id |
title |
status |
version |
created_at |
parent_spec |
| v0.8.0-intent-hybrid-routing |
意图识别混合路由优化 - 模块边界与依赖盘点 |
draft |
0.8.0 |
2026-03-08 |
spec/ai-service/requirements.md |
意图识别混合路由优化 - Scope & Dependencies
1. 模块边界说明（Module Scope）
1.1 本次覆盖范围
本次迭代仅聚焦于 意图识别子域 的混合路由优化，具体包括：
| 覆盖项 |
说明 |
| RuleMatcher |
保留现有 IntentRouter 关键词/正则匹配逻辑，增加 score 输出 |
| SemanticMatcher |
新增：基于 Embedding 的意图向量语义匹配 |
| LlmJudge |
新增：冲突/低置信场景的 LLM 仲裁 |
| FusionPolicy |
新增：三路打分融合决策策略 |
| IntentRouter 升级 |
改造：新增 match_hybrid() 方法，调用三路 Matcher + FusionPolicy |
| IntentRule 实体扩展 |
新增：intent_vector、semantic_examples 字段 |
| 路由追踪日志 |
新增：route_trace 字段支持监控 API |
| 融合配置 API |
新增：融合权重与阈值的配置管理 |
1.2 本次不覆盖范围
| 不覆盖项 |
原因 |
所属模块 |
| Orchestrator 主流程 |
仅在 Step 3 插入混合路由，不改主链路 |
orchestrator.py |
| RAG 检索模块 |
本次仅意图识别，不涉及知识库检索逻辑 |
retrieval/* |
| Flow 流程引擎 |
意图路由结果驱动流程，流程逻辑不变 |
flow/* |
| Guardrail 护栏 |
输出过滤逻辑不变 |
guardrail/* |
| Prompt 模板系统 |
模板渲染逻辑不变 |
prompt/* |
| Memory 记忆层 |
会话管理不变 |
memory/* |
| LLM Adapter |
LLM 调用逻辑不变 |
llm/* |
| /ai/chat API |
对外响应语义不变 |
api/chat.py |
| 多知识库管理 |
知识库路由逻辑不变 |
kb/* |
| Query 改写 |
Query 增强逻辑不变 |
retrieval/query_rewriter.py |
1.3 边界约束
┌─────────────────────────────────────────────────────────────────────┐
│ Orchestrator Pipeline │
│ │
│ Step 1 Step 2 Step 3 [改造] Step 4 Step 5-12 │
│ Input Flow Intent Query RAG/LLM/... │
│ Scanner Engine Router Rewriter │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ Hybrid Routing │ ← 本次改造范围 │
│ │ (Rule+Semantic+LLM)│ │
│ └─────────────────────┘ │
│ │ │
│ ▼ │
│ response_type 路由（不变） │
│ │
└─────────────────────────────────────────────────────────────────────┘
2. 依赖清单（Dependencies）
2.1 内部依赖
| 依赖模块 |
依赖方式 |
用途说明 |
| EmbeddingProvider |
复用 |
SemanticMatcher 使用现有 Embedding 提供者生成向量 |
| QdrantClient |
复用 |
SemanticMatcher 使用现有向量数据库进行相似度检索 |
| LLMClient |
复用 |
LlmJudge 使用现有 LLM 客户端进行仲裁 |
| IntentRuleService |
复用 |
规则 CRUD、缓存管理、命中统计 |
| RuleCache |
复用 |
规则内存缓存（TTL=60s） |
| GenerationContext |
扩展 |
新增 route_trace 字段 |
2.2 外部依赖
| 依赖项 |
类型 |
说明 |
| PostgreSQL |
数据库 |
IntentRule 实体存储（扩展字段） |
| Qdrant |
向量库 |
意图向量索引（复用现有 Collection 或新建） |
| LLM API |
外部服务 |
LlmJudge 仲裁调用 |
2.3 依赖接口清单
2.3.1 EmbeddingProvider 接口（复用）
class EmbeddingProvider(ABC):
async def embed(self, text: str) -> list[float]:
"""生成单个文本的向量"""
pass
async def embed_batch(self, texts: list[str]) -> list[list[float]]:
"""批量生成向量"""
pass
def get_dimension(self) -> int:
"""获取向量维度"""
pass
2.3.2 QdrantClient 接口（复用）
class QdrantClient:
async def search(
self,
collection_name: str,
query_vector: list[float],
limit: int = 10,
score_threshold: float | None = None,
query_filter: dict | None = None
) -> list[ScoredPoint]:
"""向量相似度搜索"""
pass
2.3.3 LLMClient 接口（复用）
class LLMClient:
async def generate(
self,
messages: list[dict],
max_tokens: int = 1000,
temperature: float = 0.7
) -> LLMResponse:
"""生成回复"""
pass
2.3.4 IntentRuleService 接口（复用）
class IntentRuleService:
async def get_enabled_rules_for_matching(self, tenant_id: str) -> list[IntentRule]:
"""获取启用的规则列表（按优先级降序）"""
pass
async def increment_hit_count(self, tenant_id: str, rule_id: uuid.UUID) -> bool:
"""更新命中统计"""
pass
3. 对外提供能力（Provider Contracts）
3.1 新增接口
| 接口 |
类型 |
说明 |
IntentRouter.match_hybrid() |
内部方法 |
混合路由入口，返回融合结果 |
GET /admin/intent-rules/fusion-config |
Admin API |
获取融合配置 |
PUT /admin/intent-rules/fusion-config |
Admin API |
更新融合配置 |
POST /admin/intent-rules/{id}/generate-vector |
Admin API |
生成意图向量 |
3.2 扩展接口
| 接口 |
变更说明 |
IntentRule 实体 |
新增 intent_vector、semantic_examples 字段 |
POST /admin/intent-rules |
支持 intent_vector、semantic_examples 参数 |
PUT /admin/intent-rules/{id} |
支持 intent_vector、semantic_examples 参数 |
GET /admin/monitoring/conversations/{id} |
响应新增 route_trace 字段 |
3.3 不变的对外契约
| 契约 |
说明 |
/ai/chat 响应 |
reply、confidence、shouldTransfer 字段语义不变 |
IntentRouter.match() |
保留原有方法，向后兼容 |
| 意图规则响应类型 |
fixed/rag/flow/transfer 路由逻辑不变 |
4. 数据模型变更
4.1 IntentRule 实体扩展
ALTER TABLE intent_rules ADD COLUMN intent_vector JSONB;
ALTER TABLE intent_rules ADD COLUMN semantic_examples JSONB;
COMMENT ON COLUMN intent_rules.intent_vector IS '意图向量（预计算）';
COMMENT ON COLUMN intent_rules.semantic_examples IS '语义示例句列表（动态计算）';
4.2 ChatMessage 实体扩展
ALTER TABLE chat_messages ADD COLUMN route_trace JSONB;
COMMENT ON COLUMN chat_messages.route_trace IS '意图路由追踪日志';
4.3 新增配置模型
class FusionConfig:
w_rule: float = 0.5
w_semantic: float = 0.3
w_llm: float = 0.2
semantic_threshold: float = 0.7
conflict_threshold: float = 0.2
gray_zone_threshold: float = 0.6
min_trigger_threshold: float = 0.3
clarify_threshold: float = 0.4
multi_intent_threshold: float = 0.15
5. 风险评估
| 风险项 |
等级 |
缓解措施 |
| Embedding 调用增加延迟 |
中 |
SemanticMatcher 设置超时（100ms），超时跳过 |
| LLM Judge 频繁触发增加成本 |
中 |
配置合理的触发阈值，默认仅在冲突/灰区触发 |
| 语义向量配置复杂度高 |
低 |
提供自动生成 API，支持示例句模式降低门槛 |
| 多路匹配结果不一致 |
中 |
FusionPolicy 明确优先级规则，记录决策原因 |
| 向后兼容性 |
低 |
保留 match() 方法，新增 match_hybrid() 方法 |
6. 准入条件检查
7. 文件变更清单
7.1 新增文件
| 文件路径 |
说明 |
app/services/intent/semantic_matcher.py |
语义匹配器 |
app/services/intent/llm_judge.py |
LLM 仲裁器 |
app/services/intent/fusion_policy.py |
融合决策策略 |
app/services/intent/models.py |
数据模型定义 |
tests/test_semantic_matcher.py |
语义匹配单元测试 |
tests/test_llm_judge.py |
LLM 仲裁单元测试 |
tests/test_fusion_policy.py |
融合决策单元测试 |
tests/test_intent_router_hybrid.py |
混合路由集成测试 |
7.2 修改文件
| 文件路径 |
变更说明 |
app/models/entities.py |
扩展 IntentRule、ChatMessage 实体 |
app/services/intent/router.py |
新增 match_hybrid() 方法 |
app/services/orchestrator.py |
Step 3 调用 match_hybrid() |
app/api/admin/intent_rules.py |
新增融合配置 API |
app/api/admin/monitoring.py |
返回 route_trace 字段 |
7.3 数据库迁移
| 迁移文件 |
说明 |
alembic/versions/xxx_add_intent_vector_fields.py |
新增 intent_vector、semantic_examples 字段 |
alembic/versions/xxx_add_route_trace_field.py |
新增 route_trace 字段 |