Sqlsure：AI生成SQL的确定性语义检查工具

背景

随着大语言模型（LLM）在代码生成领域的普及，文本到 SQL（Text-to-SQL）工具日益流行，AI 能够自动编写 SQL 查询。然而，一个查询即使语法完全正确、运行无报错，也可能返回看似合理但实际上有严重问题的结果——例如通过 JOIN 导致收入重复计数、对平均值再次求和、意外暴露患者标识符等语义错误。传统数据库不会捕获这些错误，静态代码检查工具（linter）也检测不到，甚至让 LLM 审查自己生成的 SQL 同样无能为力。这种“无声错误”在数据分析和生产系统中可能造成严重损失，急需一种可靠的语义验证机制。

核心内容

Sqlsure 是一个确定性语义检查工具，专为 AI 生成的 SQL 设计。它能在查询执行之前，以 0.1 毫秒的速度确定性地判断 SQL 是否存在语义违规，且不依赖任何网络调用或数据库连接。其核心原理是：将团队已经在数据模型中声明的语义事实（如 dbt 中的 unique 测试、relationship 测试、meta 标签）转化为可执行的规则，而不是依赖 LLM 或外部模型。规则本质上是字典查找——相同的输入规则总会输出相同的裁决，全程离线可审计。

Sqlsure 在两大 Text-to-SQL 基准（Spider 和 BIRD）的黄金答案上进行了验证：2,568 条专家编写的查询被扫描，共标记 45 个违规，零误报。其中包含 BIRD 开发集的一个黄金答案，因 Sqlsure 锁定的 bug 类别被证明偏差高达 8 倍，以及一个已向上游报告的模式缺陷。

当 Sqlsure 无法验证某项语义时，它会明确回答“can't verify”，而不是说“looks fine”——诚实的不确定性被视为一项特性。

每个被拒绝的查询都附带机器可操作的修复建议（machine-actionable fix），因此 AI agent 可以自动修复：草稿 → 检查 → 修复 → 检查 → 执行。在基准测试中，逐字应用修复建议后，10/10 次都能生成通过检查的查询。

使用方式

Sqlsure 提供了多种集成方式：

• CI gate：在 PR 合并前阻塞，例如当查询可能造成重复计数时，退出码 1。
• MCP 服务器：AI agent 在执行前必须通过 Sqlsure 的检查（如 claude mcp add sqlsure）。
• 库嵌入：check() 函数可直接集成到任何 Text-to-SQL 产品或 agent 框架中。提供了 SemanticGate 包装器，用于 Vanna/WrenAI 风格的生成器；还提供语义评估指标，用于评分 NL2SQL 输出（执行准确率无法捕捉的语义维度）。
• 安装：pip install sqlsure，一行代码即可使用：from sqlsure import SemanticModel, check; violations = check(sql, model)。

规则来源（语义模型）

Sqlsure 可以从多种来源构建其语义规则书（SemanticModel），无需学习新语言或手动维护模型：

• dbt（现成可用）：读取 manifest.json 或 schema.yml，团队已有的测试（unique → grain，relationship → join cardinality，meta tags → 可安全性求和字段）直接转化为可执行的语义。
• 明文 PK/FK 声明：支持直接声明主键/外键（已在基准审计中使用）。
• 实时数据库：通过 sqlsure.introspect 从数据库目录（如 SQLite 的 PRAGMA、PostgreSQL/MySQL 的 information_schema）构建规则书。例如，从 BIRD 自己的数据库文件中恢复出了基准发布模式中缺失的两个外键。
• 手写 JSON：提供示例模板。
• OSI 和 WrenAI MDL：集成目录中已有加载器，可将 OSI 规范或 WrenAI 的 MDL 格式自动解析为 SemanticModel（主键→grain，关系→join 边，度量→加性等）。
• Cube、Snowflake 语义视图：适配器正在开发中；引擎内部只处理一个统一的 SemanticModel。

安全与供应链

• 确定性：相同 SQL + 相同规则书 = 相同裁决，规则都是字典查找，可逐行审计。
• 离线：零网络调用，SQL 永远不会离开本机。
• 无数据访问：只解析查询文本，从不连接数据库。
• 无遥测：从不收集任何信息（详见 SECURITY.md）。
• 供应链安全：仅通过 PyPI Trusted Publishing（OIDC）从带标签的提交发布，CI 运行公开；运行时依赖只有两个。

文档与测试

项目提供了全面的文档：METRICS.md（16/16 规则测试，100% 召回率 / 0% 假阳性）、TEST-REPORTS.md（真实仓库如 Mattermost 的仓库、Fivetran 包、dbt 的 jaffle shop 的测试报告）、EVIDENCE.md（每项声明都链接到可重复的测量）、ARCHITECTURE.md（从 ELI5 到专家级解释并附中间输出）、FOR-DUMMIES.md（零基础概念）、INTEGRATIONS.md（GitHub Action、pre-commit、MCP、Snowflake UDF / Cortex Agent 工具、查询历史审计）、MCP.md（MCP 服务器文档）、CONTRIBUTING.md（贡献规则和加载器的方法）。

许可证：Apache-2.0，官网 sqlsure.ai。

关键要点

• 确定性检查：始终返回相同裁决，不含 LLM 随机性，规则基于字典查找，可审计。
• 零误报基准：在 Spider 和 BIRD 的 2,568 条黄金查询上，45 个标记均为真阳性，零误报。
• 可操作修复：每个违规都附带具体修复建议，AI agent 可自动迭代修复，测试中 10/10 成功。
• 支持多种语义层：dbt manifest、明文 PK/FK、实时数据库 introspection、手写 JSON、OSI、WrenAI MDL 等，无需额外学习成本。
• 完全离线与私密：零网络调用，不连接数据库，不收集任何遥测数据。
• 供应链安全：仅通过 PyPI Trusted Publishing 发布，公共 CI，仅两个运行时依赖。
• 轻量高速：0.1 ms 内完成检查，适合嵌入 CI 管道或 AI agent 循环。
• 诚实的不确定性：无法验证时明确告知“can't verify”，避免虚假安全。
• 开源友好：Apache-2.0 许可证，丰富的文档和集成示例。

意义与影响

Sqlsure 填补了 AI 生成 SQL 验证链中的一个关键空白：语法正确性之外，语义正确性长期缺乏自动化的、确定性的检查手段。传统方法依赖人工审查或 LLM 自我评估，既不靠谱也不可重复。Sqlsure 通过将团队已有的数据模型声明（如 dbt 测试）转化为可执行的语义约束，让校验过程变得透明、离线、可审计，且与现有工具链无缝集成。

对于使用 Text-to-SQL 的产品（如数据查询助手、自然语言分析平台），Sqlsure 提供了一种防御机制，防止 AI 产生“看起来对但实际错”的查询，从而避免错误数据被用于决策。其确定性特性使得法规合规、数据治理场景下可以信赖；无数据访问的设计也降低了对敏感数据的暴露风险。此外，它为 AI agent 自修复循环提供了可靠的裁判，加速了从草稿到正确查询的迭代。

从社区角度看，Sqlsure 作为 Apache-2.0 开源项目，为数据库语义检测领域引入了新的方法论——基于现有模型声明（而非额外标注或机器学习）的确定性验证。这有望推动语义层标准化，并鼓励更多数据团队在建模阶段就声明语义关系，从而让下游工具受益。其与 dbt、Cube、Snowflake 等多路径的适配计划，也体现了广泛的兼容性，可能成为数据生态中一个基础性的验证层。