AI Agent 工程实践教程 · 第 11 章

围绕 SQL 正确性、执行结果、用例集和指标，建立 Text-to-SQL 的评测闭环。

返回系列目录

第十一天：Text-to-SQL 评测体系建设

前面几天我们已经把 Text-to-SQL 主流程跑起来了。

用户输入一个自然语言问题，系统会经过：

问题路由
  ↓
业务识别和业务 Skill 加载
  ↓
指标检索和表结构检索
  ↓
SQL 生成
  ↓
SQL 安全校验和执行
  ↓
结果分析

这条链路跑通以后，系统已经从 Demo 进入了“可用”的阶段。

但真实项目里，“可用”还不够。我们还要继续回答几个更难的问题：

这次改 Prompt 以后，效果有没有变好？
这次改业务 Skill 以后，原来正确的问题有没有被改错？
这次新增表结构以后，模型会不会误选表？
这次澄清逻辑调整以后，模型是更谨慎了，还是更容易过度追问？
这次最终回答看起来差不多，语义上到底算不算正确？

这些问题不能靠感觉回答，也不能靠开发同学手动问两三个问题回答。

我们需要一套可以长期沉淀、重复执行、自动对比的机制。

这就是今天要建设的内容：Text-to-SQL 评测体系。

1. 为什么 Text-to-SQL 必须做评测

普通后台接口大多是确定性的。

固定输入
  ↓
固定代码逻辑
  ↓
固定输出

但 Text-to-SQL 不是这样。

Text-to-SQL 中间有大模型参与，模型会做很多判断：

例如用户问：

统计上个月订单状态的分类占比

这句话看起来很简单，但系统需要判断：

订单指的是支付订单还是预支付订单？
上个月用 created_at 还是 pay_success_time？
分类占比按 order_status 还是 status？
是否需要先澄清？
如果不澄清，应该选择哪张表？

所以评测不能只看：

SQL 能不能执行？

更应该看：

整条 Text-to-SQL 链路中的关键判断是否符合预期？

2. 当前项目的评测总览

当前项目的评测体系已经不再是“写一个 JSON 去比对 State”的简单版本，而是拆成了几层：

整体架构是：

现在的核心思想是：

样本只负责描述“要测什么”
断言负责描述“怎么判定”
评测任务负责“真实跑一遍”
评测结果负责“留下证据”

3. 从真实运行到评测样本

评测样本最好不要完全靠拍脑袋录入。

真实项目里，最有价值的样本通常来自这几类场景：

一条真实运行记录里有：

原始问题
最终 State
生成 SQL
执行 SQL
最终回答
每一步 graph 状态

如果人工发现这次结果有问题，比如：

应该查 order_payment，不应该查 prepay_order。

就可以把它加入评测样本，变成以后每次都能复跑的回归用例。

样本状态分为：

只有 ACTIVE 样本会进入评测任务。

4. 评测样本应该保存什么

一条评测样本不是简单保存一个问题。

它至少要回答四件事：

测什么问题？
属于哪个业务？
主要测哪段能力？
怎么判断通过？

当前样本主表是 text_to_sql_eval_question，重点字段如下：

这里要注意一个变化：

新版已经不再使用 expected_state_json 作为主要判断方式。

原因是 expected_state_json 虽然灵活，但对页面不友好，用户要手写 JSON，不适合长期维护。

新版改成了“表格化判断标准”：

期望 Key
判断方式
期望 Value
失败原因
是否必过
语义判断参考答案
关键要点
禁止内容
最低分

这样业务人员和测试人员不需要写 JSON，也能维护评测标准。

5. 评测目标和样本场景

不是所有样本都测端到端。

同一个问题可以用于验证不同能力：

样本场景用于标记这条样本属于哪类测试：

这些选项不建议写死在前端。

当前项目把它们放在动态配置里：

text.to.sql.eval.metadata

前端通过接口读取配置，用于渲染：

评测目标
样本场景
判断方式
失败类型

这样后续新增一个评测目标或失败类型，不需要改前端代码。

6. 判断标准：从 JSON 改成断言规则

新版评测判断标准使用独立表：

text_to_sql_eval_assertion

一条样本可以有多条判断标准。

例如问题：

统计上个月每天支付成功的订单数量

可以配置两条标准：

其中第一条是客观判断：

实际 state.used_tables 必须包含 order_payment。

第二条是主观判断：

最终回答不要求逐字一致，但要语义上覆盖参考答案和关键要点。

