SQL-Eval：LLM SQL 生成质量评估的行业基准工具

GitHub: defog-ai/sql-eval | 744 Stars | Apache-2.0 | Python

---

一、当 AI 写出错误 SQL 时，你如何发现？

你让 GPT-4o 写了一条查询月活用户的 SQL，兴冲冲地在数据库里跑了一下——没有报错，返回了 10 万行数据，看起来完全正确。

但真正的答案是 12 万行。你的 SQL 漏掉了 2 万个「当月注册但未消费」的用户。

这不是语法错误，而是语义错误——传统数据库测试框架根本测不出来。

这就是 defog-ai/sql-eval 试图解决的核心问题：如何科学、系统地评估 LLM 生成的 SQL 到底「对不对」？

---

二、项目起源：从「感觉差不多」到「数据说了算」

sql-eval 由新加坡 AI 创业公司 Defog 开源。Defog 的核心产品是一款面向数据库的自然语言查询工具——用户用自然语言提问，AI 生成 SQL 查询。

在产品开发过程中，Defog 团队发现 LLM 生成 SQL 的评测存在一个根本性困难：LLM 写出的 SQL 即使在语法上完全正确，也可能在业务语义上出错。而这种错误无法通过简单的语法检查或 SQL Linter 发现。

为了解决这个问题，Defog 在 Spider 基准数据集的基础上，设计了一套自有的评测方法论，并在 2024 年初将代码开源，很快成为 AI-SQL 领域最活跃的开源评估工具之一。

---

三、核心原理：让「两段 SQL」赛跑

sql-eval 的评测逻辑非常清晰，可以用一句话概括：让「标准答案 SQL」和「LLM 生成的 SQL」同时在真实数据库中执行，比较两者返回的结果集是否等价。

具体流程如下：

1. 输入自然语言问题：如「找出每个月的活跃用户数」
2. 获取标准答案 SQL：从评测题库中取出预存的 ground-truth SQL
3. 调用 LLM 生成 SQL：通过 Runner 将问题发送给 OpenAI/Claude 等模型
4. 两段 SQL 同时执行：在目标数据库（PostgreSQL/MySQL/BigQuery 等）上分别运行
5. 结果集比对：用 pandas 的 assert_frame_equal 做精确比对，包含两种模式：
   • Exact Match：两结果集的每一行、每一列完全一致
   • Subset Match：LLM 的结果集是标准答案的子集（允许生成更宽松的查询）
6. 聚合报告：输出 CSV，包含准确率、执行时间、Token 消耗、成本等指标

---

四、架构解析：Runner-Eval-Utils 三层设计

┌─────────────────────────────────────────────────┐
│                    main.py                       │
│              （CLI 入口，参数解析）                │
└──────────────────────┬──────────────────────────┘
                       │
         ┌─────────────┼─────────────┐
         ▼             ▼             ▼
┌─────────────┐ ┌──────────┐ ┌──────────┐
│Runner Layer │ │Eval Layer │ │Utils Layer│
│（LLM 调用）  │ │（执行比对）│ │（辅助功能）│
│             │ │          │ │          │
│openai_runner│ │ eval.py  │ │  llm.py  │
│anthropic_...│ │          │ │pruning.py│
│  hf_runner  │ │          │ │dialects..│
│  api_runner │ │          │ │questions.│
│ gemini_...  │ │          │ │reporting.│
└─────────────┘ └──────────┘ └──────────┘
                       │
                       ▼
              ┌─────────────────┐
              │  Target Database│
              │(PG/MySQL/BQ/...)│
              └─────────────────┘

Runner 层：统一接口调用所有主流 LLM

Runner 层是 sql-eval 的「连接器」，负责将评测任务分发给不同的 LLM 提供商。目前已支持的 Runner 包括：

• openai_runner.py：OpenAI 全系列（GPT-4o、o1、o3-mini 等），支持并行请求
• anthropic_runner.py：Claude 3.5 Sonnet / Opus / Haiku
• hf_runner.py：本地 HuggingFace 模型（如 Qwen 等）
• gemini_runner.py / mistral_runner.py / deepseek_runner.py / together_runner.py：其他主流 API
• api_runner.py：通用自定义 API 端点，兼容任意 LLM

