BIRD-INTERACT 1.0

⚠️ 公告

请注意，在进行评估之前，当 Docker 加载数据库时，由于环境不一致，可能会偶尔出现错误（这些错误不会终止进程，但会显示在 Docker 日志中）。因此，部分数据库可能无法正确加载，导致数据库为空。这将使评估结果异常偏低。
👉 因此，我们强烈建议您在运行评估之前，先检查 Docker 日志中是否存在任何错误，并确认所有数据库是否已成功加载。

👉 我们已更新了提交指南，其中支持自定义智能体框架。请随时查看我们的详细提交指南此处。

📰 新闻

• [2026-03-29] 🔥🔥🔥 BIRD-Interact-ADK: 我们发布了基于Google ADK的实现——BIRD-Interact-ADK，采用模块化的三微服务架构（智能体、用户模拟器和数据库环境）。您可以轻松替换自己的智能体、用户模拟器或数据库环境。支持并行执行以及任何与LiteLlm兼容的LLM提供商。建议您在研究中使用此实现。

• [2026-02-08] 🔥🔥🔥 我们的**Bird-Interact论文已被ICLR 2026（口头报告）**接收！里约热内卢见哦 🇧🇷！

• [2025-11-06] 🐛 Bug修复 & 🐳 Docker更新: 将sqlglot版本更新至26.16.4，以修复用户模拟器中SQL解析器无法正确解析SQL的问题。您可以通过在bird_interact_eval环境中运行pip install sqlglot==26.16.4来解决此问题。同时，bird_interact_eval镜像也已更新，您可以拉取新镜像并重新创建bird_interact_eval容器。

• [2025-10-21] 🐳 Docker更新: 我们新增了完整数据库环境的Docker镜像，并将3个Docker镜像（基础镜像、完整数据库环境镜像以及用于a-Interact和c-Interact的评估环境镜像）推送到Docker Hub，以简化环境搭建。无需再手动下载数据库转储文件并构建镜像！

• [2025-10-08] 📝 我们的**Bird-Interact论文**现已公开发布！
  论文详细介绍了我们的交互式文本到SQL基准测试的全部细节、方法论及评估结果。
  👉 欢迎查阅，了解更多关于BIRD-Interact背后的理念。

• [2025-08-26] 🚀 我们很高兴宣布推出**BIRD-Interact-Full (600)数据集！
  这是一份极具挑战性的数据集——目前最佳的LLM模型仅能达到16.33%的成功率，其中c-Interact和a-Interact部分的成功率更是低至10.0%**。
  👉 更多详情请访问我们的项目官网。

• [2025-08-26] 📬 本周我们将向邮件列表发送真值数据与测试用例。
  若您希望提前获取，请按照网站上的说明发送邮件，即可获得自动下载链接。

• [2025-08-26] 💾 另外，我们还发布了SQLite版本的**LiveSQLBench-Lite，方便本地研究。
  完整版的LiveSQLBench-Base和-Large**也将很快推出！

• [2025-08-22] Bug修复: 在Bird-Interact-Agent代码中，我们修复了一个bug：在评估第二阶段SQL时，存储的第一阶段SQL无法成功执行，从而导致第二阶段的成功率降低。该bug仅影响那些第一阶段SQL会对数据库进行操作的任务，例如CREATE TABLE等。

🧸 概述

BIRD-INTERACT是一个交互式的文本到SQL基准测试，它通过动态交互的视角重新定义了文本到SQL的评估方式。 该环境结合了分层知识库、数据库文档以及函数驱动的用户模拟器，以重现涵盖完整CRUD操作的真实企业级环境。 它提供两种严格的测试模式：(1)被动的对话式交互和(2)主动的代理式交互，共包含600个标注任务，涵盖商业智能（BI）、CRUD操作等，每个任务都配有可执行的测试用例。 典型的评估过程中，模型与用户模拟器之间会进行1,968至5,496轮交互，而当前最先进的推理模型仅能分别解决约**24%和18%**的任务，这充分体现了该基准测试的挑战性。

✅ 两种评估模式

如上所述，BIRD-INTERACT支持两种评估模式：

• c-Interact: 对话式交互，属于被动模式，工作流程固定。相关代码和详细信息可在bird_interact_conv中找到。
• a-Interact: 代理式交互，属于主动模式，工作流程由模型主导且动态变化。相关代码和详细信息可在bird_interact_agent中找到。

🐣 精简版

我们发布了BIRD-INTERACT的精简版bird-interact-lite-exp，其中包括270个高质量的真实世界任务，专门针对PostgreSQL。这是进行快速实验的良好起点。

🦜 完整版

