Graphiti: 为你的AI智能体打造实时动态知识图谱！

AI铜锣猫
1,092 阅读12分钟

字数 3369，阅读大约需 17 分钟

Graphiti: 为你的AI智能体打造实时动态知识图谱！

Zep Logo

Zep Logo

[1]

你是否正在为你的AI智能体寻找一种能够处理动态变化信息、并能准确记忆历史状态的解决方案？传统的检索增强生成（RAG）方法在面对频繁更新的数据时常常显得力不从心。今天，我们为你介绍一个强大的开源框架——Graphiti，它专为在动态环境中运行的AI智能体设计，用于构建和查询具有时间感知能力的知识图谱。

告别静态，拥抱实时：Graphiti的核心优势

与传统的RAG方法不同，Graphiti能够持续地将用户交互、结构化和非结构化的企业数据以及外部信息整合到一个连贯、可查询的图谱中。想象一下，你的AI助手不仅能理解当前对话，还能记住几周前用户的偏好变化，或者实时整合最新的业务数据更新——这就是Graphiti的强大之处。

Graphiti temporal walkthrough

Graphiti temporal walkthrough

简单来说，知识图谱是一个由相互连接的事实组成的网络，例如“Kendra 喜欢 Adidas 鞋子”。每个事实是一个“三元组”，由两个实体（节点，如“Kendra”、“Adidas 鞋子”）和它们之间的关系（边，如“喜欢”）表示。知识图谱在信息检索领域已被广泛探索。而Graphiti的独特之处在于它能够自主构建知识图谱，同时处理不断变化的关系并保持历史背景。

Graphiti的核心能力在于：

  • • 整合与维护动态信息： 无缝集成用户交互和业务数据，保持信息的时效性。
  • • 支持基于状态的推理与任务自动化： 让AI智能体能够根据历史和当前状态做出更智能的决策和行动。
  • • 复杂演化数据的查询： 支持语义、关键词和基于图的三种搜索方法，精确查询不断变化的数据。

Graphiti的起源：Zep记忆层的核心动力

Graphiti并非凭空出现，它构成了先进的AI智能体记忆解决方案 Zep[2] 的核心记忆层。基于Graphiti，Zep被证明在智能体记忆领域达到了业界顶尖水平（State of the Art）。相关的研究成果已经发表在论文 Zep: A Temporal Knowledge Graph Architecture for Agent Memory[3] 中。

Zep: A Temporal Knowledge Graph Architecture for Agent Memory

Zep: A Temporal Knowledge Graph Architecture for Agent Memory

[4]

现在，Zep团队将Graphiti开源，相信它在AI记忆之外的领域也拥有巨大的应用潜力。

为什么选择Graphiti？深入了解其独特特性

传统的RAG方法通常依赖于批处理和静态数据摘要，这使得它们在处理频繁变化的数据时效率低下。Graphiti通过以下特性解决了这些挑战：

  • • 实时增量更新 (Real-Time Incremental Updates): 新的数据片段（episodes）可以立即被整合，无需进行批量的重新计算。这对于需要快速响应变化的系统至关重要。
  • • 双时间数据模型 (Bi-Temporal Data Model): Graphiti明确跟踪事件发生时间和事件被记录到系统的时间。这使得进行精确的“时间点”查询成为可能，例如“在昨天下午3点时，系统知道用户喜欢什么品牌？”
  • • 高效混合检索 (Efficient Hybrid Retrieval): 结合了语义嵌入（理解含义）、关键词（BM25，精确匹配）和图遍历（利用关系）的检索方式。这种混合方法能够在不依赖大型语言模型（LLM）进行摘要的情况下，实现低延迟（通常亚秒级）的复杂查询。
  • • 自定义实体定义 (Custom Entity Definitions): 开发者可以轻松地通过Pydantic模型定义自己的实体类型，创建灵活的本体（ontology），以适应特定的业务需求。
  • • 可扩展性 (Scalability): 通过并行处理等优化，Graphiti能够高效管理大规模数据集，非常适合企业级应用环境。

Graphiti structured + unstructured demo

Graphiti structured + unstructured demo

上图展示了Graphiti如何处理结构化和非结构化数据，将其融入动态知识图谱中。

安装Graphiti：快速入门

在开始之前，请确保满足以下要求：

  • • Python: 3.10 或更高版本
  • • Neo4j: 5.26 或更高版本（用作嵌入存储后端）
  • • OpenAI API 密钥: 用于LLM推理和嵌入生成（这是默认配置）

重要提示： Graphiti 在使用支持结构化输出（Structured Output）的LLM服务（如OpenAI和Gemini）时效果最佳。使用其他服务可能导致输出模式错误和数据提取失败，尤其是在使用较小模型时。

可选：

  • • Google Gemini, Anthropic, 或 Groq API 密钥 (用于使用这些替代的LLM提供商)

小贴士： 安装 Neo4j 最简单的方法是通过 Neo4j Desktop[5]。它提供了一个用户友好的界面来管理 Neo4j 实例和数据库。

