2026-09-07

Text2SQL 实践：企业自然语言查数怎么做

从边界、指标语义层、权限隔离到 SQL 校验，系统拆解 Text2SQL 实践方法，帮助企业安全、可控地实现自然语言查数。

一、先定边界：不要从“万能查数”开始试点

Text2SQL 试点首先要确定系统在哪些问题上可以作答，而不是先追求覆盖多少问法。边界判断可看两个变量：查询本身有多复杂，以及回答错误会造成多大影响。BIRD-CRITIC 的公开评测反映出，涉及多表推理、复杂约束与深层嵌套时，现有模型仍难保持稳定。因此，复杂度不能全部交给模型消化，能通过数据建模简化关联、用 ETL 固化计算的逻辑，应先在数据侧处理。

首批范围宜收敛到一个业务主题内：数据表之间的关系已经固定，指标定义不存在争议，查询主要完成条件过滤、汇总统计与维度分组，并且只允许读取。跨主题的数据归因、需要多层子查询的分析，以及直接影响结算结果的计算，可保留人工审核，不进入自动执行范围。这样做不是降低目标，而是把模型变量与数据治理问题分开，避免试点失败后无法判断究竟错在语义、数据还是 SQL。

还要先区分使用对象。分析师具备阅读和修改 SQL 的能力，系统可以定位为代码辅助工具：生成草稿、展示引用对象，由使用者检查后执行。业务人员通常只看到最终数字，无法识别错误连接、遗漏过滤或聚合层级偏差，因此需要更严格的准入条件。此类入口应绑定经过治理的数据集，并限定可提问的指标、维度和时间范围。两种模式不能共用同一套验收门槛。

白名单应描述“允许查询什么”，而不只是维护一组禁用词。每个场景需要绑定可访问的数据对象、支持的指标和维度、允许的查询形态、结果粒度，以及异常时的处理方式。否则，同一句自然语言在数据结构变化后，可能生成语法正确但业务含义已经漂移的 SQL。

试点验收也不能停留在“是否成功生成 SQL”。至少要分别记录：语句执行后是否得到正确结果，输出是否遵循既定业务定义，系统在歧义问题上是否主动追问，对越界请求是否拒绝，端到端响应耗时是否可接受，以及多少请求最终需要人工处理。生成率只能说明链路能运行，不能证明它适合开放给业务使用。

边界确定后，团队应形成一份可审查的场景清单：哪些问题自动回答，哪些必须补充条件，哪些只生成草稿，哪些始终拒绝。后续扩展应以评测结果为依据逐项放开，而不是通过修改 Prompt 一次性扩大能力范围。

二、指标口径先于 Prompt：建设可检索的语义层

企业查数最先暴露的问题通常不是 SQL 语法，而是业务词没有唯一解释。模型看到订单表、付款表和收入明细表，可以分别写出可执行的“销售额”查询，但数据库能运行不代表结果符合经营口径。因此，Prompt 不应承担定义指标的职责；口径要先被整理成机器可检索、可执行、可追溯的语义资产。

指标目录是语义层的入口。每个指标条目需要描述其业务含义、标准称谓、计算表达式、适用维度、默认周期、前置过滤、维护责任、版本状态与生效区间。这里不能只保存一段说明文字，还要明确数据来源、聚合方式、时间字段、去重规则以及空值处理。否则，检索虽然找到了指标，生成阶段仍要猜测具体算法。

“新增客户”“活跃用户”之类的名称往往同时存在集团定义和部门定义。工程上应为标准口径设置稳定标识，再把部门变体和自然语言别称挂接到对应版本。若用户问题能够命中多个有效定义，系统应返回候选项并询问统计部门、时间范围或业务范围。让模型根据上下文自行挑选，会把口径冲突隐藏成一个看似正常的数字。

语义层还要能够下沉到执行侧。可将已审核的指标逻辑发布为受约束的查询模板、语义模型或统一指标接口。模型只解析用户提出的指标、观察维度、条件、周期和排序要求，再由确定性组件组装查询。复杂计算、固定过滤和标准关联不再临时生成，审计时也能追踪结果使用了哪个口径版本。

Schema Linking 的目标不是把整个数据库结构塞进上下文，而是缩小模型的选择范围。一次请求可以先检索相关指标，再扩展到必要的事实数据、维度数据、字段说明、连接键和候选枚举值。输入模型的结构应限于本次查询需要的子图，并保留关联方向与字段语义，避免模型仅凭相似的物理命名建立错误连接。

中文检索需要把术语理解和值匹配分开处理。企业缩写、业务同义表达和字段注释适合进入语义检索；机构名、地区名、商品名等具体值，则可同时建立字符、拼音和模糊匹配通道，再对候选结果精排。常见错字、同音输入及键盘误触不应直接交给大模型猜测，而应在检索层产生可核验的候选值。

