BIRD-CRITIC 1.0 (SQL)

新闻

• 📢 [2026-03-24] 我们发布了BIRD-Critic GT & Test Cases Auto-Reply System，支持通过邮件请求自动发送完整数据集（包括sol_sql和test_cases），邮箱地址为📧 bird.bench25@gmail.com，主题标签为[bird-critic-1 GT&Test Cases]。
• 📢 [2026-03-23] 我们发布了BIRD-Critic-SQLite，该数据集包含500个高质量的用户问题，专注于真实的SQLite数据库应用。
• 📢 [2026-01-08] 我们最近更新了评估代码（特别是remove_distinct函数）。请从我们的GitHub仓库拉取最新代码。
• 📢 [2025-07-09] 我们在网站上公布了人类表现分数！三个排行榜上显示的分数均来自数据库专家的人工评估，他们可以使用标准工具（如数据库教材、官方文档或IDE），但不能使用AI助手。当允许另一组具有相同专业知识的人员使用AI工具（ChatGPT、Claude或Gemini）时，性能提升至Open版的83.33、PG版的87.90以及Flash版的90.00，这表明人机协作在SQL问题解决中具有巨大潜力。
• 📢 [2025-06-28] 我们在arXiv上发布了论文SWE-SQL（又名BIRD-CRITIC）。
• 📢 [2025-06-09] 我们发布了bird-interact-lite，该版本具备多轮对话和代理式交互功能，适用于现实世界中模糊且具有挑战性的文本转SQL任务。
• 📢 [2025-06-08] 我们发布了bird-critic-1.0-postgresql，这是一个包含530个复杂任务的单一方言SQL问题调试数据集。
• 📢 [2025-05-30] 我们很高兴发布LiveSQLBench-Base-Lite，其中包含18个终端用户级别的数据库和270个任务（180个仅SELECT任务，90个管理任务）。每个任务都涉及基于外部知识的明确且简单的用户查询，SQL语句难度介于中等至困难之间。

🧸 概述

BIRD-Critic 1.0推出了一种全新的SQL基准测试，旨在评估一项关键能力：大型语言模型（LLMs）是否能够在真实世界的数据库环境中诊断并解决用户问题？

该基准测试包含600个开发用任务和200个保留的分布外（OOD）测试任务。BIRD-CRITIC 1.0基于四种主流开源SQL方言中的真实用户问题构建：MySQL、PostgreSQL、SQL Server和Oracle。它不仅限于简单的SELECT查询，还涵盖了更广泛的SQL操作，以反映实际的应用场景。此外，还配备了一个优化的基于执行的评估环境，用于进行严格而高效的验证。

✅ 验证流程

BIRD-CRITIC中的每项任务都经过人工专家在以下几个方面的验证：

1. 在BIRD环境中重现错误，以防止数据泄露。
2. 为每项任务精心设计测试用例：
   • Soft EX：此指标可用于评估仅包含SELECT语句的任务。
   • Soft EX + 解析：此指标可用于评估具有特定用户需求或细化要求的任务。
   • 测试用例：对于DBA任务，例如CRUD（创建、读取、更新、删除），测试用例旨在评估逻辑的正确性。这对于需要多个连续SQL查询才能解决的用户问题也非常有效。
   • 查询执行计划：对于涉及效率提升或运行时错误的用户任务，可以通过QEP（查询执行计划）在算法层面评估解决方案SQL查询。
3. 通过PostgreSQL模板和Docker快速搭建评估沙盒。
4. 创建不同规模和专业领域的全新RDB。

🐣 精简版

我们发布了BIRD-Critic的精简版bird-critic-1.0-flash-exp，其中包括200个高质量的PostgreSQL用户问题，用于开发真实世界的应用程序。我们通过以下方式精选任务：

• 收集并理解真实的用户问题。
• 提炼问题定义和SQL知识。
• 在BIRD环境中重现错误和解决方案。
• 设计测试用例进行评估。

🦜 开放版

BIRD-CRITIC 1.0的开放版bird-critic-1.0-open是一个综合性的基准测试，包含570个任务，覆盖MySQL、PostgreSQL、SQL Server和Oracle四种SQL方言。它涵盖了广泛的SQL操作和用户问题。

BIRD-CRITIC 1.0 Open版模型性能结果

排名	模型名称	分数	等级
1	o3-mini-2025-01-31	34.50	🏆 领先
2	deepseek-reasoner (r1)	33.67	🌟 精英
3	o1-preview-2024-09-12	33.33	🌟 精英
4	claude-3-7-sonnet-20250219(thinking)	30.67	🌟 精英
5	gemini-2.0-flash-thinking-exp-01-21	30.17	🌟 精英
6	grok-3-beta	29.83	💎 卓越

Open版的完整结果可在此处查看：这里。 Bird-CRITIC 1.0 Flash版的结果可在此处查看：这里

🕊️ PostgreSQL版

bird-critic-1.0-pg是一个包含530个高质量用户问题的数据集，专注于真实的PostgreSQL数据库应用。

