瑶池Data Agent实战：基于BIRD-CRITIC的Text-to-SQL性能突破与可解释设计

在数据库和自然语言处理这个交叉领域摸爬滚打几年后，我愈发觉得一件事：让大模型直接输出一段能跑的 SQL 并不难，难的是让它在复杂的业务语境下，知道自己查得对不对、错在哪里、要不要回头重来。这也是为什么当团队决定把“瑶池 Data Agent”这个内部代号的项目从想法变成产品时，我们最先盯上的不是模型参数量，而是“自纠错+可解释”的完整链路。项目后来同时在两件事上有了结果：在 BIRD-CRITIC 这类公开的 Text-to-SQL 评测榜单上拿到了有竞争力的名次，把性能指标做到了第一梯队；同时在真实用户手里的体验，也从“能问答”进步到“敢信任”。

这里说的 Data Agent，不是一个简单的 NL2SQL 工具，而是一个能自己规划、执行、反思并回应用户的数据分析代理。它解决的是业务人员明明有数据权限，却不会写 SQL、不了解表结构、不熟悉指标口径的问题。如果你正在做 Text-to-SQL、智能数据分析、企业知识库问答，或者只是好奇“大模型做数据分析到底能不能落地”，这篇文章都值得往下看。我会把项目从评测到顶会演示这一路上的架构选择、性能优化和体验设计，按实操视角拆开讲。

1. 先从“性能”说起：BIRD-CRITIC 到底是什么，为什么难

1.1 榜单的“含金量”：为什么大家都盯着这个评测

BIRD-CRITIC 这个名字，业内听起来可能有点门槛，但拆开看并不复杂。它来自一整套跨领域的 Text-to-SQL 评测体系，覆盖了金融、医疗、教育、体育、购物、地理等大量行业数据库，每个问题都要求模型把一句自然语言翻译成可执行、结果正确的 SQL。和很多只算“生成是否命中”的评测不同，BIRD-CRITIC 额外引入了一个关键环节：系统不仅要给 SQL，还要能够自我批判、定位错误并修正。换句话说，它考的不是一次性的运气，而是“发现问题后能不能自救”的能力。

这恰恰是很多系统从论文走向产品时最要命的地方。第一跳准确率不错，但一旦执行报错、结果为空、数值明显异常，大多数方案就只能把错误原样抛给用户。用户看到的是“查询失败”或者一个心里觉得不对的数字，却没有路径让系统自己修正。BIRD-CRITIC 把这个短板放大了，所以它近两年成了 Text-to-SQL 方向绕不开的标尺。

评测时主要看两个硬指标：

• Execution Accuracy（EX）：生成 SQL 执行结果与标准答案完全一致的比例。
• Valid Efficiency Score（VES）：在结果正确的前提下，还要考虑执行代价和效率，防止模型为了正确写出全表扫描这种低效查询。

如果你只优化 EX 而忽略 VES，很容易得到一个“答案对但慢到没法用”的系统。放在真实业务里，就是报表跑了几分钟还没出来，体验直接归零。

1.2 瑶池 Data Agent 的立项目标：不是为了刷榜

团队最开始给瑶池 Data Agent 定的目标很朴素：把数据分析师从“接需求、写 SQL、查数、解释数据”的重复劳动里解放出来。但做一个真正的产品，光有目标不够，还需要一个可以量化的突破口。于是我们选了 BIRD-CRITIC 作为性能度量衡，同时把“用户愿不愿意把业务判断交给它”作为体验度量衡。

这两条线不是并列关系，而是互相支撑的。性能不够，用户在问题稍微绕一点的时候就得不到答案；体验不好，哪怕准确率再高，业务人员也会选择继续用 Excel。瑶池 Data Agent 的立项关键词是“双突破”：一是让公开评测数字能打，二是让真实交互闭环能用的。这两件事在后续开发中经常打架，但恰恰是这种张力，逼着我们做了很多更务实的设计。

举个具体例子。做评测优化时，我们希望模型尽可能多地尝试不同 SQL 写法；但做体验时，用户最烦的就是等了半天看系统反复“思考”。这两个目标最终促使我们设计了一套“受控的反思机制”：模型可以在内部迭代，但每次迭代都必须有明确依据，不能靠瞎试。这个机制后来成了项目能够同时兼顾榜单成绩和用户口碑的核心原因。

