质量评估体系

本页范围

统一整理 TTD 系统的两类质量评估：运行时评估（per-query）和治理评估（per-asset）。 两者协同确保系统输出准确、相关、安全。

---

1. 概述

质量评估在 TTD 体系中运行于两个层面：

层面	时机	目标	工具
运行时评估 (Runtime)	每次用户查询	确保单次响应的准确性与完整性	LangGraph evaluator nodes
治理评估 (Governance)	CI/CD + 定期审计	确保语义资产（元数据）的合规性与质量	CI scripts + quality fields

graph LR
    A[用户提问] --> B[Agent Pipeline]
    B --> C{运行时评估}
    C -->|Pass| D[返回结果]
    C -->|Fail| E[Corrective Retrieval / Repair]
    E --> B

    F[元数据变更 PR] --> G{治理评估}
    G -->|Pass| H[Merge & Publish]
    G -->|Fail| I[PR Blocked]

---

2. 运行时评估节点

2.1 概览

系统在 deep_analysis_workflow 和 analytical_workflow 路径中嵌入三个 evaluator sub-agent 节点，对查询管线的中间产出做自动化质量检查：

graph TD
    DR[data_retrieval] --> RR[reranker]
    RR --> SG[sql_generator]
    SG --> GR[guardrails]
    GR --> SE[sql_executor]
    SE --> RP[result_processor]
    RP --> EX[sql_explainer]
    EX --> RE["🔍 retrieval_evaluator"]
    RE --> SQE["🔍 sql_evaluator"]
    SQE --> VIZ[visualization]
    VIZ --> INS[insights]
    INS --> AE["🔍 answer_evaluator"]
    AE --> END_NODE[END]

    style RE fill:#fff3cd
    style SQE fill:#fff3cd
    style AE fill:#fff3cd

2.2 retrieval_evaluator

职责

评估检索结果的充分性——我们是否找到了正确的 tables、columns、metrics？

源码位置: backend/app/agents/sub_agents/evaluators/retrieval_evaluator.py

评估逻辑:

检查项	阈值	行为
Table 命中数	≥ 1	低于阈值触发 corrective retrieval
Column 命中数	≥ 1	低于阈值追加 issues
Relevance score	≥ 0.55	检索结果平均相关性
Metric coverage	100% expected	检查期望指标是否被召回

输出格式:

{
    "retrieval_quality": {
        "pass": bool,           # 是否通过
        "reason": str,          # 通过/失败原因
        "issues": list[str],    # 具体问题列表
        "score": float,         # 0.0 ~ 1.0 综合分
    }
}

跳过条件: 非 SQL 路径（graph_reasoning、business_knowledge_qa、clarification_required）不执行检索评估。

2.3 sql_evaluator

职责

评估生成 SQL 的质量——SQL 是否正确回答了用户的问题？

源码位置: backend/app/agents/sub_agents/evaluators/sql_evaluator.py

评估维度:

检查项	说明
执行成功	SQL 是否无错误执行
非空结果	查询返回行数 > 0（warning 级别）
维度覆盖	结果列是否包含期望的维度字段
聚合对齐	度量列与 metric_candidates 的匹配度

输出格式:

{
    "sql_quality": {
        "pass": bool,
        "issues": list[str],
        "row_count": int,
        "column_match_ratio": float,
    }
}

2.4 answer_evaluator

职责

评估最终答案的质量——响应是否完整、准确、基于数据 grounded？

源码位置: backend/app/agents/sub_agents/evaluators/answer_evaluator.py

评估维度:

检查项	说明
执行结果存在	SQL 路径必须有 execution_result
非空结果集	结果行数 > 0
可视化生成	若 routing plan 含 visualization_agent 则必须产出
业务上下文锚定	sql_business_context 中的 tables 非空

输出格式:

{
    "answer_quality": {
        "pass": bool,
        "issues": list[str],
        "grounding_check": bool,  # 数据锚定
        "completeness": float,    # 0.0 ~ 1.0
    }
}

2.5 Evaluator 触发条件

deep_analysis_workflowanalytical_workflow

planner → data_retrieval → reranker → sql_generator → guardrails
  → sql_executor → result_processor → sql_explainer
  → retrieval_evaluator → sql_evaluator
  → visualization → insights → answer_evaluator → END

