fischer
/
fischer-agentkit
1
0
Fork 0
Code Issues Pull Requests Actions 87 Packages Projects Releases Wiki Activity
fischer-agentkit/docs/plans/2026-06-15-004-feat-semanti...

7.6 KiB
Raw Blame History

feat: SemanticRouter 启用与回测体系升级

title: feat: SemanticRouter 启用与回测体系升级
status: active
created: 2026-06-15
plan_id: "2026-06-15-004"

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

  • 多轮对话回测框架
  • 对抗性输入测试
  • 意图分类微调流水线
  • 关键词自动扩充工具

Risks

Risk Likelihood Impact Mitigation
Embedding API 不可用 Medium High 回测跳过 SemanticRouter，降级到纯关键词路由
LLM-as-Judge 评分不稳定 Medium Medium 多次评估取平均，使用结构化评分 prompt
SemanticRouter 阈值需调优 High Low 先用默认值，根据回测结果微调