BIRD-Interact 评测避坑清单:Docker 数据库加载失败、sqlglot 解析错误等 8 个常见问题全解

原创2026-10-16 16:31:551,949 阅读

BIRD-Interact 评测避坑清单:Docker 数据库加载失败、sqlglot 解析错误等 8 个常见问题全解

BIRD-Interact 是 ICLR 2026 Oral 收录的交互式 Text-to-SQL 评测基准,它通过「LLM 智能体 × 用户模拟器 × PostgreSQL 数据库」的多轮动态交互来考察模型的 SQL 能力。首次跑评测时最容易栽在 Docker 数据库加载、sqlglot 版本、Ground Truth 数据合并这些细节上。本文整理出 8 个高频问题的排查步骤与解决方案,按顺序过一遍,基本可以一次跑通完整评测流程。

先搞懂评测架构:为什么这些坑会存在

BIRD-Interact 的评测链路分三层:数据层是 Docker 里的 PostgreSQL(lite 版 18 个库 / full 版 26 个库),交互层是智能体与用户模拟器的多轮对话,评测层是带可执行测试用例的打分脚本。理解这张总图,后文每个坑的位置就都清晰了:

BIRD-Interact Text-to-SQL 评测工作流:数据库、LLM 动作与用户模拟器交互示意

两种评测模式的核心区别:

模式 特点 参考代码
c-Interact 被动对话式,固定工作流(澄清→提交→调试→追问) bird_interact_conv/
a-Interact 主动智能体式,Agent 自主决定动作,受 bird-coin 预算约束 bird_interact_agent/
ADK 版 Google ADK 模块化微服务实现,支持并行与 Oracle 自检,官方推荐用于研究 BIRD-Interact-ADK/

a-Interact 中智能体在用户模拟器与数据库环境中循环执行 Action/Observation:

BIRD-Interact a-Interact 模式评测流程:智能体与用户模拟器多轮交互

坑1:Docker 数据库加载失败,评测分数异常偏低(官方警告)

这是官方在 README 首页用 ⚠️ Announcement 特别标注的问题:Docker 加载数据库时可能因环境不一致出现报错,导致部分库为空,评测分数因此异常偏低——而且错误不会中断进程,只藏在 Docker 日志里。

正确姿势:

  1. 启动容器后等待数分钟完成初始化:
cd env
docker compose pull
docker compose up -d
docker compose logs -f --tail=100 bird_interact_postgresql_full
  1. 确认日志无 Errors occurred during import:,并出现 database system is ready to accept connection。
  2. 用官方脚本核验库元数据:Lite 应为 18 库 / 175 表 / 2286 列,Full 应为 22 库 / 244 表 / 2011 列:
docker compose exec bird_interact_eval bash
python check_db_metadata.py --host bird_interact_postgresql
python check_db_metadata.py --host bird_interact_postgresql_full

脚本位于 env/check_db_metadata.py。如果导入出错,删卷重建:

docker compose down -v
docker compose pull
docker compose up -d --force-recreate

经验法则:跑评测前先查日志 + 元数据双确认,比事后怀疑分数可靠得多。

坑2:sqlglot 解析错误,用户模拟器行为异常

用户模拟器内部用 sqlglot 的 tokenizer 对 SQL 做子句切分(见 bird_interact_conv/code/sql_parser.py)。官方在 2025-11-06 将 env/requirements.txt 中的 sqlglot 钉死为 26.16.4 以修复解析 bug。如果你的 bird_interact_eval 环境是旧镜像或旧依赖,会出现 SQL 分段错误、模拟器"答非所问"。

修复方法(二选一):

  • 在 bird_interact_eval 环境内执行:pip install sqlglot==26.16.4
  • 或拉取更新后的镜像重建评测容器:docker compose down -v && docker compose pull && docker compose up -d --force-recreate

坑3:数据缺少 sol_sql / test_cases,评测直接跑不了

公开数据集(HuggingFace 上的 bird-interact-lite / bird-interact-full)故意不包含 Ground Truth SQL 与测试用例,以防止自动爬取造成数据泄露。很多人跑通代码后才发现分数全为 0,根因就是缺字段。

解决路径:

  1. 邮件 bird.bench25@gmail.com,标题带 [bird-interact-lite GT&Test Cases] 或 [bird-interact-full GT&Test Cases],会自动收到 GT 文件。
  2. 用官方脚本把 GT 字段合并进 bird_interact_data.jsonl,再替换原文件:
python combine_public_with_gt.py \
  /path/to/bird-interact-lite/bird_interact_data.jsonl \
  /path/to/gt_kg_testcases.jsonl \
  /path/to/bird_interact_data.jsonl