BIRD-INTERACT的完整版bird-interact-full是一个全面的基准测试，包含600个针对PostgreSQL的任务，覆盖广泛的SQL操作和用户查询。完整版即将发布。

BIRD-INTERACT-FULL上的模型性能结果

1. c-Interact文本到SQL性能

2. a-Interact文本到SQL性能

* 预算参数：初始预算/用户耐心预算，以我们的虚拟货币bird-coins衡量。更多详情请参阅bird_interact_agent/README.md。

交互时间缩放定律（ITS）

交互时间缩放定律（ITS）是指模型通过多轮交互能够持续提升其最终性能的能力。当这种交互性能在完全明确、无歧义的任务上超越了模型的理想化单轮性能时，我们就说该模型满足ITS定律。随着用户耐心的增加和交互轮次的累积，性能会不断提升，这表明模型能够在长时间的对话中保持有效的沟通。目前，我们只发现claude-3-7-sonnet满足ITS定律。

环境搭建

1. 运行用于bird-interact-lite数据库、bird-interact-full数据库以及评估环境的Docker容器：

如果你只想在bird-interact-lite上进行评估，可以注释掉docker-compose.yml中的postgresql_full服务，以加快环境搭建速度。

通过以下命令启动环境：

cd env
docker compose pull 
docker compose up -d

等待几分钟完成数据库初始化。

你可以通过以下命令跟踪构建进度：

docker compose logs -f --tail=100 bird_interact_postgresql_full # 或者 bird_interact_postgresql 用于 bird-interact-lite

如果完成，你应该会看到没有错误的日志，例如：

bird_interact_postgresql_full  | 2025-10-28 17:58:30.413 HKT [1] LOG:  database system is ready to accept connection

如果你之前已经创建过容器并希望重新创建，可以运行以下命令：

docker compose down -v # 此命令会移除容器及其数据卷
docker compose pull   # 从Docker Hub拉取最新镜像
docker compose up -d --force-recreate # 重新构建并启动容器。--force-recreate表示强制重新创建容器。
# 或者 `docker compose up -d --force-recreate bird_interact_eval` 只重新创建用于评估代码环境的bird_interact_eval容器。

这将使用Docker Hub上的预构建镜像运行3个容器：

• bird_interact_postgresql: 用于bird-interact-lite的PostgreSQL数据库
• bird_interact_postgresql_full: 用于bird-interact-full的PostgreSQL数据库
• bird_interact_eval: 用于a-Interact和c-Interact评估的环境。

现在，你可以通过执行以下命令来启动评估环境：

docker compose exec bird_interact_eval bash

2. （可选）手动搭建环境（如果你想从头开始构建镜像）：

   • 下载数据库转储文件
     • bird-interact-lite。解压后重命名为env/postgre_table_dumps。
     • bird-interact-full。解压后重命名为env/postgre_table_dumps_full。
   • 通过运行docker-compose.build.yml手动构建环境。

     cd env/
     docker compose -f docker-compose.build.yml build
     docker compose -f docker-compose.build.yml up -d
     

3. （推荐）检查数据库容器是否已成功构建并运行。

• 打印容器构建日志，以确保数据库成功构建且无错误：

  docker logs bird_interact_postgresql > build_bird_interact_postgresql.log 2>&1
  docker logs bird_interact_postgresql_full > build_bird_interact_postgresql_full.log 2>&1
  

  如果出现错误，日志文件中会显示“导入过程中发生错误：”字样。

• 检查数据库容器的状态是否良好。

  使用我们提供的Python脚本验证数据库元数据：

  docker compose exec bird_interact_eval bash
  cd /app/env
  python check_db_metadata.py --host bird_interact_postgresql
  python check_db_metadata.py --host bird_interact_postgresql_full
  

  预期结果：

  • bird-interact-lite：
    • 📈 数据库总数：18
    • 📋 表格总数：175
    • 🔢 列总数：2286
    • 📈 每表平均行数：1,038.48
    • 💾 总大小：207.15 MB（左右）
  • bird-interact-full：
    • 📈 数据库总数：22
    • 📋 表格总数：244
    • 🔢 列总数：2011
    • 📈 每表平均行数：1,121.19
    • 💾 总大小：272.00 MB（左右）

📦 数据集详情

数据集描述

• 数据库：完整的PostgreSQL数据库可以从鸟互动轻量版和鸟互动完整版下载。

