做 Text2SQL 项目这大半年我最大的感触是把自然语言变成一条能执行、还查得对的 SQL难的不是让模型开口说话而是让它说出来的每一句都经得起检查。模型生成 SQL 的能力已经很成熟了无论是早期基于 seq2seq 的方案还是现在以 LLM 为核心的生成链路都能输出像模像样的语句。但真把这条 SQL 丢到生产库上一跑问题就会接踵而至语法错误、表名瞎编、条件漏掉、查出来一堆无关数据严重的甚至直接把生产库拖垮。SQL 检查就是这条流水线上最关键的那道质检闸门。这篇内容我打算把 Text2SQL 链路里 SQL 检查这件事讲透。适合正在做大模型应用、数据问答平台、BI 增强分析以及任何打算把 LLM 接到数据库上的人看。我会从为什么要检查、到底查什么、一条检查流水线怎么配再到我实际踩过的坑按实战顺序一条一条说。1. 为什么 SQL 检查是 Text2SQL 里绕不开的一环1.1 模型生成 SQL 的“幻觉”从哪来Text2SQL 本质上是把自然语言映射到结构化查询语言属于结构化生成任务。但 LLM 是 token 级自回归生成它在输出每个 token 时只知道“概率最高”并不知道自己拼出来的整条语句是不是真的和数据库 schema 对应。这就是“幻觉”的根源它不是在查字典而是在做概率推理。在实际项目里幻觉高发在几个地方。第一是 schema 太长表多、字段多的时候单次 prompt 塞不全模型就会凭印象编出表名或者列名比如把user_id写成userid把order_items写成order_item。第二是列名相似同一张表里有created_time和update_time模型很容易选错一个。第三是训练语料带来的惯性模型见过太多公开数据集里的 SQL会把那些库的表结构套到你的业务表上。这里我想强调一个关键认知依赖 prompt 里的“请严格遵守数据库结构”这类提示完全不够。提示词是软约束模型对它的遵循度不稳定尤其是对话历史一长、schema 信息变多之后规则很容易被稀释。SQL 检查要解决的就是把这些“概率上可能错”的部分用硬性的代码逻辑兜住。1.2 不检查 SQL 会发生什么几种典型事故拿真实场景举例。用户对着数据平台问“把测试数据清掉”如果模型生成了一条不带 WHERE 的DELETE FROM test_records开发环境里跑一下没事生产环境上哪怕漏了一条记录也会变成事故。这不是危言耸听很多 Text2SQL 项目上线前最大的顾虑就是这类高危操作。另一种情况是语义偏差。用户问“近 7 天订单金额”模型给出的 SQL 里有订单金额字段却没有时间过滤条件或者把时间条件写死成了一个固定日期。结果就是报表数据全错业务方过来问责而这个错从 SQL 语法上看完全正常只有做语义层校验才能发现。还有一种事故是性能炸弹。用户问“对比所有区域的销售情况”模型生成了三张表的 JOIN但 JOIN 条件写错导致笛卡尔积。一执行几千万行级别的大表瞬间把数据库 CPU 打满整个业务系统都跟着卡顿。这些例子都指向一个结论SQL 检查不能只停留在“能不能跑”还要管“查得对不对”“跑得安不安全”。2. Text2SQL 的 SQL 检查到底查什么2.1 语法层先让模型的 SQL“能跑”语法检查是整个检查体系的地基。做这层的原因很简单数据库在执行一条 SQL 之前会先做语法解析任何括号不匹配、引号缺失、关键字拼写错误都会直接抛异常。我们提前用自己的解析器检查一遍可以避免把明显有问题的 SQL 发送到数据库端。我推荐用 sqlglot 这个库它是个纯 Python 的 SQL 解析器和转译器支持多种方言。用它可以快速把 SQL 解析成抽象语法树AST一旦解析失败说明 SQL 存在语法问题。import sqlglot def syntax_check(sql, dialectmysql): try: sqlglot.parse_one(sql, dialectdialect) return True, 语法检查通过 except Exception as e: return False, f语法错误: {e}这里有一个细节sqlglot 的parse_one只对单条语句有效如果模型输出了多条语句需要用parse方法遍历每一条。多语句注入本身也是安全上的红线建议在检查层直接禁止多条执行只允许单条 SELECT。def multi_statement_check(sql, dialectmysql): try: statements sqlglot.parse(sql, dialectdialect) return len(statements) 1, f不支持多语句共 {len(statements)} 条 except Exception as e: return False, f语法错误: {e}如果项目用的是企业内部数据库比如某国产数据库或者 Hive、ClickHouse 之类sqlglot 对部分方言的老版本语法支持有限这里建议解析失败时不要立刻返回错误而是标记为“需人工确认”再交给 LLM 重写避免误杀。2.2 语义层跑通了不代表查对了通过语法层之后SQL 已经是一条语法合法的语句但离“正确”还很远。语义检查的核心是把 SQL 和数据库 schema、以及用户的原始意图放在一起做交叉验证。第一步是表名和列名校验。从 AST 里提取所有用到的表名和列名和元数据里的真实 schema 比较from sqlglot import exp def validate_identifiers(sql, schema_tables, schema_columns, dialectmysql): ast sqlglot.parse_one(sql, dialectdialect) for table in ast.find_all(exp.Table): table_name table.name if table_name not in schema_tables: return False, f表不存在: {table_name} for column in ast.find_all(exp.Column): column_name column.name table_name column.table if table_name: cols schema_columns.get(table_name, []) if column_name not in cols: return False, f列不存在: {table_name}.{column_name} else: # 未指明表名时遍历所有涉及表 matched any(column_name in cols for cols in schema_columns.values()) if not matched: return False, f列不存在: {column_name} return True, 标识符校验通过第二步是条件完整性检查。处理用户问题时我会把“过滤条件”作为显式任务交给模型输出在结构化返回里单独标注时间范围、业务维度、排序字段等而不是只让它拼一段 SQL。这样检查层就能拿着这些标注去 SQL 里对照少了哪个条件一目了然。第三步是聚合逻辑与排序方向。用户问“最高”“最多”“最近”这些词有明确的映射MAX、COUNT、ORDER BY DESC。我把这些映射规则也做成硬规则SQL 里出现与意图相反的聚合或排序时直接打回。补充一点语义检查永远做不到 100% 自动但它可以把明显错误拦截在九成以上。剩下的边缘 case要靠执行计划和用户确认兜底。2.3 安全层高危操作与数据越权安全层是我在项目里优先级最高的一层宁可拦错不能放过。核心思路是“默认拒绝白名单放行”只允许 SELECT其他任何写操作必须显式配置后才会放行。静态规则能拦截大部分问题禁止直接匹配到DROP、TRUNCATE、ALTER、CREATE、GRANT等 DDL 关键字或 AST 节点UPDATE和DELETE必须带有 WHERE 子句且 WHERE 不能为空条件强制添加 LIMIT默认 100 行防止一次拉全表禁止多语句拼接执行SELECT *默认拦截要求显式列出字段防止列越权用 sqlglot 的 AST 可以直接判断 DELETE 或 UPDATE 有没有 WHEREdef check_danger_ops(sql, dialectmysql): ast sqlglot.parse_one(sql, dialectdialect) for node in ast.find_all(exp.Delete, exp.Update): if where not in node.args: return False, f禁止无 WHERE 的写操作: {node.sql()} for expr in ast.find_all(exp.Drop, exp.TruncateTable, exp.Alter, exp.Create): return False, f禁止 DDL 操作: {expr.sql()} return True, 安全规则校验通过除了语句本身还要做权限映射。每个用户或角色能访问的表来自后台的权限配置检查层在通过静态规则后还要把 SQL 涉及的所有表拿去和权限清单比对。这个动作必须在 SQL 真正执行之前完成一旦发现越权访问就拒绝执行避免数据泄漏。2.4 性能层检查执行计划即使一个 SQL 语法正确、语义对、也安全它仍然可能把数据库压垮。性能检查的核心手段是 EXPLAIN它不会真正执行查询而是让数据库给出执行计划。执行计划里重点看几类信号表的访问类型是ALL全表扫描还是index/range/ref/const预计扫描行数 rows 是否过大是否有Using filesort或Using temporary多表 JOIN 时是否用上了索引。把这些指标交给规则引擎超过阈值就直接拦截。def explain_check(connection, sql): explain_sql fEXPLAIN {sql} with connection.cursor() as cursor: cursor.execute(explain_sql) rows cursor.fetchall() for row in rows: if row.get(type) ALL: return False, f存在全表扫描: 表 {row.get(table)} if Using filesort in row.get(Extra, ): return False, 存在文件排序建议优化索引 return True, 执行计划检查通过除了 EXPLAIN实际执行时还要设置硬限制数据库连接层面启用只读事务、设置 statement 超时时间、限制最大返回行数。这样就算静态检查漏掉了一个慢查询数据库本身也能在造成破坏之前把它掐掉。3. 实操一条 SQL 检查流水线的落地配置理论部分说完接下来是这套检查体系在项目里的实际样子。我没有把所有检查逻辑写在一个函数里而是按分层方式设计每一层都可以独立开关和配置方便在不同业务域里复用。3.1 第一级静态规则与关键词过滤第一级跑得最快开销几乎可以忽略所以我在这个阶段尽量把能拦的先拦住。它主要包含两部分一是基于 AST 的规则判断二是基于词法模式的黑名单匹配。配置上我用一个 JSON 文件来管理规则开关和阈值{ allowed_statements: [SELECT], blocked_keywords: [DROP, TRUNCATE, ALTER, GRANT, REVOKE], force_limit: 100, block_select_star: true, block_multi_statements: true }在这个层级代码逻辑就是把 SQL 解析成 AST然后逐条跑规则。被拦下来的 SQL 会返回给用户一个可理解的提示比如“禁止删除表操作”而不是抛出一个底层异常。这里有个小经验提示信息写得越具体后面 LLM 自纠错的成功率就越高。3.2 第二级LLM 自纠错与语义对齐静态规则拦截后对于“语法错误”“标识符错误”这类问题我不会直接把失败返回给用户而是调用一次 LLM 自纠错。做法是把原始问题、第一次生成的 SQL、检查器给出的错误信息、相关表的 schema 片段一起发给同一个模型让它重新生成。def llm_self_correct(original_question, bad_sql, error_msgs, schema_prompt): prompt f 你是一个 SQL 修复助手。用户的问题是{original_question} 当前生成的 SQL{bad_sql} 校验器发现了以下问题{error_msgs} 相关信息{schema_prompt} 请重新生成一条能正确执行的 SQL只输出 SQL不要解释。 response llm.generate(prompt) new_sql extract_sql(response) return new_sql自纠错最多重试两次超过直接放弃避免模型陷入无限循环。经过这一级语法错误和标识符错误能修复很大一部分因为这些错误的信息很明确模型完全有依据去改。语义对齐这块我目前用两条腿走路。一条是把用户问题里的限定词拆出来和 SQL 里的条件做映射比如“只查已支付订单”映射到status PAID“按时间倒序”映射到ORDER BY created_time DESC。另一条是让 LLM 反向解释把 SQL 转成一句中文描述和用户原始问题做相关性打分相关性过低就判定语义不一致。3.3 第三级EXPLAIN 试跑与执行保护安全检查和语义校验都通过之后SQL 会进入试跑环境。这个环境连接到实际的业务库但所有操作都被约束在安全范围里。连接配置上我建议单独建一个只读账号或使用事务回滚。MySQL 可以设置max_execution_time来限制单条语句运行时间PostgreSQL 可以用statement_timeout参数SQL Server 也有对应的 query timeout。最稳妥的版本是把试跑池指向一个从库或只读副本再从源头避免写入风险。在试跑阶段我会用 EXPLAIN 拿执行计划然后根据业务规模设置阈值预估扫描行数超过某个值就拦截JOIN 数量超过限制就降级返回列包含大字段TEXT、BLOB时就裁剪或提示。通过试跑之后SQL 才真正交给执行模块去取数据。这里要强调一个观点试跑和真正执行之间时间窗口内数据库状态可能已经变了可能上次 EXPLAIN 还能用索引这次因为统计信息更新就变成全表扫描。所以生产执行时前面提到的超时和 LIMIT 保护不能因为试跑通过就撤销。3.4 失败兜底与用户反馈闭环不管检查层多完善总会有边缘 case 漏过去。所以我在执行层也做了兜底SQL 执行异常时捕获错误信息同时把这条 SQL 和错误一起回传给用户让用户知道发生了什么而不是看到一个空的查询结果。更重要的是反馈闭环。用户在查询结果右侧点“结果正确”或“结果错误”拿到用户的确认后把正确的 SQL 沉淀到 few-shot 示例库。下次遇到相似问题模型会参考这些人工确认过的样例从源头上降低生成错误的概率。这一步是把 Text2SQL 从一个“一次性模型调用”升级成“持续学习系统”的关键。4. 常见问题与排查技巧实录4.1 常见问题速查表现象可能原因排查方法解决方案SQL 报语法错误生成了方言不适配的语句查看错误详情确认方言在解析和转译阶段指定 dialect必要时用 sqlglot 转译列不存在列名被模型改写把列名误写提取出来自纠错时补充 schema 片段与相似列名提示查询结果为空值条件不符合实际数据对比 SQL 中值条件与数据分布提示用户调整描述条件值由参数映射而非硬编码查询超时全表扫描或缺少索引查看执行计划优化索引加 LIMIT限制扫描行数用户反馈越权权限清单未同步检查后台权限配置权限变更后刷新缓存或定期从元数据中心同步4.2 我踩过的三个坑先说第一个坑只做语法检查就上线。项目早期我图省事只对生成 SQL 做了 sqlglot 解析认为“能跑就等于正确”。结果用户问“各品类销售额最高的是哪一天”模型生成了语法完全正确但聚合逻辑错误的 SQL查出来的结果和业务结论对不上。这个问题在测试集上根本看不出来只有让业务方实际去用才发现。从此我意识到SQL 检查的语义层一定不能省。第二个坑DELETE 无 WHERE 的测试事故。我有一套 SQL 检查规则但最初只应用在了 SELECT 上默认所有 Text2SQL 场景都是只读查询。直到一次联调模型在生成一段自然语言分析时“不小心”生成了一条 DELETE 语句幸好目标库是测试环境数据可以恢复但那次之后我把“默认拒绝写操作”作为最高优先级规则写死不再做任何假设。第三个坑EXPLAIN 结果解析用错字段。不同数据库的 EXPLAIN 输出字段差别很大MySQL 5.x 有 rows 和 typeMySQL 8.0 多了一层 JSON 结构PostgreSQL 又是另一套格式。最初我按 MySQL 字段硬编码解析换到别的库直接报错。现在我把执行计划解析封装成适配层按数据库类型分别解析兼容性好了很多。4.3 检查体系怎么持续迭代SQL 检查规则不是写好就不动的。它需要随业务和数据一起迭代我的做法是把线上拦截日志和用户反馈收集起来定期分析那些“通过了检查但用户仍标记错误”的 SQL抽出来看是哪个环节没拦住然后把新规则补进对应层级。另外schema 总是在变的新表、新字段、字段改名都会影响标识符校验。我建议从元数据管理系统同步 schema 信息并设置定时刷新而不是把表清单硬编码在项目里。检查层拿到的是实时 schema标识符校验的准确率才有保证。上面这些规则和代码都是我在项目里反复验证过、相对通用的一套方案。你要是正在做类似的事可以从语法检查加高危操作拦截开始先跑起来再逐步补语义和性能层。刚开始不要求全但那条安全底线一定要在第一天就立好。