• 唯一命中：携带指标版本和相关 Schema 进入查询规划。
• 多口径命中：展示差异点，完成澄清后再生成 SQL。
• 只能匹配术语、无法定位指标：返回已识别条件，并提示补充业务范围。
• 没有可靠匹配：停止生成，避免从物理表名推断业务含义。

这一层的验收重点不是模型是否“理解”了术语，而是同一问题能否稳定绑定到确定的指标版本、连接路径和过滤规则。只有这些决策可以被记录和复现，后续的 SQL 校验才有明确依据。

三、权限隔离：模型有能力生成，不等于用户有权查询

Text2SQL 的权限边界不能建立在提示词上。模型可以按要求补出表名、连接条件和过滤表达式，但它既不是身份认证组件，也不应参与授权决策。用户在问题中写下“我是财务负责人”，只能被当作查询文本；真实的人员身份、所属组织、业务角色、租户范围与访问目的，应由登录态、身份服务或审批系统提供，并以不可被对话内容覆盖的上下文传入查询链路。

可信上下文进入系统后，应先完成权限判定，再允许生成结果被执行。即使模型漏写了部门条件，底层控制仍须阻止跨部门读取；即使生成语句引用了敏感列，执行侧也必须拒绝或按规则处理。换言之，授权约束要落在确定性组件中，而不是期待模型每次都正确拼接 WHERE 子句。

权限设计需要覆盖对象、记录、字段和结果交付。对象范围通过库表或视图清单收敛；记录范围按租户、组织或数据归属强制裁剪；字段范围控制敏感列是否可见，并按策略隐藏或转换内容；结果交付则约束返回规模、文件下载和批量导出。这里的关键不是多设一道检查，而是确保任何单点失效都不会直接扩大数据可见范围。

生成组件与执行组件也应隔离。模型侧只产出查询候选，不接触可直接连接数据源的凭据；执行服务使用专门的受限账号，只开放必要的读取能力。建表、修改结构、写入、删除、调用存储过程以及不必要的危险函数，应在账号权限和网关规则中关闭，而不是只做字符串拦截。数据访问可经过查询网关、隔离环境或只读副本，使生成错误和恶意输入无法直接影响生产写路径。

只读并不等于低风险。一个合法的 SELECT 仍可能读取过多明细、绕过租户范围，或通过复杂计算消耗大量资源。因此，执行前还要核对引用对象、权限策略和查询结构；执行时应用超时、资源配额与结果规模约束；需要下载时，再进行独立授权。输入检查和 SQL 注入防护属于基础措施，不能替代完整的权限模型。

审计记录应贯穿整个请求，而不只是保存最终 SQL。可追溯信息包括原始提问、认证系统提供的主体属性、检索到的元数据、候选语句及其变更轨迹、授权判断、执行状态、结果概况，以及查看或导出动作。日志中不应再次暴露完整敏感结果，但要能回答：谁在什么上下文中请求了哪些数据，系统依据什么规则放行或阻断，最终返回到了哪里。

验收权限隔离时，不要只测试正常查询。还应覆盖伪造身份、跨租户提问、诱导访问未授权表、请求敏感字段、超量明细导出和借助复杂 SQL 绕过限制等情况。合格标准不是模型“通常会拒绝”，而是无论模型生成什么，确定性的执行边界都能保持不变。

四、生成链路：把一次性回答拆成可控制的工程流水线

企业 Text2SQL 不宜把需求理解、选表、SQL 编写和错误修复全部塞进一个 Prompt。这样虽然链路短，但中间决策不可见：一旦结果错误，很难判断问题出在业务语义、表关系还是 SQL 表达。更可控的做法，是把生成过程拆成若干有明确输入和输出的环节。

其中最关键的隔离层是查询计划。模型不应从自然语言直接跳到最终 SQL，而应先提交机器可读的中间表示。例如，将“统计对象”“分组字段”“谓词条件”“日期边界”“聚合算子”和“连接关系”分别放入固定字段。后续组件再把它编译成 MySQL、PostgreSQL 或数仓所需方言。这样，业务语义与数据库语法被分开处理：修改表名或函数写法时，不必重新解释用户意图；发生错误时，也能定位是计划本身有误，还是编译结果偏离计划。

生成方式不必全部交给模型。对于结构稳定、参数有限的查询，应优先匹配查询模板或参数化 SQL。模型只负责抽取日期、区域、产品等参数，并选择适用模板。需要临时组合维度、跨表探索且无法覆盖模板的问题，再进入自由生成路径。两类路径应显式分流，而不是让模型每次都重新组织完整语句。

