LlamaIndex 知识图谱检索器完全指南：KGTableRetriever 与 KnowledgeGraphRAGRetriever 原理与实战-北京尧图网络

LlamaIndex 知识图谱检索器完全指南KGTableRetriever 与 KnowledgeGraphRAGRetriever 原理与实战【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本篇技术指南以 LlamaIndex 官方 API 参考文档中 retrievers/knowledge_graph.md 为核心系统讲解 LlamaIndex 两大知识图谱检索器KGTableRetriever与KnowledgeGraphRAGRetriever的设计意图、全部构造参数、检索模式与底层实现。读完本文你将掌握如何基于KnowledgeGraphIndex构建知识图谱索引、如何用关键词/嵌入/混合模式检索三元组子图以及如何通过实体抽取与同义词扩展实现 SubGraph RAG 检索。一、文档定位两个被官方 API 收录的知识图谱检索器在 LlamaIndex 的 API 参考中llama_index.core.retrievers命名空间下集中导出了全部核心检索器其中知识图谱相关的两个成员正是本文的主角它们被声明在 llama-index-core/llama_index/core/retrievers/init.py 中与VectorIndexRetriever、SummaryIndexRetriever等并列导出from llama_index.core.indices.knowledge_graph.retrievers import ( KGTableRetriever, KnowledgeGraphRAGRetriever, )两者的完整实现位于 llama-index-core/llama_index/core/indices/knowledge_graph/retrievers.py同目录下还有知识图谱索引本体 base.py。从职责上看KGTableRetriever服务于KnowledgeGraphIndex的经典表格式检索器以关键词命中文档 → 沿图谱遍历三元组 → 回灌原文 chunk的方式组织检索上下文KnowledgeGraphRAGRetriever面向知识图谱的 RAG 检索器从查询中抽取实体、扩展同义词、抓取子图SubGraph将知识序列knowledge sequence直接拼装成上下文节点。需要注意的是两个类在源码中均标注了deprecated.deprecated(version0.10.53)官方推荐改用PropertyGraphIndex及其关联检索器但这不影响它们作为理解 LlamaIndex 知识图谱检索机制的经典范式的价值。二、前置背景KnowledgeGraphIndex 与 GraphStore要理解两个检索器先明确它们操作的数据对象。KnowledgeGraphIndex见 base.py负责在索引期用 LLM 从文本 chunk 中抽取三元组(subject, predicate, object)关键构造参数包括参数默认值作用kg_triplet_extract_template内置三元组抽取 Prompt控制从文本提取(subj, pred, obj)的 Promptmax_triplets_per_chunk10每个 chunk 最多抽取的三元组数量include_embeddingsFalse是否对每条关系文本rel_text生成并存储嵌入max_object_length128三元组 object 的最大长度kg_triplet_extract_fnNone自定义三元组抽取函数替代 LLM 抽取抽取得到的三元组会写入GraphStore图存储抽象接口定义见 graph_stores/types.py其核心方法是get_rel_map(subjs, depth, limit)负责返回指定主体subjects在给定深度下的关系映射rel map。内置的SimpleGraphStoresimple.py将图谱以内存 dict 形式保存并提供upsert_triplet、delete、persist等基础操作。检索期两个检索器正是围绕get_rel_map展开的。三、KGTableRetriever表格式知识图谱检索器3.1 构造参数全解KGTableRetriever的签名位于 retrievers.py核心参数如下参数默认值说明index必填一个KnowledgeGraphIndex实例构造时通过assert isinstance(index, KnowledgeGraphIndex)强校验llmSettings.llm用于查询关键词抽取的 LLMembed_modelSettings.embed_model用于 embedding 模式检索的嵌入模型query_keyword_extract_template内置查询关键词抽取 Prompt从查询中抽取关键词的 Prompt 模板max_keywords_per_query10单次查询最多抽取的关键词数num_chunks_per_query10最终返回给下游的文本 chunk 上限include_textTrue是否把命中三元组对应的原始文档文本一并纳入检索结果retriever_modeKGRetrieverMode.KEYWORD检索模式见 3.2similarity_top_k2embedding 模式下取相似度最高的关系文本条数graph_store_query_depth2图谱遍历深度决定子图展开几跳use_global_node_tripletsFalse是否从关键词命中的 chunk 中再抽取关键词以引入更多全局知识更贵默认关闭max_knowledge_sequence30拼入响应的知识序列关系文本最大条数3.2 检索模式KGRetrieverMode 枚举检索模式由 KGRetrieverMode 枚举定义可传枚举或对应字符串class KGRetrieverMode(str, Enum): KEYWORD keyword # 默认用关键词命中三元组 EMBEDDING embedding # 用嵌入相似度找相似三元组 HYBRID hybrid # 关键词嵌入结合三种模式在_retrieve中的执行逻辑retrievers.py分别为KEYWORD对查询用 LLM 抽取关键词 → 通过index_struct.search_node_by_keyword找到命中文档节点每个关键词最多取GLOBAL_EXPLORE_NODE_LIMIT 3个节点→ 以这些节点内容再次抽取关键词扩充主体集合 → 调用graph_store.get_rel_map(list(subjs), graph_store_query_depth)取回关系映射展平为 rel_text 列表EMBEDDING仅当index_struct.embedding_dict非空时生效索引需以include_embeddingsTrue构建否则打印 warning 并跳过用embed_model编码查询、经get_top_k_embeddings在全部关系文本中取 top-similarity_top_k相似者HYBRID两者结果合并后先去重再按长度降序剔除较短文本是较长文本子串的冗余项最后截断到max_knowledge_sequence条。3.3 检索结果的组织方式检索结束后_retrieve会构造一个特殊的TextNoderetrievers.py其文本以如下模板开头随后逐行罗列关系文本The following are knowledge sequence in max depth {graph_store_query_depth} in the form of directed graph like: subject -[predicate]-, object, -[predicate_next_hop]-, object_next_hop ...该节点的 metadata 中写入kg_rel_texts全部关系文本与kg_rel_map关系映射若图存储支持 schemagraph_store.get_schema()成功返回还会附带kg_schema。这些 metadata 键被列入excluded_embed_metadata_keys/excluded_llm_metadata_keys避免在嵌入与 LLM 调用时被重复计入。所有节点统一打上DEFAULT_NODE_SCORE 1000.0的高置信分数防止被下游截断过滤。若关键词未命中任何关系则回退为返回关键词命中的文本节点若连文本节点也没有则返回一个文本为No relationships found.的兜底节点。3.4 使用示例标准用法是通过KnowledgeGraphIndex.as_retriever()创建该方法base.py会根据索引是否包含嵌入自动选择默认模式索引含嵌入时默认HYBRID否则默认KEYWORDfrom llama_index.core import Settings from llama_index.core.indices.knowledge_graph.base import KnowledgeGraphIndex from llama_index.core.graph_stores import SimpleGraphStore from llama_index.core.storage.storage_context import StorageContext from llama_index.core.schema import Document # 1. 构建图存储与知识图谱索引 graph_store SimpleGraphStore() storage_context StorageContext.from_defaults(graph_storegraph_store) index KnowledgeGraphIndex.from_documents( [Document(textJane is mother of Bob. Bob is a programmer.)], storage_contextstorage_context, ) # 2. 通过 as_retriever 获取 KGTableRetriever可传入 retriever_mode retriever index.as_retriever(retriever_modehybrid) # 3. 直接实例化类更精细控制 from llama_index.core.retrievers import KGTableRetriever retriever KGTableRetriever( index, retriever_modehybrid, # 或 keyword / embedding similarity_top_k3, graph_store_query_depth2, max_keywords_per_query10, num_chunks_per_query10, include_textTrue, use_global_node_tripletsFalse, ) # 4. 检索 nodes retriever.retrieve(Who is Jane?) for node in nodes: print(node.node.get_content())四、KnowledgeGraphRAGRetrieverSubGraph RAG 检索器4.1 构造参数全解KnowledgeGraphRAGRetriever的签名位于 retrievers.py它不直接绑定KnowledgeGraphIndex而是面向独立的StorageContext内部必须包含graph_store构造时通过 assert 强校验。完整参数参数默认值说明storage_context必填必须携带graph_store的存储上下文llmSettings.llm用于实体抽取、同义词扩展的 LLMentity_extract_fnNone自定义实体抽取函数如基于规则/NERentity_extract_template内置查询关键词抽取 PromptLLM 抽取实体的 Prompt 模板entity_extract_policyunion函数与 LLM 两种抽取结果如何合并可选union/intersectionsynonym_expand_fnNone自定义同义词扩展函数synonym_expand_template内置同义词扩展 PromptLLM 生成同义词的 Prompt 模板synonym_expand_policyunion同上控制同义词结果合并策略max_entities5单次查询最多抽取的实体数max_synonyms5每个实体最多扩展的同义词数retriever_modekeyword可选keyword/embedding/keyword_embeddingwith_nl2graphqueryFalse是否把 NL2GraphQuery 的结果一并并入上下文graph_traversal_depth2图谱遍历深度max_knowledge_sequence30知识序列关系文本最大条数verboseFalse是否打印调试信息4.2 核心流程实体抽取 → 同义词扩展 → 子图抓取该检索器的流水线可从源码中完整还原实体抽取_get_entities→_process_entitiesretrievers.py若提供了entity_extract_fn则先由函数抽取同时用 LLM 按entity_extract_template预测解析KEYWORDS:前缀后的关键词。两条结果按entity_extract_policy合并——union取并集、intersection取交集交集模式强制要求函数与模板同时提供同义词扩展_expand_synonyms把上一步实体列表作为输入按内置的DEFAULT_SYNONYM_EXPAND_TEMPLATE让 LLM 生成大小写、复数、常见表达等变体解析SYNONYMS:前缀同样按synonym_expand_policy合并最终实体集合原实体 ∪ 同义词子图抓取_get_knowledge_sequence调用graph_store.get_rel_map(entities, graph_traversal_depth, limitmax_knowledge_sequence)取回深度感知的关系映射展平为知识序列knowledge_sequence同时保留rel_map供后续元数据使用节点构建_build_nodes将知识序列拼入上下文模板与 3.3 相同的 directed-graph 格式封装为带kg_rel_map、kg_rel_text以及可选的kg_schema元数据的NodeWithScore相关元数据键同样被排除在嵌入与 LLM 元数据之外。4.3 检索模式与 NL2GraphQuery 融合_retrieveretrievers.py按以下顺序聚合结果if self._with_nl2graphquery: nodes.extend(self._kg_query_engine._retrieve(query_bundle)) # NL2GraphQuery 结果 nodes.extend(self._retrieve_keyword(query_bundle)) # 关键词/实体模式 nodes.extend(self._retrieve_embedding(query_bundle)) # 嵌入模式其中_retrieve_keyword在retriever_mode为keyword或keyword_embedding时执行上述四步流水线_retrieve_embedding在embedding/keyword_embedding模式下调用但源码中标注# TBD: will implement this later with vector store.并直接raise NotImplementedError即当前版本嵌入模式尚未落地实践时以keyword为主。当with_nl2graphqueryTrue时构造器会额外实例化KnowledgeGraphQueryEngineknowledge_graph_query_engine.py把自然语言转图查询的结果作为补充上下文若该引擎检索抛异常仅记录 warning不影响主流程。4.4 使用示例from llama_index.core.retrievers import KnowledgeGraphRAGRetriever from llama_index.core.graph_stores import SimpleGraphStore from llama_index.core.storage.storage_context import StorageContext storage_context StorageContext.from_defaults(graph_storeSimpleGraphStore()) retriever KnowledgeGraphRAGRetriever( storage_contextstorage_context, retriever_modekeyword, # 当前推荐 keyword entity_extract_policyunion, synonym_expand_policyunion, max_entities5, max_synonyms5, graph_traversal_depth2, max_knowledge_sequence30, verboseTrue, # 打印实体、上下文等调试信息 ) nodes retriever.retrieve(Who is Jane?)verboseTrue时检索器会用绿色打印Entities processed: [...]、用蓝色打印Graph RAG context:及其后的知识序列方便调试实体抽取质量与子图命中情况。五、底层支撑GraphStore.get_rel_map 与知识序列两个检索器最终都依赖图存储的get_rel_map取回子图其协议定义于 graph_stores/types.pydef get_rel_map( self, subjs: Optional[List[str]] None, depth: int 2, limit: int 30 ) - Dict[str, List[List[str]]]: Get depth-aware rel map.subjs主体实体列表作为子图遍历的起点depth遍历深度KGTableRetriever的graph_store_query_depth与KnowledgeGraphRAGRetriever的graph_traversal_depth均直接透传该参数limit返回关系条数上限RAG 检索器将max_knowledge_sequence作为 limit 传入。返回结构Dict[str, List[List[str]]]以主体为键值为沿深度展开的关系链。此外两个检索器在初始化时都会尝试调用graph_store.get_schema(refreshrefresh_schema)获取图谱 schema 并写入检索节点的kg_schema元数据SimpleGraphStore不支持该能力get_schema直接raise NotImplementedErrorsimple.py因此使用内存图存储时kg_schema为空。六、源码测试验证检索行为的关键证据KGTableRetriever的行为在单元测试 llama-index-core/tests/indices/knowledge_graph/test_retrievers.py 中得到验证可对照理解实现细节test_as_retriever通过index.as_retriever()创建检索器并检索foo断言返回 2 个节点其中第二个节点的内容等于rel_initial_text \n raw_text即知识序列说明模板关系文本的组合印证了 3.3 节的结果组装方式test_retrievers直接实例化KGTableRetriever(index, query_keyword_extract_template..., graph_store...)用QueryBundle(foo, custom_embedding_strs[foo])检索验证知识序列文本格式与默认深度2test_retriever_no_text设置include_textFalse后检索结果只剩知识序列节点不再包含原始文本节点对应参数include_text对输出结构的直接影响。测试同时展示了配套的MockEmbedding与mock_extract_triplets说明 embedding 模式依赖索引期对关系文本(subj, pred, obj)的嵌入存储。七、弃用提示与迁移建议两个检索器均从0.10.53起被标记为 deprecated见 retrievers.py 与 retrievers.py弃用原因是官方建议改用PropertyGraphIndex及其关联检索器PGRetriever、CypherTemplateRetriever、TextToCypherRetriever、VectorContextRetriever、LLMSynonymRetriever等均已在 retrievers/init.py 中导出。若新建项目应优先评估PropertyGraphIndex而本文两个类仍适合作为理解知识图谱检索机制、阅读旧代码或维护既有索引的学习范本。结语KGTableRetriever与KnowledgeGraphRAGRetriever分别代表了 LlamaIndex 知识图谱检索的两种范式前者以索引为核心、关键词/嵌入双路命中并回灌原文后者以图存储为中心、实体抽取同义词扩展子图抓取构建独立 RAG 上下文。理解两者的参数语义retriever_mode、遍历深度、知识序列上限、文本回灌开关与底层get_rel_map调用链即可在真实项目中灵活组合知识图谱与 RAG 检索也为迁移到PropertyGraphIndex新一代检索体系打下基础。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

