💬 NLP

SQL Query Engine: A Self-Healing LLM Pipeline for Natural Language to PostgreSQL Translation

本文介绍了"SQL Query Engine"，这是一个开源的自托管服务，通过包含自动模式内省、多策略解析及基于 PostgreSQL 诊断信息的迭代自修复机制的两阶段 LLM 流水线，将自然语言问题转化为经过验证的只读 PostgreSQL 查询，并在多个基准测试中显著提升了执行准确率。

原作者： Muhammad Adeel Ijaz

发布于 2026-04-21

📖 1 分钟阅读☕ 轻松阅读

CC BY 4.0

原作者： Muhammad Adeel Ijaz

原始论文采用 CC BY 4.0 许可（http://creativecommons.org/licenses/by/4.0/）。 ✨ 这是对下方论文的AI生成解释。它不是由作者撰写或认可的。如需技术准确性，请参阅原始论文。阅读完整免责声明

这篇技术报告介绍了一个名为 SQL Query Engine（SQL 查询引擎）的开源工具。简单来说，它是一个**“智能翻译官 + 自我纠错专家”**，能把普通人说的“大白话”自动变成数据库能听懂的“专业指令”（SQL 查询语句），并且如果指令错了，它还能自己发现并修改，直到跑通为止。

为了让你更容易理解，我们可以把这个系统想象成一家**“高级餐厅的厨房”**。

1. 核心角色：谁在做什么？

顾客（你）：你不需要懂复杂的数据库代码，只需要像点菜一样用自然语言提问。
- 例子：“帮我看看上个月卖得最好的产品是什么？”
翻译官（LLM 大模型）：这是餐厅里的“主厨助手”。它负责把你的“大白话”翻译成厨房（数据库）能听懂的“专业指令”。
- 现状：以前，如果助手翻译错了（比如把“上个月”理解错了，或者写错了菜名），这道菜就废了，或者直接把错误端给顾客。
试菜员（自我修复循环）：这是本系统的核心创新。在菜端给顾客之前，有一个严格的“试菜员”。
- 如果指令执行报错（比如“找不到这个菜”），试菜员不会直接放弃，而是把错误报告（比如“菜名拼错了”）拿回来，重新交给“翻译官”。
- 翻译官看到错误报告后，会想：“哦，原来是我拼错了，我改一下。”然后重新生成指令。
- 这个过程会重复几次，直到指令完美运行，或者找到最好的结果。

2. 这个系统是怎么工作的？（两阶段流程）

这个系统像是一个**“双保险”**的流水线：

第一阶段：生成与翻译

动作：系统先快速扫描一下数据库的“菜单”（表结构），然后让 AI 根据你的问题生成一条 SQL 指令。
创意比喻：就像主厨看了一眼冰箱里有什么食材，然后根据你的要求写了一张“做菜清单”。
亮点：不管 AI 输出的是代码块、JSON 格式还是纯文字，系统都能像“万能解码器”一样把它提取出来，不需要 AI 必须按特定格式说话。

第二阶段：试错与修复（自我愈合）

动作：生成的指令会在数据库里试运行。
- 情况 A（成功）：如果指令跑通了，而且有结果，系统会立刻把结果给你（这叫“早期接受”），不再让 AI 瞎改，防止把对的改错。
- 情况 B（失败）：如果报错了（比如“列名不存在”），系统会抓取详细的错误信息（就像医生看 X 光片一样精准），然后把这些信息反馈给 AI。
- 修复：AI 根据错误信息，像“修理工”一样修改指令，再次尝试。
创意比喻：
- 如果菜做错了（比如盐放多了），试菜员会告诉厨师：“太咸了，下次少放点。”厨师改完再试。
- 关键点：如果第一次做的菜其实是对的，只是刚好没人吃（结果为空），系统会记住这个“最好的半成品”，而不是盲目地让它重做，避免越改越错。

3. 为什么它很厉害？（三大亮点）

像“自动驾驶”一样的自我修复：
- 以前的系统，AI 写错一次就完了。这个系统像一辆有自动驾驶功能的汽车，如果撞了墙（报错），它会自动倒车、调整方向，再试一次，直到成功。
- 效果：在测试中，这种“自我修复”让准确率提高了 4.6% 到 9.3%。这听起来不多，但在复杂的数据库世界里，这相当于从“及格”变成了“优秀”。
绝对安全（只读模式）：
- 你不用担心 AI 会把数据库里的数据删掉或修改。系统给 AI 戴上了“手铐”——只读权限。
- 比喻：就像你带朋友参观博物馆，朋友可以指指点点（查询），但绝对不允许他拿走展品或涂画墙壁（修改/删除）。这是由底层技术强制执行的，AI 再聪明也越界不了。
像“聊天机器人”一样好用：
- 它可以直接接入你现有的聊天工具（比如 Open WebUI），就像你在和 ChatGPT 聊天一样。你不需要学习任何新软件，直接问问题，它就能从数据库里把答案吐出来。