data_retrieval → reranker → sql_generator → guardrails
  → sql_executor → result_processor → sql_explainer
  → analytical_agent → visualization → insights
  → suggest_followup_agent → END

Note

analytical_workflow 中 evaluator 以内嵌检查方式运行，不单独暴露为节点。

---

3. 语义资产质量门控

3.1 CI 校验脚本

四个校验脚本构成语义层的硬门禁，在 PR 合入前必须全部通过：

#	脚本	功能	实现
1	validate_all_yaml.py	JSON Schema v7 合规性	逐文件对 8 个 schema 做 jsonschema 校验
2	validate_sql_definitions.py	SQL 语法可解析	使用 sqlparse 对 metric 定义中的 SQL 做 parse
3	validate_cross_layer_refs.py	跨层引用完整性	检查 bound_assets、bound_terms 引用目标存在
4	check_version_bump.py	SemVer 递增合规	比对 PR 分支 version > base 分支 version

执行方式:

# 单独执行
task sp:validate           # 运行全部 4 个校验

# 细粒度
task sp:validate:yaml      # 仅 schema 校验
task sp:validate:sql       # 仅 SQL 语法
task sp:validate:refs      # 仅跨层引用
task sp:check:version      # 仅版本递增

3.2 资产内嵌质量字段

除 CI 门禁外，资产自身携带质量元数据：

table_assetbusiness_termmetric_asset

quality_score: 85          # 0-100，数据质量综合评分
certification_status: certified  # draft → reviewed → certified → deprecated

confidence_score: 0.92     # 术语定义置信度
lifecycle_status: active   # draft → active → deprecated → archived

certification_status: certified
quality_notes: "经过 3 轮 SME 审核"

3.3 认证生命周期

stateDiagram-v2
    [*] --> draft : 新建
    draft --> reviewed : Data Steward 审核
    reviewed --> certified : Governance Lead 批准
    certified --> deprecated : 标记废弃
    deprecated --> [*] : 归档删除
    reviewed --> draft : 打回修改

状态	对 LLM 的影响
draft	不参与检索，不暴露给 Agent
reviewed	可检索但标注"未认证"
certified	完全可用
deprecated	检索时降权，附带 deprecation notice

---

4. LLM-as-a-Judge 框架

4.1 评估维度

系统采用 LLM-as-a-Judge 方法，从四个维度做自动化评估：

Retrieval Quality（检索质量）

指标	定义	计算方式
Context Relevance	检索到的上下文与问题的相关程度	LLM 评分 0-1
Asset Coverage	回答所需的资产是否全部被检索	期望集 ∩ 实际集 / 期望集
Precision	检索结果中有多少是有用的	有用 chunks / 总 chunks
Recall	所有相关内容是否被检索	被检索的相关 / 全部相关

SQL Quality（SQL 质量）

指标	定义	计算方式
Syntax Correctness	SQL 是否能无错执行	执行成功率
Semantic Correctness	SQL 逻辑是否匹配问题意图	LLM 评判 + 人工标注
Performance	查询效率	EXPLAIN cost / 实际耗时
Safety	无注入、无越权	Guardrails 检查

Answer Quality（答案质量）

指标	定义	计算方式
Completeness	是否回答了问题的所有方面	LLM 维度检查
Accuracy	答案与数据是否一致	交叉验证 execution_result
Faithfulness	答案是否基于检索到的事实	Ragas faithfulness
Answer Relevancy	答案与原始问题的相关度	Ragas answer_relevancy

Safety（安全性）

指标	定义	计算方式
PII Leakage	是否在输出中暴露了 PII 字段	规则匹配 + LLM 检测
Unauthorized Access	是否访问了超出用户权限的表	ABAC policy 校验
Injection	是否存在 SQL / Prompt injection	Guardrails 检查

4.2 评估工具

本项目集成两套评估框架：

DeepEvalRagas

# backend/pyproject.toml
"deepeval>=0.21.73"

用途: 通用 LLM 评估指标，支持自定义 metric、批量测试

from deepeval import evaluate
from deepeval.metrics import AnswerRelevancyMetric, FaithfulnessMetric

