BIRD-Interact 评测避坑清单:Docker 数据库加载失败、sqlglot 解析错误等 8 个常见问题全解
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 个库),交互层是智能体与用户模拟器的多轮对话,评测层是带可执行测试用例的打分脚本。理解这张总图,后文每个坑的位置就都清晰了:
两种评测模式的核心区别:
| 模式 | 特点 | 参考代码 |
|---|---|---|
| c-Interact | 被动对话式,固定工作流(澄清→提交→调试→追问) | bird_interact_conv/ |
| a-Interact | 主动智能体式,Agent 自主决定动作,受 bird-coin 预算约束 | bird_interact_agent/ |
| ADK 版 | Google ADK 模块化微服务实现,支持并行与 Oracle 自检,官方推荐用于研究 | BIRD-Interact-ADK/ |
a-Interact 中智能体在用户模拟器与数据库环境中循环执行 Action/Observation:
坑1:Docker 数据库加载失败,评测分数异常偏低(官方警告)
这是官方在 README 首页用 ⚠️ Announcement 特别标注的问题:Docker 加载数据库时可能因环境不一致出现报错,导致部分库为空,评测分数因此异常偏低——而且错误不会中断进程,只藏在 Docker 日志里。
正确姿势:
- 启动容器后等待数分钟完成初始化:
cd env
docker compose pull
docker compose up -d
docker compose logs -f --tail=100 bird_interact_postgresql_full
- 确认日志无
Errors occurred during import:,并出现database system is ready to accept connection。 - 用官方脚本核验库元数据: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,根因就是缺字段。
解决路径:
- 邮件 bird.bench25@gmail.com,标题带
[bird-interact-lite GT&Test Cases]或[bird-interact-full GT&Test Cases],会自动收到 GT 文件。 - 用官方脚本把 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" 拼接,不改就会生成一堆不存在的路径、产出空结果文件。运行前需:
- 把 run_gpt.sh 第 12 行 的
project_root改成项目根目录(容器内通常为/app); - 按需在 bird_interact_conv/code/config.py 配置系统模型名与 API Key(
US_model_name/system_model_name也可在同文件头部调整)。
坑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。对照动作成本表核对参数是否符合预期:
- 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 供应商:
其中 --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% 的成功率,分数的每一分都值得认真对待。



