Graphiti 2025详解：实时知识图谱框架构建AI智能体指南

引言

Graphiti 是一个用于构建和查询具有时间感知能力的知识图谱A structured knowledge base that represents entities and their relationships in a graph format.的框架，专为在动态环境中运行的 AI 智能体量身定制。与传统检索增强生成（RAG）方法不同，Graphiti 持续地将用户交互、结构化和非结构化的企业数据以及外部信息整合到一个连贯、可查询的图谱中。该框架支持增量数据更新、高效检索和精确的历史查询，无需完整的图谱重新计算，使其非常适合开发交互式、上下文感知的 AI 应用程序。

使用 Graphiti 可以实现：

• 集成和维护动态的用户交互与业务数据。
• 为智能体提供基于状态的推理和任务自动化支持。
• 通过语义、关键词和图遍历在图结构中沿着边从一个节点移动到另一个节点的搜索过程，用于发现实体间的关联路径和关系网络。等混合搜索方法，查询复杂且不断演化的数据。

核心理念

什么是知识图谱？

知识图谱是一个由相互关联的事实构成的网络，例如“Kendra 喜欢阿迪达斯鞋”。每个事实都是一个“三元组”，由两个实体（或称节点，如“Kendra”、“阿迪达斯鞋”）和它们之间的关系（或称边，如“喜欢”）表示。知识图谱在信息检索领域已被广泛探索。Graphiti 的独特之处在于其能够自主构建知识图谱，同时处理变化的关系并维护历史上下文。

Graphiti 与 Zep 的关系

Graphiti 是 Zep 上下文工程平台的核心。Zep 提供智能体记忆、用于动态数据的图 RAG 以及上下文检索与组装功能。通过使用 Graphiti，我们已证明 Zep 在智能体记忆领域处于领先地位。我们很高兴能将 Graphiti 开源，相信其潜力远不止于 AI 记忆应用。

Zep 与 Graphiti 对比

何时选择哪个？

• 选择 Zep：如果您想要一个开箱即用、具有企业级安全性、性能和支持的平台。
• 选择 Graphiti：如果您想要一个灵活的开源核心，并且愿意构建/运维周边系统。

Graphiti 的核心优势

传统的 RAG 方法通常依赖批处理和静态数据摘要，对于频繁变化的数据效率低下。Graphiti 通过提供以下功能应对这些挑战：

• 实时增量更新无需重新计算整个图谱，仅对新数据片段进行即时整合的数据更新机制，适用于动态变化的数据环境。：无需批处理重新计算，即可立即集成新的数据片段。
• 双时间数据模型同时跟踪事件发生时间和数据摄入时间的时序数据模型，支持精确的时间点查询和历史上下文维护。：明确追踪事件发生时间和摄取时间，允许进行精确的时间点查询。
• 高效的混合检索结合语义嵌入、关键词搜索和图遍历等多种检索技术的综合查询方法，旨在提高检索精度和效率。：结合语义嵌入将文本或实体转换为高维向量表示的技术，使语义相似的实体在向量空间中距离相近，支持基于语义的相似性搜索。、关键词（BM25）和图遍历，实现低延迟查询，无需依赖 LLM 摘要。
• 自定义实体定义对关键技术术语的明确解释和描述：通过简单的 Pydantic 模型，支持灵活的本体创建和开发者定义的实体。
• 可扩展性：通过并行处理高效管理大型数据集，适用于企业环境。

Graphiti 与 GraphRAG 对比

Graphiti 专门设计用于应对动态和频繁更新数据集的挑战，使其特别适用于需要实时交互和精确历史查询的应用程序。

快速入门

安装

要求：

• Python 3.10 或更高版本
• 图数据库后端：Neo4j 5.26 / FalkorDB 1.1.2 / Kuzu 0.11.2 / Amazon Neptune Database Cluster 或 Neptune Analytics Graph + Amazon OpenSearch Serverless collection（作为全文搜索后端）
• OpenAI API 密钥（Graphiti 默认使用 OpenAI 进行 LLM 推理和嵌入）

