符号级索引拆解:open-glean 用一张 symbol graph,把「搜代码」变成「问代码」
符号级索引拆解:open-glean 用一张 symbol graph,把「搜代码」变成「问代码」
2024 年 8 月至今,Glean 相关的社区内容持续发酵:从"企业版 Google"的定位讨论,到 GraphRAG 知识图谱如何重构企业知识管理,再到估值一路冲到 72 亿美元、ARR 突破 1 亿美金(净收入留存率超 120%)的商业叙事,几乎每一篇都指向同一个技术内核——搜索的对象不再是"文本",而是"关系"。而 open-glean 这个开源项目,恰好把这个内核以工程代码的形式完整地摆在了台面上:它不是又一个向量检索玩具,而是一套把检索、图谱、引用、研究与问答串成一条流水线的"符号级索引"工作台。
本文不打算复述市场故事,而是直接打开仓库源码,沿着一条真实的请求链路走一遍:一次提问进来,系统如何从文本匹配跃迁到符号与关系的检索,如何用一张 symbol graph 兜住调用链与语义上下文,最终把"搜代码"变成"问代码"。
从文本匹配到符号图的范式跃迁
传统代码搜索的两条路线都有天花板。纯文本检索(grep、全文索引)只能回答"哪里出现了某个字符串",对"这段代码为什么存在""这个函数被谁调用"无能为力;纯向量检索(embedding 相似度)能兜住语义近似,却对"调用关系""类型归属"这类结构化事实毫无感知,还会把"谁调用了我"和"谁和我长得很像"混为一谈。
open-glean 的答案是把两者同时交出去,并让它们互相补位。打开 lib/hydra/client.ts 的 QueryParams,能看到一组耐人寻味的参数:
operator?: "or" | "and" | "phrase";
queryBy?: "hybrid" | "text";
mode?: "fast" | "thinking" | "auto";
graphContext?: boolean;
alpha?: number;
recencyBias?: number;
queryApps?: boolean;
queryForcefulRelations?: boolean;
queryBy 决定走词法还是混合,mode 决定单次检索是"快"还是"想",而 graphContext 一打开,检索就不再是孤立的向量打分——后端会围绕命中的 chunk 拉出它的图上下文。这正是社区文章中反复出现的"从关键词匹配到语义理解跃迁"的工程落点:图不是检索完之后的装饰,而是检索过程中的一等公民。
在 lib/chatMode.ts 里,三种模式被明确命名:
fast: "Fast: quick hybrid retrieval",
thinking:"Deep: graph-augmented retrieval (slower)",
research:"Deep Research: plans a DAG of sub-questions, runs them in parallel, then writes a cited answer"
fast 与 thinking 之间不是速度差别,而是索引深度差别——后者把 graph 上下文带进打分。到了 research,则完全进入符号级编排:一次提问被拆成一张子问题 DAG,逐层并行执行。范式跃迁就发生在这三档开关之间:从"匹配文本"到"顺着符号找关系"再到"把关系喂给模型让它替你推理"。
symbol graph 的构建管线:解析、关联、去重
图谱从哪来?答案是每一次接入都在建图。README 里描述得很直白:"Mindmap: the knowledge graph Hydra builds from your context"。而仓库里真正让人看清"解析 → 关联 → 去重"三段式的是 Mindmap 页面与 SourceGraph 组件。
打开 app/(app)/mindmap/page.tsx/mindmap/page.tsx),加载逻辑分三步走:
- 解析:确定作用域(单 collection 优先于多选,多选优先于全库),然后
relations({ limit })按 collection 拉取三元组,每个三元组是source 实体 → target 实体 + 一组谓词; - 关联:
normalizeTriplet把 SDK 的 camelCase 字段映射回后端 wire 格式的 snake_case——entityId→entity_id、canonicalPredicate→canonical_predicate、relationshipId→relationship_id,并保留context、confidence、timestamp、chunk_id等证据字段; - 去重:以
source_id(或 chunk uuid、标题)为分组键建立 Map,同一文档的多个 chunk 归并为一个 citation 条目,最后按首次出现顺序全局编号。
去重逻辑的完整实现藏在 lib/citations.ts 的 buildCitationIndex:
for (const c of chunks) {
const key = groupKey(c, map.size);
let entry = map.get(key);
if (!entry) {
entry = { ref: map.size + 1, key, title: displayTitle(c), chunks: [], web: false, ... };
map.set(key, entry);
}
entry.chunks.push(c);
}
文件头部的注释把设计动机写得一清二楚:"Group by source, not by chunk. A citation means 'this document said so'。"——引用编号是符号,不是文本片段。模型看到的 [1]、面板上的一张卡片、来源里的一个文档,三者严格同构;这正是社区讨论里 GraphRAG 方案的杀手锏:数字稳定,才谈得上可验证。
更深一层的"关联"发生在 components/SourceGraph.tsx 的 entityMergeKey:当图谱同时混有 knowledge 与 memory 两个子图时,同一个真实世界的实体可能带着不同的 entity_id 到达前端,此时按 namespace:type:identifier 归一化合并成一个"Both"节点——跨子图的实体消歧是符号图区别于平面标签体系的关键工程。
查询如何走图:从符号到调用链到语义答案
单次查询的完整链路在 lib/qa.ts 的 runQa 里一目了然:先 hydra.search 做检索(thinking 模式会带上 graphContext: true),把返回的 envelope 归一化成扁平 chunk 列表;然后 chunksToContext 把 chunk 按来源归并成编号上下文块,拼进系统提示词;最后 streamChat 把答案流式吐出,<a href="https://link.gitcode.com/i/31eab80e185adc4a0f236903bb6c9adb" target="_blank">n] 标记在 [lib/citationMarkup.ts 的 linkCitations 里被校验后转成可点击的引用按钮。
这里有一个值得展开的工程细节——引用编号的"单一事实来源"。citationMarkup 只允许匹配 [1-3位数字] 且在 code/pre/a/button 标签外出现,并拒绝超出 maxRef 的引用(模型多引用了一个不存在的来源,就保持为纯文本而不是指向空链接)。所有这一切都建立在 lib/citations.ts 那条"prompt 与面板共用同一个 index"的约束上。引用是链接到证据的符号指针——回答可溯源,幻觉无处藏身。
而当单次查询不够用时,调用链被放到更大一张图上:Deep Research。打开 app/api/research/route.ts,五段式流水线写得清清楚楚:
1. plan — 模型把问题拆成 DAG 子问题
2. layer — Kahn 算法把 DAG 变成可并行执行的分层波次
3. execute — 每层并发打到 Hydra;子问题结果前馈给下一层
4. dedup — 所有节点的来源合并成一份全局编号引用表
5. answer — 基于去重后的来源流式写出最终答案
规划器的约束在 lib/research/planner.ts 里非常严格:子问题必须自包含("no pronouns referring to other nodes")、dependsOn 只能引用更早的 id、禁止环、最多 8 节点 4 层。layerPlan 用 Kahn 算法分配执行层级,遇到环时确定性打破而不是死锁:
if (ready.length === 0) {
// Cycle (or a dependency on a dropped node): break it deterministically.
const fallback = Math.max(-1, ...level.values()) + 1;
for (const n of remaining) level.set(n.id, fallback);
break;
}
执行时每个子问题都以 mode: "thinking" + graphContext: true + queryApps: true 打给 Hydra——也就是每一跳检索都走图增强,同时开启连接器专属检索通道。跨层依赖的查询还会先被 refineQuestion 用上一层发现的事实改写一遍,把"依赖"从抽象的边变成具体的追问。而 SourceRegistry 是整个管线的符号中枢:同一文档被多个子问题反复召回时,编号只在首次出现时分配一次,foundBy 记录哪些节点发现了它——这就是把"调用链"摊平成"可引用的证据链"的过程。
与全文索引、向量索引的边界
要理解 open-glean 的定位,得先划清三条索引的边界:
- 全文索引:命中字符串,返回片段。open-glean 用它兜底(
queryBy: "text"、operator: "phrase"的精确短语场景),但从不把它当作答案的来源——答案永远由 LLM 基于检索上下文合成; - 向量索引:命中语义近邻,返回相似 chunk。这是混合检索(hybrid)的默认通道,负责把"语义像"的东西捞上来,但对"这个函数被谁调用""这条消息回复了谁"无能为力;
- 符号图索引:命中实体与关系,返回带证据的三元组。
relations、graphContext、Mindmap、实体消歧、全局引用编号,全部建立在这一层。
在 app/(app)/chat/[id]/page.tsx 的渲染链路里,三层索引最终汇合:buildCitationIndex 先按来源编号 Hydra 上下文,再追加 Web 引用并按 URL 去重、续编号——本地证据与联网证据共享同一套编号命名空间。而 lib/qa.ts 里 chunksToContext(...).slice(0, MAX_CONTEXT_CHARS) 的 12000 字符预算,则在物理上决定了:上下文是稀缺资源,必须由符号层决定谁有资格进入。这正是社区文章讨论向量搜索局限时的核心论点——向量负责召回候选,但召回之后的排序、过滤、编号与证据锚定,必须交给符号与关系层,否则模型面对的就是一堆无法验证的文本碎片。
从"搜"到"问":一张图完成的事
回到标题的问题:open-glean 怎么把"搜代码"变成"问代码"?
答案藏在它把三种检索范式编进同一个交互流的方式里:词法检索负责精确召回,向量检索负责语义召回,symbol graph 负责把召回结果组织成可验证、可引用、可推理的证据结构,LLM 再在这个结构之上完成最后的合成。检索、图谱、引用、研究、问答——在仓库里不是五个孤立功能,而是同一条流水线的五个工位:lib/hydra/client.ts 提供统一客户端,lib/qa.ts 串联检索与生成,lib/citations.ts 与 lib/citationMarkup.ts 保证编号一致性与安全渲染,app/api/research/route.ts 把单跳问答升级为图上的并行推理。
而用户看到的就是那个极简的提问框——"Ask your second brain"。背后的 symbol graph 不用你理解,但它决定了每个答案里 [1]、[2] 背后的证据是否经得起点开核对。社区热议的 GraphRAG 不再是一个营销词,而是一段可以逐行阅读、逐条测试的代码。这或许就是开源的价值:当一家公司把"知识图谱 + 生成式问答"讲成估值故事时,open-glean 直接把故事变成了可以 npm ci && npm run dev 的工程现实。