sql-eval
LLM 生成 SQL 质量评估基准工具，支持多数据库对比
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
LLM 生成 SQL 质量评估基准工具，支持多数据库对比
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
GitHub: defog-ai/sql-eval | 744 Stars | Apache-2.0 | Python
你让 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-eval 的评测逻辑非常清晰，可以用一句话概括：让「标准答案 SQL」和「LLM 生成的 SQL」同时在真实数据库中执行，比较两者返回的结果集是否等价。
具体流程如下：
assert_frame_equal 做精确比对，包含两种模式：
┌─────────────────────────────────────────────────┐
│ 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 层是 sql-eval 的「连接器」，负责将评测任务分发给不同的 LLM 提供商。目前已支持的 Runner 包括：
openai_runner.py：OpenAI 全系列（GPT-4o、o1、o3-mini 等），支持并行请求anthropic_runner.py：Claude 3.5 Sonnet / Opus / Haikuhf_runner.py：本地 HuggingFace 模型（如 Qwen 等）gemini_runner.py / mistral_runner.py / deepseek_runner.py / together_runner.py：其他主流 APIapi_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.py，关键函数包括：
normalize_table()：标准化结果集（去重、按列名排序、处理 ORDER BY 语义）compare_query_results()：执行两段 SQL 并用 pandas assert 比对deduplicate_columns()：处理重复列名问题这套方法解决了 SQL 评测中的两大难点：
SELECT a,b vs SELECT b,a），通过列排序和行去重解决dialects.py + sqlglot/sqlparse：PostgreSQL → MySQL/BigQuery/Snowflake 等 SQL 方言转换pruning.py：NLTK + spaCy 命名实体识别，裁剪 prompt 中的无关表信息，降低 LLM 上下文干扰gen_prompt.py：将数据库 schema 转换为适合 LLM 理解的 promptllm.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）。
局限性：
defog-data 仓库才能运行上手门槛评估：
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 应用的必备工具。