核心链路与 Schema 治理

• 端到端 Text2SQL 管线的各环节职责
• 各环节失败模式的识别与定位
• 分环节指标与归因方法

Text2SQL 的核心链路通常分为四步：首先是 Schema 选择（Schema Linking），从可用表中挑选相关表与字段，并进行字段消歧；其次是 SQL 生成，由模型基于 Schema 与用户问题产出 SQL；然后是执行，将 SQL 提交到数据库，处理权限、超时与错误；最后是结果解释，把查询结果转成自然语言或图表。各环节的失败模式各不相同：Schema 选择失败表现为选错表、选错字段或漏选字段，导致结果口径错误；SQL 生成失败表现为语法错误、JOIN 条件臆造、聚合口径错误；执行失败表现为超时、权限不足、列不存在；结果解释失败表现为对数值的误读、单位换算错误或趋势判断失误。归因时可通过分段点检与误差归因法：在 Schema 选择后单独检查选中的表与字段是否合理，用解析器对生成 SQL 做语法校验，用执行计划与返回结果核对 SQL 真实性，最后用口径核对验证解释逻辑，从而把失败定位到具体环节。

分环节归因的价值在于把"最终答案错误"这个结果反推为可修复的环节缺陷。实践中可给每个环节打上中间产物（选中的 Schema、生成的 SQL、执行行数、解释文本），并分别记录正确率，从而精确判断是"该 SQL 就该错"还是"SQL 对但解释错"。

• Schema Linking 成为主要误差源的原因
• 多表/宽表/同名字段下的裁剪策略
• 消歧与字段选择方法

Schema Linking 是误差最大的来源，因为它的错误会传导到下游所有环节：一旦选错表或字段，即使 SQL 语法完全正确，结果也是错的，且这种错误难以通过语法检查发现。模型面对几百张表、几千个字段时，检索空间巨大，容易因文本相似度误导而选错（例如把"销售额"映射到同名但不同口径的字段）。多表场景需要先根据问题中的实体与指标识别相关表，再通过外键关系串联；宽表场景需要裁剪候选字段，只保留与查询维度、度量相关的列；同名字段场景需要用表名、Schema 名、注释和口径做消歧。裁剪策略通常采用两级方法：先做表级粗选（基于问题关键词与表注释的检索），再做字段级精选（基于度量、维度、过滤条件的语义匹配）；消歧则依赖字段注释、表主题、以及 Few-shot 示例中对同名字段的使用方式。

把 Schema Linking 单独抽出并给足够预算，是提升端到端正确率最高性价比的手段。因为下游的 SQL 生成、执行与解释都建立在选对 Schema 的前提上，所以业界普遍用"Schema 命中率"作为独立指标来评估和优化。

• 元数据分析与 Schema 描述的组织方式
• 注释质量对生成正确率的影响机制
• Schema 注入的格式与 Token 控制

组织 Schema 描述的关键是把"人可读的元数据"转成"模型可理解的结构化文本"。常见做法是：表层面输出表名与表注释、行数量级、所属业务域；字段层面输出字段名、类型、单位、注释、枚举值（如 status 的 0/1/2 各代表什么）、是否可空；关系层面输出外键、索引与多对多关联表。可使用统一的模板（如 JSON 或 <table> 标记）保持格式稳定。注释质量直接影响正确率，因为模型主要靠注释建立语义映射：注释缺失或含糊（如"金额"不说明是含税还是不含税）会导致模型猜错口径；注释与实际枚举值不一致会误导模型生成错误的过滤条件。因此需要建立元数据治理流程，保证注释准确、完整、口径清晰。

注释本质上是模型唯一的"领域知识来源"，注释质量差时模型只能靠猜，正确率必然下降。所以 Schema 治理被视为 NL2SQL 正确率的第一杠杆，应优先在数据仓库层补齐注释，而不是依赖模型事后纠错。

• 表间关系在 Schema 中的表达方式
• 星型/雪花模型与多对多处理
• 防止臆造 JOIN 条件的手段

