11.1 · 快速入门教程

快速入门教程

快速入门教程

相关源文件

以下文件为本维基页面的生成提供了上下文：

• README.md
• examples/quickstart/README.md
• examples/quickstart/quickstart_falkordb.py
• examples/quickstart/quickstart_neo4j.py
• examples/quickstart/quickstart_neptune.py
• examples/quickstart/requirements.txt
• graphiti_core/decorators.py

本页面将逐一讲解 examples/quickstart/ 目录下三个针对不同后端的快速入门脚本：quickstart_neo4j.py、quickstart_falkordb.py 和 quickstart_neptune.py。每个脚本都演示了相同的六步工作流——初始化、索引设置、剧集入库、边搜索、图距离重排序和节点搜索——但分别针对不同的图数据库后端。

关于 Graphiti 类本身的背景信息，请参见 Graphiti 核心客户端。关于搜索配置选项，请参见 搜索配置与调优。关于通用安装指南，请参见 入门指南。

工作流概览

所有三个快速入门脚本都遵循相同的操作顺序：

快速入门工作流

来源：examples/quickstart/quickstart_neo4j.py:57-239, examples/quickstart/quickstart_falkordb.py:65-250, examples/quickstart/quickstart_neptune.py:61-252

前提条件

安装基础包：

pip install graphiti-core

如需 FalkorDB 支持，安装额外依赖：

pip install graphiti-core[falkordb]

如需 Neptune 支持：

pip install graphiti-core[neptune]

快速入门中的 requirements.txt 仅固定了 graphiti-core 和 python-dotenv。

来源：examples/quickstart/README.md:14-54, examples/quickstart/requirements.txt:1-2

第一步——配置

每个脚本都使用 python-dotenv 从环境变量读取连接参数。

Neo4j examples/quickstart/quickstart_neo4j.py:47-54：

FalkorDB examples/quickstart/quickstart_falkordb.py:59-62：

Neptune examples/quickstart/quickstart_neptune.py:49-58：

对于 Neptune，主机字符串格式取决于集群类型：

• Neptune Database：neptune-db://<集群端点>
• Neptune Analytics：neptune-graph://<图标识符>

来源：examples/quickstart/quickstart_neo4j.py:47-54, examples/quickstart/quickstart_falkordb.py:59-62, examples/quickstart/quickstart_neptune.py:49-58, examples/quickstart/README.md:36-58

第二步——驱动实例化与 Graphiti 初始化

驱动与客户端实例化

Neo4j——Graphiti 类可以直接接受连接参数，并在内部构造 Neo4jDriver examples/quickstart/quickstart_neo4j.py:67：

graphiti = Graphiti(neo4j_uri, neo4j_user, neo4j_password)

FalkorDB——显式实例化 FalkorDriver，并通过 graph_driver 参数传入 examples/quickstart/quickstart_falkordb.py:75-78：

falkor_driver = FalkorDriver(
    host=falkor_host, port=falkor_port, username=falkor_username, password=falkor_password
)
graphiti = Graphiti(graph_driver=falkor_driver)

Neptune——显式实例化 NeptuneDriver，同时传入 Neptune 端点和 OpenSearch Serverless 主机 examples/quickstart/quickstart_neptune.py:71-73：

driver = NeptuneDriver(host=neptune_uri, aoss_host=aoss_host, port=neptune_port)
graphiti = Graphiti(graph_driver=driver)

索引初始化： Neo4j 和 FalkorDB 脚本在快速入门中并未显式调用 build_indices_and_constraints()——Graphiti 构造函数会自动处理。Neptune 脚本则显式调用了该方法 examples/quickstart/quickstart_neptune.py:77-80，因为它还需要先调用 driver.delete_aoss_indices() 和 driver._delete_all_data() 来重置状态。

来源：examples/quickstart/quickstart_neo4j.py:67, examples/quickstart/quickstart_falkordb.py:75-78, examples/quickstart/quickstart_neptune.py:71-80, graphiti_core/__init__.py:126-154

第三步——添加剧集

所有三个脚本都添加了相同的四个剧集。其中两个使用 EpisodeType.text，另外两个使用 EpisodeType.json。内容涉及加州政客卡玛拉·哈里斯（Kamala Harris）和加文·纽森（Gavin Newsom）。

剧集数据（所有后端）

每个剧集通过 graphiti.add_episode() 添加 examples/quickstart/quickstart_neo4j.py:117-127：

await graphiti.add_episode(
    name=f'Freakonomics Radio {i}',
    episode_body=episode['content']
    if isinstance(episode['content'], str)
    else json.dumps(episode['content']),
    source=episode['type'],           # EpisodeType.text 或 EpisodeType.json
    source_description=episode['description'],
    reference_time=datetime.now(timezone.utc),
)

