12 KiB

Raw Permalink Blame History

feature_id

iteration_id

title

status

version

created_at

inputs

AISVC

v0.8.0-intent-hybrid-routing

意图识别混合路由优化 - 任务清单

draft

0.8.0

2026-03-08

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 字段

12 KiB Raw Permalink Blame History Unescape Escape