LlamaIndex 图存储集成实战：在 Neo4j、NebulaGraph、FalkorDB、Amazon Neptune 与 TiDB 上构建知识图谱

LlamaIndex 图存储集成实战在 Neo4j、NebulaGraph、FalkorDB、Amazon Neptune 与 TiDB 上构建知识图谱【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文基于 LlamaIndex 官方文档《Using Graph Stores》展开系统讲解五款图存储Graph Store集成——Neo4j、NebulaGraph、FalkorDB、Amazon Neptune 与 TiDB 的接入方式与参数细节并结合仓库源码剖析GraphStore协议与PropertyGraphStore双层抽象的底层设计以及KnowledgeGraphIndex从文本三元组抽取到落库查询的完整调用链。读完后你可以独立完成安装对应集成包、用StorageContext注入图存储、构建知识图谱索引并借助KnowledgeGraphQueryEngine以 text2cypher 方式问答已有图数据。图存储的抽象GraphStore 协议与 PropertyGraphStoreLlamaIndex 中所有图存储集成都实现 核心协议 GraphStore。该协议一个runtime_checkable的Protocol规定了一个图存储必须具备的最小能力集成员签名作用clientpropertyAny底层数据库客户端Neo4j driver、FalkorDB graph 等get(subj)List[List[str]]查询某主题实体subject出发的全部三元组get_rel_map(subjs, depth, limit)Dict[str, List[List[str]]]返回扁平化的多跳关系路径默认depth2, limit30upsert_triplet(subj, rel, obj)None写入一条三元组已存在则保持不变delete(subj, rel, obj)None删除一条三元组get_schema(refresh)str返回图 schema 的文本描述供 LLM 生成查询时参考query(query, param_map)Any执行数据库方言Cypher、nGQL 等的原始查询persist(persist_path, fs)None将图存储持久化到文件协议中提供空实现这套三元组协议是轻接口适配各数据库中最通用的节点 关系模型。在 types.py 中还定义了面向新架构的抽象基类PropertyGraphStore它支持带标签的节点与关系LabelledNode/Relation含properties字典并要求实现get/get_triplets/get_rel_map按entity_names、relation_names、properties、ids等维度过滤upsert_nodes/upsert_relations批量写入带属性的节点与关系并内置upsert_llama_nodes将 LlamaIndex 的BaseNode文本 元数据 embedding转换为ChunkNode写入图库structured_query与vector_query分别执行结构化语句查询与向量相似度查询由类属性supports_structured_queries、supports_vector_queries标记能力一组以a开头的异步方法aget、aupsert_nodes等默认退化为同步调用子类可覆写。仓库中的每个图存储集成包通常同时提供两类实现旧协议的XxxGraphStore如Neo4jGraphStore与新协议的XxxPropertyGraphStore如 Neo4jPropertyGraphStore分别服务KnowledgeGraphIndex与PropertyGraphIndex两条索引路径。KnowledgeGraphIndex从文本到三元组五款图存储集成的统一消费入口是KnowledgeGraphIndex其实现位于 knowledge_graph/base.py。需要注意源码中该类已被标记废弃base.py 的deprecated.deprecated装饰器提示自 0.10.53 起推荐使用PropertyGraphIndex仓库中仍保留完整实现与示例本文以它为主线讲解。其核心构建流程_build_index_from_nodes见 base.py对每个文本节点调用_extract_triplets默认用 LLM 以DEFAULT_KG_TRIPLET_EXTRACT_PROMPT提示词抽取每块文本最多抽取max_triplets_per_chunk默认 10条三元组解析 LLM 输出中的(subj, rel, obj)形式_parse_triplet_response会过滤非法行、按 UTF-8 字节长度截断超长 token默认上限max_object_length128并做去引号 首字母大写以消歧逐条调用self.upsert_triplet(triplet)该方法直接转发给self._graph_store.upsert_triplet(*triplet)——这正是GraphStore协议被触达的地方通过index_struct.add_node([subj, obj], n)把三元组两端实体与源文本节点关联起来KG结构实现命中图节点 → 反查原文 chunk → 交给 LLM 合成回答的检索闭环。其他关键行为include_embeddingsTrue时会把每条三元组的文本向量化并写入embedding_dict此时as_retriever()默认切换为KGRetrieverMode.HYBRID关键词 向量混合否则使用KGRetrieverMode.KEYWORD见 base.py 的as_retrieverget_networkx_graph(limit)借助get_rel_map(subjs, depth1, limit)把图转成 NetworkX 对象用于可视化需pip install networkx支持自定义抽取函数构造时传入kg_triplet_extract_fn可完全替换 LLM 抽取逻辑。标准构建流程五款图库通用各集成示例 Notebook如 Neo4jKGIndexDemo.ipynb都遵循同一套五步流程只有第一步的图库客户端不同from llama_index.core import ( SimpleDirectoryReader, StorageContext, KnowledgeGraphIndex, ) # 第一步实例化图存储以 Neo4j 为例见下文各节参数 graph_store Neo4jGraphStore(username..., password..., url..., database...) # 第二步将图存储注入存储上下文 storage_context StorageContext.from_defaults(graph_storegraph_store) # 第三步加载文档 documents SimpleDirectoryReader(./data).load_data() # 第四步构建知识图谱索引LLM 逐块抽取三元组并 upsert 到图库耗时较长 index KnowledgeGraphIndex.from_documents( documents, storage_contextstorage_context ) # 第五步查询 query_engine index.as_query_engine() response query_engine.query(文档作者的主要观点是什么)五款图存储集成详解以下逐一对应文档中列出的五个集成给出安装包名、构造参数含默认值均摘自源码与示例 Notebook 位置。所有集成位于 llama-index-integrations/graph_stores/ 目录各自独立发包。Neo4jGraphStoreNeo4j 是被文档着墨最多的集成既可以持久化、可视化 LlamaIndex 构建的图也支持对已有 Neo4j 图通过text2cypherKnowledgeGraphQueryEngine直接问答。环境与插件要求继承自原文档若从未使用过 Neo4j可先下载 Neo4j Desktop 客户端在 Desktop 中新建项目后点击项目、在左侧菜单选择Plugins安装APOC插件并重启服务器。APOC 不是可选项——Neo4jGraphStore的refresh_schema依赖apoc.meta.data()生成 schema 描述源码在refresh_schemaTrue默认下若执行 APOC 失败会抛出ValueError: Could not use APOC procedures...见 base.py。构造函数参数摘自 neo4j/base.py参数类型 / 默认值说明username/password/url必填str连接三元组初始化时立即verify_connectivity()失败分别报url 不正确或用户名密码不正确databaseneo4j目标数据库名node_labelEntity所有实体节点统一使用的标签refresh_schemaTrue构造时是否立即用 APOC 刷新 schemaapoc_sampleNone传入后以{sample: n}配置apoc.meta.data对大图做采样式 schema 探测timeoutNone查询超时秒user_agentLLAMAINDEX-GRAPH驱动 user-agent构造时的两个细节值得注意自动建约束初始化会尝试创建n.id唯一约束先按 Neo4j 5 语法CREATE CONSTRAINT IF NOT EXISTS ... REQUIRE ...执行失败则回退旧语法base.py从而兼容 Neo4j 5 的服务端也加速按 id 的插入与检索schema 生成refresh_schema依次执行节点属性、关系属性、关系模式三条apoc.meta.data查询base.py拼成 Node properties are the following: ... / The relationships are the following:(:A)-[:REL]-(:B) 的文本即get_schema()返回值正是 text2cypher 查询引擎生成 Cypher 的上下文。写入路径上upsert_triplet使用三条MERGE语句幂等地合并两端节点与关系关系类型名会做rel.replace( , _).upper()规范化base.pydelete则在删除关系后检查两端节点是否还有边无边的孤立实体一并删除。该实现还支持上下文管理器with Neo4jGraphStore(...) as graph:与显式close()query方法在遇到隐式事务类错误时会自动降级到 session 级执行base.py。完整示例见 Neo4jKGIndexDemo.ipynbgraph_store Neo4jGraphStore( usernameusername, passwordpassword, urlurl, databasedatabase, ) storage_context StorageContext.from_defaults(graph_storegraph_store) index KnowledgeGraphIndex.from_documents(documents, storage_contextstorage_context) query_engine index.as_query_engine()对应安装包为llama-index-graph-stores-neo4jpyproject.toml 显示依赖neo4j5.16.0,6与llama-index-core0.13.0,0.15要求 Python3.10,4.0导出类见init.pyNeo4jGraphStore、Neo4jPropertyGraphStore别名Neo4jPGStore以及 cypher_corrector.py 中的Schema与CypherQueryCorrector——后者用于校验/修正 LLM 生成的 Cypher是 text2cypher 问答链路的配套组件。NebulaGraphStoreNebula 集成的实现位于 nebula_graph_store.py同样支持将图直接持久化到 Nebula并配合KnowledgeGraphQueryEngine以自然语言问答。与 Neo4j 的三元组自由写入不同Nebula 是强模式图数据库需要在建空间space时预先声明标签与边类型因此构造函数要求显式传入模式信息graph_store NebulaGraphStore( space_namespace_name, # 图空间名 edge_typesedge_types, # 允许的边类型列表 rel_prop_namesrel_prop_names, # 关系属性名 tagstags, # 节点标签 )上述用法摘自 NebulaGraphKGIndexDemo.ipynb。该包llama-index-graph-stores-nebula依赖nebula3-python3.8.0,4目录内还提供新协议的 NebulaPropertyGraphStore。FalkorDBGraphStoreFalkorDB 集成见 falkordb/base.py构造函数参数参数默认值说明url必填FalkorDB 连接串示例中使用redis://localhost:6379databasefalkor图名FalkorDB 一个连接下可建多个图node_labelEntity实体节点标签**kwargs—透传给客户端可传username、password、ssl等graph_store FalkorDBGraphStore(redis://localhost:6379, decode_responsesTrue)实现细节上构造时会自动执行CREATE INDEX FOR (n:Entity) ON (n.id)建立 id 索引已存在则忽略refresh_schema通过CALL DB.PROPERTYKEYS()与CALL DB.RELATIONSHIPTYPES()两个 OpenCypher 过程拼装 schema 文本base.py此外还提供switch_graph(graph_name)在同一连接内切换活动图base.py适合多图隔离的部署。三元组写入逻辑与 Neo4j 一致三条MERGE 关系名规范化。安装包为llama-index-graph-stores-falkordb依赖falkordb1.0.8,2完整示例见 FalkorDBGraphDemo.ipynb新协议实现为 FalkorDBPropertyGraphStore。Amazon Neptune Graph Stores文档中唯一按一条产品线、两种服务形态展开的集成同时支持Neptune Database与Neptune Analytics。仓库中 llama-index-graph-stores-neptune 包按这一结构组织database.pyNeptuneDatabaseGraphStore基于 OpenCypher 端点连接参数为host与port默认 8182analytics.pyNeptuneAnalyticsGraphStore参数为graph_identifier两者共享抽象基类NeptuneBaseGraphStorebase.py并各自配有NeptuneDatabasePropertyGraphStore/NeptuneAnalyticsPropertyGraphStore属性图版本。示例 NotebookNeptuneDatabaseKGIndexDemo.ipynb中两种形态的写法# Neptune Database graph_store NeptuneDatabaseGraphStore( hostGRAPH NAME.CLUSTER ID.REGION.neptune.amazonaws.com, port8182, ) # Neptune Analytics graph_store NeptuneAnalyticsGraphStore( graph_identifierINSERT GRAPH IDENIFIER ) storage_context StorageContext.from_defaults(graph_storegraph_store) index KnowledgeGraphIndex.from_documents(documents, storage_contextstorage_context)该 Notebook 在环境准备阶段会%pip install boto3用于 AWS 侧的凭证与服务调用。TiDBGraphStoreTiDB 集成实现位于 tidb/graph.py核心只有一个连接串参数——TiDB 本身是兼容 MySQL 协议的分布式数据库LlamaIndex 通过tidb-vector客户端走 MySQL 协议接入graph_store TiDBGraphStore( db_connection_stringmysqlpymysql://user:passwordhost:4000/dbname )摘自 TiDBKGIndexDemo.ipynb。安装包llama-index-graph-stores-tidb依赖tidb-vector0.0.9,0.0.10同包内还提供 TiDBPropertyGraphStore。对已有图问答text2cypher 与 KnowledgeGraphQueryEngine文档对 Neo4j、Nebula、FalkorDB 均提到同一能力对已经存在的图生成图查询语句并返回自然语言回答。在仓库中对应两个核心组件KnowledgeGraphQueryEngineknowledge_graph_query_engine.py属于BaseQueryEngine工作方式是schema 描述 用户问题 → LLM 生成查询语句 → 交给graph_store.query()执行 → 将结果集喂给 LLM 合成回答提示词模板graph_stores/prompts.py 中定义了默认 Cypher 模板types.py中引用的DEFAULT_CYPHER_TEMPALTE作为PropertyGraphStore.text_to_cypher_template的默认值。Neo4j 集成还额外提供了 CypherQueryCorrector在查询前对 LLM 输出的 Cypher 做 schema 约束下的修正。get_schema()/refresh_schema()在整条链路中扮演图结构说明书的角色Neo4j 用 APOC 元数据过程、FalkorDB 用DB.PROPERTYKEYS()等内置过程动态生成这也是为什么前文强调 APOC 插件必须装好——没有它schema 描述缺失text2cypher 的生成质量无从谈起。安装与环境要求五款集成均为独立 PyPI 包按所用图库按需安装pip install llama-index-graph-stores-neo4j pip install llama-index-graph-stores-nebula pip install llama-index-graph-stores-falkordb pip install llama-index-graph-stores-neptune pip install llama-index-graph-stores-tidb各包的pyproject.toml均声明llama-index-core0.13.0,0.15第三方客户端版本约束摘自各包 pyproject.toml 的dependencies段集成包第三方依赖约束llama-index-graph-stores-neo4jneo4j5.16.0,6Python3.10,4.0llama-index-graph-stores-falkordbfalkordb1.0.8,2llama-index-graph-stores-nebulanebula3-python3.8.0,4llama-index-graph-stores-tidbtidb-vector0.0.9,0.0.10llama-index-graph-stores-neptune依赖 AWS SDK示例 Notebook 中通过boto3安装适用前提小结所有XxxGraphStore均实现同一GraphStore三元组协议因此与KnowledgeGraphIndex的组合方式完全一致切换图库只需替换第一步的客户端实例同时建议新代码关注各包中配套的XxxPropertyGraphStore与PropertyGraphIndex路径因为旧版KnowledgeGraphIndex在源码中已被标记为待废弃。小结五款图存储Neo4j / NebulaGraph / FalkorDB / Amazon Neptune / TiDB通过 GraphStore 协议 提供统一的三元组读写、schema 获取与原始查询接口KnowledgeGraphIndex.from_documents完成LLM 抽三元组 →upsert_triplet落库 → 节点-文本关联的建图闭环as_query_engine()完成检索问答各集成的差异化体现在连接参数与 schema 生成策略上Neo4j 依赖 APOC、Nebula 需要预声明模式、FalkorDB 支持多图切换、Neptune 区分 Database/Analytics 两种形态、TiDB 复用 MySQL 连接串对已有图库可直接用KnowledgeGraphQueryEnginetext2cypher做自然语言问答Neo4j 还附带CypherQueryCorrector提升查询正确率。【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考