表达表间关系首先要明确注入关系信息：外键可以在 Schema 中显式标注（如 orders.user_id -> users.id），星型模型以事实表为中心、维度表通过外键关联，雪花模型则维度表再被规范化拆分。多对多关系通常通过中间关联表表达，应把关联表与两端的连接键都注入。避免模型臆造 JOIN 条件的关键是"只允许使用已声明的关系"：在 Schema 中枚举所有可用的连接路径，并指示模型只能从这些路径中选择，而不是自行猜测连接字段；同时可在 Few-shot 中展示正确 JOIN 的写法。对于复杂关系，可预先把"常用 JOIN 路径"预编译为候选，让模型做选择而非生成。

模型臆造 JOIN 条件（如把不相关的字段硬连接）是典型错误，因为语义上"看起来能连"。通过显式声明关系与约束生成空间，能显著减少这类错误。执行层还可以用 EXPLAIN 或元数据校验连接键是否真实存在。

• 术语表（glossary）的建模与注入
• 业务术语到字段的映射
• 跨部门口径不一致的处理

建立术语表需要把业务术语（如"下单""活跃用户""成交额"）与具体的字段、过滤条件、口径绑定起来，形成"术语→{表, 字段, 计算逻辑, 口径说明}"的映射。术语表可以注入 Prompt 的独立段落，或作为检索增强的一部分，在用户问题命中某个术语时把对应定义加入上下文。跨部门口径不一致是常见难题，处理方式包括：在术语表中明确标注口径差异（如 GMV 按支付口径还是发货口径），优先使用平台统一的指标口径；当问题含糊时，通过追问澄清或使用默认口径并明确告知用户；在结果解释中标注所用口径，避免歧义。若存在多个口径，应让术语表记录"该术语在哪个业务域下对应哪个字段/口径"。

术语表本质上是把"人类语言"与"数据库语言"之间的桥梁显式化，避免模型每次从零猜测。跨部门口径问题属于组织级治理问题，技术上用术语表 + 追问 + 默认口径兜底，管理上需要建立统一的指标口径定义。

• 方言差异对生成的影响
• 方言适配策略
• 方言回归测试

不同方言在语法、函数与类型上差异很大：例如分页语法（MySQL 的 LIMIT offset, count 与 PostgreSQL 的 LIMIT count OFFSET offset）、日期函数（DATE_FORMAT vs to_char vs formatDateTime）、字符串拼接与聚合函数、方言特有特性（如 ClickHouse 的 ifNull、Doris 的数组函数）都不同。生成时必须把目标方言显式注入 Prompt，并让模型只使用该方言支持的语法。适配策略包括：维护每个方言的语法说明与函数白名单，提供该方言的 Few-shot 示例；同一套业务语义在不同方言下分别生成，并分别做回归测试。回归测试应针对每个方言运行同一组评估用例，确保方言升级或模型变更后各方言正确率不退化。

方言是确定性约束，注入方言信息可以把模型从"猜方言"中解放出来，是低成本高收益的做法。而跨方言回归是防止模型在某个方言上"悄悄退化"的必要手段。

• Few-shot 示例的检索方法
• 三元组相似度度量
• 示例选择对正确率的影响

Few-shot 示例通常组织为"问题-表结构-SQL"三元组，即一个问题、用到的表结构、标准 SQL。选择示例时，不是固定用几条，而是根据当前查询动态检索最相似的历史示例。相似度度量可以从三个维度进行：问题文本相似度（用 embedding 或 BM25 度量语义/词面相似）、表结构相似度（用到的表集合重合度）、SQL 结构相似度（如聚合类型、JOIN 数量、过滤条件个数）。将三者加权融合得到综合相似度，选出 top-k 示例放入 Prompt。动态检索示例比固定示例更能匹配当前查询的复杂度，从而提升生成正确率。

检索式 Few-shot 让示例与目标查询"同构"，模型能模仿相近的写法，尤其对复杂查询有效。相似度度量要兼顾语义与结构，避免只按文本相似导致选到了结构差异很大的示例。

• 复杂查询的分解策略
• "先定维度度量过滤再生成"的思维链
• 正确率差异的评估方法

复杂查询的分解策略是：先让模型从问题中抽取结构化的查询规格，包括维度（GROUP BY 的字段）、度量（聚合函数与字段）、过滤条件（WHERE 支持的时间区间等）、排序与分页需求，形成中间表示，再基于该中间表示生成 SQL。这种"先定规格再生成"的方式比直接生成更可控，因为中间规格可供人审阅与纠错，且模型在生成 SQL 时有了明确的骨架。评估正确率差异可采用 A/B 对比：同一评估集分别用"直接生成"与"先分解再生成"两条管线跑，对比 Execution Accuracy，并针对不同复杂度（简单、中等、复杂）分层统计，从而量化分解策略在复杂查询上的增益。