LlamaIndex 知识图谱检索器完全指南：KGTableRetriever 与 KnowledgeGraphRAGRetriever 原理与实战

相关推荐

JAVA毕设选题推荐：基于 SpringBoot 技术的养老院管理系统开发与实现【附源码、mysql、文档、调试+代码讲解+全bao等】

JAVA毕设选题推荐：基于 SpringBoot 的高校党员档案管理系统的设计与实现基于 SpringBoot 的高校党员信息管理系统【附源码、mysql、文档、调试+代码讲解+全bao等】

ToolJet REST API 查询传参实战：Raw JSON 与键值对两种动态值传递方式

更多资讯

Frigate+ 如何提交标注图像并请求你的第一个自定义检测模型？

Fabric Contexts 与 Sessions 实战指南：对话状态管理与可复用提示词注入

oh-my-pi Natives Addon Loader Runtime 深度解析：ESM 入口与已校验 `.node` 原生模块之间的运行时

静态代码分析工具盘点与实战：从选型到CI落地指南

Maestro 移动端自动化测试完整指南：5 分钟从安装到跑通第一个端到端流程

高效课堂笔记方法与数字工具应用指南

今日更新

Linux 内核 ARM 虚拟内存布局全解析：从 4GB 地址空间划分到源码级验证

AIGC降重工具测评与教育应用指南

数据容灾核心指标与实战方案解析

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？