Agent 适合处理需要多步工具调用的任务，例如筛选候选表、读取必要的 Schema、审查候选语句、依据数据库报错进行修订，或按需要发起后续查询。但它不能拥有无限循环的自主权。运行配置至少要约束以下边界：

• 只允许调用经过批准的检索、检查和查询工具；
• 限制单次任务能够推进的工具步骤；
• 限制同一错误触发的修订次数；
• 对整次任务设置统一的执行资源预算。

数据库返回错误后，可以把候选 SQL 与错误内容送入修订环节，用于处理标识符引用、字段类型或对象名称等生成问题。但修订必须重新经过检查，而不是直接执行修改后的语句。整条链路的目标不是增加步骤，而是让每次转换都有可检查的产物，使模板、模型和 Agent 分别承担边界清楚的工作。

五、SQL 校验：从“能执行”升级到“可证明地可信”

数据库接受一条 SQL，只能说明它符合语法并且引用对象存在，不能证明查询安全、业务口径正确或资源消耗合理。企业查数需要把校验拆成执行前静态检查、业务语义核对、成本控制和执行后结果检查，并为每一步保留可审计的判断结果。

先解析结构，不直接检查字符串

执行服务应按目标数据库方言把 SQL 解析为抽象语法树，再检查语句类型、引用对象、表达式与关联关系。简单搜索 DELETE、DROP 等关键词容易受到注释、大小写、嵌套表达式或方言差异影响，也无法识别隐藏在函数和子查询中的风险。

• 语句范围：仅放行只读 SELECT，拒绝多语句以及任何数据定义、数据修改和权限变更操作。
• 对象范围：表、视图、字段和函数必须位于授权清单内，通配字段也要展开后逐项检查。
• 结构风险：识别无连接条件的多表查询、可疑关联键、条件未传递到关联表，以及可能放大结果集的 JOIN。
• 扫描风险：检查明细查询是否缺少必要的时间或租户约束，是否存在无边界排序、全表扫描倾向和过宽字段投影。
• 绕过风险：拒绝注释混淆、危险函数、动态 SQL、外部访问能力及无法可靠解析的语句。

无法完成解析的 SQL 不应带病执行。与其用字符串规则猜测风险，不如返回生成环节重新构造，或者进入人工处理。

语法通过后，再核对业务语义

更隐蔽的问题通常不是 SQL 报错，而是结果看似合理、实际口径错误。校验器需要将查询计划与语义层中的指标定义逐项对照：计算表达式是否匹配，使用的是业务发生时间还是数据写入时间，聚合层级是否符合问题，去重主键是否正确，以及币种处理和业务时区是否一致。

多表查询还要验证关联路径。事实表连接维表时，错误的键或不完整的过滤条件可能改变行数；一对多关系参与汇总时，则需要确认聚合发生在连接之前还是之后。若用户问题存在时间范围、组织范围或指标定义歧义，应先澄清，不应依靠模型自行补齐。

把资源预算放在执行之前

静态检查和语义检查通过后，再使用 EXPLAIN、优化器估算结果或数据平台提供的成本信息评估查询。执行策略应同时约束预计扫描规模、结果行数、运行时长和并发占用。超过预算时，可缩小时间范围、减少返回字段、改为预聚合查询；仍无法降到预算内的任务，转为异步处理或拒绝执行。

执行成功不等于校验结束

结果返回后仍需检查空集、数量级偏离、同比变化异常，以及分项汇总与总计无法对齐等情况。发现异常时，应区分“数据确实如此”和“查询可能有误”：前者附带提示，后者阻止直接回答并进入修正流程。执行报错可以把 SQL 与错误信息交回修正环节，但必须限制重试，避免反复生成近似语句持续消耗数据库资源。

最终展示不应只有数字。至少应说明采用的指标口径、实际筛选条件、统计时间范围和数据截至时间；必要时补充表来源、关联方式及聚合逻辑。这里的目标不是向用户倾倒完整 SQL，而是让结果能够被复核，让安全、语义和成本判断都有记录可查。

六、失败兜底：明确什么时候澄清、重试、降级或转人工

Text2SQL 的兜底不能统一处理成“生成失败，请重试”。不同故障对应不同动作：缺信息时补充条件，口径冲突时让用户选择，越权请求直接终止，语法问题才进入修复，资源消耗不可接受时改用低成本路径，结果可信度不足时停止作答。先完成故障归类，再决定是否继续执行，避免模型在原因不明时反复改写 SQL。

澄清环节应输出有限选项，而不是继续开放式猜测。例如，要求用户确认采用哪一种指标定义，选择自然月还是自定义日期，限定组织范围，并确定按日、周、月还是明细记录返回。对话模块只负责收集缺失参数；参数未齐全之前，执行模块不应被调用。这样可以避免同一个模型一边补全假设，一边把假设写入查询。

