Graphiti-构建适用于 AI 智能体的实时知识图谱

推荐语

Graphiti，为AI智能体构建动态知识图谱的新框架。

核心内容：
1. Graphiti框架的核心功能与特点
2. Graphiti与传统RAG方法的对比优势
3. Graphiti在Zep AI智能体中的应用案例

杨芳贤

53A创始人/腾讯云(TVP)最具价值专家

? 小提示

了解一下 Graphiti 的新 MCP 服务器^[1]！为 Claude、Cursor 等 MCP 客户端提供基于知识图谱的强大记忆能力。

什么是 Graphiti？

Graphiti 是一个用于构建和查询时间感知知识图谱的框架，专为在动态环境中运行的 AI 智能体设计。
与传统的检索增强生成（RAG）方法不同，Graphiti 能够持续整合用户交互、结构化与非结构化企业数据，以及外部信息，构建成一个连贯且可查询的图谱。
该框架支持增量数据更新、高效检索与精准的历史查询，且无需整体重新计算图谱，非常适合开发交互式、上下文感知型 AI 应用。

使用 Graphiti 可以：

•整合并维护动态的用户交互和业务数据。•支持智能体基于状态的推理和任务自动化。•通过语义搜索、关键词搜索、图遍历等方式，查询复杂、不断演化的数据。

知识图谱是由互相关联的事实组成的网络，例如：“Kendra 喜爱 Adidas 鞋子。”
每条事实是一个“三元组”，由两个实体（或称节点，如“Kendra”和“Adidas 鞋子”）以及它们之间的关系（或称边，如“喜爱”）表示。
知识图谱已在信息检索领域得到了广泛的研究与应用。

Graphiti 的独特之处在于，它能够自主构建知识图谱，同时处理关系变化并保持历史上下文。

Graphiti 与 Zep 记忆

Graphiti 驱动着 Zep 的 AI 智能体记忆核心。

通过 Graphiti，我们证明了：Zep 是当前智能体记忆领域的最先进方案。

? 阅读我们的论文：Zep：面向智能体记忆的时间知识图架构^[2]

我们非常激动地将 Graphiti 开源，因为我们相信它的潜力远远超越了 AI 记忆应用。

为什么选择 Graphiti？

传统的 RAG 方法通常依赖批量处理和静态数据摘要，因此在处理经常变化的数据时效率低下。

Graphiti 针对这一挑战，带来了以下优势：

•实时增量更新
新数据片段能够即时整合，无需批量重计算。•双时间数据模型
明确记录事件的发生时间和接收时间，支持精准的时点查询。•高效的混合检索
结合了语义嵌入、关键词检索（BM25）和图遍历，实现了低延迟查询，且无需依赖大型语言模型（LLM）摘要。•自定义实体定义
通过直观简单的 Pydantic 模型，开发者可以灵活创建本体论和自定义实体。•优异的可扩展性
支持并行处理，能够高效管理大规模数据集，适用于企业级应用场景。

Graphiti 与 GraphRAG 对比

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

安装指南

环境要求：

•Python 3.10 或更高版本•Neo4j 5.26 或更高版本（用作嵌入存储后端）•OpenAI API 密钥（用于 LLM 推理与嵌入生成）

重要提示

Graphiti 在支持结构化输出的 LLM 服务（如 OpenAI 和 Gemini）上效果最佳。
使用其他服务可能导致输出模式错误或数据导入失败，尤其是在使用小型模型时问题更为明显。

可选项：

•Google Gemini、Anthropic 或 Groq 的 API 密钥（用于接入其他 LLM 提供商）

小提示

安装 Neo4j 最简单的方式是使用 Neo4j Desktop。
它提供了一个用户友好的界面，便于管理 Neo4j 实例和数据库。

pip install graphiti-core

或者

poetry add graphiti-core

你也可以通过安装可选的 LLM 提供商支持来扩展功能：

# 安装并支持 Anthropicpip install graphiti-core[anthropic]
# 安装并支持 Groqpip install graphiti-core[groq]
# 安装并支持 Google Geminipip install graphiti-core[google-genai]
# 同时安装多个提供商支持pip install graphiti-core[anthropic,groq,google-genai]

快速开始

重要提示

Graphiti 使用 OpenAI 进行 LLM 推理和嵌入生成。请确保你的环境中已设置 OPENAI_API_KEY。
同时也支持 Anthropic 和 Groq 的 LLM 推理。其他 LLM 提供商可通过兼容 OpenAI API 的方式接入。

完整的示例请参考 examples 目录中的 Quickstart Example^[3]。
该快速入门示例演示了以下内容：

•连接到 Neo4j 数据库•初始化 Graphiti 的索引与约束•将情节（包括文本和结构化 JSON）添加到图中•使用混合检索方法搜索关系（边）•通过图距离对搜索结果进行重新排序•使用预定义的搜索配方搜索节点

示例中包含了每项功能的详细说明，并提供了一个完整的 README，包含环境搭建指南和后续步骤。

MCP 服务器

mcp_server 目录包含了 Graphiti 的**模型上下文协议（MCP）**服务器实现。
通过 MCP 协议，AI 助手可以与 Graphiti 的知识图谱能力进行交互。

MCP 服务器的主要功能包括：

•情节管理（添加、检索、删除）•实体管理与关系处理•支持语义与混合搜索•分组管理，用于组织相关数据•图谱维护操作

MCP 服务器可以通过 Docker 与 Neo4j 一起部署，
这使得将 Graphiti 集成到你的 AI 助手工作流中变得非常简单。

详细的安装说明和使用示例，请参阅 MCP server 目录下的 README 文档。

REST 服务