分解策略把"一步到位"的隐性推理变成"可审计的分步推理"，降低了复杂查询的出错率，代价是增加一次中间输出。评估时分层统计能揭示出该策略主要在复杂查询上收益明显，简单查询上可能相差不大。

• NL2SQL 中 RAG 的输入构成
• 检索质量对正确率的影响
• 检索增强的实现

在 NL2SQL 中引入 RAG，是把表结构描述、术语表条目和相似示例作为检索增强输入，在生成前动态检索并注入上下文。检索质量直接决定正确率：若检索命中正确的表、字段与术语，模型就拥有足够信息生成准确 SQL；若检索到无关或错误的表结构，反而会引入误导，降低正确率。检索质量可从召回率（正确表/字段是否被检索到）与精度（检索结果是否相关）两个维度评估，它们与最终 SQL 正确率存在强相关。因此要优化检索的 embedding、索引与重排策略，并确保检索结果与 Schema 裁剪一致。

RAG 的价值在于"按需注入信息"，避免把全部 Schema 塞进上下文导致噪声与 Token 浪费。但检索质量是它的命门，检索不准时增强反而有害，所以必须单独度量检索命中率并监控其对 SQL 正确率的影响。

• 分层裁剪的层次结构
• 裁剪策略与召回率的权衡
• 大规模表场景的 Schema Linking

面对数百张表，一次性把所有 Schema 注入会超出上下文且引入大量噪声。分层裁剪策略是：先在库/Schema 层粗筛出相关的数据库或 Schema，再在表层用问题关键词与表注释检索出候选表，最后在字段层选出与维度、度量、过滤相关的字段。每层都应用"先粗筛保召回、再精排提精度"的思路。裁剪策略与召回率的权衡在于：裁剪得越狠，进入上下文的候选越少、精度越高，但可能漏掉正确表/字段导致召回率下降；裁剪得越宽，召回率越高但噪声和 Token 成本上升。设计时需分层设定召回目标（如每层召回率 ≥ 一定阈值），并在裁剪后保留一个略大的候选集，由模型在候选内做最终选择，从而兼顾召回与精度。

分层裁剪把"一次全量处理"变成"逐层收敛"，是解决大规模 Schema 的核心手段。权衡的关键是"宁可多留候选让模型二次选择，也不要在粗筛时就漏掉正确项"，因为漏掉就永远无法挽回。

• 意图先行思维链的实现
• 中间步骤的可审计性
• 纠错价值

"先输出查询意图再生成 SQL"的思维链方式，让模型在写 SQL 前先明确列出维度、度量、过滤条件与排序，形成可读的中间产物。其可审计性在于：用户或开发者可以直接审阅意图文本，判断模型是否理解对了问题，而不必去读难懂的 SQL；当结果错误时，可以根据意图判断是"理解错了（意图错了）"还是"理解了但写错了（SQL 错了）"。其纠错价值在于：意图输出给了人机交互的切入点，可以在意图错误时直接修正意图再重新生成，而无需整体重跑；同时意图作为结构化规格，也被用于后续的 Schema 选择与结果校验。

思维链的本质是把隐性推理显式化，让中间状态可被检查与干预。意图先行不仅提升正确率，更提供了审计与纠错的可操作路径，是工程化落地的重要一环。

• 多轮对话的指代消解
• 前序 SQL 与查询状态的复用
• 增量 SQL 生成

多轮对话中的"再按月份分组""换成本周数据"等表达依赖上下文，指代对象是前一轮查询的结果。处理方式是把前序 SQL、前轮生成的结果摘要以及查询状态（如当前选中的表、字段、过滤条件）作为上下文注入，让模型理解"再""本周"指代什么，并生成增量修改。例如"再按月份分组"应在已有 SQL 基础上补充 GROUP BY 月份，"换成本周数据"则修改时间过滤条件。实现上可维护一个"当前查询状态"对象，每轮把上一轮的 SQL 与状态传给模型，模型输出增量 SQL 或输出完整新 SQL 替换旧 SQL。需要保证多轮不丢失权限与上下文，并在每轮重新校验。