候选口径需要展示决定结果的差异，而不只是列出几个相近名称。系统可以说明各候选项对应的时间字段、过滤条件和聚合方式，让用户做业务选择。若系统采用预设值，也应在结果前显式列出，不能把默认条件隐藏在 SQL 内部。

自动修复的范围必须收窄。适合机器处理的是技术性、局部且可验证的问题，例如列名解析失败、字符串引号不符合目标数据库要求、比较两端类型不一致，或生成语法与实际数据库方言不匹配。指标定义冲突、连接关系不确定、授权失败和结果异常不属于语法修补，不应交给修复循环自行猜测。

每轮修订都应视为一条新查询：重新检查用户权限和数据范围，重新执行语法与对象校验，再评估扫描成本、返回规模和运行限制。系统还要设置固定的重试上限；达到上限后立即退出，不能因错误信息变化而无限循环。修复记录应保留原始 SQL、错误摘要、修改内容与最终状态，便于后续定位。

降级不等于返回一个精度更差却未说明的数字。可行做法是收窄时间区间、减少维度、切换到已授权的汇总粒度，或者只生成查询计划供人工确认。任何降级都要向用户说明哪些条件被调整；如果调整会改变业务含义，则必须再次确认。

最终兜底仍需提供下一步动作。输出至少应说明失败属于语义、权限、执行还是结果校验问题，列出已经识别的指标、时间、组织与粒度条件，并给出可直接选择或改写的问题模板。需要人工介入时，应一并移交原问题、结构化查询计划、候选 SQL、校验结论和执行错误，减少数据分析人员重复排查。

七、从试点到上线：用评测集、影子流量和灰度机制推进

Text2SQL 上线不应以演示案例是否成功为依据，而要验证系统在真实问题、权限约束和异常输入下是否稳定。评测数据可从历史查数工单、BI 搜索记录与分析师编写的 SQL 中整理，并去除敏感信息。样本需要覆盖常见查询、同义改写、表达不完整、越权请求、多表关联、无数据返回及错误字段等情况。

每条样本应保留用户问题、授权身份、预期口径、参考结果和允许访问的数据范围。标准答案不宜只标一条 SQL，因为不同写法可能得到相同结果；指标负责人应确认业务定义，分析师负责核对连接路径、过滤条件与聚合方式。生产中发现的新问题再持续补入评测集，使其成为后续变更的回归基线。

Text2SQL 可以直接连接生产数据库吗？

试点阶段不应让模型生成的语句直接进入生产执行链路。上线前可先做影子运行：系统接收真实请求并生成候选 SQL，但结果不返回用户。若需要验证结果，应在受控的只读环境中执行，再由分析师与既有报表或已确认查询进行对照。

影子验证通过后，再按业务部门、数据主题和风险级别逐步开放。灰度范围内仍需保留只读权限、查询限额、审计记录与人工停用入口。辅助分析师编写 SQL 与面向业务人员自动返回答案，对准确性的要求不同，不能采用同一放行标准。

SQL 执行成功，是否就说明答案正确？

不能。数据库接受语法，只能说明语句可运行，无法证明指标定义、时间字段、关联关系或权限范围正确。离线评测应把不同问题拆开观察，包括查询能否正确执行、结果是否与参考数据一致、业务口径是否命中、越权请求是否被阻断，以及危险语句是否被错误放行。

也不宜用 SQL 字符串完全一致作为主要判据。字段顺序、别名、子查询和连接写法不同，仍可能产生相同结果。评测应结合结构检查、结果对照和口径审核；涉及空结果时，还要区分“业务上确实没有数据”与“过滤或连接条件写错”。

遇到“销售额怎么样”这类模糊问题，系统应该猜还是追问？

当缺失的条件会改变业务结论时，应追问而不是猜测。评测集中需要专门加入歧义样本，检查系统能否识别缺少的时间范围、组织范围、统计口径或对比基准。用户补充条件、选择澄清项以及改写问题的记录，都应进入后续回归测试。

若缺失信息不影响结果，或语义层中已有经过确认的默认规则，可以继续执行，但答案中应明确展示采用的条件。系统是否需要追问，应由口径规则决定，不能依赖模型临时推断。

企业应如何判断 Text2SQL 已达到上线标准？

上线标准应按场景风险分别设定，而不是只看一个综合准确率。团队需要为结果正确性、口径符合度、权限阻断和危险语句控制分别设置门槛；高风险主题未通过时，可以继续关闭，即使其他主题已经开放。

生产运行后，应持续采集用户改写、澄清选择、评价反馈、失败分类和分析师修正后的 SQL。模型版本、Prompt、语义层或权限策略发生变化时，都要回放固定评测集，并比较新增失败与历史退化。只有离线评测、影子对照和限定范围灰度均符合既定门槛，才适合扩大开放范围。