Graphiti

为AI代理构建实时知识图谱

:star: 帮助我们吸引更多开发者并壮大Graphiti社区。给这个仓库点个星吧！

[!TIP] 查看新的 Graphiti MCP服务器！为Claude、Cursor和其他MCP客户端提供强大的基于知识图谱的记忆功能。

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

使用Graphiti可以：

• 整合和维护动态的用户交互和业务数据。
• 促进基于状态的推理和代理的任务自动化。
• 通过语义、关键词和图谱搜索方法查询复杂且不断变化的数据。

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

Graphiti与Zep记忆

Graphiti为Zep的记忆层提供核心支持。

使用Graphiti，我们已经证明Zep是代理记忆的顶尖技术。

阅读我们的论文：Zep：用于代理记忆的时间知识图谱架构。

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

为什么选择Graphiti？

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

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

Graphiti vs. GraphRAG

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

安装

要求：

• Python 3.10或更高版本
• Neo4j 5.26 / FalkorDB 1.1.2或更高版本（作为嵌入存储后端）
• OpenAI API密钥（用于LLM推理和嵌入）

[!IMPORTANT] Graphiti最适合支持结构化输出的LLM服务（如OpenAI和Gemini）。 使用其他服务可能会导致输出模式不正确和摄入失败。这在使用较小模型时尤其明显。

可选：

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

[!TIP] 安装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

您还可以安装可选的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]

快速入门

[!IMPORTANT] Graphiti使用OpenAI进行LLM推理和嵌入。确保在您的环境中设置了OPENAI_API_KEY。 也支持Anthropic和Groq的LLM推理。其他LLM提供商可以通过OpenAI兼容的API支持。

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

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

该示例详细记录了每个功能，并包括一个全面的README，其中包含设置说明和后续步骤。

MCP服务器

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

MCP服务器的关键功能包括：

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

MCP服务器可以使用Docker与Neo4j一起部署，从而轻松将Graphiti集成到您的AI助手工作流中。

有关详细的设置说明和使用示例，请参见MCP服务器README。

REST服务

server目录包含一个用于与Graphiti API交互的API服务。它是使用FastAPI构建的。

有关更多信息，请参见服务器README。

可选环境变量

除了Neo4j和OpenAi兼容的凭据外，Graphiti还有一些可选的环境变量。 如果您使用的是我们支持的模型之一，例如Anthropic或Voyage模型，则必须设置必要的环境变量。

USE_PARALLEL_RUNTIME是一个可选的布尔变量，如果您希望为我们的几个搜索查询启用Neo4j的并行运行时功能，可以将其设置为true。 请注意，此功能不支持Neo4j社区版或较小的AuraDB实例，因此默认情况下此功能关闭。

使用Graphiti与Azure OpenAI

Graphiti支持Azure OpenAI进行LLM推理和嵌入。要使用Azure OpenAI，您需要为LLM客户端和嵌入器配置Azure OpenAI凭据。

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

# Azure OpenAI配置
api_key = "<your-api-key>"
api_version = "<your-api-version>"
azure_endpoint = "<your-azure-endpoint>"

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

# 使用Azure部署的模型名称创建LLM配置
azure_llm_config = LLMConfig(
    small_model="gpt-4.1-nano",
    model="gpt-4.1-mini",
)

# 使用Azure OpenAI客户端初始化Graphiti
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=OpenAIClient(
        llm_config=azure_llm_config,
        client=azure_openai_client
    ),
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            embedding_model="text-embedding-3-small"  # 使用您在Azure OpenAI服务中部署的嵌入模型名称
        ),
        client=azure_openai_client
    ),
    # 可选：使用Azure OpenAI配置OpenAI交叉编码器
    cross_encoder=OpenAIRerankerClient(
        llm_config=azure_llm_config,
        client=azure_openai_client
    )
)

# 现在您可以使用Graphiti与Azure OpenAI

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

使用Graphiti与Google Gemini

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

安装Graphiti：

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

# 或

pip install "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密钥配置
api_key = "<your-google-api-key>"

# 使用Gemini客户端初始化Graphiti
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"
        )
    )
)

# 现在您可以使用Graphiti与Google Gemini

使用Graphiti与Ollama（本地LLM）

Graphiti支持Ollama通过Ollama的OpenAI兼容API运行本地LLM和嵌入模型。这对于注重隐私的应用或当您希望避免API成本时非常理想。

安装模型： ollama pull deepseek-r1:7b # LLM ollama pull nomic-embed-text # 嵌入

from graphiti_core import Graphiti
from graphiti_core.llm_client.config import LLMConfig
from graphiti_core.llm_client.openai_client import OpenAIClient
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient

# 配置Ollama LLM客户端
llm_config = LLMConfig(
    api_key="abc",  # Ollama不需要真实的API密钥
    model="deepseek-r1:7b",
    small_model="deepseek-r1:7b",
    base_url="http://localhost:11434/v1", # Ollama提供此端口
)

llm_client = OpenAIClient(config=llm_config)

# 使用Ollama客户端初始化Graphiti
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=llm_client,
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            api_key="abc",
            embedding_model="nomic-embed-text",
            embedding_dim=768,
            base_url="http://localhost:11434/v1",
        )
    ),
    cross_encoder=OpenAIRerankerClient(client=llm_client, config=llm_config),
)

# 现在您可以使用Graphiti与本地Ollama模型

确保Ollama正在运行（ollama serve），并且您已经拉取了您想要使用的模型。

文档

• 指南和API文档。
• 快速入门
• 使用LangChain的LangGraph和Graphiti构建代理

遥测

Graphiti收集匿名使用统计数据，以帮助我们了解该框架的使用情况，并为每个人改进它。我们相信透明度很重要，因此以下是我们在收集的内容及其原因。

我们收集的内容

当您初始化Graphiti实例时，我们会收集：

• 匿名标识符：一个随机生成的UUID，存储在~/.cache/graphiti/telemetry_anon_id中
• 系统信息：操作系统、Python版本和系统架构
• Graphiti版本：您使用的版本
• 配置选择：
  • LLM提供商类型（OpenAI、Azure、Anthropic等）
  • 数据库后端（Neo4j、FalkorDB）
  • 嵌入器提供商（OpenAI、Azure、Voyage等）

我们不收集的内容

我们致力于保护您的隐私。我们从不收集：

• 个人信息或标识符
• API密钥或凭据
• 您的实际数据、查询或图内容
• IP地址或主机名
• 文件路径或系统特定信息
• 您的片段、节点或边中的任何内容

我们收集这些数据的原因

这些信息帮助我们：

• 了解哪些配置最受欢迎，以优先支持