Cupertino 搜索质量评估体系:Cranfield 范式下 P@1/MRR/NDCG 量化评测方法论
Cupertino 搜索质量评估体系:Cranfield 范式下 P@1/MRR/NDCG 量化评测方法论
Cupertino 是一款本地 Apple 文档爬虫与 MCP 服务器,它的搜索质量评估体系把"新数据库到底变好没有"变成了可复现的数字:50 条人工设计的查询语料、P@1 / MRR / NDCG@10 三个排名指标、配对 Wilcoxon 与 McNemar 统计检验,构成一套完整的 Cranfield 范式量化评测流水线。这篇文章带你从指标定义到真实审计战果,看懂这套体系如何运作。
1. 为什么搜索质量必须量化评估 🔍
Cupertino 会周期性重建 search.db:语料扩容(更多 Apple framework 被索引)、AST 抽取增强、FTS5 权重调整、schema 变更……每次新构建出炉,团队都要回答同一个问题——两个 search.db 文件 A 和 B,B 的搜索质量是更好、更差还是没变?
设计上明确否掉了所有"偷懒"做法(见 docs/design/search-quality-eval.md):
- ❌ 跑几条查询"肉眼判断"——8 条精选查询是轶事,不是评估,少于 30 条查询时排名指标几乎没有区分度
- ❌ 比较文档行数——数量只反映召回侧信号,对排序质量零信息量
- ❌ 让 LLM 当裁判——截至 2025 年底,IR 领域不接受 LLM 作为记录级证据
而量化评估对 Cupertino 尤其重要,因为它服务的核心用户恰恰是 AI 编码代理:代理一次会话只有 3~5 条 MCP 结果的 token 预算,搜索结果排在第几名,直接决定它拿到的是正确 API 还是幻觉素材。
2. Cranfield 范式:搜索评测的方法论基石 📐
这套体系的方法论底座是信息检索领域的 Cranfield 范式(Cranfield paradigm)。用新手友好的话说,它规定了一类"系统对比"实验的标准姿势:
- 固定文档集:两个待对比系统各自索引自己的语料;
- 固定查询集(query corpus):一组预先设计好的、代表真实用户意图的查询;
- 相关性判定(qrels / ground truth):每条查询预先声明"什么算正确结果";
- 逐查询计算排名指标,再聚合比较。
Cupertino 的 Phase 1 做了一个务实的简化:ground truth 不靠人工逐条标注,而是用**"正确答案 URI 正则"**——例如查询 Hashable 的正则锚定到 apple-docs://swift/hashable。50 条查询与正则直接内嵌在 scripts/eval/search-quality-phase1.py 源码中,可读、可版本化、可扩展(超过 200 条再迁移到 TSV)。
3. 三大核心指标:P@1、MRR 与 NDCG@10 怎么算 📊
每条查询会取 top-10 结果,与正确正则比对后计算四个指标(定义见设计文档 §6.2):
| 指标 | 定义 | 直觉 |
|---|---|---|
| P@1 | 排名第 1 是否命中(0/1) | "一查即中"率 |
| MRR | 1 ÷ 首个正确结果的名次;top-10 内无命中记 0 | 正确结果"多靠前"的倒数 |
| P@k | top-k 内命中数 ÷ k | 前 k 条里捞到几个 |
| NDCG@10 | Σ relᵢ / log₂(i+2),二元相关性 | 越靠后的命中,折扣越大 |
举例:正确答案排在第 2 位 → MRR 贡献 0.5;排第 1 位 → 1.0;top-10 没出现 → 0。NDCG@10 中,top-1 命中值得 1.0,top-2 值得 0.63,top-10 只值 0.29。
两个新手容易踩的坑,项目里都给出了诚实说明:
- P@5 看起来偏低是正常的:每条查询只有一个规范正确答案,单查询 P@5 上限只有 0.2;
- NDCG@10 可能大于 1:当正则合法地匹配多个兄弟 URI(如 framework-root 模式)时增益会累加——这是已知的记账特性,指标仍可用于配对比较。
4. 8 类查询分类学:不同问题用不同指标 🗂️
把每类查询都当同一种问题处理是错的。设计文档定义了 Apple 平台开发搜索的 8 类查询(§1.4),每类"正确"的含义与适配指标都不同:
| 类 | 场景 | 示例查询 | 适配指标 |
|---|---|---|---|
| A 规范查找 | "X 定义在哪" | Hashable |
MRR、P@1 |
| B framework 根 | "打开这个框架" | SwiftUI |
MRR、P@1 |
| C 缩写/同义词 | 缩写路由到规范框架 | NFC → CoreNFC |
MRR(依赖 synonyms 表) |
| D CamelCase 片段 | 复合标识符的一部分 | Grid 应召回 LazyVGrid |
P@5、P@10 |
| E 弃用感知 | 现代 Swift 形应压过旧 Obj-C 形 | URLSession vs NSURLSession |
成对符号检验 |
| F 跨源规范 | 概念存在于多个权威源 | Swift 6 并发提案 | 逐源 MRR |
| G 散文/概念 | 多词问题,无单一规范 URI | actor 重入语义 | R-Precision / NDCG@10 |
| H 符号属性 | 按属性/签名找符号 | @MainActor 的 View 属性 |
仅 P@k(MRR 无意义) |
Phase 1 只覆盖 A、B 两类,其余各自有独立语料与审计文档(如 docs/audits/search-quality-acronym-baseline-v1.2.0.md、docs/audits/search-quality-deprecation-baseline-v1.2.0.md)。按类报告是强制要求——把八类指标折成一个"综合分"会掩盖真实的权衡取舍。
5. 评估流水线:从查询语料到审计档案 🏭
所有 phase 脚本共享同一套骨架,契约在 docs/audits/eval-harness-standard-v1.0.md 中固化,公共库是 scripts/eval/lib_harness.py(查询结果 dataclass、聚合指标、McNemar/Wilcoxon 配对检验、分桶、JSON 输出、argparse 契约)。各 phase 只提供三样东西:自己的语料、score_query 打分函数、Markdown 审计写入器。
流水线一次跑通是这样的:
查询语料 → 逐条调用
cupertino search --format json --limit 10(30 秒超时、只读)→ 解析 top-10 URI → 逐查询计算 P@1 / MRR / P@5 / NDCG@10 → 聚合 + 配对检验 → 输出 JSON 全量转储 + Markdown 审计。
每个 phase 暴露完全一致的 CLI 参数,支持单臂基线、双臂配对、--smoke 冒烟(只跑 1 条 fixture,<5 秒,供 CI 使用)三种模式:
python3 scripts/eval/search-quality-phase1.py \
--arm-a-binary /opt/homebrew/bin/cupertino --arm-a-search-db ~/.cupertino/search.db \
--arm-b-binary Packages/.build/release/cupertino --arm-b-search-db ~/.cupertino-dev/search.db \
--out /tmp/comparison.json --md-out docs/audits/search-quality-versiondiff.md
| Phase | 覆盖对象 | fixtures 数 |
|---|---|---|
| Phase 1 | search 规范查找 + framework 根 |
50 |
| Phase 1 扩展 | 不重叠语料交叉验证 + 弃用对(Swift vs NS 前缀) | ~30 + 30 |
| Phase 2 | 5 个 AST 工具(search_symbols 等,走 MCP stdio) |
20 |
| Phase 3 | inheritance 上下行遍历 |
22 |
| Phase 4 | read 系列命令(含负路径) |
13 |
| Phase 5 | list / doctor / package-search |
15 |
6. 配对统计检验:Wilcoxon 与 McNemar ⚖️
单看均值差会骗人,所以配对比较强制做两个统计检验:
- 配对 Wilcoxon 符号秩检验(作用于逐查询 RR 差值向量):MRR 取值离散、右偏(大量 1.0/0.5,很少 0.0),不满足配对 t 检验的高斯假设,Wilcoxon 是 IIR 教科书的标准替代;
- McNemar 精确二项检验(作用于 rank-1 结果的 2×2 列联表):只看"谁在 rank-1"这个二元结果的差异。
同时输出六个变化分桶,让回归可逐条追溯:Added(原来 top-10 外,现在 rank-1)、Fixed、Removed、Degraded、Unchanged、Both-suboptimal。
7. 实测战果:v1.1.0 → v1.2.0 版本差异对比 📈
这套体系不是纸上谈兵。v1.2.0 重索引后的首次正式配对审计(docs/audits/search-quality-versiondiff-v1.1.0-to-v1.2.0.md)给出了这样的结论:
| 指标 | v1.1.0 (brew) | v1.2.0 (dev) | Δ |
|---|---|---|---|
| MRR | 0.6900 | 0.9467 | +0.2567 |
| P@1 | 26 / 50 | 46 / 50 | +20 条新上 rank-1 |
| NDCG@10 | 0.9892 | 1.4809 | +0.4917 |
- Wilcoxon:N_nonzero = 22,W+ = 251.50,单侧 p = 0.000025(v1.2.0 显著更优)
- McNemar:不一致对 b=0 / c=20,精确 p = 0.000002
- 分桶:Added 4(
Optional、Dictionary、Data、URL)、Fixed 16、Degraded 仅 1(CoreDatarank 2→3)、Removed 0
一句话结论从"感觉变好了"变成了"20/50 条查询新晋 rank-1,0 条回归,p 值可引用"——这正是量化评估的价值。
8. 基线、审计与 CI 冒烟:让评测可复现 🔁
体系的可复现性靠三层落盘:
- 基线文档:首次运行产出 docs/audits/search-quality-baseline-v1.2.0.md(50 查询、MRR 0.9467、P@1 46/50),此后任何排序变更都必须跑同样的 50 查询语料,MRR 或 P@1 perfect 数回落即要求解释;
- 版本差异审计:配对模式自动生成
docs/audits/下的 Markdown(聚合表 / 统计检验 / 分桶 / 方法回顾 / 测量盲区),JSON 全量转储保留每条查询的双臂 top-10,作为声明的审计轨迹; - CI 冒烟:
query-batteries-smokejob 在 PR 上对每个 phase 跑--smoke(各 1 条 fixture,总预算 <30 秒),全量运行保留给 tag 发布仪式。
新增一个 Phase 的工作量约 200~400 行:写语料、写 score_query、写 Markdown 写入器,其余交给公共库。
9. 诚实的边界:MRR 测不到什么 🚧
设计文档用一整节 Non-goals 划清了红线,值得新手学习这种"知道自己不知道"的诚实:
- Cranfield 指标 ≠ 反幻觉结果:MRR 高只说明"正确文档可找到",不保证 AI 代理"产出可编译、符号真实、可用性正确"的 Swift——后者(Criterion 2)需要独立的端到端代理评测(Phase 1.7,约 30 个手工 Swift 编码任务 + McNemar 配对);
- 不做单一综合分:不同查询类别的优化目标互相冲突,折成一个数会误导;
- 不重建 trec_eval:这是聚焦 Cupertino 自身 CLI 形态与语料的工具,不是通用 IR 工具箱;
- P@5 / NDCG 的记账特性(§3 所述)在每份审计中显式声明,而不是悄悄藏掉。
延伸阅读 📚
- 方法论总设计:docs/design/search-quality-eval.md
- 评估 harness 标准 v1.0:docs/audits/eval-harness-standard-v1.0.md
- 公共评测库:scripts/eval/lib_harness.py
- 各 phase 基线与版本差异审计:docs/audits/
- 项目概览与安装:README.md
