tuning-hybrid-retrieval

能力目标

让 Agent 把 brain 的向量索引建起来使 hybrid 检索真正可用，看清 hybrid 相对纯 BM25 多召回了什么、graph_augment 如何把关系型 query 的答案捞回来、某条结果的分数由哪些 factor 合成，并能按 cost/quality 权衡切换搜索模式。

前置

• brain 已 import。hybrid 的 vector 半边需要 pages.embedding 列填满；embedding 空时 HNSW 半边返回 0、RRF 融合后等价于纯 BM25。
• 需要 export DASHSCOPE_API_KEY=...，且 DashScope 国内端点补丁已生效（见 deploying-gbrain-runtime）。
• 7 阶段管线：intent_classify → expansion → hybrid(HNSW+BM25) → RRF fusion → graph_augment → reranker → token_budget。CLI 不 dump 各阶段中间分数。
• gbrain 命令用 timeout -k 5 60 gbrain ... 包裹（exit 124 正常），读输出用 > /tmp/out.txt 2>&1; cat。

实操流程

1. 核验 DashScope 端点补丁仍在，再建向量索引。embed --stale 只 embed 空的或 content_hash 变了的 page，比 --all 经济：

   grep -n "base_url_default" ~/.bun/install/global/node_modules/gbrain/src/core/ai/recipes/dashscope.ts
   # 应含 dashscope.aliyuncs.com/compatible-mode/v1
   export DASHSCOPE_API_KEY="<你的 key>"
   timeout -k 5 120 gbrain embed --stale > /tmp/embed.txt 2>&1; cat /tmp/embed.txt
   timeout -k 5 30 gbrain stats   # Embedded 应接近 Pages
   

2. 对比 BM25 与 hybrid 召回同一 query，看 hybrid 多召回的纯语义结果：

   timeout -k 5 30 gbrain search "inference optimization" > /tmp/bm25.txt 2>&1     # 只走 BM25 半边
   timeout -k 5 60 gbrain query  "inference optimization" > /tmp/hyb.txt 2>&1      # 走全 7 阶段
   diff <(sort /tmp/bm25.txt) <(sort /tmp/hyb.txt)
   

   gbrain search 是排障用的 BM25「分量级」命令；日常检索用 gbrain query 走完整管线。hybrid 多出来的结果是不含字面关键词、靠向量语义 + graph_augment 召回的。

3. 用 gbrain whoknows --explain 拆解打分——这才是真正的 pipeline 可视化命令（gbrain query --explain 的 flag 被静默接受但输出和不带一样、不要用）。whoknows 面向「找人/找机构/找谁懂 X」的 entity query，输出每条结果的 factor JSON：

   timeout -k 5 60 gbrain whoknows "inference optimization" --explain > /tmp/wk.txt 2>&1; cat /tmp/wk.txt
   

   四个 factor：raw_match（RRF 融合后含 graph_augment boost 的原始分）、expertise（对 raw_match 的 sub-linear 变换）、recency_decay（6 个月半衰期指数衰减，今天导入≈1.0、半年前≈0.5）、salience_factor（入度归一化含 0.5 基线）。最终 score ≈ expertise × recency_factor × salience_factor。

4. 验证 graph_augment 对关系型 query 的价值。who X-ed Y 类 query（投资人本人 page 常不含目标关键词）靠 Stage 5 沿 typed-link 反向补 1-hop 邻居：

   timeout -k 5 30 gbrain graph-query "people/bob-zhang"   # 直接看 Stage 5 的 typed-link 遍历
   timeout -k 5 60 gbrain query "who invested in inference optimization startups"
   # 投资人 / 投资机构会通过 invested_in 反向边进 top-N
   

5. 切换 search mode。3 个 preset 打包了 searchLimit / tokenBudget / expansion / reranker 四个开关，用 config set search.mode 切换（不是 gbrain query --mode X——该 flag 不存在）：

   timeout -k 5 15 gbrain config set search.mode conservative   # searchLimit 10 / 4K / 无 reranker
   timeout -k 5 15 gbrain config set search.mode balanced       # 25 / 12K / zerank-2（默认推荐）
   timeout -k 5 15 gbrain config set search.mode tokenmax       # 50 / 无上限 / expansion + zerank-2
   timeout -k 5 15 gbrain config set search.mode balanced       # 用完恢复默认
   

校验回路

• gbrain stats 的 Embedded 数达到可用规模，hybrid query 的 top score 明显高于纯 BM25（RRF 多路融合、score 1.0+ 正常，不是 cosine 相似度、不能跨 brain 横比）。
• gbrain query 比 gbrain search 多召回若干不含字面关键词的纯语义 page。
• whoknows --explain 输出可对账：某条结果的 expertise × recency_factor × salience_factor 逐位等于其 score。
• 关系型 query 的结果里出现只能靠 typed-link 反向边召回的实体（投资人 / 投资机构）。

常见陷阱

• gbrain query --explain 静默不工作：flag 被接受但输出等同不带 flag；真正的 factor 分解只在 gbrain whoknows --explain 下实现。
• gbrain query --no-graph flag 不存在、graph_augment 无法 ablation：graph_augment 当前总是开。想看「没有 graph 会怎样」，间接对比 gbrain query（走 Stage 5）与 gbrain search（纯 BM25、不走 Stage 5）。
• 小 brain 上 3 个 mode 输出完全一致、不是 bug：page 数 < searchLimit（如 9 page < conservative 的 10）时所有 mode 返回全部候选、无 filtering；且 balanced/tokenmax 的 zerank-2 reranker 在未配 ZEROENTROPY_API_KEY 时 fails-open（直接返回 RRF 原排名）。要看 mode 差异需 brain ≥ 100 page + 配置 ZEROENTROPY_API_KEY。
• gbrain query 输出完不自动退出、timeout 的 wall-clock 是 ceiling 不是真实延迟：小 brain 真实查询 < 1s，测延迟用更小的 timeout 1.5 观察收敛点。
• cost 旋钮在下游 LLM、不在 embedding：单 query embedding cost ≈ $0.00001（只对短 query 跑一次），主 cost 在下游 LLM 消费 chunk（Sonnet 处理 25 chunk ≈ $0.03/query、占 99%+）。DashScope 与 OpenAI 的 embedding 价差对总 cost 影响 < 1%。conservative+Haiku ≈ $40/mo、balanced+Sonnet ≈ $300/mo、tokenmax+Opus ≈ $1000/mo。