2. 架构设计：Data Agent 不是“一个大模型加 SQL 提示词”

2.1 从 Pipeline 到 Agent：为什么传统方案会卡死

早期做自然语言转 SQL，主流方案是 Pipeline：先做 schema linking，选出相关表字段，再生成 SQL，最后执行。这个流程看似清晰，实际使用中却非常脆。问题出在它是一条单向链路，前面的错误不会在后面被纠正，只会一路放大。

我习惯把传统 Pipeline 比作“不开调试器写代码”。你写完一个函数，直接交给测试环境跑一遍，如果结果不对，你不会看运行时报错，不会追踪中间变量，而是从头重新生成一遍整个函数。可现实是，大多数错误都出在局部：表 join 关系选错了、条件值类型不对、字段单位没换算。这些局部错误需要的是“定位-修正-验证”，而不是推倒重来。

瑶池 Data Agent 从第一天起就走 Agent 路线。它把任务拆成循环：规划、行动、观察、反思，然后再规划。模型可以先生成一个执行计划，调用工具去数据库里看 metadata、执行 SQL、拿到真实结果，再根据结果判断这还是不是用户想要的答案。这套循环让系统第一次拥有了“看执行反馈”的能力。

你可能会说，这不就是 ReAct 模式吗？确实，底层逻辑类似，但真正难的不是套一个框架，而是为数据分析这个特殊场景设计每一步的观察粒度。我们不需要 Agent 在那里泛泛推理，需要它看到报错码、看到行数、看到值的分布，然后基于这些结构化反馈做下一步决策。

2.2 瑶池 Data Agent 的核心模块拆分

瑶池 Data Agent 的逻辑结构可以拆成四个模块：查询规划器、语义增强上下文管理器、工具执行器、Critic 反思器。每个模块都不复杂，但组合在一起，才让系统有了接近真实数据分析师的思考方式。

查询规划器负责把用户问题拆成可执行的步骤。比如用户问“华东区今年 Q2 毛利率为什么比 Q1 低”，规划器不会直接写 SQL，而是先拆：先确认年度和季度定义，再明确毛利率口径，然后定位收入、成本相关表，最后计算并生成解释。这一步把一个大模型最难一次性完成的任务，变成了几个相对简单的子任务。

语义增强上下文管理器是我们的重点投入方向。数据库 schema 只是骨架，字段注释、枚举值、业务词典、同义映射、历史查询记录，才是真正的血肉。我们把这一层做成一个动态的上下文包裹：模型看到的不只是一个表名列表，而是带业务含义的解释，例如“sales_amount 单位是万元，2019 年以前某些地区未接入”。这种信息能从源头上避免大量“模型把金额单位搞混”的问题。

工具执行器负责安全地访问数据。它不是简单执行 SQL，而是包含只读校验、查询超时、结果行数上限、成本预估等约束。再智能的 Agent，如果没有执行边界，都不可能在真实企业环境里落地。我们在这层还加了一个“预执行预览”能力：对高风险查询先跑一个 LIMIT 10，让模型确认数据长什么样，再决定是否全量执行。

Critic 反思器则是 BIRD-CRITIC 测试中的关键模块。它接收 SQL、执行结果、报错信息、用户原始问题，输出三个判断：结果是否合理、如果不合理可能错在哪一步、下一步应该改什么。这个模块不需要每次都启动，但一旦触发，它必须给出可追溯的理由，而不是简单说“我重试一次”。

对应关系可以看下表：

2.3 关键权衡：为什么用“少 Agent 化”而不是多智能体狂欢

这两年多智能体框架很火，一上来就是规划 Agent、写码 Agent、测试 Agent、解释 Agent 各来一个。但我们在瑶池 Data Agent 里刻意做了收敛，核心只有一个主 Agent，加上若干工具和内部的 Critic 模块，没有把决策权分散给多个 LLM Agent。原因很现实：多智能体之间的上下文传递是有损的，数据分析场景又特别依赖对业务口径的一致理解。一条用户问题在两个 Agent 之间转手一次，细节就可能丢一分。

