LangChain图检索RAG实战：双路召回与知识图谱构建

1. 为什么要在RAG里引入图检索

做RAG的同行大概都有过这种体验：文档切了一堆chunk，向量库也建好了，用户问一个稍微绕一点的问题，检索出来的片段单看每一条都沾边，拼在一起却答不到点子上。尤其是那种需要跨多个实体、跨多段材料做关联推理的问题，纯向量相似度检索基本抓瞎——它擅长找"长得像"的文本，不擅长找"连得上"的关系。

这就是图检索要解决的问题。简单说，图检索查询（Graph Retrieval）在RAG里的角色，是把散落在不同chunk里的实体和关系先抽出来、连成一张知识图谱，查询时沿着图的边去扩展召回，而不是只靠向量距离做一锤子买卖。打个生活化的比方：向量检索像在图书馆里按书名关键词找书，图检索像先看索引卡片上"这本书引用了哪几本、被哪几本引用"，然后顺藤摸瓜把一整条知识链捞出来。

我用LangChain做这套东西，核心原因有两个。一是LangChain对图存储的抽象做得比较统一，GraphStore、LLMGraphTransformer这些组件把"抽实体—写图—查图"的链路串起来了，换后端（内存图、图数据库）时上层代码改动小。二是它和现有的Retriever、Chain体系能拼在一起，图检索召回的文本可以继续走原来的rerank和生成流程，不用把整条RAG管线推倒重来。

适合谁来参考这份总结？如果你已经搭过一个能跑的向量RAG，现在被"多跳问题答不准""实体关系丢失"折磨，想加一层图结构但不知道从哪下手，那这篇就是写给你的。完全没接触过RAG的朋友也能看，但最好先把"文档切分—向量化—检索—生成"这条主线跑通一遍，不然图检索这层会显得悬空。

需要先说明一点：LangChain的图相关API迭代比较快，不同小版本之间类名和参数会有出入。下面涉及具体代码的地方，我按当前较稳定的接口来写，同时会标注哪些地方容易随版本变化，你落地时以自己环境的实际签名为准。这是基于常见实践的补充说明，不是官方文档的逐字复述。

2. 整体设计与方案选型拆解

2.1 图检索RAG的分层结构

我最终落地的结构分四层，从下往上依次是：文档层、图构建层、检索层、生成层。这个分层不是为了好看，而是为了让每一层可以独立替换和调试。

文档层负责原始材料的加载和切分，和普通RAG没区别，用PyPDFLoader、TextLoader之类加载，再走RecursiveCharacterTextSplitter切块。这里有个容易被忽略的点：切块大小会直接影响图构建的质量。块太大，一个chunk里塞了十几个实体，抽取时LLM容易漏；块太小，实体之间的关系被切断，抽出来的图全是孤立节点。我实测下来，中文材料用500到800字符、重叠100字符左右比较稳，英文可以放到1000字符上下。

图构建层是这套方案的重头戏。它做两件事：用LLM从每个chunk里抽"实体—关系—实体"三元组，然后把三元组写进图存储。LangChain里对应的组件是LLMGraphTransformer配合GraphStore（内存版是InMemoryGraph，生产环境一般接图数据库）。

检索层要同时干两件事：向量召回拿语义相关的chunk，图召回拿实体邻域扩展出来的关联信息。两路结果合并去重后再送进生成层。这一步的合并策略很关键，后面会细讲。

生成层就是常规的prompt组装加LLM调用，把合并后的上下文喂给模型出答案。

2.2 为什么不用纯向量，也不全押图

有人会问，既然图这么好，干脆全用图检索行不行？我试过，不行。原因很实在：图检索的召回质量高度依赖实体抽取的准确率。LLM抽实体不是百分百靠谱，漏抽、错抽、关系方向搞反都常见。如果只靠图，一旦某个关键实体没被抽出来，整条召回链就断了，而且断得悄无声息——用户看到的是"答非所问"，你排查半天才发现是建图阶段漏了一个节点。

纯向量的问题前面说了，跨实体关联弱。所以我的选择是双路并行、互为兜底：向量路保证"至少能召回语义相近的内容"，图路负责"把关联实体补进来"。两路都空的情况极少，稳定性比单路高一个档次。

2.3 图存储的选型考量

LangChain支持多种图后端，我按使用场景分了三档：

我自己的做法是：原型阶段一律先用内存图跑通链路，确认实体抽取prompt和检索逻辑没问题了，再切到图数据库。这个顺序很重要，因为建图和检索的逻辑bug在内存图阶段暴露得最快，切到数据库后排查成本会翻倍。

2.4 实体抽取的粒度设计