4. 实际效果如何？

研究人员在两个地方做了测试：

模拟考场（合成数据）：就像做数学题。最好的模型（Llama 4 Scout）在自我修复后，准确率从 48% 飙升到 57.3%，而且没有一次把原本做对的题改错。
真实战场（BIRD 基准）：这是用真实的、混乱的企业数据做的测试。虽然难度更大，但系统依然让准确率提升了 4.6%，达到了 49% 的通过率，超过了之前很多著名的系统。

5. 总结

SQL Query Engine 就是一个**“懂数据库的、会自我反省的、绝对安全的”**智能助手。

以前：你问问题 -> AI 猜答案 -> 错了就报错 -> 你只能干瞪眼。
现在：你问问题 -> AI 猜答案 -> 错了 -> AI 自己看错误报告 -> AI 自己改答案 -> 直到给你正确答案。

它让普通人也能轻松驾驭复杂的数据库，就像让一个不懂开车的人也能通过“自动驾驶”安全地到达目的地一样。而且，它是开源的，任何人都可以免费使用或部署在自己的服务器上。

SQL Query Engine 技术报告详细总结

1. 研究背景与问题 (Problem)

将自然语言转换为可执行的 SQL 查询（Text-to-SQL）一直是数据库和自然语言处理领域的核心挑战。尽管大型语言模型（LLM）显著提升了该领域的性能（如在 Spider 基准测试上达到 85% 以上的执行准确率），但在实际生产环境中仍面临以下关键瓶颈：

错误恢复能力差：传统的单轮生成方法在 LLM 生成错误查询时，通常直接返回数据库错误给用户或静默失败。实际上，许多错误（如列名拼写错误、类型转换错误、过滤条件过严）是可以通过提供诊断信息让 LLM 自我修复的。
生产环境的不确定性：现实世界的数据库模式（Schema）庞大、动态且缺乏文档，静态的 Schema 表示难以适应。
安全性与可观测性：企业环境要求系统不能修改数据（只读），并且需要实时监控查询修复过程。
基准测试与现实的差距：在 Spider 等合成基准上表现良好的模型，在 BIRD（大规模真实世界数据库）基准上表现往往大幅下降，且现有系统缺乏针对真实错误（如空结果集、复杂类型转换）的鲁棒修复机制。

2. 方法论 (Methodology)

本文提出了 SQL Query Engine，一个开源的、自托管的、基于 LLM 的双阶段管道系统，旨在通过“执行 grounded"的自愈合（Self-Healing）机制将自然语言转换为经过验证的 PostgreSQL 查询。

核心架构

系统由三个外部依赖（OpenAI 兼容的 LLM 端点、PostgreSQL 数据库、Redis 实例）和一个 FastAPI 服务组成，包含六个核心模块：

阶段一：查询生成 (Query Generation)
- 动态 Schema 内省：首次请求时，系统自动查询 information_schema 获取表结构，并提取样本行。
- LLM 辅助描述：将原始 Schema 传递给 LLM，生成人类可读的 Schema 描述（涵盖表用途、列语义、关系等），并缓存至 Redis 以支持多轮对话。
- 多策略响应解析：不依赖结构化输出 API，而是通过五步级联策略从 LLM 输出中提取 SQL：(1) 直接 JSON 解析，(2) 嵌入 JSON 提取，(3) Markdown 代码块提取，(4) SELECT 正则匹配，(5) 纯文本回退。此设计兼容任何输出格式的模型（包括 Qwen3、DeepSeek-R1 等推理模型）。
阶段二：评估与自愈合 (Evaluation & Self-Healing)
- 执行与诊断：生成的 SQL 在 PostgreSQL 中执行。如果失败或返回空结果，系统捕获完整的 PostgreSQL 诊断信息（包括 SQLSTATE 错误代码、详细消息、提示 hints 和 Python 堆栈跟踪）。
- 迭代修复循环：将错误诊断反馈给 LLM，要求其生成修正后的查询。此过程最多重复 $N$ 次（默认 5 次）。
- 安全机制：
  - Early-Accept（早期接受）：如果查询执行无错且返回非空结果，立即返回，不再进行 LLM 重新评估，防止“画蛇添足”导致正确查询变错。
  - Best-Result Tracking（最佳结果追踪）：在重试耗尽时，返回所有尝试中最好的部分结果，而不是直接失败。
  - 忽略 LLM 自我评估：系统不信任 LLM 对查询有效性的自我判断（isValid 字段始终设为 False），仅以实际执行结果为准。
