评估、优化与 Agent 化落地

• Execution Accuracy 与 Exact Match 定义
• 两者的差异
• 为何执行准确率更贴近业务

Exact Match 比较生成 SQL 与标准 SQL 是否字符串完全一致，过于严格，因为同一语义可有多种等价写法（不同别名、不同实现），导致误判。Execution Accuracy 则把生成 SQL 与标准 SQL 都执行，比较结果集是否一致，只要结果正确即算对。执行准确率更贴近业务，是因为业务关心的是"查到的数据对不对"，而非"SQL 写法是否和标准答案相同"；同时它能容忍合法的多样化实现，反映真实能力。因此业界普遍以执行准确率作为主要指标，Exact Match 仅作辅助参考。

指标要与业务目标对齐。执行准确率以"结果正确"为评判标准，天然契合用户诉求；而 Exact Match 的过度严格会掩盖等价解，导致低估模型能力。

• 评估集采样
• 标准答案标注
• 判定口径制定

自建评估集应以真实查询日志为基础采样，保证覆盖真实业务分布：按业务域、查询复杂度、表单复杂度分层采样，纳入真实的多轮、口径、时区等场景，避免只采简单查询。标注标准答案时，由熟悉业务的数据分析师或 SQL 专家为每个问题标注标准 SQL 与期望结果，并记录口径（如金额是否含税、时间范围）。判定口径需明确"等价"的定义：数值等价（聚合结果一致即可，容忍精度差异）、语义等价（结果集一致，容忍 SQL 写法差异），并约定行序、空值处理等边界。判定口径要写成文档，供标注者与自动化工具统一执行。

评估集质量决定评估可信度。真实采样 + 专家标注 + 明确判定口径，能让评估集代表真实业务、结果可复现，是控制上线风险的关键。

• Bad case 分类
• 错误类型识别
• 驱动 Schema 与示例优化

Bad case 回流把线上错误分类，以便针对性优化。常见分类包括：Schema 选错（表/字段选择错误）、JOIN 错误（连接条件臆造或错误）、过滤遗漏（漏掉必要过滤条件）、方言错误（用了目标方言不支持的语法）、聚合/口径错误（聚合方式或口径不对）。分类后，每类错误对应不同的优化手段：Schema 选错则改进 Schema 描述与字段注释、加强 Schema Linking；JOIN 错误则补充表间关系与连接路径示例；过滤遗漏则补充过滤模式示例；方言错误则强化方言语法约束与方言示例。通过把典型 bad case 转成 Few-shot 示例或修正 Schema 描述，形成"错误→优化→回归"的闭环。

Bad case 回流的价值在于把"错误"变成"优化信号"。分类让优化方向明确，示例与 Schema 描述随错误类型迭代，是持续提升正确率的核心机制。

• NL2SQL Agent 化的编排
• Agent 化的价值
• Agent 化的成本与评估

NL2SQL Agent 化把单一"生成"过程拆成多步可编排的 Agent：先澄清查询意图（必要时追问）、再做 Schema 选择、生成 SQL、执行、验证结果、必要时修正重试。其价值在于：每步可独立控制与审计，能在复杂问题、多轮、需要纠错时展现灵活性，正确率通常高于单步直接生成，尤其适合复杂与边界场景。成本则包括：多步调用带来的更高延迟与 Token 消耗、更复杂的执行链与错误处理、以及更高的工程实现难度。评估时应同时看正确率收益与成本增量（延迟、成本、成功率），用"达到相同正确率所需的成本"或"正确率-成本曲线"来判断 Agent 化是否值得，并针对简单查询保留单步路径以控制成本。

Agent 化是"用更多步骤换更高正确率与灵活性"。评估要权衡正确率、延迟与成本，通常采用"简单查询走单步、复杂查询走 Agent"的分级策略，兼顾效果与成本。

• NL2SQL 与指标平台的结合
• 指标口径与维度字典
• 避免口径打架

在 BI 场景，NL2SQL 若直接查明细表，容易与指标平台的定义"口径打架"（如一处用"支付口径"另一处用"下单口径"）。避免的方式是把指标平台作为权威口径来源：把指标定义（指标名→计算逻辑、口径、维度）与维度字典注入 NL2SQL 的 Schema 或术语表，让模型优先使用已定义的指标口径，而不是自行从明细表推算。当用户问到平台已定义的指标时，直接引用该指标口径；对未定义的指标，则按规则生成并明确标注口径。这样 NL2SQL 与指标平台共用一套口径，避免数值不一致。