这是整个方案里最需要动脑子的地方。LLMGraphTransformer默认会抽比较宽泛的实体类型（人、组织、地点等），但具体项目里往往需要收窄。比如做技术文档问答，你希望抽的是"组件""接口""配置项"这类实体，而不是泛泛的"事物"。

我的做法是给transformer传一个allowed_nodes和allowed_relationships白名单，把实体类型和关系类型限定在业务真正关心的范围内。这样做的好处是图更干净、检索时噪声少；代价是白名单设计不好会漏抽。白名单怎么定？我的经验是先从业务问题反推：把用户最常问的十类问题列出来，看每类问题需要哪些实体和关系才能答，这些就是白名单的候选。

3. 核心细节解析与实操要点

3.1 建图阶段：三元组抽取的prompt调优

LLMGraphTransformer底层是靠LLM按结构化输出抽三元组的，所以prompt质量直接决定图的质量。默认prompt能用，但针对中文材料经常抽得不全。我做了两处调整。

第一处是在指令里明确要求"关系必须是动词或动词短语"。默认抽取有时会给出"属于""包含"这种泛关系，图里全是这种边，检索时区分度很低。要求用具体动词后，边变得有信息量，比如"调用""依赖""覆盖""替代"。

第二处是要求实体名保持原文表述，不做归一化改写。这点反直觉——归一化不是能让图更干净吗？问题是LLM做归一化时经常把不同实体合并成一个，或者把专有名词改得面目全非，导致后续按实体名查图时对不上。我的做法是抽取阶段保留原文，归一化放到写入图存储之前用规则做（比如统一大小写、去首尾空格），规则可控，出错好查。

代码上大概是这样组织的（以内存图为例，接口随版本可能微调）：

from langchain_experimental.graph_transformers import LLMGraphTransformer from langchain_community.graphs import NetworkxEntityGraph transformer = LLMGraphTransformer( llm=llm, allowed_nodes=["组件", "接口", "配置项", "模块"], allowed_relationships=["调用", "依赖", "覆盖", "替代"], node_properties=["描述"], ) graph_documents = transformer.convert_to_graph_documents(chunks) graph = NetworkxEntityGraph() graph.add_graph_documents(graph_documents, baseEntityLabel=True, include_source=True)

include_source=True这个参数值得单独说：它会把原始chunk作为节点的来源信息挂上去。这样图检索召回一个实体时，能顺带把该实体出处的那段原文带回来，生成阶段就有据可依，而不是只拿到一个干巴巴的实体名。这个细节对答案的可追溯性帮助很大。

3.2 检索阶段：图查询的两种走法

图检索查询在LangChain里我主要用两种模式，对应不同的问题类型。

第一种是实体邻域查询。用户问题里如果明确提到了某个实体（比如问"某模块依赖哪些组件"），就先做实体识别，定位到图里的节点，然后取它的一跳或两跳邻居。一跳适合"直接关系"类问题，两跳适合"间接影响"类问题。跳数不是越多越好，两跳以上召回范围爆炸，噪声会淹没信号，我一般封顶两跳。

第二种是子图匹配查询。问题涉及多个实体时（比如"组件A和组件B之间通过什么接口交互"），把问题里的实体都定位到节点，然后找它们之间的路径。LangChain本身没有现成的"找两节点间路径"的高层封装，需要落到具体图后端的查询接口上，内存图可以用networkx的路径算法，图数据库用其原生查询语言。这块是方案里最需要按后端定制的地方。

两种模式的选择逻辑我写成了一个简单的路由：问题里识别出的实体数≥2走子图匹配，=1走邻域查询，=0退回纯向量检索。这个路由规则很朴素，但实测覆盖了大部分场景，比让LLM去判断"该用哪种检索"稳定得多。

3.3 双路结果的合并与去重

向量路召回的是chunk，图路召回的是实体及其来源chunk，两路结果格式不一致，合并前要先对齐。我的对齐方式是统一转成"文本片段+来源标识"的结构，然后按来源标识去重。

去重之后还有个排序问题：两路结果混在一起，谁排前面？我的策略是给图路结果一个加权系数（比如1.2），因为图路召回的内容通常关联性更强、更聚焦。但这个系数不能太高，否则向量路召回的"语义相近但图上没连上"的内容会被挤掉。系数具体取多少，建议拿一批标注过的问题做小规模评测来定，别拍脑袋。

注意：合并时一定要保留每段文本的来源信息（来自哪个文档、哪个chunk、经由哪个实体召回）。生成阶段如果答案出错，来源信息是排查的第一手线索。我踩过的坑就是早期没保留来源，出了问题只能从头复现，效率极低。

