querying-brain-first

能力目标

让 Agent 在回答一个 query 时先按 4 步序列查 brain——最便宜的 keyword 粗筛、失败升级到 hybrid 精排、已知目标则 slug 直取、都没有可用结果才走外部 fallback——并把这套序列封装成一个跨 brain 通用的可复用脚本，同时识别「hybrid 总能返回最近邻」导致的语义错误 match 陷阱。

前置

• brain 已就位、page 已 import；hybrid 一步需要 embedding 已建（gbrain stats 的 Embedded 非零）。启用向量索引见 tuning-hybrid-retrieval。
• 需要 export DASHSCOPE_API_KEY=...（hybrid query 每次要把 query 送去 embedding）。
• gbrain 命令用 timeout -k 5 30 gbrain ... 包裹（exit 124 正常），读输出用 > /tmp/out.txt 2>&1; cat、不 pipe。

实操流程

4 步序列按 cost/speed 递进排：最便宜在前、最精准在后。

1. Step 1 — keyword 粗筛（gbrain search，纯本地 BM25，无 embedding、毫秒级、零 API quota）。用来最经济地排除「brain 完全没相关内容」：

   timeout -k 5 30 gbrain search "alice" > /tmp/s1.txt 2>&1; cat /tmp/s1.txt
   

   输出格式 [score] slug -- snippet。BM25 只做粗筛：目标 page 未必排第一（按 query term 总加权频度排），只需确认「至少有相关内容」，精排交给下一步。No results. 是最清晰的 miss 信号、可直接判 MISS。

2. Step 2 — hybrid 精排（gbrain query --no-expand，HNSW 向量 + BM25 + RRF 融合，需 embedding、几百 ms~秒级、每次一次 embedding 调用）。用于 keyword 命中不准、需要语义召回时：

   export DASHSCOPE_API_KEY="<你的 key>"
   timeout -k 5 60 gbrain query "who founded acme-ai" --no-expand > /tmp/s2.txt 2>&1; cat /tmp/s2.txt
   

   --no-expand 关掉 LLM query expansion（否则引入额外 LLM 调用、延迟可达 30s）。hybrid 的 score 尺度整体高于 keyword（区间约 0.440.87 vs 0.260.32），不能跨检索器直接比数字大小、只在同一检索器内部排序有意义。

3. Step 3 — slug 直取（gbrain get，按主键直查 pages 表一行、无检索无 embedding、< 50 ms）。前提是已知 slug——通常在 Step 1/2 拿到候选 slug 后、后续轮次转用 get 走快路径取完整页面：

   timeout -k 5 30 gbrain get people/alice-chen > /tmp/s3.txt 2>&1; cat /tmp/s3.txt
   

   不存在的 slug 返回 Error [page_not_found]——这是干净 miss 信号。

4. Step 4 — fallback 判定：三步是否拿到「真正回答了问题」的结果？是则结束；否则走 external fallback（WebSearch / 用户文档等）。brain-first 不是 brain-only，fallback 是序列的合法终点、不是异常。关键：判定不能是简单布尔「有没有返回结果」——见陷阱。

5. 封装成可复用脚本。用附带的 scripts/brain-first-lookup.sh，接受 <query> + 可选 [slug_hint]，自动按序跑三步并输出 brain HIT / brain MISS：

   export DASHSCOPE_API_KEY="<你的 key>"
   bash scripts/brain-first-lookup.sh "who founded acme-ai" "people/alice-chen"
   

   换自己 brain 复用时，挑 query 的策略：2 个一定在的 + 1 个一定不在的，就能把命中 / 干净 miss / 语义错误 match 三条分支跑齐。

校验回路

• 至少 1 个 query 在 Step 1、Step 2 都 HIT，且同一 query 上 hybrid 的 top-1 score 明显高于 keyword 的 top-1 score（验证 cost/speed 递进真实存在）。
• 至少 1 个 query 在 Step 1 看到 No results. 干净 miss。
• 至少 1 个 brain 里不存在的实体，Step 1 干净 miss 但 Step 2 返回一个 score 很高（>0.7）却答非所问的结果——复现语义错误 match，证明理解了 brain miss 双形态。
• 脚本对 HIT query 输出 brain HIT — external fallback NOT needed。

常见陷阱

• hybrid query 几乎总返回结果，哪怕 brain 里根本没有相关知识：向量空间里任何 query 都有最近邻。查一个不存在的实体，hybrid 会把语义相近的现有 page（如把「某公司 CEO」凑成 brain 里另一家 AI 公司的 CEO）以高 score 返回。所以 Step 4 判定必须是「返回的结果是否回答了问题」（需 LLM relevance evaluation），不是「有没有返回」。
• 简单布尔 fallback 判定会被语义错误 match 污染：if search_hit || query_hit || get_hit 在 keyword 干净 miss + hybrid 语义错误 match + get 失败的组合下，会因 hybrid 的假 HIT 把整体误判成 brain HIT、跳过 fallback。附带脚本故意保留这个简单布尔作反例；生产实现须在 Step 4 前加一层 LLM 判定：把 query + top-N 结果全文喂给 LLM，判 RELEVANT / NOT_RELEVANT。
• 别用 pipe 过滤 gbrain 输出：EPIPE 会卡死；exit 124 当正常退出处理。