指代消解是 NL2SQL 从单轮走向多轮的关键能力。把前序 SQL 与状态显式传入，比让模型"记住"对话更可靠，也能避免指代不清导致的误解。

• Prompt 版本管理
• Schema 描述、示例集与模型版本的绑定
• 回归门禁设计

NL2SQL 的正确率由 Schema 描述、示例集、Prompt 模板与模型版本共同决定，因此需要把它们作为一个整体进行版本管理。可持续集成中使用"配方（recipe）"的概念，把 Schema 描述版本、示例集版本、Prompt 模板版本、模型版本组合成一个不可变快照，并记录其评估指标。回归门禁设计为：任何一项变更（如升级模型、重写 Schema 描述、增删示例）都必须先在固定评估集上跑回归，只有执行正确率达到基线阈值才允许上线；可采用 A/B 对比新旧配方的正确率，若新配方不劣于旧配方才放行。这样避免"某个组件升级导致整体正确率悄悄下降"。

版本绑定的意义在于可复现与可追溯：当线上出问题时，能精确知道是哪个组件的哪次变更导致的。回归门禁把"变更成本"前置到上线前，是最稳妥的工程质量保障。

• Execution Accuracy 与 Exact Match 的定义与差异
• 业界偏好执行正确率的原因
• 评估集按复杂度分层

Exact Match 要求生成 SQL 与标准 SQL 字符串完全一致，过于严苛，因为实现同一语义的 SQL 写法可以多样（如不同的等价写法、不同的别名）；Execution Accuracy 则把生成 SQL 在数据库上执行，与参考答案的执行结果比对，只要结果一致即视为正确。业界更关注执行正确率，因为它贴近业务价值——用户要的是"查对数据"，而不是"SQL 写法一样"，且执行正确率能容忍多样化的等价实现。企业评估集按查询复杂度分层，通常把查询分为简单（单表、单过滤）、中等（多表 JOIN、聚合）、复杂（多级子查询、窗口函数、多条件组合）等层级，分别统计各层正确率，从而识别模型在哪个复杂度层级的短板，并针对性优化。

执行正确率是"结果导向"的指标，更符合业务诉求；分层统计则让评估从"一个平均数"变成"能力画像"，指导优化方向，避免被简单查询拉高平均分而掩盖复杂查询的缺陷。

• Schema 变更的影响面
• 描述、示例与缓存的失效管理
• 变更检测与自动回归

表结构变更（新增/删除字段、改字段名、改类型、改枚举）会让已注入的 Schema 描述失效，使模型基于旧信息生成错误 SQL，同时缓存的查询结果也可能已过期。失效管理需要：当检测到 Schema 变更时，重新生成或更新 Schema 描述，重新校验并更新依赖该表/字段的示例，使依赖变更字段的缓存结果失效。自动检测可监听 DDL 事件或周期性比对元数据快照，一旦发现变更就触发回归：在评估集上重跑受影响的用例，确认正确率未退化，并更新版本快照。这样保证 Schema 变更不会"静默"破坏线上正确率。

Schema 变更往往是静默风险，因为表面上看系统没报错，但结果已错。通过变更检测 + 缓存失效 + 自动回归，把"变更"纳入可治理的流程，避免累积错误。

• 执行层只读控制
• 行数与时间限制
• 敏感列过滤与防泄露

防止 Text2SQL 成为数据泄露入口，必须在执行层强制执行安全约束，而不是依赖模型自觉。包括：只读控制，通过专为查询创建的只读数据库账号 + 语句级拦截（只允许 SELECT），双保险确保无法执行写操作；行数限制，在 SQL 外包一层 LIMIT 或由执行器截断返回行数，防止一次拉取全表；时间限制，设置查询超时，超时即终止，防止慢查询与资源耗尽；敏感列过滤，在执行结果返回前对 PII、密码、证件号等敏感字段做掩码或脱敏，并做字段级授权过滤，未授权字段不返回。这些约束在网关上统一强制，与模型输出解耦。