我见过不少团队在一个任务里塞了五六个 Agent，最终效果并没有比单 Agent 高，反而延迟翻了几倍，成本更是没法看。数据分析场景有个特点：错误往往不是出在“不会推理”，而是出在“没有看到关键信息”。这种情况下，与其增加 Agent 数量，不如把每个 Agent 的上下文质量做厚。瑶池 Data Agent 选择“单主 Agent + 工具 + Critic”的模式，好处是可控、可解释、可调试，也方便我们在 bad case 分析时一眼看到整个决策链路。

当然，少 Agent 化不等于不做分工。主 Agent 负责规划，Critic 负责验证，工具执行器负责跑数，这本身就是一种更轻量、更稳定的分工。重点是不要让多个模型互相猜测对方的意图，而是通过明确协议协作。这个选择在后续顶着榜单压力迭代时，被证明是极其正确的：我们可以很轻松地追踪一次失败到底是因为规划错了、上下文缺知识，还是 Critic 误判，而不是在复杂的 Agent 网格里反复查日志。

3. 性能突破的实操细节：我们如何把内部准确率从 70 分推到 90 分以上

3.1 评测环境与指标口径：先让数字可复现

做评测优化第一件要做的事，不是调模型，而是让数字可复现。很多人拿着公开榜单代码直接跑，数据库版本、SQLite/PostgreSQL 兼容层、依赖包版本、评测脚本分支稍有不同，结果就会飘。我们刚开始也吃过这个亏，同一份代码上午跑是 78，下午跑就变成 74，后来排查发现是某个依赖库自动升级了。

所以瑶池 Data Agent 这边专门建立了一套容器化评测镜像，把数据集、数据库引擎、Python 依赖、评测脚本全部固定住。每次改动代码，都在这套镜像里从零重建，跑三次取中位数。别嫌麻烦，这个动作至少帮我们避开了 20% 的无效优化，否则你根本不知道自己是在改进模型还是改进测试噪声。

指标口径也要提前对齐。BIRD-CRITIC 的 EX 要求执行结果精确匹配，VES 则涉及执行成本计算，不同实现方式会得出不同结果。我们统一采用官方脚本的约定，中间不做任何自定义“修正”。这一条看起来死板，但能保证最后对外说数字时底气足，也是我们后来能在顶会现场放真实评测日志的前提。

评测配置里有两个参数值得特别注意：最大执行时间和最大返回行数。设计得不好，很容易让模型钻空子。比如某个查询很慢，如果超时设置过长，VES 会被拉低；如果超时设置过短，正确的复杂查询会被误杀。我们没有一味追求宽松，而是参照真实业务系统的容忍底线，把单条查询超时控制在 20 秒以内，超过就触发 Critic 改写，改写后再超时则放弃。这种做法不一定适合所有团队，但至少能让评测结果映射到真实可用性。

3.2 从失败样本反推优化：三类高频错误

只看总分数没有意义，我们做的是把每个失败 case 过一遍，标记错误出现的阶段。瑶池 Data Agent 早期 iter 跑完，我们抽了两百条失败样本，发现高频问题集中在三类：表连接关系选错、数值条件错误、同义表达匹配不上。

第一类表连接关系选错，典型表现是模型选择了可以通过两个表直接 join 的路径，但因为忽略业务上的多对多关系，导致结果翻倍。这类错误的根因是 schema 信息太薄，模型不知道哪张表是事实表、哪张是维度表。我们的解法是在语义增强上下文里显式标注表之间的基数关系，并给常见 join 路径打上业务标签，比如“订单表 join 订单明细表，应该用 order_id，且是一对多”。

第二类数值条件错误，最典型的是百分比和绝对值的混淆。用户问“退款率环比变化”，模型可能直接把退款金额做加减，而正确口径应该是退款金额占支付金额的比例差值。这块不能靠提示词硬压，我们做的是在业务词典里维护“指标-计算口径”映射，并在规划阶段就让模型先查看指标定义，再进入 SQL 生成。

第三类同义表达匹配失败，也是业务落地最常见的摩擦点。用户说的是“流水”，表里叫“交易额”；用户说“退货”，表里叫“逆向订单”。唯一的解法不是让模型猜，而是把同义词表做成可维护的资产。前期靠人工录入，后期从历史查询和用户反馈里增量抽取，再注入上下文。

下表总结了这三类问题和我们的应对策略：

3.3 让 Critic 真正起作用的三板斧