重要提示： Graphiti 最适合支持结构化输出的 LLM 服务（如 OpenAI 和 Gemini）。使用其他服务可能导致输出模式不正确和摄取失败。在使用较小模型时尤其如此。

可选：

• Google Gemini、Anthropic 或 Groq API 密钥（用于替代 LLM 提供商）

提示： 安装 Neo4j 最简单的方法是使用 Neo4j Desktop。它提供了一个用户友好的界面来管理 Neo4j 实例和数据库。或者，您可以通过 Docker 在本地使用 FalkorDB，并立即开始使用快速入门示例：docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest

安装核心库：

pip install graphiti-core
# 或
uv add graphiti-core

安装特定后端支持：

• FalkorDB：pip install graphiti-core[falkordb] 或 uv add graphiti-core[falkordb]
• Kuzu：pip install graphiti-core[kuzu] 或 uv add graphiti-core[kuzu]
• Amazon Neptune：pip install graphiti-core[neptune] 或 uv add graphiti-core[neptune]

安装 LLM 提供商支持：

# 安装 Anthropic 支持
pip install graphiti-core[anthropic]
# 安装 Groq 支持
pip install graphiti-core[groq]
# 安装 Google Gemini 支持
pip install graphiti-core[google-genai]
# 组合安装
pip install graphiti-core[falkordb,anthropic,google-genai]

并发控制

Graphiti 的摄取管道设计为高并发。默认情况下，并发度设置得较低，以避免 LLM 提供商的 429 速率限制错误。如果您觉得 Graphiti 运行缓慢，可以按照以下说明增加并发度。

并发度由 SEMAPHORE_LIMIT 环境变量控制。默认情况下，SEMAPHORE_LIMIT 设置为 10 个并发操作，以帮助防止来自 LLM 提供商的 429 错误。如果遇到此类错误，请尝试降低此值。如果您的 LLM 提供商允许更高的吞吐量，您可以增加 SEMAPHORE_LIMIT 以提高片段摄取性能。

基本使用示例

重要提示： Graphiti 默认使用 OpenAI 进行 LLM 推理和嵌入。请确保在环境中设置了 OPENAI_API_KEY。也支持 Anthropic 和 Groq LLM 推理。其他 LLM 提供商可能通过 OpenAI 兼容的 API 得到支持。

有关完整的工作示例，请参阅 examples 目录中的 快速入门示例。该示例演示了：

• 连接到 Neo4j、Amazon Neptune、FalkorDB 或 Kuzu 数据库
• 初始化 Graphiti 索引和约束
• 向图中添加片段（包括文本和结构化 JSON）
• 使用混合搜索查找关系（边）
• 使用图距离对搜索结果进行重排序
• 使用预定义的搜索方案搜索节点

高级配置与集成

自定义数据库配置

从 v0.17.0 开始，如果您需要自定义数据库配置，可以实例化一个数据库驱动并将其传递给 Graphiti 构造函数，使用 graph_driver 参数。

Neo4j 自定义数据库名示例：

from graphiti_core import Graphiti
from graphiti_core.driver.neo4j_driver import Neo4jDriver

driver = Neo4jDriver(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    database="my_custom_database"  # 自定义数据库名
)
graphiti = Graphiti(graph_driver=driver)

FalkorDB 自定义数据库名示例：

from graphiti_core import Graphiti
from graphiti_core.driver.falkordb_driver import FalkorDriver

driver = FalkorDriver(
    host="localhost",
    port=6379,
    username="falkor_user",  # 可选
    password="falkor_password",  # 可选
    database="my_custom_graph"  # 自定义数据库名
)
graphiti = Graphiti(graph_driver=driver)

与 Azure OpenAI 集成

Graphiti