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/requirements.md

213 lines
9.5 KiB
Markdown
Raw 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"
parent_spec: "spec/ai-service/requirements.md"
ac_range: "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](./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 置信度）
- [AC-AISVC-112] WHEN RuleMatcher 命中规则 THEN 系统 SHALL 输出匹配结果包含：
- `rule_id`：命中的规则 ID
- `match_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`（示例句列表）动态计算平均相似度
### 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 按以下优先级：
1. 若 RuleMatcher 命中且 `rule_score=1.0`，优先采用规则意图
2. 若 RuleMatcher 未命中但 SemanticMatcher 高置信（>semantic_threshold），采用语义意图
3. 若存在冲突或低置信，触发 LlmJudge 仲裁
4. 若三路均低置信，返回 `no_match`（回退默认 RAG）
### 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 消耗是否需要单独计费统计？
- 融合配置是否需要支持租户级差异化配置？