- 只读强制：在数据库驱动层（psycopg3）强制设置连接为只读模式，从底层杜绝数据修改风险。

实时流与 API

实时流：利用 Redis Pub/Sub 和 Server-Sent Events (SSE) 实时向客户端推送修复进度（如 Schema 描述、修复尝试、思考过程）。
双 API 接口：提供原生 REST API 和完全兼容 OpenAI 的 /v1/chat/completions 接口，使得 Open WebUI 等现有工具无需修改即可接入。

3. 关键贡献 (Key Contributions)

执行 grounded 的自愈合循环：提出了一种结合完整 PostgreSQL 诊断信息（SQLSTATE、hints）的迭代修复机制，无需人工干预即可自动纠正错误。
无结构化输出的通用解析器：设计了一种多策略解析器，能够从不规范的 LLM 输出（JSON、代码块、纯文本）中可靠提取 SQL，降低了对特定模型输出格式的依赖。
防止退化的安全机制：通过“早期接受”和“最佳结果追踪”机制，有效解决了迭代修复中常见的“将正确查询改错”的退化问题。
生产级部署特性：实现了基于 Redis 的会话级 Schema 缓存、细粒度的只读控制、实时进度流以及 OpenAI 兼容接口，使其易于集成到现有工作流中。
全面的实证评估：在合成基准和 BIRD 真实世界基准上，对 5 种不同 LLM 后端进行了详细评估。

4. 实验结果 (Results)

研究在两个基准上进行了评估：一个包含 75 个问题的合成基准（3 个数据库）和 BIRD 基准（437 个问题，11 个数据库，从 SQLite 迁移至 PostgreSQL）。

合成基准结果

准确率提升：自愈合循环显著提升了执行准确率。最佳模型 Llama 4 Scout (17B) 从单轮生成的 48.0% 提升至 57.3%（+9.3 个百分点），且零退化（Regressions）。
模型差异：不同模型对修复的响应不同。Llama 4 Scout 和 GPT-OSS-20B 表现最佳；而 GPT-OSS-120B 和 Qwen3-32B 在某些情况下出现轻微退化，主要是因为初始正确但返回空结果的查询被错误地触发修复。
难度相关性：自愈合对“困难”类查询提升最大（Llama 4 Scout 从 5.6% 提升至 44.4%），对简单查询影响较小。

BIRD 基准结果（真实世界）

最佳表现：GPT-OSS-120B 在 BIRD 上表现最佳，从 44.4% 提升至 49.0%（+4.6 个百分点）。
与基线对比：该结果超过了原始 BIRD 论文中 ChatGPT (39.3%) 和 Claude 2 (42.7%) 的表现，尽管未使用特定微调。
退化分析：在 BIRD 上退化率较高（17-24 例/模型），主要原因是许多真实查询的正确答案本身就是空结果集，触发了不必要的修复循环。这验证了“早期接受”机制在处理非空结果时的有效性，但也暴露了空结果判断的局限性。
延迟成本：自愈合带来的延迟增加约为 1.9-2.5 倍（合成数据）或更高（BIRD），但吞吐量仍保持在可接受范围（12-30 问/分钟）。

5. 意义与影响 (Significance)

填补了基准与生产的鸿沟：证明了通过执行反馈进行自我修复是提升 Text-to-SQL 在复杂、动态生产环境中鲁棒性的有效途径。
安全与可靠性：通过驱动层强制只读和“早期接受”机制，解决了 LLM 生成 SQL 在安全方面的核心顾虑，使其具备生产部署的可行性。
模型无关性与灵活性：系统不依赖特定模型或微调，支持任何 OpenAI 兼容端点，使得用户可以根据成本和质量需求灵活选择模型（从本地小模型到云端大模型）。
开源与可复现：作为一个完全开源的项目，它提供了从 Schema 内省到查询修复的完整参考实现，推动了社区在 Text-to-SQL 领域的进一步发展。

总结：SQL Query Engine 通过引入基于诊断信息的迭代自愈合机制和严格的安全控制，成功将 LLM 生成的 SQL 准确率在真实场景下提升了 4.6% 至 9.3%，为构建可靠、安全且易于集成的自然语言数据库接口提供了重要的技术参考。