代理在 BIRD-CRITIC 1.0 PG 上的性能结果

关键发现：

• 代理式工作流通过迭代的环境交互，显著提升了大语言模型在调试任务中的表现。
• SQLACT 在所有模型上均优于 ToolACT，这表明在处理复杂调试场景时，SQL 更丰富的动作空间具有明显优势。

🦅 BIRD-CRITIC 1.0 的完整数据集

BIRD-CRITIC 1.0 基准测试提供了以下几种配置：

1. bird-critic-1.0-flash-exp：精简版，包含 PostgreSQL 上的 200 个实例。
2. bird-critic-1.0-open：完整版，涵盖 MySQL、PostgreSQL、SQL Server 和 Oracle，共 570 个实例。
3. bird-critic-1.0-postgresql：专为 PostgreSQL 设计的版本，包含 530 个实例。
4. bird-critic-1.0-bigquery：精简版，包含 BigQuery 上的 100 至 200 个实例。

📦 数据集详情

数据集描述

• 数据库： 完整数据库可从 Google Drive 下载。更多详情请参阅 快速评估 部分。
• 数据： 每个数据实例包含以下主要部分：
  • db_id：数据库名称。
  • query：用户查询在 BIRD 环境中重写的版本。
  • issue_sql：用户编写的有缺陷的 SQL 查询。
  • sol_sql：正确答案的 SQL 解决方案。
  • preprocess_sql：在执行解决方案或预测之前需要运行的 SQL 查询。
  • clean_up_sql：在测试用例之后运行的 SQL 查询，用于撤销对数据库所做的任何更改。
  • test_cases：一组用于验证预测修正后的 SQL 的测试用例。
  • efficiency：如果该问题需要优化，则为真；通过查询执行计划 (QEP) 来衡量成本。
  • external_data：如果有外部 JSON 数据，则包含在此字段中。
• 基线： 基线代码位于 ./baseline 目录中。
• 评估： 评估代码位于 ./evaluation 目录中。
• 策划者： BIRD 团队 & Google Cloud
• 许可证： cc-by-sa-4.0
• HuggingFace 数据集卡片： bird-critic-1.0-flash-exp

数据集用途

为避免因自动爬取导致的数据泄露，某些字段（如 sol_sql 和 test_cases）未包含在公开数据集中。如需完整数据集，请发送邮件至：📧 bird.bench25@gmail.com，主题标注为 [bird-critic-1 GT&Test Cases]，我们将在 30 分钟内自动发送给您。

从 HuggingFace 使用数据集

您可以通过以下命令从 HuggingFace 下载数据集：

from datasets import load_dataset
# 加载闪存版数据集
dataset = load_dataset("birdsql/bird-critic-1.0-flash-exp")
print(dataset["flash"][0])

# 加载开放版数据集
dataset = load_dataset("birdsql/bird-critic-1.0-open")
print(dataset["open"][0])

或者您可以使用提供的脚本下载开放版数据集，并将其拆分为不同的方言版本。

cd baseline/data
python pull_data.py \
  --schema_path path/to/open_schema.jsonl \
  --input_path path/to/input.jsonl \ # 输入 JSONL 文件的路径（如果您想从 HuggingFace 下载数据集，此路径可以为空）
  --output_folder path/to/output_dir # 拆分文件的输出文件夹

💨 快速评估

文件夹结构

.
├── LICENSE
├── README.md
├── baseline
│   ├── data
│   ├── outputs
│   ├── run
│   └── src
├── evaluation
│   ├── docker-compose.yml
│   ├── env
│   ├── mssql_table_dumps
│   ├── mysql_table_dumps
│   ├── oracle_table_dumps
│   ├── postgre_table_dumps
│   ├── run
│   └── src
├── materials
│   ├── ...
└── requirements.txt

环境设置

要运行基线代码，您需要安装以下依赖项：

conda create -n bird_critic python=3.10 -y
conda activate bird_critic
pip install -r requirements.txt

生成

您还需要在 config.py 文件中设置模型名称（例如 gpt-4o-2024-08-06）以及 API 密钥。然后您可以运行以下命令来生成输出：

# 生成提示
cd baseline/run
bash generate_prompt.sh

# LLM 推理，需在 config.py 中设置 API 密钥
bash run_baseline.sh

生成的输出将保存在 ./baseline/outputs/final_output/ 目录中。

评估

我们使用 Docker 提供一个一致的环境来运行基准测试。设置环境的步骤如下：

1. 首先从 Google Drive 下载 PostgreSQL、MySQL、SQL Server 和 Oracle 数据库。
2. 解压文件夹，并将其保存在 ./evaluation 目录下，分别命名为 postgre_table_dumps、mssql_table_dumps、mysql_table_dumps 和 oracle_table_dumps。
3. 构建 Docker Compose：

cd evaluation
docker compose up --build

4. 与数据库交互 您可以使用 evaluation/src/{dialect}_utils.py 文件中的 perform_query_on_{dialect}_databases() 函数与各个数据库进行交互。该函数将返回查询结果。
5. 在 so_eval_env 容器内运行评估脚本：