执行安全的核心原则是"把安全放在执行层强制执行"，因为模型输出不可信，用户输入也可能被恶意构造。只读账号 + 语句拦截 + 行数/时间上限 + 敏感列过滤构成完整的防泄露防线。

• 基于错误信息的重写机制
• 重试上限与成本控制
• 自纠错的终止条件

自纠错的核心是把数据库返回的错误信息回喂给模型，让模型基于错误进行重写。例如语法错误、列不存在、类型不匹配等报错会指出具体问题，模型据此修正 SQL 后再次执行。关键是要控制重试：设置固定重试上限（如 2-3 次），超过即放弃并返回失败；同时可对错误类型做分级，如"列不存在"可通过 Schema 修正快速解决，"笛卡尔积""权限不足"等重试价值低则提前终止。成本控制方面，每次重试都消耗模型调用的 Token 与延迟，因此要限制重试次数、对错误先做净化（去除用户输入回显的注入风险）再回喂，并设置整体超时预算。

retry with error 是一种高效的纠错方式，因为错误信息本身提供了定位线索。但如果没有上限，可能陷入无限重试或反复生成相同错误，所以必须设重试上限与成本预算，并区分可修复与不可修复的错误。

• 公开数据集与企业查询的分布差异
• 迁移到自建评估集的方法
• 评估集构建的注意事项

Spider、BIRD 等公开数据集与真实企业查询存在显著分布差异：公开数据集的查询类型相对单一、Schema 规模较小、业务术语较少、时间过滤与多轮对话等真实场景覆盖不足；企业查询则包含复杂的业务术语、脏数据、规模更大的 Schema、多轮指代、口径差异与时区/货币等特殊处理。因此直接把公开数据集上的指标当作企业上线依据不可靠。迁移到自建评估集的方法是：从真实查询日志中采样，覆盖不同复杂度与业务主题，标注标准答案与判定口径，并补充公开数据集中缺失的场景（多轮、口径、敏感数据）。同时可用公开数据集作为跨模型泛化能力的补充参考，但以自建评估集为准。

评估集必须代表"真实业务分布"才有意义。公开数据集适合做横向对比与模型初筛，但企业上线必须用自建、贴近真实日志的评估集来度量真实正确率。

• NL2SQL 与 SQL 助手的边界
• 预填确认 vs 全自动执行的取舍
• 产品交互与安全平衡

NL2SQL 与 SQL 助手的边界取决于"是否允许自动执行"。当用户是普通业务人员、问题简单、Schema 明确、风险低时，可全自动执行并直接返回结果；当用户是分析师/开发者、问题复杂、涉及敏感数据或高风险操作时，更稳妥的做法是"自然语言→SQL 编辑器预填"，即模型生成 SQL 填入编辑器，由人审阅确认后再执行。产品交互与安全的取舍在于：预填模式以人确认为代价换取安全与信任，适合复杂、高价值或不可逆的查询；全自动模式以追求效率，适合简单、低风险、可反复验证的场景。还可采用分级策略：低风险默认自动，高风险自动转预填。

"人确认后执行"是一种低成本的安全兜底，既保留了 NL2SQL 的效率（自动生成 SQL），又避免模型错误直接作用到真实数据。产品上可根据用户角色与查询复杂度动态选择两种模式。

• 脏数据对 SQL 正确性的影响
• 枚举漂移、空值、时区差异的处理
• 数据质量检查前置

脏数据会直接导致 SQL 结果错误：枚举值漂移（如 status 枚举从 0/1 变成 0/1/2 或含义改变）会让过滤条件失效或误判；空值比例高会使聚合、连接返回错误结果（如 COUNT 与 SUM 对 NULL 的处理）；时区口径差异会让时间过滤和分组结果错位。应对策略包括：在 Schema 描述中注入准确的枚举值与空值说明，提示模型对 NULL 的处理；对时区做统一口径并显式标注。数据质量检查前置的意义在于：在 NL2SQL 之前，先对元数据与数据质量做检测（枚举漂移检测、空值率监控、时区一致性校验），发现异常时更新 Schema 描述或提醒用户，从而避免"脏数据 + 脏 Schema"双重叠加导致错误结果。

LLM 无法绕过脏数据，只能依赖元数据与口径说明。前置的数据质量检查能主动发现漂移与不一致，在生成前就修正隐患，比事后纠错更可靠。