断言表关键字段：

支持的判断方式：

7. 客观判断：每条规则都要有结果

早期实现容易犯一个错误：

遇到第一条失败规则就直接返回。

这样虽然能判断这条样本失败，但排查体验很差。

因为用户看不到：

其他规则到底有没有过？
是只错了表？
还是业务、动作、SQL、回答都错了？

所以当前实现是：

所有判断标准都会执行
所有判断结果都会保存
最终样本是否通过，由必过规则决定

判定逻辑可以理解为：

for 每条断言规则:
    从 actual_state_json 里按 actual_key 取值
    按 operator 判断
    保存一条 assertion_result

如果存在 required = true 且未通过的规则:
    样本失败
    失败类型取第一条必过失败规则
否则:
    样本通过

这样做的好处是：

8. 主观判断：用大模型评估回答质量

有些结果不能用“完全相等”判断。

尤其是最终回答：

数据覆盖 9 个有订单的日期，累计支付成功订单 21 单。
6 月 25 日达到峰值 8 单，其余交易日集中在 1 至 3 单，整体呈零星分布态势。

这类回答只要意思对，就不应该要求 100% 字符串一致。

所以新增了 SEMANTIC 判断方式。

语义判断会把下面这些内容发给 Python 服务：

Python 服务调用大模型，返回：

{
  "passed": true,
  "score": 95,
  "reason": "实际回答准确涵盖了所有关键统计数据，与参考答案语义一致。",
  "coveredPoints": ["主要的数据要正确"],
  "missedPoints": [],
  "forbiddenHits": []
}

Java 后端会保存：

这里要注意：

SEMANTIC 不需要展示期望 Value。

因为它的标准不是一个简单值，而是：

参考答案 + 关键要点 + 禁止内容 + 最低分

9. 评测任务：异步批量运行正式样本

有了正式样本以后，就可以创建评测任务。

评测任务页面负责：

选择一批 ACTIVE 样本
  ↓
点击开始评测
  ↓
后端创建任务
  ↓
接口立即返回
  ↓
后台异步逐条运行完整 graph
  ↓
保存每条结果和每条断言结果
  ↓
汇总通过率和失败原因

为什么必须异步？

因为每条样本都是真实跑一遍 Text-to-SQL graph：

模型路由
业务 Skill
检索
SQL 生成
SQL 执行
结果分析
自动判定

如果评测任务有几十条样本，同步接口会等待很久，页面体验很差，也容易超时。

现在的设计是：

1. 点击“开始评测”。
2. 后端创建 text_to_sql_eval_run，状态为 RUNNING。
3. 接口立即返回任务 ID。
4. 后台线程逐条执行样本。
5. 前端轮询任务状态和结果列表。
6. 所有样本结束后刷新通过率、失败数和失败原因分布。

任务状态：

10. 评测运行记录为什么要标记 EVAL

评测不是模拟判断。

每条评测样本都会真实调用当前 Text-to-SQL 流程。

所以评测也会产生运行记录：

text_to_sql_run.source_type = EVAL

真实用户提问则是：

text_to_sql_run.source_type = USER

为什么要区分？

如果不区分，评测任务跑几十条样本，就会把运行记录页面刷满，影响日常排查真实用户问题。

当前设计是：

评测结果里保存 conversation_id。

如果某条样本失败，可以这样排查：

评测结果
  ↓ conversation_id
EVAL 运行记录
  ↓ run_id
运行步骤 State History

11. 评测结果：保存样本级结果

每条样本运行后，会保存一条：

text_to_sql_eval_run_result

它保存的是“这条样本这次整体跑得怎么样”。

关键字段：

这里的 actual_state_json 是统一后的实际 State。

也就是说，评测会尽量把 Python 服务返回值和 Java RouteRes 中常用字段整理成统一 Key，例如：

question_type
business_id
business_name
action
sql
executed_sql
used_tables
used_fields
missing_info
interrupted
final_answer

这样前端填写断言时就可以直接写：

business_id
used_tables
action
final_answer

不需要用户关心 Python 内部字段到底叫 sql_action 还是 Java 里映射成 action。

12. 断言结果：保存每条规则的证据

样本级结果只能告诉我们：

这条样本通过还是失败。

但排查时我们更想知道：

哪条规则过了？
哪条规则没过？
实际值是什么？
语义判断得了多少分？
大模型为什么给这个分？

所以新增：

text_to_sql_eval_run_assertion_result

关键字段：

页面上“规则”弹框会把两部分放在一起：