• 数据：每个数据实例包含以下主要部分：

  • selected_database：数据库名称。
  • query：明确的用户查询。
  • amb_user_query：注入歧义后的用户查询。
  • user_query_ambiguity：注入到用户查询中的歧义。
  • non_critical_ambiguity：非关键性歧义，如排序、限制等。
  • knowledge_ambiguity：由外部知识掩盖而产生的歧义。
  • sol_sql：真实答案SQL解决方案。
  • preprocess_sql：在执行解决方案或预测之前需要运行的SQL查询。
  • clean_up_sql：测试用例执行完毕后，用于恢复数据库状态的SQL查询。
  • test_cases：一组用于验证预测修正后SQL的测试用例。
  • follow_up：标注好的后续问题。
  • external_knowledge：与特定任务相关的外部知识。

• 评估：评估代码位于./evaluation目录中。

• 整理者：BIRD团队 & Google Cloud

• 许可证：cc-by-sa-4.0

• HuggingFace 数据集卡片：bird-interact-lite 和 bird-interact-full 对应PostgreSQL；以及 mini-interact 对应SQLite。

数据集用途

为避免因自动爬取导致的数据泄露，我们未随数据一同提供GT解决方案SQL及测试用例。 请发送邮件至bird.bench25@gmail.com，标题注明[bird-interact-lite GT&Test Cases]或[bird-interact-full GT&Test Cases]，即可自动获取bird-interact-lite或bird-interact-full数据集的真实答案和测试用例。

将公开数据与真实标签和测试用例结合

然后使用以下脚本将公开数据与真实标签和测试用例结合：

以完整版为例： (1) 运行：

python combine_public_with_gt.py /path/to/bird-interact-full/bird_interact_data.jsonl /path/to/bird_interact_full_gt_kg_testcases_08022.jsonl /path/to/bird_interact_data.jsonl  # bird_interact_full_gt_kg_testcases_08022.jsonl 是真实标签字段的数据，可通过邮件向我们索取。

这将在 /path/to/bird_interact_data.jsonl 创建一个包含合并后数据的新文件。

(2) 然后用合并后的数据替换原始的公开数据：

cp /path/to/bird_interact_data.jsonl /path/to/bird-interact-full/bird_interact_data.jsonl

其他版本（如 bird-interact-lite、mini 版等）也相同。只需设置正确的公开数据路径以及真实标签和测试用例路径，然后用合并后的数据替换原始的公开数据即可。

文件夹结构

.
├── LICENSE
├── README.md
├── BIRD-Interact-ADK
│   ├── ...
│   └── README.md
├── bird_interact_conv
│   ├── ...
│   └── README.md
├── bird_interact_agent
│   ├── ...
│   └── README.md
├── evaluation
│   ├── docker-compose.yml
│   ├── env
│   ├── postgre_table_dumps
│   ├── run
│   └── src
├── materials
│   ├── ...
└── requirements.txt

关于运行 a-interact 的详细信息，请参阅 ./bird_interact_agent/README.md；c-interact 的相关信息请查阅 ./bird_interact_conv/README.md；而基于 ADK 的实现则可在 ./BIRD-Interact-ADK/README.md 中找到。

📋 待办事项清单

• 发布轻量版，bird-interact-lite（270）。
• 发布对话版，bird-interact-conv。
• 发布代理版，bird-interact-agent。
• 发布完整版 bird-interact-full（600）。
• 发布基于 ADK 的实现，BIRD-Interact-ADK。
• 对用户模拟器进行 SFT / RL 训练。

致谢

我们衷心感谢 Irina Saparina、Mohammadreza Pourreza、Mehdi Bouzouina、Hailong Li、Jiatong Shi 以及 Shinji Watanabe 教授，感谢他们富有成效的讨论和宝贵见解，这些都极大地帮助改进了本项目。

创作团队：

BIRD 团队 & Google Cloud

引用