3.4 建图成本与增量更新

全量建图是件费钱的事，每个chunk都要过一次LLM抽三元组。文档上千页时，token消耗和耗时都不小。我的应对是建图与文档入库解耦：文档入库时只做切分和向量化，建图作为一个异步任务单独跑，跑完把图持久化。这样入库不被建图阻塞，建图失败也不影响向量检索可用。

增量更新是另一个坑。新文档进来时，如果每次都全量重建图，成本受不了。我的做法是只对新chunk抽三元组，然后合并进已有图。合并时要注意实体去重——同一个实体在不同chunk里可能表述略有差异（比如带不带版本号后缀），需要一套归一化规则把它们对齐到同一个节点，否则图会越来越碎。

4. 实操过程与核心环节实现

4.1 环境准备与依赖梳理

先把依赖理清楚，避免装到一半发现版本打架。核心依赖是langchain、langchain-experimental（图转换器在这里）、langchain-community（图存储适配），以及一个LLM的客户端包。图数据库按需加。

pip install langchain langchain-experimental langchain-community

版本上我的建议是锁定小版本，别用浮动版本。图相关API在experimental包里变动频繁，今天能跑的代码明天可能因为一个参数改名就报错。用pip freeze把实际跑通的版本记下来，团队协作时直接对齐。

LLM的选择上，实体抽取对模型的指令遵循能力要求较高，能力弱的模型抽出来的三元组质量明显差一截。如果预算允许，抽取阶段用能力强的模型，生成阶段可以用稍弱的模型，这样成本和质量能平衡。

4.2 文档加载与切分的实操参数

加载和切分这段代码不复杂，但参数值得细说：

from langchain_text_splitters import RecursiveCharacterTextSplitter splitter = RecursiveCharacterTextSplitter( chunk_size=600, chunk_overlap=100, separators=["\n\n", "\n", "。", "！", "？", " ", ""], ) chunks = splitter.split_documents(documents)

separators里我把中文句号、感叹号、问号加进去了，这是针对中文材料的调整。默认分隔符以英文标点为主，中文长句容易被从中间硬切，切出来的chunk语义不完整，抽三元组时关系就断了。加上中文标点后，切分点更贴合语义边界。

chunk_overlap设100不是随便定的。重叠的作用是让被切断的关系在相邻chunk里各出现一次，提高抽取时被完整捕获的概率。重叠太小（比如20）起不到这个作用，太大（比如300）会让建图时同一关系被重复抽取，图里出现重复边。100左右是我试下来比较平衡的值。

4.3 三元组抽取与写入图的完整流程

完整流程分三步：批量抽取、归一化、写入。

批量抽取时要注意控制单次请求的chunk数量。一次塞太多chunk给LLM，容易触发输出长度限制，导致后面的chunk抽取被截断。我的做法是分批处理，每批10到20个chunk，批间加个短暂间隔，避免请求过于密集。

归一化这步我写了个小函数，做三件事：实体名去首尾空格、统一全半角、把明显同义的表述映射到标准名（映射表手工维护，从抽取结果里人工过一遍高频实体整理出来）。这步看着琐碎，但对图的连通性影响很大。

写入图时，add_graph_documents的baseEntityLabel参数建议开。它会给每个节点加一个基础类型标签，后续按类型过滤节点时方便很多。

4.4 图检索查询的组装

检索入口我封装成一个函数，输入是用户问题，输出是合并后的上下文列表。内部逻辑：

1. 用LLM或规则从问题里识别实体，得到实体名列表。
2. 实体数≥2，走子图匹配；=1，走邻域查询；=0，跳过图路。
3. 图路召回实体及其来源chunk，向量路并行召回chunk。
4. 两路结果对齐、去重、加权排序。
5. 返回top-k上下文。

实体识别这步我一开始用LLM做，后来发现对简单问题有点杀鸡用牛刀，改成"先用图里已有实体名做字符串匹配，匹配不上再调LLM"。这样大部分问题不用额外调一次模型，响应快不少。

邻域查询的核心代码（内存图版）大致是：

def graph_retrieve(graph, entity_name, hops=1): if entity_name not in graph.get_nodes(): return [] neighbors = graph.get_neighbors(entity_name) results = [] for n in neighbors: node = graph.get_node(n) source = node.properties.get("source", "") results.append({"entity": n, "source": source}) return results

这段是简化版，实际还要处理多跳展开和来源chunk的提取。source属性就是建图时include_source=True挂上去的原文，取出来直接能进上下文。

4.5 生成阶段的上下文组装