脚本:combine_public_with_gt.py(ADK 版自带 BIRD-Interact-ADK/scripts/combine_public_with_gt.py)。

坑4:Lite 和 Full 数据库主机没切换,查错库

默认配置连接的是 Lite 库(bird_interact_postgresql,容器内 5432 端口):

DEFAULT_DB_CONFIG = {
    "user": "root",
    "password": "123123",
    "host": "bird_interact_postgresql",
    "port": 5432,
}

来源 evaluation/src/postgresql_utils.py。切换到 Full 数据集时必须三处对齐,漏一处就查错库:

位置 Lite Full
postgresql_utils.py 的 DEFAULT_DB_CONFIG["host"] bird_interact_postgresql bird_interact_postgresql_full
a-Interact 运行参数 默认 --db_host=bird_interact_postgresql_full(见 run_batch_experiments.sh)
用户模拟器提示词 prompts.py prompts_for_bird_interact_full.py

坑5:连接被拒绝——评测脚本没跑在 Docker 评测容器里

评测容器 bird_interact_eval 与两个 PostgreSQL 容器通过 Docker 内部网络互通,评测代码的默认 host 是容器名而非 localhost。在宿主机直接 python eval_bird_interact_batch.py 会连不上库。正确入口永远是:

cd env
docker compose exec bird_interact_eval bash
cd /app

然后按 evaluation/run/run_eval.sh 的方式执行批量评测脚本 evaluation/src/eval_bird_interact_batch.py。

坑6:run_gpt.sh 的 project_root 是占位符,路径全错

c-Interact 的流水线 bird_interact_conv/pipeline/run_gpt.sh 默认所有路径基于 project_root="YOUR-ROOT" 拼接,不改就会生成一堆不存在的路径、产出空结果文件。运行前需:

坑7:单样本模式过期、提示词版本与预算参数选错

  • 单样本模式已过时:官方明确 run_experiment.sh 对应的单样本代码维护较少,正式实验一律用批量模式:bash run_batch_experiments.sh --user_sim_prompt_version=v1(v1 用于论文 Lite 实验,v2 更稳健、用于 Full 实验)。
  • 两种模式的"耐心"参数含义不同:c-Interact 中 patience=3 是额外澄清轮数(见 run_gpt.sh 第 9 行);a-Interact 中 patience 是 bird-coin 预算加成,论文默认 6。预算公式为 起始 6 + 2×歧义数 + 耐心值,实现在 batch_run_bird_interact/main.py。对照动作成本表核对参数是否符合预期:

BIRD-Interact a-Interact 智能体动作空间与 bird-coin 预算成本表

  • Phase-2 偏低的历史 bug 已修复:2025-08-22 曾修复"phase-1 SQL 含 CREATE TABLE 等操作时 phase-2 评测失败"的问题,分数偏低时可先确认代码为最新版本。

坑8:用错版本与目录——Mini-Interact(SQLite)是另一套代码

mini_interact/ 是面向 SQLite 的轻量版(300 题),目录结构与主项目几乎同构,但文件全部带 _sqlite 后缀:评测用 wrapper_evaluation_sqlite.py,推理用 infer_api_system_sqlite.py,数据目录也是 data/bird-mini-interact/。直接套 PostgreSQL 版脚本会找不到数据库。

如果你只是想快速验证自己改动的智能体,推荐用 ADK 版(BIRD-Interact-ADK/README.md):三个微服务(system_agent:6000 / user_simulator:6001 / db_environment:6002)+ 编排器,支持并行与任意 LiteLLM 供应商:

BIRD-Interact-ADK 三微服务架构:编排器、智能体、用户模拟器与数据库环境

其中 --mode oracle 用 Ground Truth SQL 跑全流程、不发 LLM 请求,是验证"数据→执行→评测"管线是否正常的最佳自检手段;跑通 oracle 再跑真实模型,可排除环境因素。

避坑自检清单

# 检查项 判定标准
1 Docker 库日志 无 import 错误,出现 ready to accept connection
2 元数据核验 Lite 18 库/175 表,Full 22 库/244 表
3 sqlglot 版本 26.16.4
4 GT 字段 bird_interact_data.jsonl 含 sol_sql、test_cases
5 DB 主机 与数据集(lite/full)一致
6 运行位置 在 bird_interact_eval 容器内
7 提示词版本 Lite 用 v1、Full 用 v2,勿混用
8 Oracle 自检 --mode oracle 通过后再跑真实评测

把这 8 关全部过掉,你的 BIRD-Interact 评测结果就具备可比性了——毕竟当前最强模型也只有约 24% / 18% 的成功率,分数的每一分都值得认真对待。

登录后查看全文
BIRD-Interact