8.5 KiB

Raw Permalink Blame History

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

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

当前回测暴露两个核心瓶颈：

关键词匹配 F1 仅 33.33% — 手工枚举关键词覆盖面极窄，多技能共享关键词导致歧义
回测只测路由层 — 没有验证路由后执行结果的质量，无法衡量真实智能化程度

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:

在 _build_real_components() 中构建 SemanticRouter：从 LLMGateway 获取 embedder，构建索引
将 semantic_router 传入 CostAwareRouter 构造函数
在 agentkit.yaml 中添加 semantic 配置段
回测结果中记录 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:

新增 TestSemanticRouting 测试类
测试场景：同义词查询、口语化表达、中英混合、技能描述相关查询
每个测试记录 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:

新增 OutputQualityObservation 数据类：query, expected_output, actual_output, quality_score(1-5), judge_reasoning
新增 evaluate_output_quality() 方法：使用 LLM-as-Judge 评估
L3 评估仅对 keyword_match 和 semantic_match 类别执行
报告增加"输出质量评估"章节

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:

选取 5 个核心技能，每个技能设计 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:

运行完整回测（含 SemanticRouter）
与启用前基准对比：执行模式准确率、技能路由F1、keyword_match F1
报告增加"SemanticRouter 效果对比"章节
报告增加"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	先用默认值，根据回测结果微调

8.5 KiB Raw Permalink Blame History Unescape Escape

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

Summary

Problem Frame

Requirements

Key Technical Decisions

KTD-1: SemanticRouter 阈值选择

KTD-2: L3 输出质量评估方法

KTD-3: L3 评估范围

Implementation Units

U1. 启用 SemanticRouter 并集成到回测

U2. 增加语义路由专项测试

U3. L3 输出质量评估框架

U4. L5 自适应能力测试

U5. 对比报告与基准更新

Scope Boundaries

In Scope

Out of Scope

Deferred to Follow-Up Work

Risks

8.5 KiB

Raw Permalink Blame History