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

315 lines
12 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/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 字段 |