Critic 模块听起来高大上，但如果只是让模型“你检查一下刚才的 SQL 对不对”，它很快就会退化成形式主义：模型会回答“我觉得没问题”，然后把错误结论原样输出。想让 Critic 有效，必须给它足够有说服力的观察数据。这里我给三个被验证有效的实操方法。

第一，把数据库报错转成结构化信息。原始报错“near ‘group’: syntax error”对模型来说太抽象。我们会在工具执行器层把它解析为“你的 SQL 在 ORDER BY 子句附近存在语法错误，请检查聚合字段是否出现在 GROUP BY 中”，同时附上错误位置和更建议的写法。这相当于给模型配了一个翻译官，而不是让它面对一堆乱码。

第二，引入结果合理性检查。这个要靠知识，不能靠模型硬猜。我们在 Critic 里内置了一些轻量规则，比如：结果行数为零时，检查是否条件过严；查询结果跨时间相比变化超过 10 倍时，怀疑是否忘记过滤时间；某指标返回了负数但业务上不可能是负数，则触发解释机制。模型在收到这些提示后，比单纯面对空结果更容易找到问题。

第三，控制反思轮数和置信度。我们实验下来，放弃“无限反思”的设定，默认最多迭代两轮。每轮 Critic 给出的修订方案都带一个置信度，如果置信度低于 0.6，就保留上一轮结果，不再强行修改。很多 bad case 来自“过度修正”，模型本来是对的，却被自己改错。加上这个阈值后，整体准确率反而提升了。

这三板斧用下来，Critic 才真正发挥了作用。它在 BIRD-CRITIC 评测里的贡献不是让一条 SQL 从无到有，而是让那些“差一点就对了”的查询有机会被挽回。伪代码大致是这样：

for step in range(max_steps): plan = agent.plan(question, context) sql = agent.translate(plan) result, error = executor.run(sql) verdict = critic.verify(question, sql, result, error) if verdict.confidence >= threshold: break context = context.apply_revision(verdict.suggestion)

3.4 评测以外的收益：成本曲线的意外惊喜

性能优化做到后面，我们意外发现成本也在下降。最初模型遇到复杂查询会反复试错，每次试错都是一次完整 LLM 调用，Token 消耗非常高。引入 Critic 和更精细的上下文之后，一次正确的生成率明显提升，不必要的重试少了，Token 总消耗降低了接近四成。

这个结果非常符合直觉：模型在高质量上下文里更少犯错，而少犯错就是少烧钱。很多人一谈优化就想到减小模型、上缓存，却忽略了“第一次就把 SQL 写对”才是最大的成本杠杆。我们在评测日志里拉过一个对比：同样 100 条测试问题，优化前平均每问题调用 3.2 次生成；优化后降到 1.6 次。这个数据说明，好的 Agent 设计带来的不只是准确率，还有单位成本效率的提升。

VES 也在同步变好，因为写入上下文里的“查询计划”会提醒模型优先走索引、避免不必要的子查询和大表全扫。性能优化从侧面推动了可解释性和效率的平衡，这让我对“指标会互相打架”这件事有了新看法：只要优化的方向是“让系统更像一个谨慎的数据分析师”，各项指标往往能同向增长。

4. 体验设计：从“能用”到“好用”的差距

4.1 面向业务用户，Data Agent 应该长什么样

业务用户看一个数据 Agent，第一印象绝不是“它生成了多正确的 SQL”，而是“它有没有在正确回答我的问题”。如果界面只有一个聊天框加一段 SQL，用户根本不知道怎么验证对错，提问一次失败一次，信任感很快就会耗尽。

我们给瑶池 Data Agent 设计的交互单元叫“分析会话”，而不是“对话”。每一轮问答都分成几个明显的区段：问题理解区、查询计划区、执行过程区、结果区。默认情况下，业务用户只需要看结果区和一句“为什么是这个数字”，但每个区都可以展开，看到完整 SQL、参数、执行时间和数据快照。这样既照顾了不懂 SQL 的人，也给了懂数据的人一个审查入口。

更重要的是，结果区不能只有表格。我们会生成一段自然语言解读，明确写出“你问的是华东区上半年毛利率，按订单流水表计算，Q2 比 Q1 下降了 1.2 个百分点，主要原因是总成本上升”。用户不必自己去看数字，但想核对时又随时能找到原始查询。这种“结果可追溯 + 解读可理解”的设计，是 Data Agent 体验的地基。