"口径打架"源于口径定义不统一。通过与指标平台绑定、以平台口径为权威，NL2SQL 与 BI 显示一致，避免"同一指标两个数字"的信任危机。

• SQL 结果到图表生成
• 图表类型选择与指标维度映射
• 自动图表误选校验

SQL 结果驱动图表生成时，需从结果集的维度与度量中推断图表类型：维度数量少、含时间序列时用折线图；单一维度对比时用柱状图；维度占比时用饼图；双指标相关性时用散点图。同时把指标字段映射到图表的 Y 轴/数值、维度字段映射到 X 轴/分类，结合查询意图选择合适图表。自动图表误选需要校验：根据结果集的维度个数、指标类型、行数、是否含时间字段，校验所选图表是否合理（如单行数据不该用饼图、字段过多不宜用柱状图），并在不确定时提示用户选择或提供备选图表。也可让 LLM 说明"为什么选这个图表"，供用户核对。

图表生成的关键是"基于数据特征选择类型"，而非拍脑袋。校验能拦截明显误选（如数据维度与图表不匹配），提升可视化准确性。

• 参数化单元测试
• 各查询模式正确率验证
• 回归自动化

生成 SQL 的单元测试可在固定表结构上，用参数化用例覆盖不同查询模式：单表查询、多表 JOIN、聚合、分组、子查询、窗口函数、时间过滤、分页、不同复杂度的组合。参数化是指同一模式的用例通过不同参数（不同过滤值、不同维度组合）批量生成，验证模型在该模式下的泛化正确率。测试执行时把生成 SQL 在固定测试库上执行并与标准答案比对（Execution Accuracy）。回归自动化通过 CI/CD 集成：Schema 描述、示例集、模型版本或 Prompt 变更时，自动触发全量参数化用例跑回归，输出各模式正确率并与基线对比，正确率退化即拦截上线。

参数化单元测试把"验证"从手工、样本性变成系统化、可覆盖不同模式，配合 CI 自动回归，能在变更时快速暴露某个查询模式的能力退化。

• 模型类型对比维度
• 自有评估集对比方法
• 正确率、延迟与成本权衡

模型选择需在自有评估集上对比多个维度：正确率（用 Execution Accuracy 在自建评估集上度量）、延迟（单次生成的响应时间）、成本（Token 单价与调用量，含重试成本）。对比方法是在同一评估集、同一 Schema 与示例配置下，分别跑通用旗舰、代码模型与专用 SQL 模型，得到各自的正确率-延迟-成本三项指标。通常专用 SQL 模型在正确率上可能更优或持平、成本更低，但通用旗舰在复杂推理与多轮上可能更强；代码模型在 SQL 语法上表现好。最终选择需结合业务对正确率、延迟、成本的优先级，可用"正确率/成本"或"正确率-延迟"权衡曲线做决策，并考虑是否需要 Agent 化（多步）来弥补。

模型选择不能只看单一指标，要在自有评估集上量化正确率、延迟、成本三者。不同模型各有优势，应结合业务场景与预算做综合权衡，必要时混用。

• 主动追问 vs 默认兜底
• 模糊问题的处理
• 交互设计取舍

面对模糊问题（如"销售情况"），两种策略各有取舍：主动追问能澄清用户真实意图（时间范围、指标、维度），生成更准确的结果，但多一轮交互、增加用户负担；默认口径兜底（如"近 30 天、按日、销售额"）能快速给出结果，但可能不符合用户预期，需明确标注所用口径。取舍原则：问题对结果影响大、难猜时优先追问；问题高频、有明确默认口径时优先兜底并提示。可设计为"先兜底 + 提示可调整"，或"默认给出 + 提供追问入口"，让用户既能快速拿到结果又能修正。产品上可采用置信度判断：高置信度自动执行，低置信度追问。

追问与兜底的取舍本质是"效率与准确"的平衡。好的交互是"先给可用的默认结果并从旁提示可调整"，既保留效率又保留纠错机会，避免强制追问造成挫败。

• 慢查询识别
• 执行计划检查
• 规则提示优化生成

