docs: Text2SQL/NL2SQL评估指标目录ADR

[Zhanghoks]

概要 / Summary

本PR添加了Text2SQL/NL2SQL评估指标权威目录的架构决策记录(ADR),为SqurveBridge的论文相关工作、工程实现和Demo四层映射提供可引用的指标定义。

动机 / Motivation

当前Text2SQL评估领域存在以下问题:

1. Spider EX vs BIRD EX: 两者定义不同(列顺序敏感性、bag vs set语义),但经常被混用对比
2. EM歧义: Spider的clause-set matching (ESM) vs ROSE附录的string-EM是不同的指标
3. R-VES实现差异: Mini-Dev官方实现 vs E-SQL论文简化公式存在差异
4. NL2SQLBench指标缺失: CR/IR/ER/C2I等过程指标尚未在SqurveBridge中实现
5. 自进化反馈不清: 哪些指标适合RL训练/测试时搜索 vs 仅用于离线审计

本PR内容 / What's Changed

新增文件: docs/design/2026-09-05-text2sql-evaluation-metrics-catalog-adr.md

涵盖指标分类:

结构匹配 / Structure Matching

• EM/ESM (Yu et al. Spider EMNLP 2018)
• Component Matching / Partial F1 (Spider官方;SqurveBridge cf1_* 7组件)
• PCM-F1 (Hazoom et al. arXiv:2106.05006)
• ETM (Ascoli et al. arXiv:2407.07313)
• TSED (Song et al. ICSE-SEIP 2024 arXiv:2312.14725)
• FuncEvalGMN (Zhan et al. COLING 2025 arXiv:2407.14530)

执行语义 / Execution Denotation

• Spider EX vs BIRD EX (明确区分;不可混用)
• Soft-F1 (BIRD Mini-Dev cell-bag F1)
• Test Suite Accuracy (Zhong, Yu, Klein EMNLP 2020)
• EA_soft/EA_partial (StatBot.Swiss ACL Findings 2024)

效率 / Efficiency

• VES (BIRD公式4)
• R-VES (Mini-Dev官方bins实现;与E-SQL论文简化版不同)
• VES*/VCES (EuroMLSys 2026 arXiv:2602.21480)

模块与过程 / Module & Process (NL2SQLBench)

• Schema Linking: Precision/Recall/F1
• Code Generation: CR/IR/ER (≡EX, Improvement, Error Rates)
• Code Refinement: C2I/I2C/E2C (Correct↔Incorrect转换率;C2I>0表明revision可能有害)
• Pass@k, Oracle@k
• 当前状态: SqurveBridge尚未实现;UI显示为"—"占位符

形式化验证(离线审计) / Formal Verification (Offline Audit)

• FLEX (Kim et al. NAACL 2025;LLM裁判)
• ROSE (Pei et al. ACL 2026;Prover+Refuter;EX κ仅~25.56% vs专家)
• SpotIt (ICLR 2026 arXiv:2510.26840;有界SMT)
• LLM-SQL-Solver (Zhao et al. arXiv:2312.10321)

鲁棒性 / Robustness

• QVT (Li et al. PVLDB 2024 NL2SQL360;Query Variance Testing)

自进化反馈分层 / Metrics as Feedback

五层模型:

层次	信号类型	需要gold	用途
(A) 仅执行在线	执行成功率、超时	❌	实时反馈
(B) 执行自洽性	Self-Consistency, UCT	❌	测试时搜索
(C) 学习验证器	FuncEvalGMN, Reward Model	需训练	RL密集奖励
(D) Gold EX/结构	EX, EM, VES, CF1	✅	验证门控
(E) LLM/SMT审计	FLEX, ROSE, SpotIt	✅/❌	离线审计

关键指导:

• RL训练: gold EX或密集执行奖励
• 测试时搜索: Self-Consistency + UCT (Alpha-SQL);不使用metric bundles
• 离线审计: EM/VES/SpotIt/FLEX/C2I统计(不作为内循环奖励)

SqurveBridge实现映射 / Implementation Mapping

Demo L-strip (PR #38/#39)

当前使用:

• L1 正确性: ex, sf1, em
• L2 效率: rves, ves
• L3 结构: cf1_select, cf1_where, cf1_group, cf1_order, cf1_join, cf1_iuen, cf1_keywords
• L4 归因: error_root*

Phase 2待实现

• NL2SQLBench: cr/ir/er/c2i/i2c/e2c/schema_precision/schema_f1/pass@k
• UI处理: Phase 2前显示"—"或"N/A";绝不合成代理值

备选方案 / Alternatives Considered

❌ 仅用String-EM: 假阴性率过高
❌ 仅用单一EX: gold SQL有错误;ROSE κ~25.56%证明EX不是绝对真值
❌ ROSE/SpotIt放Demo热路径: 成本/延迟不可接受;保持为离线审计
❌ 合成NL2SQLBench代理: 误导用户;宁可显示"—"

未决问题 / Open Questions

1. NL2SQLBench实现时间线: 何时实现CR/IR/ER/C2I?(依赖eval schema扩展)
2. Soft-F1门控R-VES: 是否仅在Soft-F1 > 阈值时显示效率分数?
3. 数据集标注: Demo UI如何明确显示Spider EX vs BIRD EX?
4. L6跨方法指标: 何时实现Oracle Gap、Pairwise Disagreement?
5. TSED公式版本: 使用ICSE-SEIP δ/MaxNodes 还是 ACL 2024 1−δ/MaxNodes?

验证 / Verification

# 文档一致性验证
uv run python tools/release_check.py --skip-history

# 确认无代码变更(仅文档)
git diff main --stat

预期: 仅 docs/design/2026-09-05-text2sql-evaluation-metrics-catalog-adr.md 新增。

关联工作 / Related Work

• PR docs: Architecture Decision Record for evaluation score-bundle four-layer taxonomy #39: 四层score-bundle ADR,定义SqurveBridge keys映射
• PR docs(adr): four-layer eval L-strip for Demo Run detail #38: Demo UI L-strip ADR,定义四层显示语义
• 现有文档: docs/design/2026-08-12-multidim-eval-architecture.md (L1-L6层次)
• 代码实现: reproduce/eval/registry/builtin/, demo/api_server.py, reproduce/eval/bundle/schema.py

检查清单 / Checklist

• 遵循现有 docs/design/ ADR约定
• 基于已验证的调研(截至2026-08-28)
• 每个指标链接原始论文(15篇主要引用)
• 明确Spider vs BIRD EX区别
• 明确R-VES官方实现 vs E-SQL简化公式差异
• 明确NL2SQL360 QVT ≠ CF1指标
• 自进化反馈五层指导
• SqurveBridge keys映射(交叉引用PR docs: Architecture Decision Record for evaluation score-bundle four-layer taxonomy #39)
• Phase 2待实现清单
• 未决问题文档化
• 仅文档变更,无运行时代码修改
• 中文编写,保留英文指标名称/论文引用

参考文献 / References (15篇主要论文)

Yu et al. Spider EMNLP 2018 • Hazoom et al. arXiv:2106.05006 • Ascoli et al. arXiv:2407.07313 • Song et al. ICSE-SEIP 2024 • Zhan et al. COLING 2025 • Zhong, Yu, Klein EMNLP 2020 • StatBot.Swiss ACL Findings 2024 • BIRD官方 • EuroMLSys 2026 • Hou et al. NL2SQLBench PVLDB 2026 • Kim et al. FLEX NAACL 2025 • Pei et al. ROSE ACL 2026 • SpotIt ICLR 2026 • Zhao et al. arXiv:2312.10321 • Li et al. NL2SQL360 PVLDB 2024