第 15 章 质量评估体系¶
本章学习目标 - 深入理解 Agent 评估方法论（端到端 vs 分层/轨迹评估 vs 结果评估） - 掌握 TTD 的运行时评估（三级评估器）与治理评估（CI 校验 + 资产质量） - 理解 LLM-as-a-Judge 四维评估方法与 DeepEval/Ragas 集成 - 理解反馈闭环如何驱动系统改进 - 认清当前评估体系的工程权衡与改进方向
前置知识：第 4 章 Agent 编排、第 9 章 Semantic Plane 关联代码：
backend/app/agents/sub_agents/evaluators/、scripts/（CI 校验）
15.1 背景与动机¶
15.1.1 为什么 Agent 系统需要评估¶
Agent 系统的输出是非确定性的——同一个问题可能得到不同的 SQL、不同的图表、不同的洞察。没有评估就无法回答"系统到底好不好"、"这次改动是改进还是退步"。评估是 Agent 系统可迭代的基础——没有评估的优化是盲目的。
15.1.2 评估的两个维度¶
TTD 的评估分两个维度：
| 维度 | 时机 | 对象 | 方法 |
|---|---|---|---|
| 运行时评估 | 在线查询时 | 单次查询的检索/SQL/答案质量 | 三级评估器 |
| 治理评估 | 离线 CI/审批时 | 语义资产质量、系统回归 | CI 校验 + LLM-as-a-Judge + 基准 |
AI Agent 理论关联：Agent 评估方法论
Agent 评估有三种主流方法，理解它们的差异是设计评估体系的基础：
端到端评估（End-to-End Evaluation） - 方法：只看最终结果对不对（如生成的 SQL 执行结果是否匹配期望）。 - 优势：简单直接，贴近用户体验。 - 劣势：无法定位问题环节——结果错了不知道是检索、规划还是生成的错。 - 适用：快速评估整体效果，如 Spider/BIRD 基准的 execution accuracy。
分层评估（Hierarchical / Trajectory Evaluation） - 方法：评估 Agent 执行轨迹的每一步——检索准不准、规划对不对、生成好不好。 - 优势：能精确定位问题环节，指导针对性改进。 - 劣势：成本高（每步都要评估）、需定义每步的评估标准。 - 代表：AgentBench、Trajectory Evaluation。
结果评估（Outcome Evaluation） - 方法：用 LLM 或人工判断最终答案质量（不只对错，还有完整性、准确性、安全性）。 - 优势：灵活，能评估开放式任务。 - 劣势：LLM-as-a-Judge 本身有偏差、成本高、非确定。 - 代表：LLM-as-a-Judge、DeepEval、Ragas。
TTD 的三级评估器（retrieval/sql/answer）是分层评估的工程实现——分别评估检索、SQL、答案三个环节。LLM-as-a-Judge 是结果评估。两者互补：分层评估定位问题，结果评估判断整体质量。
诚实声明：评估基础设施已就绪但尚未产出系统化评估报告
TTD 的评估基础设施（三级评估器、EvaluationDataset/Task ORM、Admin API、DeepEval/Ragas 集成、反馈闭环）均已实现，但尚未产出系统化的评估报告。本章出现的所有指标阈值与目标值均为设计目标或经验设定，未经真实评估数据校准。我们选择诚实标注而非编造评估分数——这与项目"工程诚实性"的价值观一致。
当前评估覆盖的局限：
- 三级评估器仅在
deep_analysis_workflow路由启用，主路径（nl2sql_query）无运行时评估（因延迟敏感，见 15.2.1）。 - 离线基准仅在 H&M 单一数据集上验证（详见 附录 E），无跨 schema 回归基准。
- LLM-as-a-Judge 的评估者间信度（inter-rater reliability）尚未度量。
系统化评估的改进路线见 第 16 章（"评估归一化"与"公开基准回归"）。
15.2 设计原理¶
15.2.1 三级评估器（运行时分层评估）¶
| 评估器 | 评估对象 | 评估内容 | 触发条件 |
|---|---|---|---|
| Retrieval Evaluator | 检索结果 | 召回的覆盖度、相关性 | deep_analysis_workflow 路由 |
| SQL Evaluator | 生成 SQL | 正确性、性能、安全性 | 同上 |
| Answer Evaluator | 最终回答 | 完整性、准确性 | 同上 |
评估器设计
评估器为纯规则引擎（def 而非 async def），无 LLM/IO 调用，确保低延迟。仅在 deep_analysis_workflow 路由启用。低分可触发重试（Reflexion 范式）。
为什么只在 deep_analysis 启用？因为三级评估器有延迟成本，主路径（nl2sql_query）对延迟敏感。deep_analysis 是"质量优先于速度"的路由，适合做完整评估。
15.2.2 治理评估¶
| 评估对象 | 方法 | 详见 |
|---|---|---|
| 语义资产 YAML | pre-commit hooks + CI 4 脚本 | 第 13 章 |
| 资产质量字段 | quality_score + 认证生命周期 |
第 9 章 |
| 系统回归 | LLM-as-a-Judge + 离线基准 | 本章 |
| RAG 质量 | DeepEval + Ragas | 本章 |
15.2.3 反馈闭环¶
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#e8f0fe','primaryTextColor':'#202124','primaryBorderColor':'#1a73e8','lineColor':'#5f6368','secondaryColor':'#e0f2f1','tertiaryColor':'#f8f9fa'}}}%%
flowchart LR
USER["用户反馈<br/>like · dislike · 纠正答案"] --> ADMIN["Admin 审核反馈"]
ADMIN --> ACTION1["记忆纠正<br/>Correction Memory"]
ADMIN --> ACTION2["资产修订<br/>YAML 更新"]
ADMIN --> ACTION3["Few-Shot 审批<br/>Dynamic Cache"]
ACTION1 & ACTION2 & ACTION3 --> SYSTEM["系统改进<br/>Memory · Semantic Layer<br/>Few-Shot Pool"]
SYSTEM --> METRICS["评估指标变化<br/>SQL 正确率 ↑<br/>幻觉率 ↓"]
METRICS -.-> USER
classDef bpUser fill:#f8f9fa,stroke:#5f6368,stroke-width:2px,color:#202124
classDef bpProcess fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px,color:#202124
classDef bpData fill:#e0f2f1,stroke:#0d7377,stroke-width:2px,color:#202124
classDef bpSuccess fill:#e6f4ea,stroke:#1e8e3e,stroke-width:2px,color:#202124
classDef bpInfo fill:#f3e8fd,stroke:#9334e6,stroke-width:2px,color:#202124
class USER bpUser
class ADMIN bpProcess
class ACTION1,ACTION2,ACTION3 bpInfo
class SYSTEM bpData
class METRICS bpSuccess用户反馈是系统改进的重要信号源——负反馈经 Admin 审核后转化为 correction memory（第 7 章）或资产修订（第 9 章）或 few-shot 审批（第 7 章）。
15.3 实现详解¶
15.3.1 LLM-as-a-Judge 四维评估¶
| 维度 | 指标 | 目标 | 评估方法 |
|---|---|---|---|
| Retrieval | 召回率、相关性分数 | 覆盖关键资产 | 规则评估器（运行时）+ LLM 判断（离线） |
| SQL | 正确性、性能、安全性 | 语法对、成本低、安全 | 规则评估器（运行时）+ Ragas faithfulness |
| Answer | 完整性、准确性 | 回答了用户问题 | LLM-as-a-Judge（离线） |
| Safety | 越权、PII 泄露、注入 | 零安全事件 | 规则 + LLM 双重检查 |
15.3.2 DeepEval + Ragas 集成¶
| 工具 | 用途 | 关键指标 |
|---|---|---|
| DeepEval | LLM 评估框架，支持自定义指标与 pytest 集成 | answer_relevancy、faithfulness |
| Ragas | RAG 专项评估 | context_precision、context_recall、faithfulness、answer_relevancy |
Ragas 的核心指标：
- faithfulness：生成的答案是否忠于检索到的上下文（不幻觉）
- answer_relevancy：答案是否切题
- context_precision：检索的上下文是否相关
- context_recall：是否检索到了回答问题所需的全部上下文
15.3.3 评估任务系统¶
| 组件 | 说明 |
|---|---|
EvaluationDataset |
评估数据集（问题 + 期望结果） |
EvaluationTask |
评估任务 |
EvaluationTaskItem |
评估任务项（单条评测） |
通过 Admin API（/admin/evaluations/*）管理评估任务，支持回放（/admin/evaluation_replay/*）——对历史 turn 重新评估，量化系统改进效果。
评估数据集示例¶
以 H&M 数据集为例，一个 EvaluationDataset 条目的结构（问题 + 期望结果 + 路由 + schema 上下文）：
{
"dataset_id": "eval_hm_baseline_v1",
"name": "H&M 基线评估集 v1",
"domain": "hm_fashion",
"items": [
{
"question": "上月销量 Top 10 商品",
"expected": {
"route": "nl2sql_query",
"intent": "ranking",
"expected_tables": ["gold_hm.fact_transaction", "gold_hm.dim_article"],
"expected_sql_pattern": "COUNT.*GROUP BY.*ORDER BY.*DESC.*LIMIT 10",
"expected_metric": "transaction_count"
}
},
{
"question": "线上和线下的交易量分别是多少？",
"expected": {
"route": "nl2sql_query",
"intent": "comparison",
"expected_tables": ["gold_hm.fact_transaction"],
"expected_sql_pattern": "GROUP BY sales_channel_id",
"term_bindings": ["sales_channel_id"]
}
},
{
"question": "客户分群分析",
"expected": {
"route": "analytical_workflow",
"intent": "clustering",
"expected_tool": "clustering_tool"
}
}
]
}
每个 EvaluationTaskItem 的 expected 字段定义了该问题的期望路由、意图、涉及表、SQL 模式（正则）与术语绑定——评估器据此判断检索覆盖度、SQL 正确性与路由准确性。
15.3.4 评估分数解读指南¶
各维度指标的"好/需关注/需修复"阈值区间：
| 指标 | 好（≥） | 需关注 | 需修复（<） | 说明 |
|---|---|---|---|---|
| faithfulness | 0.85 | 0.70-0.85 | 0.70 | 答案忠于检索上下文的程度（不幻觉） |
| answer_relevancy | 0.80 | 0.65-0.80 | 0.65 | 答案切题程度 |
| context_precision | 0.80 | 0.60-0.80 | 0.60 | 检索上下文的相关比例 |
| context_recall | 0.85 | 0.70-0.85 | 0.70 | 是否检索到全部所需上下文 |
| SQL 执行准确率 | 0.90 | 0.75-0.90 | 0.75 | SQL 执行结果匹配期望的比例 |
| 路由准确率 | 0.95 | 0.85-0.95 | 0.85 | 路由决策匹配期望路由的比例 |
阈值均为经验设定
上述阈值区间为经验初始值，尚未用真实评估数据校准。"好/需关注/需修复"的边界应基于实际业务场景与用户期望调整。改进方向：积累足够评估样本后，用统计方法（如分位数）校准阈值（第 16 章）。
15.3.5 评估成本分析¶
LLM-as-a-Judge 评估的成本考量：
| 评估方式 | 单次成本（估算） | 延迟 | 适用场景 |
|---|---|---|---|
| 规则评估器（三级） | ~0 token | < 50ms | 运行时常态化（deep_analysis 路由） |
| LLM-as-a-Judge（单维度） | ~1-2K token | 1-3s | 离线评估，每条样本每维度一次 LLM 调用 |
| LLM-as-a-Judge（四维度） | ~4-8K token | 4-12s | 离线完整评估 |
| Ragas 四指标 | ~6-10K token | 5-15s | RAG 专项离线评估 |
规模化策略：对一个含 100 条样本的评估数据集，完整四维度 LLM-as-a-Judge 评估约消耗 400-800K token。建议：① 日常 CI 只跑规则评估器 + 抽样 LLM 评估（如 10%）；② 版本发布前跑完整 LLM 评估；③ 评估者间信度通过同一样本多次评估的方差度量。
成本为设计估算
上述 token 消耗为基于典型 prompt 长度的估算，未经实际测量。实际成本取决于评估 prompt 设计、上下文长度与模型定价。改进方向：接入 Langfuse 追踪实际评估 token 消耗，校准成本模型。
15.3.6 资产认证生命周期¶
资产 quality_score + lifecycle_status 字段驱动认证流程，高质资产进入 certified 状态优先检索。这是"用质量信号驱动检索优先级"的设计。
15.3.7 小规模 Pilot 评估数据¶
虽然系统化评估报告尚未产出，本节提供一份小规模手工 pilot——20 条 H&M 典型查询的人工评估结果，作为基线参考。
Pilot 数据的局限
以下为 20 条查询的手工评估，样本量极小，不可外推为系统整体准确率。其价值在于：(1) 提供一个可比较的基线起点；(2) 暴露典型失败模式；(3) 为系统化评估提供数据点校准。完整系统化评估见改进路线（第 16 章 16.8.1）。
Pilot 数据集¶
20 条查询覆盖 5 种路由，每条 4 条：
| 路由 | 查询数 | 难度分布 |
|---|---|---|
| nl2sql_query | 8 | 简单 4 / 中等 3 / 困难 1 |
| deep_analysis_workflow | 4 | 中等 2 / 困难 2 |
| analytical_workflow | 4 | 中等 2 / 困难 2 |
| kpi_lookup | 2 | 简单 2 |
| graph_reasoning | 2 | 简单 1 / 中等 1 |
Pilot 评估结果¶
| 指标 | 结果（20 条） | 说明 |
|---|---|---|
| 路由准确率 | 19/20 = 95% | 1 条 deep_analysis 被误路由为 nl2sql_query |
| SQL 语法正确率 | 19/20 = 95% | 1 条含 CTE 语法错误（PG 方言不兼容） |
| SQL 执行成功率 | 18/20 = 90% | 1 条语法错误 + 1 条超时（EXPLAIN 未拦截大扫描） |
| 结果正确率（人工判定） | 16/20 = 80% | 2 条结果部分正确（聚合粒度偏差）+ 2 条执行失败 |
| 修复循环触发率 | 3/20 = 15% | 3 条触发 corrective_retrieval，其中 2 条修复成功 |
| 平均端到端延迟 | nl2sql ~3.5s / deep ~8.2s | 设计目标范围内 |
典型失败案例¶
| # | 查询 | 失败类型 | 根因 | 改进方向 |
|---|---|---|---|---|
| 1 | "各品类的退货率趋势" | 路由错误 | 误判为 nl2sql（应为 deep_analysis） | 路由规则补充趋势+归因组合意图 |
| 2 | "对比线上线下客户的客单价" | SQL 方言 | CTE 语法在 pg_mooncake 不兼容 | 方言适配增强（16.4.1） |
| 3 | "过去三年每月销量" | 执行超时 | 全表扫描未走列存 | EXPLAIN 阈值调优 + 列存索引 |
15.3.8 评估数据集设计指南¶
如何构建一个高质量的 NL2SQL 评估集？以下是 TTD 的设计规范。
问题多样性维度¶
评估集应覆盖以下维度，避免单一模式过拟合：
| 维度 | 取值 | 示例 |
|---|---|---|
| 路由类型 | 7 种路由各覆盖 | nl2sql / deep_analysis / analytical / kpi / graph / clarification / off_topic |
| 意图 | ranking / trend / comparison / forecasting / anomaly / exploration | — |
| 难度 | 简单（单表）/ 中等（2 表 join）/ 困难（多表 + 子查询 + 窗口函数） | — |
| 术语覆盖 | 含明确术语 / 含口语化表达 / 含未登记术语 | "GMV" / "卖得最好的" / "客单价"（未登记） |
| 时间范围 | 绝对时间 / 相对时间 / 无时间约束 | "2020-08" / "上月" / "总量" |
| 聚合复杂度 | COUNT/SUM / GROUP BY / 窗口函数 / CTE | — |
| 边缘情况 | 空结果 / 歧义 / 越权 / 超时 | "查 CEO 的工资"（越权） |
期望结果标注规范¶
每条评估样本的 expected 字段应包含：
question: "上月销量 Top 10 商品"
expected:
route: nl2sql_query
intent: ranking
difficulty: easy
expected_tables:
- gold_hm.fact_transaction
- gold_hm.dim_article
term_bindings:
销量: met_hm_transaction_count
商品: dim_article
expected_sql_pattern: "COUNT.*GROUP BY.*ORDER BY.*DESC.*LIMIT 10"
expected_columns: [prod_name, sales_count]
expected_row_count: 10
notes: "术语'销量'应绑定 transaction_count，非 SUM(price)"
难度分级标准¶
| 难度 | 标准 | 占比建议 |
|---|---|---|
| 简单 | 单表 + 基础聚合（COUNT/SUM） | 30% |
| 中等 | 2 表 join + GROUP BY + 时间过滤 | 40% |
| 困难 | 多表 + 窗口函数/CTE + 复杂术语 + 修复循环 | 20% |
| 边缘 | 歧义/越权/空结果/超时 | 10% |
评估集维护
评估集应纳入 Git 版本控制（与语义资产同级），每次系统改进后回归。新增失败案例应补充进评估集，形成"失败 → 修复 → 回归"的闭环。目标评估集规模：100+ 条（当前 pilot 20 条）。
15.4 方案选型对比¶
15.4.1 评估框架对比¶
| 框架 | 类型 | 优势 | TTD 用法 |
|---|---|---|---|
| DeepEval | LLM 评估 | 自定义指标、pytest 集成 | |
| Ragas | RAG 评估 | faithfulness/relevancy 指标 | |
| AgentBench | Agent 基准 | 多任务端到端 | （可引入做回归） |
| LangSmith | LangChain 评估 | 轨迹追踪 + 评估 | （用 Langfuse 替代追踪） |
15.4.2 评估策略对比¶
| 策略 | 优势 | 劣势 | TTD 状态 |
|---|---|---|---|
| 纯规则评估 | 快、确定性 | 覆盖面窄 | 三级评估器 |
| LLM-as-a-Judge | 灵活、覆盖广 | 慢、贵、非确定 | 治理评估 |
| 人工评估 | 最准 | 慢、不可扩展 | 反馈审核 |
| 基准回归 | 可追踪 | 需维护基准 | 仅 H&M（附录 E） |
当前实现可改进之处
- 评估器纯规则，覆盖面窄：三级评估器是确定性规则，无法评估语义正确性（如"SQL 语法对但答非所问"）。改进：引入 LLM-as-a-Judge 作为运行时评估的补充（在 deep_analysis 路由），或用轻量模型做实时语义校验。
- 缺离线基准数据集：只在 H&M 单一数据集上验证（附录 E），无跨 schema 的回归基准。无法回答"改了 Reranker 后整体准确率变了吗"。改进：引入 Spider/BIRD 公开基准 + 自建业务基准，CI 中跑回归。
- 反馈未真正驱动优化：用户反馈经 Admin 审核后写入 correction memory 或修订资产，但无自动化机制把高频反馈转化为系统改进（如"某类查询频繁失败"应触发路由/资产调整）。改进：建立反馈分析看板，聚类高频问题，自动生成改进建议。
- 评估未常态化：三级评估器只在 deep_analysis 路由启用，主路径（nl2sql_query）无评估。改进：轻量评估常态化（如只跑 SQL 评估器），低分触发 Self-RAG 式自纠错。
改进方向
评估的演进方向是常态化 + 自动化驱动改进。短期：引入公开基准做回归、反馈聚类驱动优化。长期：评估器从纯规则升级为"规则 + 轻量 LLM"混合，在主路径常态化运行低成本的 SQL/结果校验，低分自动触发自纠错（Self-RAG/Corrective-RAG），形成"评估→纠错→改进"的自动闭环。
15.5 小结与延伸阅读¶
本章要点：
- 评估两维度：运行时（三级评估器，分层评估）+ 治理（CI 校验 + LLM-as-a-Judge，结果评估）。
- 三级评估器是分层评估的工程实现，定位问题环节；LLM-as-a-Judge 是结果评估，判断整体质量。
- LLM-as-a-Judge 四维：Retrieval / SQL / Answer / Safety。
- DeepEval + Ragas 做 RAG 专项评估（faithfulness/relevancy），评估任务系统支持回放。
- 反馈闭环：用户反馈 → Admin 审核 → 闭环动作（记忆/资产/few-shot）。
延伸阅读：
- AgentBench — arxiv.org/abs/2308.03688
- DeepEval — github.com/confident-ai/deepeval
- Ragas — github.com/explodinggradients/ragas
- LLM-as-a-Judge — arxiv.org/abs/2306.05685
- Spider 基准 — yale-lisp.github.io/text2sql
下一章：第 16 章 演进路线与改进方向——全书收尾，系统性梳理所有可改进点与演进路线，是动手贡献的入口。