慢查询治理需要识别生成的 SQL 是否低效：通过 EXPLAIN 查看执行计划，判断是否走索引、是否全表扫描、JOIN 顺序、预估扫描行数等。若发现全表扫描、无索引、预估行数过大，则判定为慢查询风险。优化生成的方式包括：规则提示，在 Schema 中标注高频查询字段的索引，并提示模型优先使用索引字段做过滤与连接；改写优化，对明显低效的 SQL 自动改写（如补充过滤条件、优化 JOIN 顺序、减少不必要的 SELECT 列）；以及把"走索引"纳入生成约束，让模型在选择过滤/连接字段时优先索引字段。对命中慢查询阈值的 SQL 可直接拦截或降级。

慢查询治理的关键是"在执行前用 EXPLAIN 评估代价"，把低效查询拦截在生成侧。规则提示让模型"从源头写高效 SQL"，比事后优化更有效。

• 口语化问题的转写纠错
• 口语中的指代消解
• 语音/IM 集成

语音/IM 场景下，用户问题口语化、含省略与指代，如"这月还剩多少预算"隐含"本月""预算总量-已用"等逻辑。接入时需先做转写纠错：语音转写可能产生错别字或语义歧义，可结合上下文纠错（如"这月"明确为"本月"）。指代消解需结合对话上下文与业务背景：把"这月"解析为当前月份，"预算"解析为预算字段与剩余计算逻辑，"还剩"解析为"总预算-已用"。可把口语问题先归一化为规范描述（补充省略的维度、指标、时间），再进入 NL2SQL 管线。同时要考虑语音/IM 的短对话、多轮上下文，复用前序查询状态做消解。

口语化问题的核心是"把省略口语归一化为规范查询描述"。转写纠错 + 指代消解 + 上下文复用，是让 NL2SQL 在语音/IM 场景可用性的关键。

• 语义等价判定规则
• 标注者间一致性
• 不一致样本仲裁

多人标注时，需先定义统一的"语义等价"判定规则，明确什么算正确（结果集一致、数值等价、容忍差异的边界），并给标注者提供判定指南与示例。控制标注者间一致性用 Cohen's Kappa（两名标注者）或 Fleiss' Kappa（多名）度量，Kappa 值反映标注的一致程度，一般 ≥0.7 视为可接受。当标注不一致时需仲裁：由资深专家或业务负责人复核该类样本，给出最终判定；同时把仲裁结果反馈给标注指南，更新规则以降低后续分歧。对高分歧样本可单独标记，作为易错集重点分析。

标注一致性是评估集可信度的前提。明确定义判定规则 + 度量化一致性 + 仲裁不一致并回写规则，能保证标准答案质量与可复现性。

• 线上效果指标
• 采纳率、改错率、执行成功率
• 离线与线上差距弥合

线上效果度量需关注真实用户行为指标：采纳率（用户是否接受了生成的 SQL/结果）、用户改错率（用户是否修改了生成的 SQL 或结果，反映生成质量）、执行成功率（SQL 执行成功比例）。这些指标能反映真实业务价值。与离线评测的差距主要来自分布差异（离线评估集与真实查询分布不同）与动态变化（线上数据、Schema 变化）。弥合差距的方法包括：持续从线上日志采样回流到评估集，使评估集逼近真实分布；用线上指标（采纳率、改错率）作为反馈，驱动离线评估集与优化；建立"离线评估 + 线上监控"的双轨机制，离线预测变化、线上验证实际效果，持续校准。

离线评测是"预测"，线上指标是"事实"。通过把线上失败样本回流评估集、用线上行为指标校准优化方向，可逐步缩小离线与线上的差距。

• 查询意图分类
• 分类驱动的路由
• 减少无效生成

在进入 NL2SQL 前，先用分类器对问题做意图路由，可避免对不可查询或需澄清的问题做无效生成。分类可分为：可直接查询（问题明确、有对应表结构，走 NL2SQL）、需澄清（问题模糊或缺关键信息，先追问再生成）、超出范围（问题与数据无关，如闲聊、不存在的指标，直接拒答或走 RAG）。分类器可用小模型、规则或 LLM 分类实现，输出分类结果并据此路由。这样能减少把"无关问题"或"模糊问题"误当成可查询问题导致的无效生成与错误结果，提升资源利用率与用户体验。

意图分类与路由是"前置过滤"，把有限的计算资源用在真正可查询的问题上。对"超出范围"直接拒答、对"需澄清"先追问，能显著减少无效生成与错误。

• 失败案例中字段问题识别
• 描述缺失/误导检测
• 自动驱动描述维护