docker compose exec so_eval_env bash
cd run
bash run_eval.sh 

您必须在 run_eval.sh 脚本中指定要评估的方言。选项包括：

• postgresql
• mysql
• sqlserver
• oracle 评估报告文件将保存在与输入文件相同的文件夹中。如果您希望为每个实例生成日志文件，可以在 run_eval.sh 脚本中将 --logging 设置为 true。

📄 论文

如果您觉得我们的工作有所帮助，请引用如下：

@article{li2025swe,
  title={SWE-SQL: Illuminating LLM Pathways to Solve User SQL Issues in Real-World Applications},
  author={Li, Jinyang and Li, Xiaolong and Qu, Ge and Jacobsson, Per and Qin, Bowen and Hui, Binyuan and Si, Shuzheng and Huo, Nan and Xu, Xiaohan and Zhang, Yue and others},
  journal={arXiv preprint arXiv:2506.18951},
  year={2025}
}

📋 待办事项清单

• 发布精简版，bird-critic-1.0-flash (200)。
• 开源代码和排行榜页面。
• 发布完整版 bird-critic-1.0-open (570 个实例，涵盖 4 种方言)。
• 发布完整版 bird-critic-1.0-postgresql (530 个 PostgreSQL 任务)。
• 发布 SIX-GYM (Sql-fIX)，包含 2000 多个类似健身房的训练环境。
• 发布经过训练的代理式基线 BIRD-Fixer。
• 更新代理式 (SQL-Act) 基线。

创作团队：

BIRD 团队 & Google Cloud

BIRD-CRITIC-1 快速上手指南

BIRD-CRITIC-1 是一个用于评估大语言模型（LLM）在真实数据库环境中诊断和解决用户 SQL 问题能力的基准测试工具。它支持 MySQL、PostgreSQL、SQL Server 和 Oracle 等多种方言，涵盖从简单查询到复杂 CRUD 操作及性能优化的多种场景。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux, macOS 或 Windows (需支持 Docker)
• Python 版本: 3.10 或更高版本
• 核心依赖:
  • conda (推荐用于环境管理)
  • docker 和 docker compose (用于构建隔离的数据库评估沙箱)
  • git
• API 密钥: 如果您计划运行基线模型推理，需要准备好对应 LLM 服务商的 API Key (如 OpenAI)。

安装步骤

1. 克隆项目与创建环境

首先克隆代码仓库并创建独立的 Python 虚拟环境：

git clone <repository_url>
cd BIRD-CRITIC-1

# 创建并激活 conda 环境
conda create -n bird_critic python=3.10 -y
conda activate bird_critic

# 安装 Python 依赖
pip install -r requirements.txt

2. 获取数据集

公共 HuggingFace 数据集仅包含部分字段（为防止数据泄露，sol_sql 和 test_cases 等关键字段被隐藏）。

方式 A：使用 HuggingFace Lite/Open 版本（快速体验）

from datasets import load_dataset

# 加载 Flash 精简版 (PostgreSQL, 200 条)
dataset = load_dataset("birdsql/bird-critic-1.0-flash-exp")
print(dataset["flash"][0])

# 加载 Open 完整版 (多 dialect, 570 条，不含完整答案)
dataset = load_dataset("birdsql/bird-critic-1.0-open")
print(dataset["open"][0])

方式 B：获取完整评估数据集（含标准答案与测试用例） 若需进行完整的本地评估，请发送邮件至 📧 bird.bench25@gmail.com，邮件主题务必标注：[bird-critic-1 GT&Test Cases]。系统将在 30 分钟内自动回复包含完整数据集的下载链接。

3. 配置数据库沙箱

评估过程依赖 Docker 容器运行真实的数据库实例。

1. 下载完整的数据库转储文件（PostgreSQL, MySQL, SQL Server, Oracle）：Google Drive 下载链接。
2. 解压下载的文件，并将文件夹重命名后移至 ./evaluation 目录下，结构如下：
   • postgre_table_dumps
   • mssql_table_dumps
   • mysql_table_dumps
   • oracle_table_dumps
3. 构建并启动 Docker 环境：

   cd evaluation
   docker compose up --build
   

基本使用

1. 配置模型

编辑 baseline/run/config.py 文件，填入您的模型名称（例如 gpt-4o-2024-08-06）和对应的 API Key。

2. 生成提示词与推理

进入基线运行目录，执行脚本生成 Prompt 并调用 LLM 进行推理：

cd baseline/run

# 生成提示词
bash generate_prompt.sh

# 运行基线模型推理 (需确保 config.py 中已配置 API Key)
bash run_baseline.sh

推理结果将保存在 ./baseline/outputs/final_output/ 目录中。

3. 执行评估

在 Docker 环境运行正常且已生成模型输出后，即可运行评估脚本对比模型生成的 SQL 与标准答案（需拥有完整数据集权限）。评估逻辑位于 ./evaluation 目录中，支持基于执行结果（Execution Accuracy）、解析匹配及查询执行计划（QEP）的多维度打分。