benchmarking-retrieval-quality

能力目标

让 Agent 在本机跑一次 BrainBench 评测，得到 GBrain 完整检索管线与 grep-only（纯 BM25）baseline 的 P@5 / R@5 对账，并能正确解读这组数字的口径、知道它是 self-produced ablation、不能直接拿去横评别的记忆系统。

前置

• 需要 GBrain CLI 已装、本机已 import 一个 brain（gbrain adapter 用它）。
• bun run eval:run:dev 的 dev 模式设计为「快速 + 无 LLM 依赖」，grep-only adapter 不需任何 API key；gbrain adapter 用本机 brain；~15 min 跑完。
• 完整的 vector-grep-rrf-fusion adapter 需要 DashScope key 通过 gateway 注入，不配则该 adapter 报错、但不影响 gbrain 与 grep-only 两个主对账。

实操流程

1. 克隆并安装 gbrain-evals：

   WORKSPACE="/path/to/workspace"
   git clone https://github.com/garrytan/gbrain-evals.git "$WORKSPACE/gbrain-evals"
   cd "$WORKSPACE/gbrain-evals" && bun install
   

2. 跑完整 multi-adapter side-by-side（N=1，每 adapter 1 个 run、页面顺序 shuffled）：

   cd "$WORKSPACE/gbrain-evals"
   BRAINBENCH_N=1 timeout -k 5 1200 bun run eval:run:dev > /tmp/brainbench.txt 2>&1
   

   语料是 eval/data/world-v1/ 下 240 page 虚构 rich-prose，gold 是 145 条关系型 query + 261 expected answers。

3. 单独跑 grep-only baseline（不需 API key，作为 BM25 对照）：

   BRAINBENCH_N=1 timeout -k 5 300 bun eval/runner/multi-adapter.ts --adapter=grep-only \
     > /tmp/brainbench-grep.txt 2>&1
   

4. 读结果对账。核心行形如 done (1.4s). P@5 49.1%, R@5 97.9%, 248/261 correct (run 1)：

   grep -E 'P@5|R@5|correct' /tmp/brainbench.txt /tmp/brainbench-grep.txt
   

校验回路

• 输出里 gbrain adapter 与 grep-only adapter 各有一行 P@5 / R@5 / correct 计数。
• gbrain 完整管线（graph + vector + BM25 + RRF）的 R@5 显著高于 grep-only（纯 BM25），delta 数十个百分点——量化证明 vector + graph + reranker + token_budget 相对纯字面检索的增量。
• 同一份语料重跑 N=1，数字可复现（说明评估流程稳定、不是随机波动）。

常见陷阱

• P@5 / R@5 的口径：P@5 = 145 个 query 的前 5 结果里平均多少比例是 gold（precision 视角）；R@5 = 前 5 结果累计覆盖了多少比例的 gold（recall 视角）。数字是「在这 145 条关系型 query 上」的统计，不是「对所有知识库都能跑出这个数」。
• BrainBench 是 self-produced ablation、不能直接横评 mem0 / Zep：语料是 gbrain-evals 内部生成的虚构 corpus、天然适配 gbrain 的 page schema；gold answers 由 gbrain 自己的 facts 表派生；adapter 接口偏向 gbrain 内部 API，其他系统接入需包一层兼容代码、未必公平。它只回答「gbrain 自己的管线在自己的语料上召回多少 gold」，不回答「gbrain 比别的系统强多少」。
• 想做跨系统横评应用第三方公开数据集：LongMemEval（HuggingFace 公开、多轮对话长记忆）与 NaRRA（narrative-based relational retrieval）上不同系统有可比的公开数字，才是横评的正确口径。
• eval:run:dev 不输出 nDCG：完整 nDCG@5/10 要跑 bun run eval:brainbench（不是 eval:run:dev），dev 路径优先服务「快速跑通 + 无 LLM 依赖」。
• vector-grep-rrf-fusion adapter 报 AI gateway not configured：未配 DashScope gateway 时该 adapter 直接 ERROR，属预期，不影响 gbrain / grep-only 两个主对账。