样本定义的规则
  +
本次运行的实际回答、实际值、评分、判断原因

这样看主观题时，不需要在“规则”和“详情”之间来回切。

13. 澄清样本怎么评测

Text-to-SQL 里有一类很重要的场景：需要澄清。

例如：

统计上个月订单状态占比

如果业务里同时有预支付订单和支付订单，这句话可能信息不足。

系统应该先追问：

请问要统计预支付订单，还是支付订单？

这种样本不能简单判定为失败。

它应该进入：

WAITING_CLARIFICATION

当前设计是：

1. 第一轮评测运行问题。
2. 如果 graph 返回需要澄清。
3. 当前结果标记为 CLARIFICATION_REQUIRED。
4. 任务状态变成 WAITING_CLARIFICATION。
5. 页面上对这条结果显示“补充澄清”。
6. 人工输入这条样本的补充回答。
7. 后端立即把该结果标记为 CLARIFICATION_RUNNING 并返回。
8. 后台异步用这条结果自己的 conversation_id 调用 continue。
9. 更新这条结果的实际 State、SQL、回答和断言结果。
10. 所有待澄清结果处理完后，任务变成 COMPLETED。

为什么要一条一条澄清？

因为每条样本都有自己的 graph thread：

样本 A -> conversationId A -> 补充回答 A -> continue A
样本 B -> conversationId B -> 补充回答 B -> continue B
样本 C -> conversationId C -> 补充回答 C -> continue C

不同样本缺的信息不同，会话上下文也不同。

所以不能把所有澄清答案一起发送。

14. 页面使用流程

当前后台主要有三个相关页面。

14.1 评测样本页面

评测样本页面负责维护样本。

常用操作：

这个页面回答的是：

哪些问题可以用来评测？
每个问题应该怎么判断？

14.2 评测任务页面

评测任务页面负责真正跑评测。

常用操作：

这个页面回答的是：

这次系统整体表现怎么样？
具体失败在哪里？

14.3 运行记录页面

运行记录页面默认看真实用户提问，也就是：

source_type = USER

如果要排查评测失败，可以筛选：

source_type = EVAL

然后根据评测结果里的 conversation_id 找到完整运行步骤。

15. 一个完整例子

假设我们有一条样本：

统计上个月每天支付成功的订单数量

这条样本期望使用支付订单表，并且最终回答要说清楚主要统计结果。

可以配置两条判断标准：

语义判断里再配置：

评测运行后，可能得到：

used_tables = ["order_payment"]
final_answer = "数据共覆盖 9 个有订单的日期，累计支付成功订单 21 单..."

断言结果：

样本通过。

如果实际用了 prepay_order：

used_tables = ["prepay_order"]

第一条规则失败：

failure_type = TABLE_SELECTION_ERROR
failure_reason = used_tables CONTAINS 期望 order_payment，实际 ["prepay_order"]

样本失败。

16. 课程练习

今天的练习建议按这个顺序做：

1. 在“数据分析”页面提出一个订单统计问题。
2. 查看“运行记录”，观察最终 State 和每步 State History。
3. 把这条运行记录加入“评测样本”。
4. 在“评测样本”页面整理： - 评测目标 - 样本场景 - 判断标准 - 判断说明
5. 添加一条客观规则，例如： - used_tables - 包含 - order_payment
6. 添加一条语义规则，例如： - final_answer - 语义判断 - 参考答案 - 关键要点 - 最低分
7. 把样本状态改成 ACTIVE。
8. 在“评测任务”页面新建任务，选择这条正式样本。
9. 开始评测，查看结果。
10. 打开“规则”弹框，查看每条规则的实际值、得分和原因。
11. 如果进入待澄清，补充澄清答案继续评测。
12. 到“运行记录”页面筛选 EVAL，查看评测产生的完整 graph 记录。

17. 小结

今天这节课的重点不是某张表，也不是某个按钮。

重点是建立一套 AI 应用的工程闭环：

真实问题
  ↓
运行记录
  ↓
人工反馈
  ↓
评测样本
  ↓
判断标准
  ↓
异步评测任务
  ↓
客观判断 + 语义判断
  ↓
断言结果明细
  ↓
澄清继续评测
  ↓
失败分析和回归优化

有了这套机制以后，每次改 Prompt、改 Skill、改表结构、改澄清策略，都可以通过评测任务验证。

Text-to-SQL 也就从：

能跑通

升级为：

能验证、能回归、能持续优化。