205 lines
8.5 KiB
Markdown
205 lines
8.5 KiB
Markdown
# feat: SemanticRouter 启用与回测体系升级
|
||
|
||
```yaml
|
||
title: feat: SemanticRouter 启用与回测体系升级
|
||
status: superseded
|
||
superseded_by: "2026-06-16-005-refactor-routing-architecture-plan"
|
||
superseded_reason: "SimpleRouter 已替代 CostAwareRouter，不再需要 SemanticRouter 作为路由层组件。LLM 在 REACT agent loop 中看到完整工具描述后自主决策，无需 embedding 做意图路由。如未来工具数量 >50，可参考 Codex 的 tool_search（BM25）做工具发现。"
|
||
closed: 2026-06-16
|
||
```
|
||
|
||
## Summary
|
||
|
||
启用 Layer 1.5 SemanticRouter 提升路由召回率，并升级回测体系从"仅测路由层"扩展到"测路由+执行质量"，真正衡量 Agent 智能化程度。
|
||
|
||
## Problem Frame
|
||
|
||
当前回测暴露两个核心瓶颈：
|
||
1. **关键词匹配 F1 仅 33.33%** — 手工枚举关键词覆盖面极窄，多技能共享关键词导致歧义
|
||
2. **回测只测路由层** — 没有验证路由后执行结果的质量，无法衡量真实智能化程度
|
||
|
||
SemanticRouter 已完整实现（`src/agentkit/chat/semantic_router.py`），但配置未启用（`agentkit.yaml` 中 `router.semantic` 段不存在）。启用后，关键词未命中的查询可走向量相似度匹配，预期 F1 大幅提升。
|
||
|
||
## Requirements
|
||
|
||
- R1: 启用 SemanticRouter，使回测中关键词未命中的查询有语义路由兜底
|
||
- R2: 回测体系增加 L3 输出质量评估 — 路由后实际执行，评估输出与预期的语义相似度
|
||
- R3: 回测体系增加 L5 自适应能力测试 — 同一意图不同表达（正式/口语/中英混合）
|
||
- R4: 生成对比报告：SemanticRouter 启用前 vs 启用后
|
||
|
||
## Key Technical Decisions
|
||
|
||
### KTD-1: SemanticRouter 阈值选择
|
||
|
||
默认阈值 similarity_high=0.85 / similarity_low=0.6。回测中先使用默认值，根据结果微调。
|
||
|
||
理由：0.85 高阈值确保高置信度匹配的精确性，0.6 低阈值过滤噪声。这是业内常见配置。
|
||
|
||
### KTD-2: L3 输出质量评估方法
|
||
|
||
使用 LLM-as-Judge 方案：将路由后的执行输出与预期输出传给 LLM，让 LLM 评估语义相似度（1-5分）。
|
||
|
||
理由：BLEU/ROUGE 等字面匹配指标不适合评估 Agent 输出的语义质量。LLM-as-Judge 是业内主流方案（OpenAI、Anthropic 均采用）。
|
||
|
||
### KTD-3: L3 评估范围
|
||
|
||
仅对 keyword_match 和 semantic_match 类别的用例执行 L3 评估。DIRECT_CHAT 类别（问候/闲聊）不需要执行质量评估。
|
||
|
||
理由：DIRECT_CHAT 的输出质量主要取决于 LLM 本身，与路由无关。评估路由对执行质量的影响才是目标。
|
||
|
||
## Implementation Units
|
||
|
||
### U1. 启用 SemanticRouter 并集成到回测
|
||
|
||
**Goal:** 在回测中构建并启用 SemanticRouter，使 Layer 1.5 语义路由生效
|
||
|
||
**Requirements:** R1
|
||
|
||
**Dependencies:** 无
|
||
|
||
**Files:**
|
||
- `tests/e2e/test_capability_router_direct.py` — 构建 SemanticRouter 并传入 CostAwareRouter
|
||
- `agentkit.yaml` — 添加 `router.semantic.enabled: true` 配置
|
||
|
||
**Approach:**
|
||
1. 在 `_build_real_components()` 中构建 SemanticRouter：从 LLMGateway 获取 embedder，构建索引
|
||
2. 将 semantic_router 传入 CostAwareRouter 构造函数
|
||
3. 在 `agentkit.yaml` 中添加 semantic 配置段
|
||
4. 回测结果中记录 match_method 为 "semantic_high" / "semantic_medium" 的用例
|
||
|
||
**Test scenarios:**
|
||
- 运行回测，验证 SemanticRouter 成功构建索引（15个技能）
|
||
- 验证 match_method 包含 "semantic_high" 或 "semantic_medium" 的用例
|
||
- 验证关键词未命中的用例中，部分被 SemanticRouter 兜底匹配
|
||
|
||
**Verification:** 回测通过，keyword_match F1 提升，出现 semantic_match 类别
|
||
|
||
### U2. 增加语义路由专项测试
|
||
|
||
**Goal:** 验证 SemanticRouter 在各种查询模式下的表现
|
||
|
||
**Requirements:** R1
|
||
|
||
**Dependencies:** U1
|
||
|
||
**Files:**
|
||
- `tests/e2e/test_capability_router_direct.py` — 增加 semantic routing 测试类
|
||
|
||
**Approach:**
|
||
1. 新增 `TestSemanticRouting` 测试类
|
||
2. 测试场景：同义词查询、口语化表达、中英混合、技能描述相关查询
|
||
3. 每个测试记录 match_method 和 confidence
|
||
|
||
**Test scenarios:**
|
||
- "帮我看看代码有没有问题" → 匹配 code_reviewer（语义匹配）
|
||
- "市场怎么样" → 匹配 trend_agent 或 competitor_analyzer（语义匹配）
|
||
- "写一篇关于AI的文章" → 匹配 content_generator（语义匹配）
|
||
- "这个引用对不对" → 匹配 citation_detector（语义匹配）
|
||
|
||
**Verification:** 语义路由测试通过，match_method 包含 "semantic_*"
|
||
|
||
### U3. L3 输出质量评估框架
|
||
|
||
**Goal:** 构建输出质量评估框架，路由后实际执行并评估输出质量
|
||
|
||
**Requirements:** R2
|
||
|
||
**Dependencies:** U1
|
||
|
||
**Files:**
|
||
- `tests/e2e/capability_metrics.py` — 增加 OutputQualityObservation 和评估方法
|
||
- `tests/e2e/test_capability_router_direct.py` — 增加 L3 评估逻辑
|
||
|
||
**Approach:**
|
||
1. 新增 `OutputQualityObservation` 数据类：query, expected_output, actual_output, quality_score(1-5), judge_reasoning
|
||
2. 新增 `evaluate_output_quality()` 方法：使用 LLM-as-Judge 评估
|
||
3. L3 评估仅对 keyword_match 和 semantic_match 类别执行
|
||
4. 报告增加"输出质量评估"章节
|
||
|
||
**Test scenarios:**
|
||
- 路由到 code_reviewer 的查询，输出应包含代码审查相关内容
|
||
- 路由到 content_generator 的查询，输出应包含生成内容
|
||
- 路由失败的查询，不执行 L3 评估
|
||
|
||
**Verification:** 报告包含输出质量评分，平均分 > 3.0
|
||
|
||
### U4. L5 自适应能力测试
|
||
|
||
**Goal:** 测试同一意图不同表达的路由稳定性
|
||
|
||
**Requirements:** R3
|
||
|
||
**Dependencies:** U1
|
||
|
||
**Files:**
|
||
- `tests/e2e/benchmark_dataset.py` — 增加自适应测试用例
|
||
- `tests/e2e/test_capability_router_direct.py` — 增加自适应测试类
|
||
|
||
**Approach:**
|
||
1. 选取 5 个核心技能，每个技能设计 3 种表达变体：正式/口语/中英混合
|
||
2. 同一技能的 3 种表达应路由到同一技能
|
||
3. 计算自适应率：同一技能不同表达路由一致的比例
|
||
|
||
**Test scenarios:**
|
||
- code_reviewer: "审查代码" / "帮我看看代码" / "review this code"
|
||
- trend_agent: "分析趋势" / "最近行情怎么样" / "market trend analysis"
|
||
- content_generator: "生成内容" / "帮我写点东西" / "write an article"
|
||
- citation_detector: "检测引用" / "引用对不对" / "check citations"
|
||
- competitor_analyzer: "竞品分析" / "对手怎么样" / "competitor analysis"
|
||
|
||
**Verification:** 自适应率 > 60%（5个技能 x 3种表达 = 15个用例，至少9个路由一致）
|
||
|
||
### U5. 对比报告与基准更新
|
||
|
||
**Goal:** 生成 SemanticRouter 启用前后的对比报告，更新基准
|
||
|
||
**Requirements:** R4
|
||
|
||
**Dependencies:** U1, U2, U3, U4
|
||
|
||
**Files:**
|
||
- `tests/e2e/capability_metrics.py` — 增加对比报告生成
|
||
- `test-results/e2e/capability_report.txt` — 更新报告
|
||
|
||
**Approach:**
|
||
1. 运行完整回测（含 SemanticRouter）
|
||
2. 与启用前基准对比：执行模式准确率、技能路由F1、keyword_match F1
|
||
3. 报告增加"SemanticRouter 效果对比"章节
|
||
4. 报告增加"L3 输出质量"和"L5 自适应能力"章节
|
||
|
||
**Verification:** 报告包含前后对比数据，技能路由F1 > 80%
|
||
|
||
## Scope Boundaries
|
||
|
||
### In Scope
|
||
- 启用 SemanticRouter
|
||
- L3 输出质量评估（LLM-as-Judge）
|
||
- L5 自适应能力测试
|
||
- 对比报告生成
|
||
|
||
### Out of Scope
|
||
- L4 对话连贯性测试（多轮对话，需要会话管理改造）
|
||
- L6 压力边界测试（模糊/对抗输入，需要专门的对抗测试框架）
|
||
- 意图分类微调（需要标注数据和训练流程）
|
||
- 关键词自动扩充（从 examples 提取高频词）
|
||
|
||
### Deferred to Follow-Up Work
|
||
- 多轮对话回测框架
|
||
- 对抗性输入测试
|
||
- 意图分类微调流水线
|
||
- 关键词自动扩充工具
|
||
- **[待办] 提供 Embedding API Key** — 当前百炼 Coding Plan key (sk-sp-*) 不支持 embedding API，需要：
|
||
- 方案 A：在 DashScope 控制台单独开通 embedding 服务，获取标准 sk- 前缀 key
|
||
- 方案 B：配置本地 embedding 模型（BGE-large-zh-v1.5 via Xinference）
|
||
- 方案 C：使用其他支持 embedding 的 provider（智谱/火山等）
|
||
- 配置位置：agentkit.yaml → llm.providers 增加 embedding 专用 provider
|
||
- 预期效果：SemanticRouter 真正工作，口语化查询无需手动扩充关键词
|
||
|
||
## Risks
|
||
|
||
| Risk | Likelihood | Impact | Mitigation |
|
||
|------|-----------|--------|------------|
|
||
| Embedding API 不可用 | Medium | High | 回测跳过 SemanticRouter，降级到纯关键词路由 |
|
||
| LLM-as-Judge 评分不稳定 | Medium | Medium | 多次评估取平均，使用结构化评分 prompt |
|
||
| SemanticRouter 阈值需调优 | High | Low | 先用默认值，根据回测结果微调 |
|