@inproceedings{
huo2026birdinteract,
title={{BIRD}-{INTERACT}: Re-imagining Text-to-{SQL} Evaluation via Lens of Dynamic Interactions},
author={Nan Huo and Xiaohan Xu and Jinyang Li and Per Jacobsson and Shipei Lin and Bowen Qin and Binyuan Hui and Xiaolong Li and Ge Qu and Shuzheng Si and Linheng Han and Edward Alexander and Xintong Zhu and Rui Qin and Ruihan Yu and Yiyao Jin and Feige Zhou and Weihao Zhong and Yun Chen and Hongyu Liu and Chenhao Ma and Fatma Ozcan and Yannis Papakonstantinou and Reynold Cheng},
booktitle={The Fourteenth International Conference on Learning Representations},
year={2026},
url={https://openreview.net/forum?id=nHrYBGujps}
}

变更日志

• [2025-11-06] 🐛 Bug 修复 & 🐳 Docker 更新：将 sqlglot 版本更新至 26.16.4，以修复用户模拟器中 SQL 解析器无法正确解析 SQL 的问题。你可以在 bird_interact_eval 环境中通过运行 pip install sqlglot==26.16.4 来解决此问题。同时，bird_interact_eval 镜像也已更新，因此你可以拉取最新镜像并重新创建 bird_interact_eval 容器。
• [2025-10-21] 🐳 Docker 更新：新增完整数据库环境的 Docker 镜像。我们已将 3 个 Docker 镜像（基础镜像、完整数据库环境镜像以及用于 a-Interact 和 c-Interact 的评估环境镜像）推送到 Docker Hub，以方便环境搭建。无需再手动下载数据库转储文件并构建镜像！请从 Docker Hub 拉取最新镜像，并重新创建容器，例如使用 docker compose down -v && docker compose pull && docker compose up -d --force-recreate。
• [2025-08-22] 🐛 Bug 修复：修复了在评估第二阶段 SQL 时，无法成功执行第一阶段 SQL 的问题，该问题会导致第二阶段的成功率降低。此 bug 仅影响那些第一阶段 SQL 会对数据库进行操作的任务，例如 CREATE table 等。

BIRD-Interact 快速上手指南

BIRD-Interact 是一个交互式 Text-to-SQL 基准测试工具，旨在通过动态交互（对话式与代理式）重新定义 SQL 生成模型的评估方式。本指南将帮助您快速搭建环境并运行基础评估。

1. 环境准备

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

• 操作系统: Linux 或 macOS (推荐)，Windows 需使用 WSL2。
• Python 版本: 3.10 或更高版本。
• Docker: 必须安装并运行 Docker Desktop 或 Docker Engine，用于加载数据库环境。
• API Key: 准备好您所使用的 LLM 提供商（如 OpenAI, Anthropic, Google Cloud 等）的 API Key。

前置依赖检查：

python --version  # 确保 >= 3.10
docker --version  # 确保已安装

2. 安装步骤

2.1 克隆项目

首先从 GitHub 克隆仓库：

git clone https://github.com/bird-bench/BIRD-Interact.git
cd BIRD-Interact

2.2 创建虚拟环境

推荐使用 conda 或 venv 创建独立的 Python 环境：

python -m venv bird_interact_env
source bird_interact_env/bin/activate  # Windows 用户请使用: bird_interact_env\Scripts\activate

2.3 安装核心依赖

安装基础依赖包。如果遇到网络问题，可临时指定国内镜像源（如清华源）：

# 使用默认源
pip install -r requirements.txt

# 或使用国内加速源 (推荐)
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

2.4 关键组件修复与更新

根据官方最新公告，需特别注意以下两点以确保评估准确性：

1. 修复 SQL 解析器 bug：强制安装特定版本的 sqlglot。

   pip install sqlglot==26.16.4
   

2. 拉取 Docker 镜像：项目已提供预构建的 Docker 镜像（包含完整数据库环境和评估环境），无需手动下载数据库转储文件。

   # 拉取基础评估环境镜像
   docker pull birdsql/bird_interact_eval:latest
   
   # 如果需要完整数据库环境 (Full DB Env)
   docker pull birdsql/bird_interact_full_db:latest
   

3. 基本使用

BIRD-Interact 提供两种主要的评估模式：c-Interact (被动对话式) 和 a-Interact (主动代理式)。以下以最常用的 c-Interact 为例演示运行流程。

3.1 配置 API Key

在终端中导出您的 API Key（以 OpenAI 为例）：

export OPENAI_API_KEY="your-api-key-here"

注：若使用其他模型提供商，请参考对应目录下的 .env 配置说明。

3.2 运行评估脚本

进入对话式交互目录并运行评估。以下命令将启动 Docker 容器加载数据库，并使用指定模型对 Lite 版本数据集进行评估：

cd bird_interact_conv

# 运行评估示例 (请替换 model_name 和 dataset_path)
python eval.py \
    --model_name gpt-4o \
    --dataset_path ../data/bird-interact-lite-exp \
    --output_dir ./results

参数说明：

• --model_name: 您要测试的模型名称（需符合 LiteLLM 命名规范）。
• --dataset_path: 数据集路径，可使用 HuggingFace 下载的 bird-interact-lite-exp (270 任务) 或 bird-interact-full (600 任务)。
• --output_dir: 评估结果保存目录。

3.3 查看结果

运行结束后，检查输出目录中的 JSON 文件或日志，获取 Normalized Reward (标准化奖励) 和成功率指标。

⚠️ 重要提示： 在正式运行大规模评估前，请务必先检查 Docker 容器的日志，确认所有数据库已成功加载且无报错。若数据库加载失败（显示为空），会导致评估结果异常偏低。

检查命令示例：

docker logs <container_id_or_name>

更多高级用法（如自定义 Agent 架构、并行执行等）请参考项目根目录下的 BIRD-Interact-ADK 模块及官方详细文档。