Graphiti

Graphiti

为 AI Agent 构建实时知识图谱

:star: 帮助我们触达更多开发者并壮大 Graphiti 社区。为此仓库点个 Star 吧！

提示

快来看看全新的 Graphiti MCP 服务！为 Claude、Cursor 和其他 MCP 客户端提供强大的、基于知识图谱的记忆能力。

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

使用 Graphiti 来：

• 集成并维护动态的用户交互和业务数据。
• 支持 Agent 进行基于状态的推理和任务自动化。
• 使用语义、关键词和基于图谱的搜索方法，查询复杂且不断演变的数据。

知识图谱是由相互关联的事实构成的网络，例如 “Kendra 喜欢 Adidas 鞋。” 每个事实都是一个“三元组”，由两个实体或节点（“Kendra”和“Adidas 鞋”）及其关系或边（“喜欢”）表示。知识图谱已被广泛用于信息检索。Graphiti 的独特之处在于，它能够自主构建知识图谱，同时处理不断变化的关系并保留历史上下文。

Graphiti 与 Zep Memory

Graphiti 为 AI Agent 提供支持，是 Zep 记忆层的核心。

借助 Graphiti，我们证明了 Zep 在 Agent 记忆领域处于最先进水平。

阅读我们的论文：Zep：面向 Agent 记忆的时间知识图谱架构。

我们很高兴将 Graphiti 开源，相信它的潜力远不止于 AI 记忆应用。

## 为什么选择 Graphiti？

传统 RAG 方法通常依赖批量处理和静态数据摘要，因此在处理频繁变化的数据时效率低下。Graphiti 通过以下方式应对这些挑战：

• 实时增量更新： 无需批量重新计算，即可立即整合新的数据片段。
• 双时态数据模型： 明确跟踪事件发生时间和摄取时间，从而支持准确的时间点查询。
• 高效混合检索： 结合语义嵌入、关键词（BM25）和图遍历，实现低延迟查询，无需依赖 LLM 摘要。
• 自定义实体定义： 通过简洁的 Pydantic 模型，灵活创建本体并支持开发者定义的实体。
• 可扩展性： 通过并行处理高效管理大型数据集，适用于企业环境。

Graphiti 与 GraphRAG 的比较

方面	GraphRAG	Graphiti
主要用途	静态文档摘要	动态数据管理
数据处理	面向批处理	持续增量更新
知识结构	实体簇和社区摘要	情节数据、语义实体、社区
检索方法	按顺序进行 LLM 摘要	混合语义、关键词和基于图的搜索
适应性	低	高
时间处理	基本时间戳跟踪	明确的双时态跟踪
矛盾处理	由 LLM 驱动的摘要判断	时间边失效处理
查询延迟	数秒到数十秒	通常低于一秒
自定义实体类型	否	是，可自定义
可扩展性	中等	高，针对大型数据集进行了优化

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 提供商作为额外依赖安装：

# Install with Anthropic support
pip install graphiti-core[anthropic]

# Install with Groq support
pip install graphiti-core[groq]

# Install with Google Gemini support
pip install graphiti-core[google-genai]

# Install with multiple providers
pip install graphiti-core[anthropic,groq,google-genai]

快速开始

重要

Graphiti 使用 OpenAI 进行大模型推理和嵌入。请确保已在环境中设置 OPENAI_API_KEY。 也支持 Anthropic 和 Groq 大模型推理。其他大模型提供商可能可通过兼容 OpenAI 的 API 获得支持。

如需完整的可运行示例，请参阅 examples 目录中的快速入门示例。快速入门演示了如何：

1. 连接 Neo4j 数据库
2. 初始化 Graphiti 索引和约束
3. 向图中添加事件（文本和结构化 JSON）
4. 使用混合搜索查找关系（边）
5. 使用图距离对搜索结果重新排序
6. 使用预定义的搜索方案查找节点

该示例附有完整文档，对各项功能进行了清晰说明，并提供了全面的 README，其中包含设置说明和后续步骤。

MCP 服务

mcp_server 目录包含 Graphiti 的模型上下文协议（MCP）服务实现。此服务允许 AI 助手通过 MCP 协议与 Graphiti 的知识图谱功能交互。

MCP 服务的主要功能包括：

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

MCP 服务可与 Neo4j 一起使用 Docker 部署，便于将 Graphiti 集成到 AI 助手工作流中。

有关详细的设置说明和使用示例，请参阅 MCP 服务 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 进行大模型推理和嵌入。要使用 Azure OpenAI，需要使用 Azure OpenAI 凭据配置大模型客户端和嵌入器。

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 configuration
api_key = "<your-api-key>"
api_version = "<your-api-version>"
azure_endpoint = "<your-azure-endpoint>"

# Create Azure OpenAI client for LLM
azure_openai_client = AsyncAzureOpenAI(
    api_key=api_key,
    api_version=api_version,
    azure_endpoint=azure_endpoint
)

# Initialize Graphiti with Azure OpenAI clients
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=OpenAIClient(
        client=azure_openai_client
    ),
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            embedding_model="text-embedding-3-small"  # Use your Azure deployed embedding model name
        ),
        client=azure_openai_client
    ),
    # Optional: Configure the OpenAI cross encoder with Azure OpenAI
    cross_encoder=OpenAIRerankerClient(
        client=azure_openai_client
    )
)

# Now you can use Graphiti with Azure OpenAI

请务必将占位值替换为实际的 Azure OpenAI 凭据，并指定已部署在 Azure OpenAI 服务中的正确嵌入模型名称。

在 Google Gemini 中使用 Graphiti

Graphiti 支持使用 Google 的 Gemini 模型进行大模型推理和嵌入。要使用 Gemini，需要使用 Google API 密钥配置大模型客户端和嵌入器。

安装 Graphiti：

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

# or

uv add "graphiti-core[google-genai]"

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 key configuration
api_key = "<your-google-api-key>"

# Initialize Graphiti with Gemini clients
graphiti = 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 文档。
• 快速开始
• 使用 LangChain 的 LangGraph 和 Graphiti 构建 Agent

状态和路线图

Graphiti 正在积极开发中。我们致力于维护 API 稳定性，同时开展以下工作：

• 支持自定义图模式：
  • 允许开发者在导入事件时提供自定义的节点类和边类
  • 支持更灵活的知识表示，以适应特定使用场景
• 增强检索功能，提供更稳健且可配置的选项
• Graphiti MCP 服务
• 扩大测试覆盖率，以确保可靠性并发现边界情况

贡献

我们鼓励并感谢各种形式的贡献，无论是代码、文档、处理 GitHub Issues，还是在 Graphiti Discord 频道中解答问题。有关代码贡献的详细指南，请参阅 CONTRIBUTING。

支持

加入 Zep Discord 服务端，并前往 #Graphiti 频道！