每个 Runner 返回统一的 LLMResponse 数据结构，包含 content、model、time、input_tokens、output_tokens、cost_in_cents 等字段，由 utils/llm.py 中的成本表（LLM_COSTS_PER_TOKEN）自动计算 API 费用。

Eval 层：结果集比对的科学方法

核心逻辑在 eval/eval.py，关键函数包括：

• normalize_table()：标准化结果集（去重、按列名排序、处理 ORDER BY 语义）
• compare_query_results()：执行两段 SQL 并用 pandas assert 比对
• deduplicate_columns()：处理重复列名问题

这套方法解决了 SQL 评测中的两大难点：

1. 等价性判断：SQL 结果在数学上等价但字面不同（如 SELECT a,b vs SELECT b,a），通过列排序和行去重解决
2. 语义宽松度：允许「子集匹配」模式，接受 LLM 生成比标准答案更宽松的查询

Utils 层：SQL 方言与元数据裁剪

• dialects.py + sqlglot/sqlparse：PostgreSQL → MySQL/BigQuery/Snowflake 等 SQL 方言转换
• pruning.py：NLTK + spaCy 命名实体识别，裁剪 prompt 中的无关表信息，降低 LLM 上下文干扰
• gen_prompt.py：将数据库 schema 转换为适合 LLM 理解的 prompt
• llm.py：Token 计数与 API 成本计算

---

五、支持模型与评测模式

sql-eval 支持极其丰富的评测配置组合：

配置项	选项
数据库	PostgreSQL / MySQL / BigQuery / Snowflake / SQLite / SQL Server
模型	OpenAI GPT / Claude / Gemini / Mistral / DeepSeek / Qwen / 本地 HF
推理模式	标准生成 / Chain-of-Thought / K-shot
元数据策略	完整 schema / NER 裁剪后
并行度	1~N 线程可配置
输出	CSV / W&B / GCS / Slack

特别值得一提的是 Chain-of-Thought 推理模式（prompt_cot.md），通过在 prompt 中引导 LLM 先写出推理步骤再生成 SQL，显著提升了复杂查询的准确率。README 中还专门针对不支持 system prompt 的 o1 系列模型提供了替代 prompt 文件（prompt_openai_o1.json）。

---

六、局限性与上手门槛

局限性：

1. 没有 Docker 一键部署：项目不提供 Dockerfile 或 docker-compose，需要手动安装数据库
2. 依赖外部评测数据源：必须同时克隆 defog-data 仓库才能运行
3. 结果准确性依赖题库质量：Ground-truth SQL 如果本身有疏漏，评测结果也会失真
4. 非 AI 爱好者友好：CLI 界面，无 Web UI，需要数据库和 Python 经验

上手门槛评估：

• 需要准备至少一个数据库实例（Postgres 最推荐）
• 需要至少一个 LLM API Key（OpenAI 最成熟）
• 需要对 SQL 执行计划和结果集语义有基本理解
• 推荐阅读时间：1-2 小时可完成首次评测

---

七、行业意义：AI-SQL 评测标准化进程

sql-eval 的出现填补了 AI-SQL 领域的一个关键空白。在它之前，LLM 生成 SQL 的质量评估往往是各公司内部的黑盒流程，缺乏可比较的基准。

随着 sql-eval 的推广，AI-SQL 领域逐渐形成了这样的评测范式：用统一题库 + 统一数据库 + 统一比对方法，让不同模型、不同提示策略、不同微调方案之间的横向比较成为可能。

截至目前，该项目已被用于评估 GPT-4o、Claude 3.5 Sonnet、o1-mini/o1-preview、Qwen2.5-Coder 等主流模型的 SQL 生成能力，评测结果被多个 AI 报告和研究论文引用。

Defog 团队在开源工具的同时，也将 200+ 道自建评测题库公开（涵盖 Spider 扩展集 + Defog 内部数据集），为社区提供了宝贵的评测资源。

---

总结： sql-eval 是 AI-SQL 领域最实用的开源评估工具之一，通过科学的「双 SQL 执行比对」方法，为 LLM 生成 SQL 的质量提供了客观、可量化的评测标准。适合 AI 开发者、LLM 研究者和数据库工程师使用，是评估和迭代 AI-SQL 应用的必备工具。