--- 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/design.md" --- # 意图识别混合路由优化 - Tasks（v0.8.0） ## 1. 任务拆分原则 - **原子性**：每个任务仅解决一个具体技术点或功能逻辑 - **可验证性**：任务完成后必须可通过单元测试、接口冒烟或契约校验 - **弱模型可执行**：任务描述清晰，不依赖 AI 猜测业务逻辑 - **AC 关联**：每个任务关联明确的验收标准 ID --- ## 2. 任务状态说明 - ⏳ 待处理 - 🔄 进行中 - ✅ 已完成 - ❌ 已取消 --- ## 3. 任务执行计划 ### Phase 17.1: 数据模型扩展 - [ ] T17.1 扩展 `IntentRule` 实体：新增 `intent_vector`（JSONB）、`semantic_examples`（JSONB）字段 `[AC-AISVC-114]` - 修改文件: `app/models/entities.py` - 新增字段定义与注释 - 数据库迁移: `alembic revision --autogenerate -m "add_intent_vector_fields"` - [ ] T17.2 创建 `FusionConfig` 配置模型：定义融合权重与阈值参数 `[AC-AISVC-116]` - 新增文件: `app/services/intent/models.py` - 定义 `FusionConfig` dataclass - [ ] T17.3 创建 `RouteTrace` 追踪模型：定义三路打分日志结构 `[AC-AISVC-122]` - 修改文件: `app/services/intent/models.py` - 定义 `RouteTrace`、`FusionResult` 等 dataclass - [ ] T17.4 扩展 `ChatMessage` 实体：新增 `route_trace`（JSONB）字段 `[AC-AISVC-123]` - 修改文件: `app/models/entities.py` - 数据库迁移: `alembic revision --autogenerate -m "add_route_trace_field"` --- ### Phase 17.2: RuleMatcher 改造 - [ ] T17.5 创建 `RuleMatchResult` 数据类：封装规则匹配结果（含 score） `[AC-AISVC-112]` - 修改文件: `app/services/intent/models.py` - 定义 `RuleMatchResult` dataclass - [ ] T17.6 改造 `IntentRouter` 为 `RuleMatcher`：增加 score 输出，保留 `match()` 向后兼容 `[AC-AISVC-112]` - 修改文件: `app/services/intent/router.py` - 重构现有匹配逻辑，封装为 `RuleMatcher` 类 - 输出 `RuleMatchResult` 而非 `IntentMatchResult` --- ### Phase 17.3: SemanticMatcher 实现 - [ ] T17.7 实现 `SemanticMatcher` 类：初始化方法，注入 EmbeddingProvider 和配置 `[AC-AISVC-113]` - 新增文件: `app/services/intent/semantic_matcher.py` - 定义 `SemanticMatcher` 类 - 实现 `__init__` 方法 - [ ] T17.8 实现 `SemanticMatcher.match()`：模式 A（预置向量）相似度计算 `[AC-AISVC-114]` - 修改文件: `app/services/intent/semantic_matcher.py` - 实现 `_calculate_similarity` 方法 - 实现 `_cosine_similarity` 方法 - [ ] T17.9 实现 `SemanticMatcher.match()`：模式 B（示例句动态计算）平均相似度 `[AC-AISVC-114]` - 修改文件: `app/services/intent/semantic_matcher.py` - 支持从 `semantic_examples` 动态计算向量 - [ ] T17.10 实现 `SemanticMatcher` 异常处理：Embedding/Qdrant 失败时跳过并记录原因 `[AC-AISVC-113]` - 修改文件: `app/services/intent/semantic_matcher.py` - 添加超时控制 - 添加异常捕获与日志记录 --- ### Phase 17.4: LlmJudge 实现 - [ ] T17.11 实现 `LlmJudge` 类：初始化方法，注入 LLMClient 和配置 `[AC-AISVC-119]` - 新增文件: `app/services/intent/llm_judge.py` - 定义 `LlmJudge` 类 - 定义 `JUDGE_PROMPT` 模板 - [ ] T17.12 实现 `LlmJudge.should_trigger()`：判断是否满足触发条件（冲突/灰区/多意图） `[AC-AISVC-118]` - 修改文件: `app/services/intent/llm_judge.py` - 实现三种触发条件判断 - [ ] T17.13 实现 `LlmJudge.judge()`：构建仲裁 Prompt，调用 LLM，解析结果 `[AC-AISVC-119]` - 修改文件: `app/services/intent/llm_judge.py` - 实现 `_build_candidates_text` 方法 - 实现 `_parse_response` 方法 - [ ] T17.14 实现 `LlmJudge` 异常处理：LLM 调用失败时回退到 SemanticMatcher `[AC-AISVC-119]` - 修改文件: `app/services/intent/llm_judge.py` - 添加超时控制 - 添加异常捕获与日志记录 --- ### Phase 17.5: FusionPolicy 实现 - [ ] T17.15 实现 `FusionPolicy` 类：初始化方法，加载配置 `[AC-AISVC-115]` - 新增文件: `app/services/intent/fusion_policy.py` - 定义 `FusionPolicy` 类 - 定义 `DECISION_PRIORITY` 常量 - [ ] T17.16 实现 `FusionPolicy.fuse()`：加权融合计算 `[AC-AISVC-116]` - 修改文件: `app/services/intent/fusion_policy.py` - 实现 `_calculate_weighted_confidence` 方法 - [ ] T17.17 实现 `FusionPolicy.fuse()`：决策优先级判定（规则优先→语义→LLM→无匹配） `[AC-AISVC-117]` - 修改文件: `app/services/intent/fusion_policy.py` - 实现优先级遍历与条件判断 - [ ] T17.18 实现 `FusionPolicy.fuse()`：澄清触发判定 `[AC-AISVC-121]` - 修改文件: `app/services/intent/fusion_policy.py` - 判断 `final_confidence < clarify_threshold` - 生成 `clarify_candidates` 列表 - [ ] T17.19 实现 `FusionPolicy.fuse()`：路由追踪日志生成 `[AC-AISVC-122]` - 修改文件: `app/services/intent/fusion_policy.py` - 构建 `RouteTrace` 对象 - 记录三路打分详情 --- ### Phase 17.6: IntentRouter 升级 - [ ] T17.20 升级 `IntentRouter`：注入 RuleMatcher、SemanticMatcher、LlmJudge、FusionPolicy `[AC-AISVC-111]` - 修改文件: `app/services/intent/router.py` - 修改 `__init__` 方法 - 支持依赖注入 - [ ] T17.21 实现 `IntentRouter.match_hybrid()`：并行执行 RuleMatcher + SemanticMatcher `[AC-AISVC-111]` - 修改文件: `app/services/intent/router.py` - 使用 `asyncio.gather` 并行执行 - [ ] T17.22 实现 `IntentRouter.match_hybrid()`：条件触发 LlmJudge `[AC-AISVC-118]` - 修改文件: `app/services/intent/router.py` - 调用 `LlmJudge.should_trigger()` - 条件执行 `LlmJudge.judge()` - [ ] T17.23 实现 `IntentRouter.match_hybrid()`：调用 FusionPolicy 返回融合结果 `[AC-AISVC-115]` - 修改文件: `app/services/intent/router.py` - 调用 `FusionPolicy.fuse()` - 返回 `FusionResult` --- ### Phase 17.7: Orchestrator 集成 - [ ] T17.24 修改 `Orchestrator._match_intent()`：调用 `match_hybrid()` 替代 `match()` `[AC-AISVC-111]` - 修改文件: `app/services/orchestrator.py` - 替换方法调用 - 处理 `FusionResult` 返回值 - [ ] T17.25 修改 `Orchestrator._match_intent()`：将 `route_trace` 写入 `GenerationContext` `[AC-AISVC-122]` - 修改文件: `app/services/orchestrator.py` - 扩展 `GenerationContext` 添加 `route_trace` 字段 - [ ] T17.26 修改 `Orchestrator._build_response()`：在响应 metadata 中包含 `route_trace` `[AC-AISVC-123]` - 修改文件: `app/services/orchestrator.py` - 将 `route_trace` 写入响应 metadata --- ### Phase 17.8: 配置与 API - [ ] T17.27 新增融合配置 API：`GET /admin/intent-rules/fusion-config` `[AC-AISVC-116]` - 修改文件: `app/api/admin/intent_rules.py` - 返回当前融合配置 - [ ] T17.28 新增融合配置 API：`PUT /admin/intent-rules/fusion-config` `[AC-AISVC-116]` - 修改文件: `app/api/admin/intent_rules.py` - 更新融合配置（支持热更新） - [ ] T17.29 扩展意图规则 API：支持 `intent_vector` 和 `semantic_examples` 字段的 CRUD `[AC-AISVC-114]` - 修改文件: `app/api/admin/intent_rules.py` - 修改 `IntentRuleCreate`、`IntentRuleUpdate` schema - 修改 CRUD 方法 - [ ] T17.30 新增意图向量生成 API：`POST /admin/intent-rules/{id}/generate-vector` `[AC-AISVC-114]` - 修改文件: `app/api/admin/intent_rules.py` - 调用 EmbeddingProvider 生成向量 - 更新规则的 `intent_vector` 字段 --- ### Phase 17.9: 监控与追踪 - [ ] T17.31 修改监控 API：`GET /admin/monitoring/conversations/{id}` 返回 `route_trace` `[AC-AISVC-123]` - 修改文件: `app/api/admin/monitoring.py` - 扩展响应 schema --- ### Phase 17.10: 测试与验证 - [ ] T17.32 编写 `SemanticMatcher` 单元测试：Mock Embedding/Qdrant `[AC-AISVC-113, AC-AISVC-114]` - 新增文件: `tests/test_semantic_matcher.py` - 测试正常匹配、跳过场景、异常处理 - [ ] T17.33 编写 `LlmJudge` 单元测试：Mock LLM 调用 `[AC-AISVC-118, AC-AISVC-119]` - 新增文件: `tests/test_llm_judge.py` - 测试触发条件、仲裁结果、异常处理 - [ ] T17.34 编写 `FusionPolicy` 单元测试：覆盖各种融合场景 `[AC-AISVC-115~AC-AISVC-117]` - 新增文件: `tests/test_fusion_policy.py` - 测试决策优先级、加权融合、澄清触发 - [ ] T17.35 编写 `IntentRouter.match_hybrid()` 集成测试：验证完整路由链路 `[AC-AISVC-111]` - 新增文件: `tests/test_intent_router_hybrid.py` - 测试并行执行、条件触发、融合决策 - [ ] T17.36 性能测试：验证 P95 延迟满足约束 `[AC-AISVC-125]` - 新增文件: `tests/perf/test_intent_latency.py` - 测试 RuleMatcher < 10ms - 测试 SemanticMatcher < 100ms - 测试 P95 总增量延迟 < 500ms（不含 LlmJudge） --- ## 4. 任务进度追踪 | Phase | 描述 | 任务数 | 状态 | |-------|------|--------|------| | Phase 17.1 | 数据模型扩展 | 4 | ⏳ 待处理 | | Phase 17.2 | RuleMatcher 改造 | 2 | ⏳ 待处理 | | Phase 17.3 | SemanticMatcher 实现 | 4 | ⏳ 待处理 | | Phase 17.4 | LlmJudge 实现 | 4 | ⏳ 待处理 | | Phase 17.5 | FusionPolicy 实现 | 5 | ⏳ 待处理 | | Phase 17.6 | IntentRouter 升级 | 4 | ⏳ 待处理 | | Phase 17.7 | Orchestrator 集成 | 3 | ⏳ 待处理 | | Phase 17.8 | 配置与 API | 4 | ⏳ 待处理 | | Phase 17.9 | 监控与追踪 | 1 | ⏳ 待处理 | | Phase 17.10 | 测试与验证 | 5 | ⏳ 待处理 | **总任务数: 36** --- ## 5. 依赖关系 ``` Phase 17.1 (数据模型) │ ├──→ Phase 17.2 (RuleMatcher) │ ├──→ Phase 17.3 (SemanticMatcher) │ └──→ Phase 17.4 (LlmJudge) │ └──→ Phase 17.5 (FusionPolicy) │ └──→ Phase 17.6 (IntentRouter 升级) │ └──→ Phase 17.7 (Orchestrator 集成) │ └──→ Phase 17.8 (配置与 API) │ └──→ Phase 17.9 (监控与追踪) │ └──→ Phase 17.10 (测试与验证) ``` --- ## 6. 文件变更汇总 ### 6.1 新增文件 | 文件路径 | 说明 | |----------|------| | `app/services/intent/models.py` | 数据模型定义 | | `app/services/intent/semantic_matcher.py` | 语义匹配器 | | `app/services/intent/llm_judge.py` | LLM 仲裁器 | | `app/services/intent/fusion_policy.py` | 融合决策策略 | | `tests/test_semantic_matcher.py` | 语义匹配单元测试 | | `tests/test_llm_judge.py` | LLM 仲裁单元测试 | | `tests/test_fusion_policy.py` | 融合决策单元测试 | | `tests/test_intent_router_hybrid.py` | 混合路由集成测试 | | `tests/perf/test_intent_latency.py` | 性能测试 | ### 6.2 修改文件 | 文件路径 | 变更说明 | |----------|----------| | `app/models/entities.py` | 扩展 IntentRule、ChatMessage 实体 | | `app/services/intent/router.py` | 新增 `match_hybrid()` 方法，封装 `RuleMatcher` | | `app/services/orchestrator.py` | Step 3 调用 `match_hybrid()` | | `app/api/admin/intent_rules.py` | 新增融合配置 API、向量生成 API | | `app/api/admin/monitoring.py` | 返回 `route_trace` 字段 | ### 6.3 数据库迁移 | 迁移文件 | 说明 | |----------|------| | `alembic/versions/xxx_add_intent_vector_fields.py` | 新增 intent_vector、semantic_examples 字段 | | `alembic/versions/xxx_add_route_trace_field.py` | 新增 route_trace 字段 |