4.2 自然语言与“受控交互”结合：主动澄清比猜更稳妥

一开始我们犯过一个天真错误：以为自然语言交互就是让用户随便问，什么问题都能答。结果用户问“各产品线利润情况怎么样”，模型就开始猜时间范围、猜利润口径、猜是否包含未上市产品，猜错率高到没法接受。后来我们加入了主动澄清与默认值机制，体验立刻发生了质变。

具体做法是：意图识别先把用户问题分成“有明确指标的查询”和“缺少筛选条件的查询”，再通过槽位识别判断缺什么。如果发现用户没说时间范围，系统会追问：“你是指 2024 年全年吗？还是最近一个完整季度？” 而不是默默瞎猜。如果发现指标有歧义，比如“利润”，系统会给出选项中“毛利率、净利率、毛利额”。这看起来多了两轮对话，但实际上减少了大量返工，也帮助用户建立了对系统的信任。

受控交互的另一个好处是可纠偏。用户可能把一个内部术语说错，比如把“已发货订单”叫成“成交订单”。系统在问题理解区会主动展示：“我将‘成交订单’理解为‘已发货订单’（状态为 shipped），是否继续？” 这个确认步骤看起来不聪明，但非常实用。真实业务里术语歧义无处不在，与其让模型事后纠正，不如在提问阶段就把理解摆到台面上。

4.3 反馈闭环：一键纠错，重新规划

无论系统多努力，总会有答错的时候。真正拉开体验差距的，是出错之后怎么办。瑶池 Data Agent 在结果区放了一组反馈按钮：结果不对、报错了、不符合预期、我想换个维度。用户点一下，系统会把反馈塞回上下文，重新进入规划和执行循环。

关键点在于，这个重跑不是简单把原问题再发一次，而是触发 Critic 对旧 SQL 做差异分析。比如用户反馈“华东区的数字不对”，Critic 会优先检查区域过滤条件是否映射到 region_code，而不是把整条 SQL 推倒重写。我们还让用户可以在反馈时高亮某个具体数字，系统会锁定对应数据行，检查这个数值是从哪个字段来的、有没有精度截断、要不要做四舍五入。这个过程极大地提高了一次修正率。

我印象最深的一个真实场景，是用户问“退款单量”时系统一开始查的是当前有效的退款单，漏掉了已经关闭的退款单。用户点了一次“结果不对”，Agent 通过反馈回看，发现退款单表里有个 status 字段被我们错误地塞进了 WHERE 条件，于是自动把过滤条件移除，重新统计后给出了正确答案。用户没有写一行 SQL，却完成了一次“发现问题到修正问题”的闭环，这就是 Data Agent 该有的样子。

4.4 延迟与成本平衡：流式输出和局部刷新

数据分析查询往往需要几秒甚至十几秒才能返回，用户很容易在等待中失去耐心。我们的办法是让等待过程变得可见、可理解。Agent 在开始时先输出“正在拆解问题”，然后是“正在确认指标口径”，接着是“正在执行 SQL”，最后是“正在检查结果”。每一步都用流式文字更新，用户能感知到系统在工作，而不是卡死了。

这套体验设计还有一个副产品：我们可以对长时间任务做局部刷新。比如查询已经执行完毕，但结果解读还在生成，界面可以先展示表格数据，再异步刷新下方的文字说明，用户不必等到最终完整 JSON 返回。整体感觉就是系统“边说边做”，比一句话不说等十几秒舒服得多。

成本透明也被我们做进了体验。当系统预估一条查询要访问大量行、可能需要较长时间时，会先告诉用户“这条查询会扫描近一年的明细，大概需要 15 秒，是否继续？”。如果估算成本超过阈值，还会建议用户拆成按月查询。这种“把选择权交给用户”的设计，不仅降低了系统压力，也让业务人员理解了为什么有些问题要等。

5. 从榜单到顶会：把项目讲出去的几个思考

5.1 顶会演示的工程准备：别让现场变成翻车现场

项目数据在 BIRD-CRITIC 榜单上站稳脚跟之后，我们收到一个国际数据库方向顶会的展示邀请。兴奋归兴奋，准备工作远比想象中琐碎。顶会 Demo 最忌现场跑一个还没稳定的环境，所以我们内部定了三条铁律：录屏优先、离线可用、数据脱敏。