server 目录包含了一个用于与 Graphiti API 交互的 API 服务，
该服务基于 FastAPI 构建。

更多信息请参考 server 目录下的 README 文档。

可选环境变量

除了 Neo4j 和 OpenAI 兼容的认证信息外，Graphiti 还支持一些可选的环境变量。
如果你使用的是我们支持的模型（如 Anthropic 或 Voyage 模型），那么必须设置对应的环境变量。

•USE_PARALLEL_RUNTIME 是一个可选的布尔类型环境变量。
如果希望在某些搜索查询中启用 Neo4j 的并行运行时特性，可以将其设置为 true。
需要注意的是，该特性不适用于 Neo4j Community 版本或较小规模的 AuraDB 实例，因此默认是关闭状态。

在 Azure OpenAI 上使用 Graphiti

Graphiti 支持在 Azure OpenAI 平台上进行 LLM 推理和嵌入生成。
如果你希望使用 Azure OpenAI，需要为 LLM 客户端和嵌入器分别配置你的 Azure OpenAI 认证信息。

from openai importAsyncAzureOpenAIfrom graphiti_core importGraphitifrom graphiti_core.llm_client importOpenAIClientfrom graphiti_core.embedder.openai importOpenAIEmbedder,OpenAIEmbedderConfigfrom graphiti_core.cross_encoder.openai_reranker_client importOpenAIRerankerClient
# Azure OpenAI 配置api_key ="<你的 API 密钥>"api_version ="<你的 API 版本>"azure_endpoint ="<你的 Azure 终端地址>"
# 创建 Azure OpenAI 客户端（用于 LLM）azure_openai_client =AsyncAzureOpenAI(    api_key=api_key,    api_version=api_version,    azure_endpoint=azure_endpoint)
# 使用 Azure OpenAI 客户端初始化 Graphitigraphiti =Graphiti("bolt://localhost:7687",# Neo4j 数据库连接地址"neo4j",# Neo4j 用户名"password",# Neo4j 密码    llm_client=OpenAIClient(        client=azure_openai_client),    embedder=OpenAIEmbedder(        config=OpenAIEmbedderConfig(            embedding_model="text-embedding-3-small"# 使用你在 Azure 部署的嵌入模型名称),        client=azure_openai_client),# （可选）配置 Azure OpenAI 用于交叉编码器    cross_encoder=OpenAIRerankerClient(        client=azure_openai_client))
# 现在，你可以使用基于 Azure OpenAI 的 Graphiti 了

请确保将示例代码中的占位符（如 <你的 API 密钥>、<你的 API 版本>、<你的 Azure 终端地址>）替换为你实际的 Azure OpenAI 认证信息， 并指定正确的嵌入模型名称，该模型必须已经在你的 Azure OpenAI 服务中部署。

在 Graphiti 中使用 Google Gemini

Graphiti 支持使用 Google 的 Gemini 模型进行 LLM 推理与嵌入生成。
要使用 Gemini，需要分别为 LLM 客户端和嵌入器配置你的 Google API 密钥。

安装 Graphiti：

poetry add "graphiti-core[google-genai]"# oruv add "graphiti-core[google-genai]"

from graphiti_core importGraphitifrom graphiti_core.llm_client.gemini_client importGeminiClient,LLMConfigfrom graphiti_core.embedder.gemini importGeminiEmbedder,GeminiEmbedderConfig
# Google API key configurationapi_key ="<your-google-api-key>"
# Initialize Graphiti with Gemini clientsgraphiti =Graphiti("bolt://localhost:7687","neo4j","password",    llm_client=GeminiClient(        config=LLMConfig(            api_key=api_key,            model="gemini-2.0-flash")),    embedder=GeminiEmbedder(        config=GeminiEmbedderConfig(            api_key=api_key,            embedding_model="embedding-001")))
# Now you can use Graphiti with Google Gemini

文档资源

•提供指南与 API 文档^[4]•快速开始^[5]•使用 LangChain 的 LangGraph 和 Graphiti 构建智能体^[6]

项目状态与开发路线图

Graphiti 正在积极开发中。
在持续开发的同时，我们致力于保持 API 的稳定性，并专注于以下方向：

•支持自定义图谱模式：•允许开发者在导入情节数据时，提供自定义定义的节点类与边类•实现更灵活的知识表示，以适配特定的应用场景•加强检索能力：•提供更强大且可配置的检索选项•Graphiti MCP 服务器：•持续完善 MCP 服务器功能•扩大测试覆盖范围：•确保系统可靠性，并捕捉更多边缘场景

贡献指南

我们欢迎并感谢各种形式的贡献，无论是：提交代码，编写或完善文档，处理 GitHub Issues，在 Graphiti Discord 频道回答问题。

有关详细的代码贡献指南，请参阅 CONTRIBUTING 文档^[7]。

附加信息

希望本文能够对您有所帮助，更多信息请查看https://github.com/getzep/graphiti，谢谢！

References

[1] Graphiti 的新 MCP 服务器:https://github.com/getzep/graphiti/blob/main/mcp_server/README.md
[2]Zep：面向智能体记忆的时间知识图架构:https://arxiv.org/abs/2501.13956
[3]Quickstart Example:https://github.com/getzep/graphiti/blob/main/examples/quickstart/README.md
[4]提供指南与 API 文档:https://help.getzep.com/graphiti/graphiti/overview
[5]快速开始:https://help.getzep.com/graphiti/graphiti/quick-start
[6]使用 LangChain 的 LangGraph 和 Graphiti 构建智能体:https://help.getzep.com/graphiti/graphiti/lang-graph-Agent
[7]CONTRIBUTING 文档: https://github.com/getzep/graphiti/blob/main/CONTRIBUTING.md