上下文组装有个细节：图路召回的内容和向量路召回的内容，在prompt里最好分区呈现，而不是混成一锅。我的prompt结构是"以下是与问题直接相关的原文片段"（向量路）+"以下是相关的实体关系信息"（图路），让模型知道两类信息的性质不同。实测这样组装，模型对关系类问题的回答准确率比混排高。

上下文总长度要控制，别把两路结果全塞进去。我的做法是给两路各设一个token预算，超了就按排序截断。预算分配上，图路通常占三到四成，向量路占六到七成，具体看问题类型动态调。

5. 常见问题与排查技巧实录

5.1 图检索召回为空怎么排查

这是最高频的问题。排查顺序我固定为三步：

第一步查实体是否入图。拿问题里的关键实体名去图里查节点，查不到说明建图阶段漏抽了。漏抽的原因通常是chunk切分把实体名切断了，或者白名单没覆盖这个实体类型。

第二步查实体名是否对得上。节点存在但按问题里的表述查不到，多半是归一化没做好，图里存的是"组件A-v2"，问题里说的是"组件A"。这种情况要么补归一化规则，要么在查询时做模糊匹配。

第三步查跳数设置。实体入图了、名字也对得上，但召回还是空，可能是跳数设太小，目标信息在两跳之外。临时把跳数调大验证一下，确认是跳数问题再针对性调整。

5.2 图越建越大、检索越来越慢

这是增量更新没做好归一化的典型症状。同一个实体因为表述差异被建成多个节点，图节点数膨胀，检索时遍历成本上升。排查方法是统计节点名的相似度分布，如果发现大量高度相似但不相等的节点名，就是归一化规则不够。

解决上，我建议定期做一次图合并：把相似度超过阈值的节点名聚类，人工确认后合并。这个操作不能全自动，因为有些相似名确实是不同实体，自动合并会引入错误。人工过一遍虽然费事，但比图烂掉强。

5.3 抽取的三元组关系方向搞反

LLM抽关系时偶尔会把"A依赖B"抽成"B依赖A"。这种错误在检索时很隐蔽——召回是能召回，但关系语义反了，生成阶段可能给出错误结论。

我的应对是在抽取prompt里明确要求"关系方向必须与原文语义一致，主语在前宾语在后"，同时在写入图前加一道校验：对方向敏感的关系类型（依赖、调用、包含这类），抽样人工核对。全量核对不现实，抽样能发现系统性问题就够了。

5.4 常见问题速查表

5.5 几个踩过的坑

第一个坑是建图和向量化用了不同的切分参数。早期图路和向量路各自切分，导致同一段原文在两路里的chunk边界不一致，合并去重时对不上，重复内容大量涌入上下文。后来统一成一套切分结果，两路共用，问题消失。这个教训是：双路检索的前提是底层数据一致，切分这种基础环节千万别各搞一套。

第二个坑是图检索的top-k设得和向量路一样。图路召回的内容关联性强但数量通常少，top-k设太大反而把弱关联的邻居也拉进来。我后来给图路单独设了更小的k，噪声明显下降。

第三个坑是忽略了图路的延迟。图查询本身不慢，但实体识别如果走LLM，每次查询多一次模型调用，端到端延迟上去了。改成"先规则匹配、匹配不上再调LLM"之后，大部分查询的延迟回到了可接受范围。

提示：图检索这套东西的调试成本比纯向量高，因为多了一个建图环节，出问题时要在"抽取—存储—查询"三段里定位。建议每段都加日志，尤其是抽取阶段记录每个chunk抽出了几个三元组，异常值（比如某chunk抽出0个或几十个）往往是问题的早期信号。

6. 一点个人经验

这套图检索RAG我前后调了挺长时间，最大的体会是：图的价值不在"多"，在"准"。早期我追求图里实体多、关系全，结果噪声把信号淹了，检索效果还不如纯向量。后来把白名单收窄、把归一化做细、把跳数压到两跳以内，图变小了，效果反而上来了。所以如果你刚开始做，别急着把图建大，先把一小块业务的实体关系抽准，跑通检索闭环，再逐步扩范围。

另一个体会是关于评测。图检索的效果很难靠肉眼看出来，必须有一批带标注的问题集做回归。我习惯每次调整抽取prompt或检索参数后，跑一遍问题集看召回率和答案准确率的变化，没有这个基线，调参就是盲调。问题集不用大，几十条覆盖主要问题类型就够，关键是稳定、可重复。

最后分享一个小技巧：建图阶段抽出来的三元组，别只写进图就完事，顺手存一份原始抽取结果（chunk原文+三元组列表）。后面排查"为什么这个实体没连上"时，翻这份记录比去图里反查快得多。这个习惯帮我省了不少时间。