录屏优先不是偷懒，而是保底。现场网络、数据库服务、大模型接口都可能出问题，任何环节挂了都很尴尬。我们提前把核心场景录制成一段三分钟视频，用真实的评测日志和界面操作演示。万一现场环境无法支撑，至少可以让评审看到完整交互流程。同时，我们把 Demo 环境全部容器化，保证体验集群可以离线启动，不依赖外部 API。

数据脱敏是一条安全红线。项目是拿内部业务数据库做样例的，直接展示就泄露了真实表结构和数据分布。我们后来自己构造了一套模拟业务数据库，结构和真实情况相似，但所有数字都是随机生成的。这样既能演示系统的 Schema 理解能力，也不会带来数据合规风险。这也提醒我：Agent 演示最重要的不是“秀真实数据”，而是“秀系统如何处理问题”。

5.2 踩过的坑和避坑清单

这个项目一路走来，踩过的坑足够写一份清单。挑几个最典型、也最容易被后来者重复踩的放在这里。

第一个坑是评测环境不一致导致的结果漂移。我们有过一次“代码没改，分数降了四个点”的诡异经历，最后定位到是容器镜像里的数据库从某个小版本自动升级了，索引行为发生变化。解决方式是全部锁定版本，并把“干净重建+跑三遍取中位数”写进 CI 流程。

第二个坑是 Critic 过度修正。早期我们把反思轮数设成无限，模型经常把正确的 SQL 改错，越改越远。后来加了一个非常简单的规则：如果 Critic 认为修改的置信度低于 0.6，或者修改后 SQL 的预估执行成本大幅上升，就保持原结果。这个止损机制直接让 EX 回升了两个多点。

第三个坑是只盯着 EX，忽视 VES。有一版模型准确率确实很高，但生成的 SQL 大量使用嵌套子查询，执行时间飙升。真实用户只要体验一次这种慢查询，就不会再用第二次。后来我们才把 VES 当作一等指标，并在工具执行器里加入重写低效查询的模块。

第四个坑是“理想化用户问题”，以为用户会清晰完整地说出自己的需求。事实上，业务用户经常只说半句话。我们最初没有主动澄清，导致大量查询在错误假设上跑完，结果自然不对。后来加入追问和默认值机制之后，一次正确率明显提升，用户投诉也少了很多。

5.3 给后来者的建议：什么样的 Data Agent 值得做

如果你现在也想做一个 Data Agent，我的建议是先别急着奔着“什么都能答”去。最值得做的切入点是某个特定业务域里的高频重复问题，比如零售运营分析、财务指标解释或者客服工单统计。把一个域做深，把业务口径、同义词、表关系沉淀好，再考虑跨域泛化。这个“先窄后宽”的策略，远远好过第一天就想做一个通用产品。

另外，把评测工程当作一等公民来建设。很多团队只关注模型架构，不关注评测脚本、数据版本、日志回放，结果优化全靠感觉。我们这套项目里，功夫最深的恰恰是那套可复现评测和 bad case 分析工具。没有它，BIRD-CRITIC 的分数和顶会 Demo 里那些有理有据的案例，都不可能稳定输出。

还有一条容易被低估的建议：不要在初期过度投入多智能体。先把单 Agent 的规划、执行和反思链路跑通，跑出一批 bad case，再决定是否要引入额外的 Agent。Data Agent 的护城河不在 Agent 数量，而在业务语义资产的积累和对失败样本的响应速度。这条经验在瑶池 Data Agent 上被反复验证，我认为同样适用于绝大多数同类项目。

带这个项目走到现在，我最深的体会是：Data Agent 的性能突破，本质上是围绕失败样本做精细运营的结果；而体验上限，则由用户是否愿意把业务判断交给它决定。BIRD-CRITIC 教会我们怎样在技术上自我批判，顶会则提醒我们，任何亮眼的数字最终都要落到一个日常问题里的可解释性上。如果你也在做类似方向，我建议先别急着堆模型，找一个业务分析师，把过去三个月最难答的一百个问题整理出来，从它们开始搭建你的 Critic 和反馈闭环，这比任何榜单参数都更接近体验的本质。