对于 JSON 类型的剧集，字典会先通过 json.dumps() 序列化为字符串，再作为 episode_body 传入。source 参数（EpisodeType 枚举值）告诉管线如何解析内容以进行提取。

add_episode 会触发完整的实体/关系提取和去重管线。对于每个剧集，Graphiti 会：

1. 根据 EpisodeType 解析剧集内容。
2. 使用大语言模型提取实体节点和关系边。
3. 将提取的实体与现有图节点进行比对（去重）。
4. 持久化新节点和新边，并使矛盾边失效。

来源：examples/quickstart/quickstart_neo4j.py:80-127, examples/quickstart/quickstart_falkordb.py:91-138, examples/quickstart/quickstart_neptune.py:91-138, graphiti_core/nodes.py:27-28

第四步——基本边搜索

入库之后，最简单的检索方法是 graphiti.search()，它会返回 EntityEdge 对象（事实/关系），使用结合了向量相似度和 BM25 的混合搜索。

results = await graphiti.search('Who was the California Attorney General?')

results 中的每个结果都是一个 EntityEdge，包含以下字段：

脚本会打印每个字段，并使用 hasattr 检查来保护 valid_at 和 invalid_at，因为它们是可选字段 examples/quickstart/quickstart_neo4j.py:144-151。

来源：examples/quickstart/quickstart_neo4j.py:138-151, examples/quickstart/quickstart_falkordb.py:149-162, examples/quickstart/README.md:110-118

第五步——图距离重排序

第二次 search() 调用演示了基于图距离的重排序。基本搜索中第一个结果的 source_node_uuid 被用作 center_node_uuid。在图中距离该节点更近的结果会被排在更前面。

代码参考 examples/quickstart/quickstart_neo4j.py:162-183：

center_node_uuid = results[0].source_node_uuid
reranked_results = await graphiti.search(
    'Who was the California Attorney General?',
    center_node_uuid=center_node_uuid
)

当已知某个特定实体的上下文，并且需要更多相关事实时，这种方法非常有用。重排序使用从中心节点开始的 BFS 图距离。

来源：examples/quickstart/quickstart_neo4j.py:162-183, examples/quickstart/quickstart_falkordb.py:173-195, examples/quickstart/README.md:73-78

第六步——使用搜索配方进行节点搜索

除了边/事实搜索之外，Graphiti 还可以使用 graphiti._search() 配合 SearchConfig 直接搜索实体节点。快速入门使用了 graphiti_core.search.search_config_recipes 中预定义的配方 NODE_HYBRID_SEARCH_RRF。

代码参考 examples/quickstart/quickstart_neo4j.py:200-222：

node_search_config = NODE_HYBRID_SEARCH_RRF.model_copy(deep=True)
node_search_config.limit = 5

node_search_results = await graphiti._search(
    query='California Governor',
    config=node_search_config,
)

结果通过 node_search_results.nodes 访问。列表中的每个 EntityNode 包含以下字段：

注意，graphiti._search()（带 _ 前缀）是接受完整 SearchConfig 的底层方法。步骤 4 和步骤 5 中使用的高级方法 graphiti.search() 仅返回边。完整的搜索配置参考，请参见 搜索配置与调优。

来源：examples/quickstart/quickstart_neo4j.py:194-222, examples/quickstart/quickstart_falkordb.py:205-234, examples/quickstart/README.md:78-79, graphiti_core/decorators.py:76-77

第七步——清理

所有脚本都在 finally 块中关闭 Graphiti 客户端，以释放数据库连接：

await graphiti.close()

来源：examples/quickstart/quickstart_neo4j.py:225-235, examples/quickstart/quickstart_falkordb.py:236-246

后端对比

这三个脚本几乎完全相同。有意义的差异如下：

来源：examples/quickstart/README.md:14-54, examples/quickstart/quickstart_neptune.py:61-80, examples/quickstart/quickstart_falkordb.py:59-78

代码实体映射

快速入门代码实体映射

来源：examples/quickstart/quickstart_neo4j.py:26-29, examples/quickstart/quickstart_falkordb.py:26-29, examples/quickstart/quickstart_neptune.py:26-29

故障排查

Graph not found: default_db 错误（Neo4j）

当 Neo4j 驱动找不到目标数据库时会发生此错误。Neo4jDriver 默认使用 neo4j 数据库。如果需要使用其他数据库名称，请显式传入：

from graphiti_core.driver.neo4j_driver import Neo4jDriver

driver = Neo4jDriver(uri=neo4j_uri, user=neo4j_user, password=neo4j_password, database="your_db_name")
graphiti = Graphiti(graph_driver=driver)

速率限制错误（大语言模型提供商）

Graphiti 的入库管线是并发的。默认的 SEMAPHORE_LIMIT 为 10。如果遇到 429 错误，可以通过环境变量降低该值。

来源：examples/quickstart/README.md:92-105, README.md:226-235