使用 pip 安装 Graphiti 核心库：

pip install graphiti-core

或者使用 poetry：

poetry add graphiti-core

你还可以安装对特定 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[anthropic,groq,google-genai]

快速上手：体验Graphiti的威力

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

想要立刻体验 Graphiti？项目提供了一个完整的 快速入门示例[6]（位于 examples/quickstart 目录下）。这个示例将引导你完成：

  1. 1. 连接到 Neo4j 数据库： 建立与图数据库的连接。
  2. 2. 初始化 Graphiti 索引和约束： 设置必要的数据库结构以优化查询。
  3. 3. 向图谱中添加“事件片段”(Episodes)： 演示如何添加文本和结构化 JSON 数据，构建知识图谱。
  4. 4. 使用混合搜索查找关系（边）： 体验结合语义、关键词和图的强大搜索能力。
  5. 5. 使用图距离重排搜索结果： 根据节点在图中的接近程度优化搜索结果的相关性。
  6. 6. 使用预定义配方搜索节点： 展示如何利用内置的最佳实践来查找实体。

这个示例有详细的文档说明，解释了每个功能的用法，并包含完整的设置说明和后续步骤建议，是理解 Graphiti 工作方式的最佳起点。

Graphiti 的组件与服务

MCP 服务器 (MCP Server)

项目中的 mcp_server 目录包含一个 模型上下文协议 (Model Context Protocol, MCP) 服务器实现。这个服务器允许 AI 助手通过 MCP 协议与 Graphiti 的知识图谱能力进行交互。

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

  • • 事件片段管理（添加、检索、删除）
  • • 实体管理和关系处理
  • • 语义和混合搜索能力
  • • 分组管理，用于组织相关数据
  • • 图维护操作

MCP 服务器可以使用 Docker 配合 Neo4j 进行部署，使得将 Graphiti 集成到你的 AI 助手工作流中变得非常简单。更多详细的设置说明和使用示例，请参考 MCP 服务器 README[7]。

REST 服务 (REST Service)

server 目录包含一个基于 FastAPI 构建的 API 服务，用于通过 RESTful 接口与 Graphiti API 进行交互。如果你希望通过标准的 Web API 来使用 Graphiti 的功能，这是一个很好的选择。详情请参阅 服务器 README[8]。

集成不同的 LLM 和嵌入服务

Graphiti 提供了灵活的配置选项，允许你使用不同的 LLM 和嵌入模型提供商。

使用 Azure OpenAI

如果你使用 Azure OpenAI 服务，可以通过以下方式配置 Graphiti：

from openai import AsyncAzureOpenAI
from graphiti_core import Graphiti
from graphiti_core.llm_client import OpenAIClient
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient

# Azure OpenAI 配置信息
api_key = "YOUR_AZURE_OPENAI_KEY"
api_version = "YOUR_API_VERSION" # 例如 "2023-07-01-preview"
azure_endpoint = "YOUR_AZURE_ENDPOINT"

# 为 LLM 创建 Azure OpenAI 客户端
azure_openai_llm_client = AsyncAzureOpenAI(
    api_key=api_key,
    api_version=api_version,
    azure_endpoint=azure_endpoint
)

# 为 Embedder 创建 Azure OpenAI 客户端 (可能需要不同的部署)
# 注意：如果你为 LLM 和 Embedding 使用相同的 Azure 部署，可以复用 client
azure_openai_embedder_client = AsyncAzureOpenAI(
    api_key=api_key,
    api_version=api_version,
    azure_endpoint=azure_endpoint
)

# 初始化 Graphiti，传入 Azure OpenAI 客户端
graphiti = Graphiti(
    "bolt://localhost:7687", # Neo4j 连接 URL
    "neo4j",                 # Neo4j 用户名
    "password",              # Neo4j 密码
    llm_client=OpenAIClient(
        client=azure_openai_llm_client
        # 你可能还需要指定部署的模型名称, e.g., model="your_llm_deployment_name"
    ),
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            embedding_model="your_embedding_deployment_name" # 使用你在 Azure 部署的嵌入模型名称
        ),
        client=azure_openai_embedder_client
    ),
    # 可选: 如果使用重排器，也配置 Azure OpenAI
    cross_encoder=OpenAIRerankerClient(
        client=azure_openai_llm_client # 假设重排器使用与LLM相同的部署
        # 可能需要指定模型名称, e.g., model="your_reranker_deployment_name"
    )
)

# 现在你可以使用配置了 Azure OpenAI 的 Graphiti 实例了
print("Graphiti initialized with Azure OpenAI clients.")
# graphiti.add_episode(...)
# results = graphiti.search_relationships(...)

请确保将代码中的占位符（如 YOUR_AZURE_OPENAI_KEY, YOUR_AZURE_ENDPOINT, your_embedding_deployment_name 等）替换为你自己的实际 Azure OpenAI 凭据和部署名称。

使用 Google Gemini

Graphiti 也支持 Google 的 Gemini 模型用于 LLM 推理和嵌入生成。

首先，确保安装了 Gemini 的支持包：