Schema 描述的自适应优化是从失败案例中发现元数据问题：当一条 SQL 生成错误，可回溯其选中的字段，检查这些字段的注释是否为空、口径是否含糊、是否存在误导（如注释与枚举值不符）。可通过聚类分析：对大量失败案例中频繁出现的字段做统计，若某字段在错误案例中高频出现且注释质量差，则判定为"高风险字段"。检测到问题后驱动描述维护流程：生成待修复字段清单，提示数据团队补充注释、明确口径或修正误导信息，修复后重新生成 Schema 描述并跑回归验证。这样形成"失败→发现→修复→验证"的闭环。

描述问题往往隐藏在高频失败字段中。通过失败案例的统计聚类，自动发现"注释为空或口径含糊"的字段，让描述维护从"被动"变"主动"，持续提升 Schema 质量。

• 每轮权限校验
• 租户隔离
• 状态跨轮保持

多轮追问中，每一轮生成的 SQL 都必须重新校验权限与租户隔离，因为每轮都可能访问不同的表、字段或数据源，不能因为上一轮已通过就省略本轮校验。权限校验应基于当前用户身份与当前轮 SQL 涉及的表/字段白名单，租户隔离也应在每轮注入。查询状态（当前选中的表、字段、过滤条件、上一轮 SQL）需跨轮保持，以便指代消解与增量生成，但状态保持与权限校验是两回事：状态可以继承，权限必须每轮重新验证。状态通常保存在会话上下文，且需与服务端绑定，防止用户伪造状态绕过权限。

"状态可继承、权限每轮重验"是核心原则。多轮不能因状态复用而省略权限校验，否则存在越权风险；状态由服务端持有也避免客户端伪造。

• 灰度发布策略
• 影子查询
• 离线回归与安全放量

NL2SQL 变更（Schema 描述、示例集、模型版本）需安全放量，因为变更可能影响线上正确率。离线回归是放量前的第一道门：在评估集上跑新配方的正确率与延迟，确认不劣于基线。影子查询用于线上验证：把线上真实查询同时发给新配方与旧配方（影子模式），对比两者的 SQL 与结果，在不影响真实用户的前提下评估新配方效果，积累差异数据。确认离线回归与影子查询都达标后，再逐步放量（如 1%→10%→50%→100%），每步监控正确率、采纳率、错误率与延迟，出现异常即回滚。灰度能最大限度降低变更风险。

"离线回归 + 影子查询 + 逐步放量"是安全发布的标准流程。影子查询让新配方在真实流量下被验证又不出错，逐步放量则把风险控制在可回滚的范围内。

• 幻觉识别
• 不可计算查询的拒答
• 防幻觉机制

NL2SQL 的"防幻觉"是指在数据中不存在某个指标或无法计算时，模型应说明无法生成，而不是编造一个 SQL 或结果。实现上需要让模型"知道边界"：在 Schema 描述中明确列出可用的维度、度量与字段，并要求模型只基于已声明字段生成，对未声明的无法计算的指标（如"环比"但库里只有当期值、无历史值）应指出缺少所需数据并拒答。可通过提示词约束 + 元数据校验双保险：提示词要求模型不臆造字段/指标，执行层校验生成 SQL 引用的字段是否真实存在。若模型确需计算环比，需确认库中是否存在可供对比的历史数据，否则应说明"无法计算"。

防幻觉的关键是"让模型知道什么能算、什么不能算"。通过声明可用字段并约束模型只基于声明生成，能在源头抑制编造；字段存在性校验则是兜底。

• Schema 注入的 Token 成本
• 重试成本控制
• 成本核算与优化

NL2SQL 的成本主要由三部分构成：Schema 注入的 Token 成本（每次生成都输入 Schema 描述）、示例检索的 Token 成本（Few-shot 示例）、执行失败重试的额外成本（每次重试都重新调用模型）。核算时需把每次查询的 Token 消耗、失败重试率、调用次数相乘，得到单次查询的平均成本，再乘以调用量得到总成本。优化手段包括：裁剪 Schema 只注入相关表/字段（用 Schema Linking 缩小候选，减少 Token）；控制示例数量与长度，精选高质量示例；降低失败重试率（优化 Schema 与示例质量）从而减少重试次数；对简单查询走低成本小模型，复杂查询才用大模型。成本优化需与正确率权衡，避免过度裁剪牺牲正确率。

成本控制需要"算清楚 + 优化结构"。Token 成本、重试成本都是可优化项，通过裁剪 Schema、精选示例、降低重试率与分层模型策略，能在不牺牲正确率的前提下显著降本。