一个 TypeScript 实现的 GraphRAG 项目,把检索拆成了两条路:本地检索和全局检索。两条路共用同一份已索引数据,但召回策略完全不同。这解释了为什么同一个问题,走不同路径会得到风格迥异的答案。

项目仓库为 sadofriod/graphrag-ts,npm 包名 @ashes_born/graph-rag-ts。本地检索用实体、社区和源证据回答具体问题;全局检索则分析社区摘要批次,合成一个语料库级别的答案。

本地检索:图结构找主题,分块找证据

GraphRAGRetrievalService 先把查询交给 parseQuery,提取实体、关键词和主题,再用 entityMatcher 匹配已索引实体。匹配器支持精确、别名、模糊、语义四种通道,并用倒数排名融合(RRF)合并排名。当前检索服务传入的是空别名列表,所以实际生效的是精确、模糊和语义匹配。解析出的意图实体若命中已知实体,也会并入结果。

随后服务分两条路径构建社区候选和源证据:

  • 从匹配实体出发,communityResolver 沿图最多扩展两跳,召回相连社区;若指定了社区层级,则通过父级关系解析到该层级的候选。
  • vectorSearch 将查询嵌入与社区摘要嵌入比对,找出语义上的社区候选。
  • 按向量相似度搜索源子分块,同时用 keywordSearch 通过 PostgreSQL 的 ILIKE 子串匹配实体名和关键词。关键词命中先按匹配词数排序,再按分块长度排序。合并时保留向量结果顺序,并按分块 ID 去重。

communityRanker 合并三份排名列表:摘要向量的语义排名、查询实体与社区成员之间的 Jaccard 重叠度、以及连接查询实体与社区成员的图边权重之和。这里用 RRF 融合,而不是直接把余弦相似度、集合比例和权重相加——三者本就不可比。服务取 topK 结果,再交给 finalSelector 中的 LLM 过滤路径,只保留与问题真正相关的社区。

本地答案:摘要与证据分开标注

最终上下文分两部分:选中社区的摘要,以及证据片段。证据包括向量/关键词召回的源子分块,以及通过 evidenceRetriever 关联到社区成员实体的声明。声明保留源文档和源分块 ID,子分块证据也带分块 ID。answerGenerator 在送进模型前,把摘要和证据分别打上标签。

这样社区摘要承担主题级上下文,源分块和声明提供事实支撑。社区排名分数和 LLM 的社区过滤决定都不是事实置信度分数。做审计时,应用应把返回的证据 ID 映射回源位置,并把这些引用暴露出来。

全局检索:对社区摘要做 Map-Reduce

全局检索不从实体匹配开始。它默认使用叶子社区摘要,也可使用指定层级摘要。每条选中的摘要会补充其子孙叶子社区的声明和可用源摘录,保留证据线索供全局分析使用。

summaryBatcher 先打乱摘要,再按预估 token 预算切分打包。超大摘要会被拆成多段,标注社区 ID 和段号。token 计数是工程估算,不是精确的模型分词器。Map 和 Reduce 默认预算均为 8000 token,并预留输出空间;Map 并发默认四路,这些设置都可覆盖。

每个 Map 批次产出一个中间答案和 0 到 100 的可用性分数。输出会校验 JSON 结构和分数范围,失败批次重试一次。零分答案不进入 Reduce。其余按可用性排序,在 Reduce token 预算内逐个选取;放不下的答案跳过,让后面更短的答案仍有机会入选。部分批次失败但仍有可用答案时,结果状态为 partial;没有可用结果时,服务返回 no-results 状态。

两条路径怎么选

本地路径能更直接地返回源段落作为证据。全局路径覆盖更多主题,但 Map 阶段已把摘要压缩成中间答案,因此全局答案里的细节应对照保留的社区和声明溯源核查;Map 的可用性分数不是准确率估计。

请求隔离与取消方面,检索服务用命名空间上下文限定数据库查询范围,并用异步本地存储传递可选的 AbortSignal。数据库和模型操作会在检索工作周围检查取消状态,避免已中止的请求继续推进到后续阶段。多租户部署中,每条 SQL 和向量查询都必须继承同一命名空间范围。