metric = FaithfulnessMetric(threshold=0.9)
evaluate(test_cases, metrics=[metric])

# backend/pyproject.toml
"ragas>=0.2.6"

用途: RAG 专用评估（faithfulness, answer relevancy, context precision）

from ragas import evaluate
from ragas.metrics import faithfulness, answer_relevancy, context_precision

results = evaluate(dataset, metrics=[faithfulness, answer_relevancy, context_precision])

4.3 评估流程

sequenceDiagram
    participant Admin as 管理员
    participant API as Backend API
    participant Agent as Agent Pipeline
    participant Judge as LLM Judge

    Admin->>API: 创建评估任务 (dataset_id)
    API->>Agent: 批量执行 test questions
    Agent->>API: 返回结果 (SQL + answer + context)
    API->>Judge: 送入评估框架
    Judge->>API: 返回评分 (per dimension)
    API->>Admin: 展示评估报告

---

5. 评估任务系统

5.1 数据模型

系统提供完整的评估任务管理功能（Admin Panel）：

erDiagram
    EvaluationDataset ||--o{ EvaluationTask : "has"
    EvaluationTask ||--o{ EvaluationTaskItem : "contains"

    EvaluationDataset {
        uuid id PK
        string name
        jsonb questions "测试问题集"
        timestamp created_at
    }
    EvaluationTask {
        uuid id PK
        string name
        uuid dataset_id FK
        string status "pending/running/completed"
        jsonb summary "评估汇总"
        timestamp created_at
    }
    EvaluationTaskItem {
        uuid id PK
        uuid task_id FK
        string question "原始问题"
        string generated_sql
        jsonb execution_result
        jsonb scores "各维度评分"
        string status "pending/passed/failed"
    }

5.2 API 端点

Method	Path	功能
POST	/api/v1/admin/evaluation/tasks	创建评估任务
GET	/api/v1/admin/evaluation/tasks	列表查询（分页）
GET	/api/v1/admin/evaluation/tasks/{id}	任务详情
GET	/api/v1/admin/evaluation/tasks/{id}/items	任务项列表
POST	/api/v1/admin/evaluation/datasets	创建测试数据集
GET	/api/v1/admin/evaluation/datasets	列表数据集

5.3 使用流程

# 1. 准备测试数据集
POST /api/v1/admin/evaluation/datasets
{
  "name": "hm_fashion_基础问法集_v2",
  "questions": [
    {"question": "上个月销量最高的商品是什么？", "expected_sql": "..."},
    {"question": "复购率超过 30% 的客户有多少？", "expected_sql": "..."}
  ]
}

# 2. 创建并执行评估任务
POST /api/v1/admin/evaluation/tasks
{
  "name": "v3.2 模型升级后回归测试",
  "dataset_id": "<dataset-uuid>"
}

# 3. 查看评估结果
GET /api/v1/admin/evaluation/tasks/{task_id}/items

5.4 版本对比

评估任务支持跨版本对比，用于模型升级、Prompt 变更、资产更新前后的回归验证：

场景	对比维度
模型升级	GPT-4o → Claude Sonnet 4 评分变化
Prompt 迭代	v2.1 → v2.2 的 SQL accuracy
资产变更	新增 business_rule 后的 retrieval recall

---

6. 反馈循环

6.1 用户反馈机制

用户在每次 Agent 响应后可提交结构化反馈：

# FeedbackRequest schema
{
    "session_id": "uuid",
    "turn_id": "uuid",
    "rating": "like" | "dislike",          # 简单评价
    "comment": "可选文字说明",
    "correction_sql": "SELECT ...",         # 用户修正的 SQL（可选）
    "feedback_dimensions": {               # 细粒度维度评价
        "retrieval_quality": 4,            # 1-5
        "sql_correctness": 3,
        "answer_completeness": 5,
        "response_speed": 4
    }
}

6.2 存储与查询

反馈数据持久化到 ttd.ttd_feedback 表：

CREATE TABLE ttd.ttd_feedback (
    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    session_id    UUID NOT NULL,
    turn_id       UUID NOT NULL,
    user_id       VARCHAR(128) NOT NULL,
    rating        VARCHAR(16) NOT NULL,      -- like / dislike
    comment       TEXT,
    correction_sql TEXT,
    feedback_dimensions JSONB,
    created_at    TIMESTAMPTZ DEFAULT NOW()
);

6.3 Admin 审核面板

管理员可通过 Admin API 查看和分析反馈：

Method	Path	功能
GET	/api/v1/admin/feedbacks	分页查看反馈
GET	/api/v1/admin/feedbacks/stats	统计面板（正负比、维度分布）

6.4 反馈闭环应用

graph TD
    A[用户反馈] --> B{反馈分类}
    B -->|correction_sql 存在| C[写入 Correction Memory + Few-shot 候选]
    B -->|术语误解| D[更新 Term Disambiguation]
    B -->|检索缺失| E[补充 Business Context]
    B -->|rating=like| F[写入 Profile Memory 强化偏好]

    C --> G[Data Steward 审核]
    D --> G
    E --> G
    F --> MF[MemoryFormationService.process_feedback]
    G --> H[合入 semantic-plane]

反馈类型	闭环动作
提供了 correction_sql	写入 Correction Memory（高置信度），同时候选加入 few_shots/，经审核后正式纳入
标注术语误解	触发 term_relationships/ 消歧规则补充
标注检索缺失	检查 business_contexts/ 是否遗漏场景
Like（正向）	通过 MemoryFormationService 写入 Profile Memory，增强同类问题的路由稳定性

记忆有效性评估

记忆系统的贡献可通过 evaluation replay pipeline 进行 memory-on vs memory-off 对比实验， 衡量澄清减少率、SQL 执行成功率、评估器通过率等关键指标。

---

7. 推荐指标

7.1 核心指标与目标

维度	指标	目标值	监控方式
Retrieval	Context Precision	> 0.8	Ragas 评估
Retrieval	Context Recall	> 0.7	Ragas 评估
SQL	Execution Success Rate	> 0.9	运行时统计
SQL	Semantic Correctness	> 0.85	LLM Judge + 人工抽检
Answer	Faithfulness	> 0.9	Ragas / DeepEval
Answer	Answer Relevancy	> 0.85	Ragas / DeepEval
Safety	PII Leak Rate	0	Guardrails + 审计日志
Latency	P95 Response Time	< 15s	Backend metrics

7.2 资产质量指标

维度	指标	目标值
Schema 合规	YAML 校验通过率	100%
引用完整性	跨层引用有效率	100%
SQL 可解析	Metric SQL 语法通过率	100%
版本合规	SemVer 递增通过率	100%
认证覆盖	certified 资产占比	> 80%
双语完整	zh/en 字段成对率	100%

7.3 运维指标

维度	指标	目标值
路由准确	正确路由占比	> 0.9
澄清率	clarification_required 占比	< 15%
空结果率	返回 0 行结果占比	< 10%
重试率	Corrective retrieval 触发占比	< 20%
用户满意	Like / (Like + Dislike)	> 0.8

---

8. 运维实践

8.1 发布前检查清单

每次版本发布前建议执行：

• 运行 task sp:validate 确保语义资产门禁全通过
• 使用标准测试数据集创建评估任务，对比基线
• 抽样检查高频 query 的 route 与 SQL 输出
• 确认 P95 latency 未明显退化
• 审查 PII 审计日志是否有异常

8.2 日常监控

频率	动作
实时	监控 status=error 的 turn 占比
每日	回顾 clarification_required 与 rejected 占比
每周	审核负面反馈，提取改进点
每月	对高风险域做回归问法集验证

8.3 告警规则

推荐告警阈值

指标	告警条件	级别
执行失败率	> 20% (5min 窗口)	Critical
P95 延迟	> 30s	Warning
空结果率	> 30% (1h 窗口)	Warning
PII 泄漏	> 0	Critical

---

9. 持续改进路线

阶段	内容	状态
✅ Phase 1	运行时 evaluator 节点 + CI 脚本门禁	已实现
✅ Phase 2	用户反馈收集 + 评估任务系统	已实现
🔄 Phase 3	Ragas + DeepEval 集成批量评估	进行中
📋 Phase 4	自动反馈闭环（Few-shot 自动更新）	规划中
📋 Phase 5	A/B Testing 框架（Prompt/Model 对比）	规划中