MerCry
/
ai-robot-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai-robot-core/spec/ai-service/iterations/v0.8.0-intent-hybrid-routing/design.md

984 lines
35 KiB
Markdown
Raw Permalink Normal View History

docs: update spec and docs for v0.8.0 intent hybrid routing and mid-platform features [AC-DOCS]
2026-03-10 04:10:50 +00:00
---
feature_id: "AISVC"
iteration_id: "v0.8.0-intent-hybrid-routing"
title: "意图识别混合路由优化 - 技术设计"
status: "draft"
version: "0.8.0"
created_at: "2026-03-08"
inputs:
- "spec/ai-service/iterations/v0.8.0-intent-hybrid-routing/requirements.md"
- "spec/ai-service/iterations/v0.8.0-intent-hybrid-routing/scope.md"
---
# 意图识别混合路由优化 - Design（v0.8.0）
## 1. 设计目标与约束
### 1.1 设计目标
- 将意图识别从"单一规则匹配"升级为"规则+语义+LLM"三路混合路由
- 提升意图识别召回率与准确率
- 提供置信度评分与路由追踪日志
- 最小侵入：仅在 Step 3 插入混合路由，不改主链路
### 1.2 硬约束
- 现有规则引擎继续可用，作为混合路由的一路输入
- `/ai/chat` 对外响应语义不变
- 全部新增逻辑必须 tenantId 隔离
- 保留 `IntentRouter.match()` 方法向后兼容
---
## 2. 架构设计
### 2.1 最小侵入架构图
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Orchestrator 12-Step Pipeline │
│ │
│ Step 1: InputScanner → Step 2: FlowEngine → Step 3: IntentRouter [改造] │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐│
│ │ IntentRouter (Hybrid Routing) ││
│ │ ││
│ │ ┌─────────────────────────────────────────────────────────────────────┐││
│ │ │ Parallel Matching Layer │││
│ │ │ │││
│ │ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │││
│ │ │ │ RuleMatcher │ │SemanticMatcher│ │ LlmJudge │ │││
│ │ │ │ (现有+score) │ │ (新增) │ │ (条件触发) │ │││
│ │ │ │ │ │ │ │ │ │││
│ │ │ │ keywords │ │ embedding │ │ LLM call │ │││
│ │ │ │ regex │ │ similarity │ │ arbitration │ │││
│ │ │ │ score: 0|1 │ │ score: 0~1 │ │ score: 0~1 │ │││
│ │ │ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │││
│ │ │ │ │ │ │││
│ │ │ └───────────────────┼───────────────────┘ │││
│ │ │ ▼ │││
│ │ └─────────────────────────────────────────────────────────────────────┘││
│ │ │ ││
│ │ ▼ ││
│ │ ┌─────────────────────────────────────────────────────────────────────┐││
│ │ │ FusionPolicy (新增) │││
│ │ │ │││
│ │ │ 输入: rule_result, semantic_result, llm_result │││
│ │ │ 处理: 加权融合 + 冲突检测 + 阈值判定 │││
│ │ │ 输出: final_intent, final_confidence, decision_reason, trace │││
│ │ │ │││
│ │ └─────────────────────────────────────────────────────────────────────┘││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────┘│
│ │ │
│ ▼ │
│ response_type 路由（不变） │
│ fixed / rag / flow / transfer │
└─────────────────────────────────────────────────────────────────────────────┘
```
### 2.2 插入点标注
| 插入点 | 位置 | 改造内容 |
|--------|------|----------|
| Step 3 入口 | orchestrator.py:500 | 调用 `IntentRouter.match_hybrid()` 替代 `match()` |
| IntentRule 实体 | entities.py:420-463 | 新增 `intent_vector`、`semantic_examples` 字段 |
| IntentRouter 类 | intent/router.py | 新增 `match_hybrid()` 方法，保留 `match()` 向后兼容 |
| 新增模块 | intent/ | 新增 `semantic_matcher.py`、`llm_judge.py`、`fusion_policy.py`、`models.py` |
---
## 3. 核心接口设计
### 3.1 数据模型
```python
# 位置: app/services/intent/models.py
from dataclasses import dataclass, field
from typing import Any
import uuid
@dataclass
class RuleMatchResult:
"""规则匹配结果"""
rule_id: uuid.UUID | None
rule: "IntentRule | None"
match_type: str | None # "keyword" | "regex" | None
matched_text: str | None
score: float # 1.0 或 0.0
duration_ms: int
@dataclass
class SemanticCandidate:
"""语义匹配候选"""
rule: "IntentRule"
score: float # 0.0 ~ 1.0 相似度
@dataclass
class SemanticMatchResult:
"""语义匹配结果"""
candidates: list[SemanticCandidate] # Top-N 候选
top_score: float
duration_ms: int
skipped: bool # 是否跳过（无语义向量配置）
skip_reason: str | None # 跳过原因
@dataclass
class LlmJudgeInput:
"""LLM 仲裁输入"""
message: str
candidates: list[dict] # 候选意图列表
conflict_type: str # "rule_semantic_conflict" | "gray_zone" | "multi_intent"
@dataclass
class LlmJudgeResult:
"""LLM 仲裁结果"""
intent_id: str | None
intent_name: str | None
score: float # 0.0 ~ 1.0
reasoning: str | None # LLM 的推理过程
duration_ms: int
tokens_used: int
triggered: bool
@dataclass
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
llm_judge_enabled: bool = True
semantic_matcher_enabled: bool = True
@dataclass
class RouteTrace:
"""路由追踪日志"""
rule_match: dict = field(default_factory=dict)
semantic_match: dict = field(default_factory=dict)
llm_judge: dict = field(default_factory=dict)
fusion: dict = field(default_factory=dict)
@dataclass
class FusionResult:
"""融合决策结果"""
final_intent: "IntentRule | None"
final_confidence: float
decision_reason: str
need_clarify: bool
clarify_candidates: list["IntentRule"] | None
trace: RouteTrace
```
### 3.2 RuleMatcher（改造现有 IntentRouter）
```python
# 位置: app/services/intent/router.py
class RuleMatcher:
"""规则匹配器（基于现有 IntentRouter）"""
def match(self, message: str, rules: list[IntentRule]) -> RuleMatchResult:
"""
关键词+正则匹配
匹配算法:
1. 按 priority 降序遍历规则
2. 对每条规则，先尝试关键词匹配
3. 若无关键词匹配，尝试正则模式匹配
4. 返回第一个匹配（最高优先级）
Args:
message: 用户消息
rules: 规则列表（已按优先级降序排列）
Returns:
RuleMatchResult: 匹配结果
"""
start_time = time.time()
message_lower = message.lower()
for rule in rules:
if not rule.is_enabled:
continue
result = self._match_keywords(message, message_lower, rule)
if result:
duration_ms = int((time.time() - start_time) * 1000)
return RuleMatchResult(
rule_id=rule.id,
rule=rule,
match_type="keyword",
matched_text=result.matched,
score=1.0,
duration_ms=duration_ms
)
result = self._match_patterns(message, rule)
if result:
duration_ms = int((time.time() - start_time) * 1000)
return RuleMatchResult(
rule_id=rule.id,
rule=rule,
match_type="regex",
matched_text=result.matched,
score=1.0,
duration_ms=duration_ms
)
duration_ms = int((time.time() - start_time) * 1000)
return RuleMatchResult(
rule_id=None,
rule=None,
match_type=None,
matched_text=None,
score=0.0,
duration_ms=duration_ms
)
def _match_keywords(self, message: str, message_lower: str, rule: IntentRule) -> IntentMatchResult | None:
"""关键词匹配（保留现有逻辑）"""
pass
def _match_patterns(self, message: str, rule: IntentRule) -> IntentMatchResult | None:
"""正则匹配（保留现有逻辑）"""
pass
```
### 3.3 SemanticMatcher（新增）
```python
# 位置: app/services/intent/semantic_matcher.py
import asyncio
from typing import Any
import numpy as np
class SemanticMatcher:
"""语义匹配器"""
def __init__(
self,
embedding_provider: EmbeddingProvider,
config: FusionConfig
):
self._embedding_provider = embedding_provider
self._config = config
async def match(
self,
message: str,
rules: list[IntentRule],
tenant_id: str,
top_k: int = 3
) -> SemanticMatchResult:
"""
向量语义匹配
匹配模式:
- 模式 A: 使用规则预置的 intent_vector 直接计算相似度
- 模式 B: 使用规则的 semantic_examples 动态计算平均相似度
Args:
message: 用户消息
rules: 规则列表
tenant_id: 租户 ID
top_k: 返回候选数
Returns:
SemanticMatchResult: 匹配结果
"""
start_time = time.time()
if not self._config.semantic_matcher_enabled:
return SemanticMatchResult(
candidates=[],
top_score=0.0,
duration_ms=0,
skipped=True,
skip_reason="disabled"
)
rules_with_semantic = [r for r in rules if self._has_semantic_config(r)]
if not rules_with_semantic:
duration_ms = int((time.time() - start_time) * 1000)
return SemanticMatchResult(
candidates=[],
top_score=0.0,
duration_ms=duration_ms,
skipped=True,
skip_reason="no_semantic_config"
)
try:
message_vector = await asyncio.wait_for(
self._embedding_provider.embed(message),
timeout=self._config.semantic_matcher_timeout_ms / 1000
)
except asyncio.TimeoutError:
duration_ms = int((time.time() - start_time) * 1000)
return SemanticMatchResult(
candidates=[],
top_score=0.0,
duration_ms=duration_ms,
skipped=True,
skip_reason="embedding_timeout"
)
except Exception as e:
duration_ms = int((time.time() - start_time) * 1000)
return SemanticMatchResult(
candidates=[],
top_score=0.0,
duration_ms=duration_ms,
skipped=True,
skip_reason=f"embedding_error: {str(e)}"
)
candidates = []
for rule in rules_with_semantic:
score = await self._calculate_similarity(message_vector, rule)
if score > 0:
candidates.append(SemanticCandidate(rule=rule, score=score))
candidates.sort(key=lambda x: x.score, reverse=True)
candidates = candidates[:top_k]
duration_ms = int((time.time() - start_time) * 1000)
return SemanticMatchResult(
candidates=candidates,
top_score=candidates[0].score if candidates else 0.0,
duration_ms=duration_ms,
skipped=False,
skip_reason=None
)
def _has_semantic_config(self, rule: IntentRule) -> bool:
"""检查规则是否有语义配置"""
return bool(rule.intent_vector) or bool(rule.semantic_examples)
async def _calculate_similarity(self, message_vector: list[float], rule: IntentRule) -> float:
"""计算相似度"""
if rule.intent_vector:
return self._cosine_similarity(message_vector, rule.intent_vector)
elif rule.semantic_examples:
example_vectors = await self._embedding_provider.embed_batch(rule.semantic_examples)
similarities = [
self._cosine_similarity(message_vector, v)
for v in example_vectors
]
return max(similarities) if similarities else 0.0
return 0.0
def _cosine_similarity(self, v1: list[float], v2: list[float]) -> float:
"""计算余弦相似度"""
v1_arr = np.array(v1)
v2_arr = np.array(v2)
return float(np.dot(v1_arr, v2_arr) / (np.linalg.norm(v1_arr) * np.linalg.norm(v2_arr)))
```
### 3.4 LlmJudge（新增）
```python
# 位置: app/services/intent/llm_judge.py
class LlmJudge:
"""LLM 仲裁器"""
JUDGE_PROMPT = """你是一个意图识别仲裁器。根据用户消息和候选意图，判断最匹配的意图。
用户消息：{message}
候选意图：
{candidates}
请返回 JSON 格式：
{{
"intent_id": "最匹配的意图ID",
"intent_name": "意图名称",
"confidence": 0.0-1.0之间的置信度,
"reasoning": "判断理由"
}}
"""
def __init__(
self,
llm_client: LLMClient,
config: FusionConfig
):
self._llm_client = llm_client
self._config = config
def should_trigger(
self,
rule_result: RuleMatchResult,
semantic_result: SemanticMatchResult,
config: FusionConfig
) -> tuple[bool, str]:
"""
判断是否触发 LLM Judge
触发条件:
1. 冲突场景：RuleMatcher 与 SemanticMatcher 命中不同意图
2. 灰区场景：最高置信度在灰区范围内
3. 多意图场景：多个候选意图置信度接近
Args:
rule_result: 规则匹配结果
semantic_result: 语义匹配结果
config: 融合配置
Returns:
(是否触发, 触发原因)
"""
if not config.llm_judge_enabled:
return False, "disabled"
rule_score = rule_result.score
semantic_score = semantic_result.top_score
if rule_score > 0 and semantic_score > 0:
if rule_result.rule_id != semantic_result.candidates[0].rule.id:
if abs(rule_score - semantic_score) < config.conflict_threshold:
return True, "rule_semantic_conflict"
max_score = max(rule_score, semantic_score)
if config.min_trigger_threshold < max_score < config.gray_zone_threshold:
return True, "gray_zone"
if len(semantic_result.candidates) >= 2:
top1_score = semantic_result.candidates[0].score
top2_score = semantic_result.candidates[1].score
if abs(top1_score - top2_score) < config.multi_intent_threshold:
return True, "multi_intent"
return False, ""
async def judge(
self,
input: LlmJudgeInput,
tenant_id: str
) -> LlmJudgeResult:
"""
LLM 仲裁
Args:
input: 仲裁输入
tenant_id: 租户 ID
Returns:
LlmJudgeResult: 仲裁结果
"""
start_time = time.time()
candidates_text = "\n".join([
f"- ID: {c['id']}, 名称: {c['name']}, 描述: {c.get('description', 'N/A')}"
for c in input.candidates
])
prompt = self.JUDGE_PROMPT.format(
message=input.message,
candidates=candidates_text
)
try:
response = await asyncio.wait_for(
self._llm_client.generate(
messages=[{"role": "user", "content": prompt}],
max_tokens=200,
temperature=0
),
timeout=self._config.llm_judge_timeout_ms / 1000
)
result = self._parse_response(response.content)
duration_ms = int((time.time() - start_time) * 1000)
return LlmJudgeResult(
intent_id=result.get("intent_id"),
intent_name=result.get("intent_name"),
score=result.get("confidence", 0.5),
reasoning=result.get("reasoning"),
duration_ms=duration_ms,
tokens_used=response.total_tokens,
triggered=True
)
except asyncio.TimeoutError:
duration_ms = int((time.time() - start_time) * 1000)
return LlmJudgeResult(
intent_id=None,
intent_name=None,
score=0.0,
reasoning="LLM timeout",
duration_ms=duration_ms,
tokens_used=0,
triggered=True
)
except Exception as e:
duration_ms = int((time.time() - start_time) * 1000)
return LlmJudgeResult(
intent_id=None,
intent_name=None,
score=0.0,
reasoning=f"LLM error: {str(e)}",
duration_ms=duration_ms,
tokens_used=0,
triggered=True
)
def _parse_response(self, content: str) -> dict:
"""解析 LLM 响应"""
import json
try:
return json.loads(content)
except json.JSONDecodeError:
return {}
```
### 3.5 FusionPolicy（新增）
```python
# 位置: app/services/intent/fusion_policy.py
class FusionPolicy:
"""融合决策策略"""
DECISION_PRIORITY = [
("rule_high_confidence", lambda r, s, l: r.score == 1.0 and r.rule is not None),
("llm_judge", lambda r, s, l: l.triggered and l.intent_id is not None),
("semantic_override", lambda r, s, l: r.score == 0 and s.top_score > 0.7),
("rule_semantic_agree", lambda r, s, l: r.score > 0 and s.top_score > 0.5 and r.rule_id == s.candidates[0].rule.id if s.candidates else False),
("semantic_fallback", lambda r, s, l: s.top_score > 0.5),
("rule_fallback", lambda r, s, l: r.score > 0),
("no_match", lambda r, s, l: True),
]
def __init__(self, config: FusionConfig):
self._config = config
def fuse(
self,
rule_result: RuleMatchResult,
semantic_result: SemanticMatchResult,
llm_result: LlmJudgeResult | None
) -> FusionResult:
"""
融合决策
Args:
rule_result: 规则匹配结果
semantic_result: 语义匹配结果
llm_result: LLM 仲裁结果（可能为 None）
Returns:
FusionResult: 融合结果
"""
trace = RouteTrace(
rule_match={
"rule_id": str(rule_result.rule_id) if rule_result.rule_id else None,
"match_type": rule_result.match_type,
"matched_text": rule_result.matched_text,
"score": rule_result.score,
"duration_ms": rule_result.duration_ms
},
semantic_match={
"top_candidates": [
{"rule_id": str(c.rule.id), "name": c.rule.name, "score": c.score}
for c in semantic_result.candidates
],
"top_score": semantic_result.top_score,
"duration_ms": semantic_result.duration_ms,
"skipped": semantic_result.skipped,
"skip_reason": semantic_result.skip_reason
},
llm_judge={
"triggered": llm_result.triggered if llm_result else False,
"intent_id": llm_result.intent_id if llm_result else None,
"score": llm_result.score if llm_result else 0.0,
"duration_ms": llm_result.duration_ms if llm_result else 0,
"tokens_used": llm_result.tokens_used if llm_result else 0
},
fusion={}
)
final_intent = None
final_confidence = 0.0
decision_reason = "no_match"
for reason, condition in self.DECISION_PRIORITY:
if condition(rule_result, semantic_result, llm_result or LlmJudgeResult.empty()):
decision_reason = reason
break
if decision_reason == "rule_high_confidence":
final_intent = rule_result.rule
final_confidence = 1.0
elif decision_reason == "llm_judge" and llm_result:
final_intent = self._find_rule_by_id(llm_result.intent_id, rule_result, semantic_result)
final_confidence = llm_result.score
elif decision_reason == "semantic_override":
final_intent = semantic_result.candidates[0].rule
final_confidence = semantic_result.top_score
elif decision_reason == "rule_semantic_agree":
final_intent = rule_result.rule
final_confidence = self._calculate_weighted_confidence(rule_result, semantic_result, llm_result)
elif decision_reason == "semantic_fallback":
final_intent = semantic_result.candidates[0].rule
final_confidence = semantic_result.top_score
elif decision_reason == "rule_fallback":
final_intent = rule_result.rule
final_confidence = rule_result.score
need_clarify = final_confidence < self._config.clarify_threshold
clarify_candidates = None
if need_clarify and len(semantic_result.candidates) > 1:
clarify_candidates = [c.rule for c in semantic_result.candidates[:3]]
trace.fusion = {
"weights": {
"w_rule": self._config.w_rule,
"w_semantic": self._config.w_semantic,
"w_llm": self._config.w_llm
},
"final_confidence": final_confidence,
"decision_reason": decision_reason
}
return FusionResult(
final_intent=final_intent,
final_confidence=final_confidence,
decision_reason=decision_reason,
need_clarify=need_clarify,
clarify_candidates=clarify_candidates,
trace=trace
)
def _calculate_weighted_confidence(
self,
rule_result: RuleMatchResult,
semantic_result: SemanticMatchResult,
llm_result: LlmJudgeResult | None
) -> float:
"""计算加权置信度"""
rule_score = rule_result.score
semantic_score = semantic_result.top_score if not semantic_result.skipped else 0.0
llm_score = llm_result.score if llm_result and llm_result.triggered else 0.0
total_weight = self._config.w_rule + self._config.w_semantic
if llm_result and llm_result.triggered:
total_weight += self._config.w_llm
confidence = (
self._config.w_rule * rule_score +
self._config.w_semantic * semantic_score +
self._config.w_llm * llm_score
) / total_weight
return min(1.0, max(0.0, confidence))
def _find_rule_by_id(
self,
intent_id: str | None,
rule_result: RuleMatchResult,
semantic_result: SemanticMatchResult
) -> IntentRule | None:
"""根据 ID 查找规则"""
if not intent_id:
return None
if rule_result.rule_id and str(rule_result.rule_id) == intent_id:
return rule_result.rule
for candidate in semantic_result.candidates:
if str(candidate.rule.id) == intent_id:
return candidate.rule
return None
```
### 3.6 IntentRouter 升级
```python
# 位置: app/services/intent/router.py
class IntentRouter:
"""意图路由器（升级版）"""
def __init__(
self,
rule_matcher: RuleMatcher,
semantic_matcher: SemanticMatcher,
llm_judge: LlmJudge,
fusion_policy: FusionPolicy,
config: FusionConfig | None = None
):
self._rule_matcher = rule_matcher
self._semantic_matcher = semantic_matcher
self._llm_judge = llm_judge
self._fusion_policy = fusion_policy
self._config = config or FusionConfig()
async def match_hybrid(
self,
message: str,
rules: list[IntentRule],
tenant_id: str,
config: FusionConfig | None = None
) -> FusionResult:
"""
混合路由入口
流程:
1. 并行执行 RuleMatcher + SemanticMatcher
2. 判断是否触发 LlmJudge
3. 执行 FusionPolicy
4. 返回融合结果
Args:
message: 用户消息
rules: 规则列表
tenant_id: 租户 ID
config: 融合配置（可选，覆盖默认配置）
Returns:
FusionResult: 融合结果
"""
effective_config = config or self._config
rule_result, semantic_result = await asyncio.gather(
asyncio.to_thread(self._rule_matcher.match, message, rules),
self._semantic_matcher.match(message, rules, tenant_id)
)
llm_result = None
should_trigger, trigger_reason = self._llm_judge.should_trigger(
rule_result, semantic_result, effective_config
)
if should_trigger:
candidates = self._build_llm_candidates(rule_result, semantic_result)
llm_result = await self._llm_judge.judge(
LlmJudgeInput(
message=message,
candidates=candidates,
conflict_type=trigger_reason
),
tenant_id
)
fusion_result = self._fusion_policy.fuse(
rule_result, semantic_result, llm_result
)
return fusion_result
def match(self, message: str, rules: list[IntentRule]) -> IntentMatchResult | None:
"""
原有方法保留，向后兼容
Args:
message: 用户消息
rules: 规则列表
Returns:
IntentMatchResult | None: 匹配结果
"""
result = self._rule_matcher.match(message, rules)
if result.rule:
return IntentMatchResult(
rule=result.rule,
match_type=result.match_type,
matched=result.matched_text
)
return None
def _build_llm_candidates(
self,
rule_result: RuleMatchResult,
semantic_result: SemanticMatchResult
) -> list[dict]:
"""构建 LLM 候选列表"""
candidates = []
if rule_result.rule:
candidates.append({
"id": str(rule_result.rule_id),
"name": rule_result.rule.name,
"description": f"匹配方式: {rule_result.match_type}, 匹配内容: {rule_result.matched_text}"
})
for candidate in semantic_result.candidates[:3]:
if not any(c["id"] == str(candidate.rule.id) for c in candidates):
candidates.append({
"id": str(candidate.rule.id),
"name": candidate.rule.name,
"description": f"语义相似度: {candidate.score:.2f}"
})
return candidates
```
---
## 4. 融合公式与默认阈值
### 4.1 融合公式
```
final_confidence = (w_rule * rule_score + w_semantic * semantic_score + w_llm * llm_score) / total_weight
```
其中：
- `total_weight = w_rule + w_semantic + (w_llm if llm_triggered else 0)`
- 结果限制在 `[0.0, 1.0]` 范围内
### 4.2 默认阈值配置
```python
DEFAULT_FUSION_CONFIG = FusionConfig(
w_rule=0.5, # 规则权重
w_semantic=0.3, # 语义权重
w_llm=0.2, # LLM 权重
semantic_threshold=0.7, # 语义匹配高置信阈值
conflict_threshold=0.2, # 冲突判定阈值（置信度差值）
gray_zone_threshold=0.6, # 灰区上限阈值
min_trigger_threshold=0.3, # 灰区下限阈值
clarify_threshold=0.4, # 澄清触发阈值
multi_intent_threshold=0.15, # 多意图判定阈值
llm_judge_enabled=True, # 启用 LLM 仲裁
semantic_matcher_enabled=True, # 启用语义匹配
)
```
### 4.3 决策优先级
| 优先级 | 决策原因 | 条件 |
|--------|----------|------|
| 1 | rule_high_confidence | RuleMatcher 命中且 score=1.0 |
| 2 | llm_judge | LlmJudge 触发且返回有效意图 |
| 3 | semantic_override | RuleMatcher 未命中但 SemanticMatcher 高置信 |
| 4 | rule_semantic_agree | 规则与语义匹配同一意图 |
| 5 | semantic_fallback | SemanticMatcher 中等置信 |
| 6 | rule_fallback | 仅规则匹配 |
| 7 | no_match | 三路均低置信 |
---
## 5. 异常处理策略
| 异常场景 | 处理策略 | 可观测性 |
|----------|----------|----------|
| Embedding 调用失败 | 跳过 SemanticMatcher，仅使用 RuleMatcher | `semantic_match.skipped=true, skip_reason="embedding_failed"` |
| Embedding 超时 | 跳过 SemanticMatcher，仅使用 RuleMatcher | `semantic_match.skipped=true, skip_reason="embedding_timeout"` |
| Qdrant 检索失败 | 跳过 SemanticMatcher，仅使用 RuleMatcher | `semantic_match.skipped=true, skip_reason="qdrant_error"` |
| LLM 调用失败 | 回退到 SemanticMatcher 结果 | `llm_judge.reasoning="LLM error: ..."` |
| LLM 超时 | 回退到 SemanticMatcher 结果 | `llm_judge.reasoning="LLM timeout"` |
| LLM 响应解析失败 | 回退到 SemanticMatcher 结果 | `llm_judge.reasoning="parse_failed"` |
| 规则缓存失效 | 重新从数据库加载 | `rule_match.cache_miss=true` |
| 配置缺失 | 使用默认配置 | `fusion.using_default_config=true` |
---
## 6. 数据模型变更
### 6.1 IntentRule 实体扩展
```python
# 位置: app/models/entities.py
class IntentRule(SQLModel, table=True):
# ... 现有字段 ...
intent_vector: list[float] | None = Field(
default=None,
sa_column=Column(JSONB, nullable=True, comment="意图向量（预计算）")
)
semantic_examples: list[str] | None = Field(
default=None,
sa_column=Column(JSONB, nullable=True, comment="语义示例句列表")
)
```
### 6.2 ChatMessage 实体扩展
```python
# 位置: app/models/entities.py
class ChatMessage(SQLModel, table=True):
# ... 现有字段 ...
route_trace: dict[str, Any] | None = Field(
default=None,
sa_column=Column(JSONB, nullable=True, comment="意图路由追踪日志")
)
```
---
## 7. API 设计
### 7.1 融合配置 API
```
GET /admin/intent-rules/fusion-config
PUT /admin/intent-rules/fusion-config
```
### 7.2 意图向量生成 API
```
POST /admin/intent-rules/{id}/generate-vector
```
### 7.3 监控 API 扩展
```
GET /admin/monitoring/conversations/{id}
```
响应新增 `route_trace` 字段。
---
## 8. 性能优化
### 8.1 并行执行
RuleMatcher 和 SemanticMatcher 使用 `asyncio.gather` 并行执行。
### 8.2 超时控制
- SemanticMatcher 超时：100ms
- LlmJudge 超时：2000ms
### 8.3 缓存策略
- 规则缓存：复用现有 RuleCache（TTL=60s）
- 向量缓存：可选，后续迭代考虑
---
## 9. 风险与待澄清
### 9.1 风险
| 风险 | 等级 | 缓解措施 |
|------|------|----------|
| Embedding 调用增加延迟 | 中 | 设置超时，超时跳过 |
| LLM Judge 频繁触发增加成本 | 中 | 配置合理触发阈值 |
| 语义向量配置复杂度高 | 低 | 提供自动生成 API |
### 9.2 待澄清
- 意图向量索引是否需要独立的 Qdrant Collection？
- LlmJudge 的 Token 消耗是否需要单独计费统计？
- 融合配置是否需要支持租户级差异化配置？