pip install "graphiti-core[google-genai]"
# 或者使用 uv
# uv add "graphiti-core[google-genai]"

然后，在代码中配置 Graphiti：

from graphiti_core import Graphiti
from graphiti_core.llm_client.gemini_client import GeminiClient, LLMConfig
from graphiti_core.embedder.gemini import GeminiEmbedder, GeminiEmbedderConfig

# Google API 密钥配置
api_key = "YOUR_GOOGLE_API_KEY"

# 初始化 Graphiti，传入 Gemini 客户端
graphiti = Graphiti(
    "bolt://localhost:7687", # Neo4j 连接 URL
    "neo4j",                 # Neo4j 用户名
    "password",              # Neo4j 密码
    llm_client=GeminiClient(
        config=LLMConfig(
            api_key=api_key,
            model="gemini-1.5-flash" # 或其他 Gemini 模型
        )
    ),
    embedder=GeminiEmbedder(
        config=GeminiEmbedderConfig(
            api_key=api_key,
            embedding_model="embedding-001" # Google 的嵌入模型
        )
    )
    # Gemini 目前可能没有直接对应的 cross-encoder，这里省略
)

# 现在你可以使用配置了 Google Gemini 的 Graphiti 实例了
print("Graphiti initialized with Google Gemini clients.")
# graphiti.add_episode(...)
# results = graphiti.search_relationships(...)

同样，请将 "YOUR_GOOGLE_API_KEY" 替换为你的实际 Google API 密钥。

可选环境变量

除了 Neo4j 和 LLM 服务凭据外，Graphiti 还有一个可选的环境变量 USE_PARALLEL_RUNTIME。你可以将其设置为 true 来启用 Neo4j 的并行运行时特性，这可以加速某些查询。但请注意，Neo4j 社区版或较小的 AuraDB 实例不支持此功能，因此默认是关闭的。

文档资源

想要更深入地了解 Graphiti？这里有一些有用的资源：

同类项目比较：Graphiti vs. GraphRAG

在知识图谱与RAG结合的领域，GraphRAG 是另一个值得关注的项目。那么 Graphiti 与 GraphRAG 有何不同？下表可以帮助你理解它们的定位差异：

特性GraphRAGGraphiti
主要用途静态文档摘要动态数据管理与 AI 智能体记忆
数据处理方式批处理为主持续、增量更新
知识结构实体簇 & 社区摘要事件片段、语义实体、社区（更细粒度、时序性）
检索方法序列化的 LLM 摘要混合检索（语义、关键词、图），低延迟
适应性低（主要针对静态分析）高（为动态变化环境设计）
时间处理基本时间戳跟踪显式的双时间跟踪（事件时间+记录时间）
矛盾处理依赖 LLM 的摘要判断通过时间性使旧的关系边失效
查询延迟秒级到数十秒通常亚秒级
自定义实体类型不支持支持，可灵活定制
可扩展性中等高，为大规模数据集优化

简单来说，GraphRAG 更侧重于对已有的、相对静态的文档集合进行深入分析和摘要，通过构建图谱来理解文档间的关系，并利用 LLM 进行总结。而 Graphiti 则专注于处理持续流入的、动态变化的数据，构建一个能够反映实时状态和历史演变的知识图谱，特别适合需要快速响应、精确记忆和低延迟查询的 AI 应用，如交互式智能体、实时监控系统等。Graphiti 的增量更新、双时间模型和高效混合检索是其在动态场景下的核心优势。

当前状态与未来路线图

Graphiti 正处于活跃开发阶段。开发团队在努力保持 API 稳定性的同时，也在不断推进新功能：

  • • ✅ 支持自定义图模式（已完成）：允许开发者定义自己的节点和边类，更灵活地表示知识。
  • • ✅ 增强检索能力（已完成）：提供更强大、可配置的检索选项。
  • • ✅ Graphiti MCP 服务器（已完成）：方便与 AI 助手集成。
  • • ⏳ 扩展测试覆盖：确保持续的可靠性，覆盖更多边界情况。

Graphiti 的开源为构建下一代具有强大记忆和理解能力的 AI 应用提供了坚实的基础。如果你正在寻找一个能够处理复杂动态信息、赋予 AI 智能体“记忆”的解决方案，Graphiti 绝对值得你深入探索！

引用链接

[1] ![Zep Logo](github.com/user-attach…): www.getzep.com/
[2] Zep: www.getzep.com
[3] Zep: A Temporal Knowledge Graph Architecture for Agent Memory: arxiv.org/abs/2501.13…
[4] ![Zep: A Temporal Knowledge Graph Architecture for Agent Memory](raw.githubusercontent.com/getzep/grap…): arxiv.org/abs/2501.13…
[5] Neo4j Desktop: neo4j.com/download/
[6] **快速入门示例**: raw.githubusercontent.com/getzep/grap…
[7] MCP 服务器 README: raw.githubusercontent.com/getzep/grap…
[8] 服务器 README: raw.githubusercontent.com/getzep/grap…

avatar
文章
阅读
粉丝