9.5 KiB
9.5 KiB
| feature_id | iteration_id | title | status | version | created_at | parent_spec | ac_range |
|---|---|---|---|---|---|---|---|
| AISVC | v0.8.0-intent-hybrid-routing | 意图识别混合路由优化 - 需求规范 | draft | 0.8.0 | 2026-03-08 | spec/ai-service/requirements.md | AC-AISVC-111~AC-AISVC-125 |
意图识别混合路由优化 - Requirements（v0.8.0）
1. 背景与目标
1.1 背景
当前意图识别模块仅支持关键词+正则匹配，存在以下问题：
- 召回率不足：用户表达方式多样，关键词/正则难以覆盖所有语义等价表达
- 误匹配：关键词过于宽泛导致误匹配，正则表达式维护成本高
- 无置信度：匹配结果无置信度评分，无法区分高/低置信场景
1.2 目标
将意图识别从"单一规则匹配"升级为"规则+语义+LLM"三路混合路由：
- 提升召回率：通过语义匹配覆盖更多语义等价表达
- 提升准确率：通过融合决策降低误匹配
- 可观测性：提供置信度评分与路由追踪日志
1.3 非目标（Out of Scope）
- 不改动 Orchestrator 主流程（仅 Step 3 插入混合路由）
- 不改动
/ai/chat对外响应语义 - 不改动现有规则引擎（保留关键词/正则匹配作为一路输入）
- 不涉及 RAG 检索、Flow 流程、Guardrail 护栏等模块
2. 模块边界（Scope）
详见 scope.md
3. 用户故事
- [US-INTENT-01] 作为系统运营者，我希望意图识别能理解语义等价表达，以便提升用户意图识别的召回率。
- [US-INTENT-02] 作为系统运营者，我希望意图识别提供置信度评分，以便区分高/低置信场景并采取不同策略。
- [US-INTENT-03] 作为系统运营者，我希望在规则匹配与语义匹配冲突时能自动仲裁，以便减少误匹配。
- [US-INTENT-04] 作为系统维护者，我希望查看意图路由的详细追踪日志，以便排查问题与优化规则。
- [US-INTENT-05] 作为系统运营者，我希望配置融合决策的权重与阈值，以便根据业务场景调优。
4. 验收标准
4.1 混合路由三路打分
-
[AC-AISVC-111] WHEN 用户消息进入意图识别 THEN 系统 SHALL 并行执行三路匹配：
- RuleMatcher：关键词+正则匹配，输出
rule_score（命中=1.0，未命中=0.0） - SemanticMatcher：向量语义匹配，输出
semantic_score（0.0~1.0 相似度） - LlmJudge：仅在触发条件满足时执行，输出
llm_score（0.0~1.0 置信度）
- RuleMatcher：关键词+正则匹配，输出
-
[AC-AISVC-112] WHEN RuleMatcher 命中规则 THEN 系统 SHALL 输出匹配结果包含：
rule_id：命中的规则 IDmatch_type："keyword" | "regex"matched_text：匹配的关键词或模式rule_score：1.0（命中）或 0.0（未命中）
-
[AC-AISVC-113] WHEN SemanticMatcher 执行 THEN 系统 SHALL：
- 将用户消息向量化（复用现有 EmbeddingProvider）
- 与意图规则的语义向量进行相似度计算
- 返回 Top-N 候选意图及
semantic_score - 若无语义向量配置的规则，跳过此路并记录日志
-
[AC-AISVC-114] WHEN SemanticMatcher 执行 THEN 系统 SHALL 支持两种语义匹配模式：
- 模式 A：基于规则预置的
intent_vector直接计算相似度 - 模式 B：基于规则的
semantic_examples（示例句列表）动态计算平均相似度
- 模式 A：基于规则预置的
4.2 融合决策输出
-
[AC-AISVC-115] WHEN 三路匹配完成后 THEN 系统 SHALL 执行 FusionPolicy 融合决策，输出：
final_intent：最终意图（IntentMatchResult 或 None）final_confidence：最终置信度（0.0~1.0）decision_reason：决策原因（如 "rule_high_confidence" | "semantic_override" | "llm_judge" | "no_match"）route_trace：路由追踪信息（三路打分详情）
-
[AC-AISVC-116] WHEN 融合决策计算置信度 THEN 系统 SHALL 使用可配置的融合公式：
final_confidence = w_rule * rule_score + w_semantic * semantic_score + w_llm * llm_score默认权重：
w_rule=0.5, w_semantic=0.3, w_llm=0.2 -
[AC-AISVC-117] WHEN 融合决策判定意图 THEN 系统 SHALL 按以下优先级：
- 若 RuleMatcher 命中且
rule_score=1.0，优先采用规则意图 - 若 RuleMatcher 未命中但 SemanticMatcher 高置信（>semantic_threshold），采用语义意图
- 若存在冲突或低置信，触发 LlmJudge 仲裁
- 若三路均低置信，返回
no_match（回退默认 RAG）
- 若 RuleMatcher 命中且
4.3 LLM Judge 触发条件
-
[AC-AISVC-118] WHEN 以下任一条件满足 THEN 系统 SHALL 触发 LlmJudge：
- 冲突场景：RuleMatcher 与 SemanticMatcher 命中不同意图，且两者置信度差值 < conflict_threshold（默认 0.2）
- 灰区场景：最高置信度 < gray_zone_threshold（默认 0.6）且 > min_trigger_threshold（默认 0.3）
- 多意图场景：SemanticMatcher 返回多个候选意图且 Top-2 置信度差值 < multi_intent_threshold（默认 0.15）
-
[AC-AISVC-119] WHEN LlmJudge 执行 THEN 系统 SHALL：
- 构建仲裁 Prompt（包含用户消息、候选意图列表、规则描述）
- 调用 LLM 返回最终意图判定及置信度
- 记录 LLM 调用耗时与 Token 消耗
- 若 LLM 调用失败，回退到 SemanticMatcher 结果
-
[AC-AISVC-120] WHEN LlmJudge 配置为禁用 THEN 系统 SHALL 跳过 LLM 调用，仅使用 RuleMatcher + SemanticMatcher 融合决策。
4.4 澄清触发条件
- [AC-AISVC-121] WHEN 融合决策后
final_confidence < clarify_threshold（默认 0.4）THEN 系统 SHALL 在响应中设置need_clarify=true并提供候选意图列表供用户确认。- 说明：此 AC 复用现有澄清机制，仅新增触发条件判断。
4.5 路由追踪日志
-
[AC-AISVC-122] WHEN 意图识别完成 THEN 系统 SHALL 在
route_trace字段记录：rule_match：RuleMatcher 结果（rule_id, match_type, matched_text, score, duration_ms）semantic_match：SemanticMatcher 结果（top_candidates, scores, duration_ms）llm_judge：LlmJudge 结果（triggered, intent, score, duration_ms, tokens）fusion：融合决策结果（weights, final_confidence, decision_reason）
-
[AC-AISVC-123] WHEN 路由追踪日志写入 THEN 系统 SHALL 复用现有监控 API 的 trace 字段格式，支持
GET /admin/monitoring/conversations/{id}查询。
4.6 多租户隔离要求
- [AC-AISVC-124] WHEN 意图混合路由执行 THEN 系统 SHALL 确保：
- 所有规则查询按
tenant_id过滤 - 语义向量索引按
tenant_id隔离（Qdrant Collection 或 payload filter） - LlmJudge 调用携带
tenant_id用于计费与审计 - 路由追踪日志按
tenant_id隔离存储
- 所有规则查询按
4.7 性能约束
- [AC-AISVC-125] WHEN 意图混合路由执行 THEN 系统 SHALL 满足以下性能约束：
- RuleMatcher 延迟 < 10ms（内存缓存命中）
- SemanticMatcher 延迟 < 100ms（向量计算 + 相似度检索）
- LlmJudge 延迟 < 2000ms（仅在触发时执行）
- P95 总增量延迟 < 500ms（不含 LlmJudge）
- P95 总增量延迟 < 2500ms（含 LlmJudge）
5. 追踪映射
| AC ID | Endpoint | 方法 | Operation | 描述 |
|---|---|---|---|---|
| AC-AISVC-111 | - | - | - | 三路并行匹配 |
| AC-AISVC-112 | - | - | - | RuleMatcher 输出 |
| AC-AISVC-113 | - | - | - | SemanticMatcher 执行 |
| AC-AISVC-114 | - | - | - | 语义匹配模式 |
| AC-AISVC-115 | - | - | - | 融合决策输出 |
| AC-AISVC-116 | - | - | - | 融合公式 |
| AC-AISVC-117 | - | - | - | 意图判定优先级 |
| AC-AISVC-118 | - | - | - | LLM Judge 触发条件 |
| AC-AISVC-119 | - | - | - | LLM Judge 执行 |
| AC-AISVC-120 | - | - | - | LLM Judge 禁用 |
| AC-AISVC-121 | - | - | - | 澄清触发条件 |
| AC-AISVC-122 | - | - | - | 路由追踪日志 |
| AC-AISVC-123 | /admin/monitoring/conversations/{id} | GET | getConversationDetail | 追踪日志查询 |
| AC-AISVC-124 | - | - | - | 多租户隔离 |
| AC-AISVC-125 | - | - | - | 性能约束 |
6. 配置项说明
6.1 融合配置
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
w_rule |
float | 0.5 | 规则匹配权重 |
w_semantic |
float | 0.3 | 语义匹配权重 |
w_llm |
float | 0.2 | LLM 仲裁权重 |
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 | 是否启用 LLM 仲裁 |
semantic_matcher_enabled |
bool | true | 是否启用语义匹配 |
6.2 性能配置
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
semantic_matcher_timeout_ms |
int | 100 | SemanticMatcher 超时（毫秒） |
llm_judge_timeout_ms |
int | 2000 | LlmJudge 超时（毫秒） |
semantic_top_k |
int | 3 | SemanticMatcher 返回候选数 |
7. 约束与待澄清
7.1 约束
- 现有规则引擎必须继续可用，作为混合路由的一路输入
/ai/chat对外响应语义（reply/confidence/shouldTransfer）不变- 全部新增逻辑必须 tenantId 隔离
- 禁止整体替换现有逻辑，必须采用增量改造
7.2 待澄清
- 意图向量索引是否需要独立的 Qdrant Collection，还是复用现有知识库 Collection？
- LlmJudge 的 Token 消耗是否需要单独计费统计？
- 融合配置是否需要支持租户级差异化配置？