graphiti (Big0290)

Graphiti

Build Real-Time Knowledge Graphs for AI Agents

  

  

：星： _帮助我们接触到更多的开发人员，并发展Graphiti社区。星这个回购！_

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

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

使用Graphiti可以：

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

知识图谱是一个由相互关联的事实组成的网络，例如 _“肯德拉喜欢阿迪达斯的鞋子。”_ 每个事实都是一个“三元组” 由两个实体代表，或 节点（“肯德拉”、“阿迪达斯鞋”）及其关系，或边缘（“爱”）。知识图谱已被探索 广泛用于信息检索。Graphiti的独特之处在于它能够自主构建知识图 同时处理不断变化的关系并维护历史背景。

Graphiti和Zep的上下文工程平台。

Graphiti为核心提供动力 美国洁普，一个用于AI代理的交钥匙上下文工程平台。美国洁普 提供代理内存、用于动态数据的图形RAG以及上下文检索和组装。

使用Graphiti，我们已经证明了Zep是 这 Agent记忆的最新进展.

阅读我们的论文： 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/亚马逊海王星数据库集群或海王星分析图+亚马逊

OpenSearch无服务器集合（作为全文搜索后端）

• OpenAI API密钥（Graphiti默认为用于LLM推理和嵌入的OpenAI）

\[！重要\] Graphiti最适合支持结构化输出的LLM服务（如OpenAI和Gemini）。 使用其他服务可能会导致不正确的输出模式和摄入失败。这尤其 使用较小型号时会出现问题。

可选：

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

\[！提示\] 安装Neo4j最简单的方法是通过 Neo4j桌面。它提供了一个用户友好的 用于管理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支持进行安装

如果你打算使用FalkorDB作为你的图形数据库后端，请额外安装FalkorDB:

pip install graphiti-core[falkordb]

# or with uv
uv add graphiti-core[falkordb]

使用Kuzu支持进行安装

如果您计划使用Kuzu作为图形数据库后端，请使用Kuzu-extra进行安装：

pip install graphiti-core[kuzu]

# or with uv
uv add graphiti-core[kuzu]

使用Amazon Neptune支持进行安装

如果您计划使用Amazon Neptune作为图形数据库后端，请额外安装Amazon Neptune:

pip install graphiti-core[neptune]

# or with uv
uv add graphiti-core[neptune]

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

# Install with FalkorDB and LLM providers
pip install graphiti-core[falkordb,anthropic,google-genai]

# Install with Amazon Neptune
pip install graphiti-core[neptune]

默认为低并发；LLM提供程序429速率限制错误

Graphiti的摄取管道是为高并发性而设计的。默认情况下，并发性设置为低以避免LLM 提供程序429速率限制错误。如果您发现Graphiti运行缓慢，请按照以下说明增加并发性。

并发控制由 SEMAPHORE_LIMIT 环境变量。默认情况下， SEMAPHORE_LIMIT 设置为 10 并发操作有助于防止 429 LLM提供商的速率限制错误。如果您遇到此类错误，请尝试 降低该值。

如果您的LLM提供商允许更高的吞吐量，您可以增加 SEMAPHORE_LIMIT 促进发作摄入 演出

快速开始

\[！重要\] Graphiti默认使用OpenAI进行LLM推理和嵌入。确保 OPENAI_API_KEY 设置在您的 环境。 对Anthropic和Groq LLM推理的支持也是可用的。其他LLM提供商可能通过OpenAI获得支持 兼容的API。

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

1. 连接到Neo4j、Amazon Neptune、FalkorDB或Kuzu数据库
2. 初始化Graphiti索引和约束
3. 在图表中添加剧集（文本和结构化JSON）
4. 使用混合搜索搜索关系（边）
5. 使用图距离重新排列搜索结果
6. 使用预定义的搜索配方搜索节点

该示例有完整的文档记录，对每个功能都有清晰的解释，并包括一个全面的README，其中包含 设置说明和后续步骤。

MCP服务器

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

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

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

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

有关详细的设置说明和使用示例，请参阅 MCP服务器自述文件.

REST服务

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

请查看 服务器README 了解更多信息。

可选环境变量

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

数据库配置

数据库名称直接在驱动程序构造函数中配置：

• Neo4j：数据库名称默认为 neo4j （在Neo4jDriver中硬编码）
• FalkorDB：数据库名称默认为 default_db （在FalkorDriver中硬编码）

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

具有自定义数据库名称的Neo4j

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

# Create a Neo4j driver with custom database name
driver = Neo4jDriver(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    database="my_custom_database"  # Custom database name
)

# Pass the driver to Graphiti
graphiti = Graphiti(graph_driver=driver)

具有自定义数据库名称的FalkorDB

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

# Create a FalkorDB driver with custom database name
driver = FalkorDriver(
    host="localhost",
    port=6379,
    username="falkor_user",  # Optional
    password="falkor_password",  # Optional
    database="my_custom_graph"  # Custom database name
)

# Pass the driver to Graphiti
graphiti = Graphiti(graph_driver=driver)

月份

from graphiti_core import Graphiti
from graphiti_core.driver.kuzu_driver import KuzuDriver

# Create a Kuzu driver
driver = KuzuDriver(db="/tmp/graphiti.kuzu")

# Pass the driver to Graphiti
graphiti = Graphiti(graph_driver=driver)

亚马逊海王星

from graphiti_core import Graphiti
from graphiti_core.driver.neptune_driver import NeptuneDriver

# Create a FalkorDB driver with custom database name
driver = NeptuneDriver(
    host= ,
aoss_host = ,
port =   # Optional, defaults to 8182,
         aoss_port =   # Optional, defaults to 443
)

driver = NeptuneDriver(host=neptune_uri, aoss_host=aoss_host, port=neptune_port)

# Pass the driver to Graphiti
graphiti = Graphiti(graph_driver=driver)

在Azure OpenAI中使用Graphiti

Graphiti支持Azure OpenAI用于LLM推理和嵌入。Azure部署通常需要不同的 LLM和嵌入服务的端点，以及默认模型和小型模型的单独部署。

\[！重要\] 结构化输出需要Azure OpenAI v1 API选择 Graphiti通过以下方式使用结构化输出 client.beta.chat.completions.parse() 方法，需要Azure OpenAI 部署以选择加入v1 API。如果没有此选择加入，您将在剧集中遇到404 Resource not found错误 摄入。 要在Azure OpenAI部署中启用v1 API支持，请遵循Microsoft的 指南： Azure OpenAI API版本生命周期.

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 configuration - use separate endpoints for different services
api_key = ""
api_version = ""
llm_endpoint = ""  # e.g., "https://your-llm-resource.openai.azure.com/"
embedding_endpoint = ""  # e.g., "https://your-embedding-resource.openai.azure.com/"

# Create separate Azure OpenAI clients for different services
llm_client_azure = AsyncAzureOpenAI(
    api_key=api_key,
    api_version=api_version,
    azure_endpoint=llm_endpoint
)

embedding_client_azure = AsyncAzureOpenAI(
    api_key=api_key,
    api_version=api_version,
    azure_endpoint=embedding_endpoint
)

# Create LLM Config with your Azure deployment names
azure_llm_config = LLMConfig(
    small_model="gpt-4.1-nano",
    model="gpt-4.1-mini",
)

# Initialize Graphiti with Azure OpenAI clients
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=OpenAIClient(
        config=azure_llm_config,
        client=llm_client_azure
    ),
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            embedding_model="text-embedding-3-small-deployment"  # Your Azure embedding deployment name
        ),
        client=embedding_client_azure
    ),
    cross_encoder=OpenAIRerankerClient(
        config=LLMConfig(
            model=azure_llm_config.small_model  # Use small model for reranking
        ),
        client=llm_client_azure
    )
)

# Now you can use Graphiti with Azure OpenAI

确保用匹配的实际Azure OpenAI凭据和部署名称替换占位符值 您的Azure OpenAI服务配置。

在Google Gemini中使用Graphiti

Graphiti支持谷歌的Gemini模型，用于LLM推理、嵌入和交叉编码/重新排序。为了使用Gemini， 您需要使用Google API密钥配置LLM客户端、嵌入器和交叉编码器。

安装Graphiti：

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

# or

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
from graphiti_core.cross_encoder.gemini_reranker_client import GeminiRerankerClient

# Google API key configuration
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"
        )
    ),
    cross_encoder=GeminiRerankerClient(
        config=LLMConfig(
            api_key=api_key,
            model="gemini-2.5-flash-lite-preview-06-17"
        )
    )
)

# Now you can use Graphiti with Google Gemini for all components

双子座重新登录者使用 gemini-2.5-flash-lite-preview-06-17 默认情况下，该模型已针对 具有成本效益和低延迟的分类任务。它使用与OpenAI相同的布尔分类方法 重新排名，利用双子座的对数概率特征对文章相关性进行排名。

使用Graphiti与Ollama（本地LLM）

Graphiti支持Ollama通过Ollama的OpenAI兼容API运行本地LLM和嵌入模型。这太理想了 用于关注隐私的应用程序，或者当您希望避免API成本时。

安装模型：

ollama pull deepseek-r1:7b # LLM
ollama pull nomic-embed-text # embeddings

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

# Configure Ollama LLM client
llm_config = LLMConfig(
    api_key="ollama",  # Ollama doesn't require a real API key, but some placeholder is needed
    model="deepseek-r1:7b",
    small_model="deepseek-r1:7b",
    base_url="http://localhost:11434/v1",  # Ollama's OpenAI-compatible endpoint
)

llm_client = OpenAIGenericClient(config=llm_config)

# Initialize Graphiti with Ollama clients
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=llm_client,
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            api_key="ollama",  # Placeholder API key
            embedding_model="nomic-embed-text",
            embedding_dim=768,
            base_url="http://localhost:11434/v1",
        )
    ),
    cross_encoder=OpenAIRerankerClient(client=llm_client, config=llm_config),
)

# Now you can use Graphiti with local Ollama models

确保Ollama正在运行(ollama serve)并且你已经提取了你想要使用的模型。

文档

• 指南和API文档.
• 快速开始
• 用LangChain的LangGraph和Graphiti构建代理

遥测

Graphiti收集匿名使用统计数据，以帮助我们了解框架的使用情况，并对其进行改进 每个人。我们认为透明度很重要，所以这就是我们收集的内容及其原因。

我们收集什么

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

• 匿名标识符：随机生成的UUID存储在本地 ~/.cache/graphiti/telemetry_anon_id
• 系统信息：操作系统、Python版本和系统架构
• 图形版本：您正在使用的版本
• 配置选项:

- LLM提供者类型（OpenAI、Azure、Anthropic等） - 数据库后端（Neo4j、FalkorDB、Kuzu、亚马逊海王星数据库或海王星分析） - 嵌入器提供商（OpenAI、Azure、Voyage等）

我们不收集的东西

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

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

我们为什么收集这些数据

这些信息有助于我们：

• 了解哪些配置最受欢迎，以确定支持和测试的优先级
• 确定哪些法学硕士和数据库提供商需要重点开发
• 跟踪采用模式以指导我们的路线图
• 确保跨不同Python版本和操作系统的兼容性

通过分享这些匿名信息，您可以帮助我们使Graphiti更好地服务于社区中的每个人。

查看遥测代码

遥测代码 可以在这里找到.

如何禁用遥测

遥测是 退出 并且可以随时禁用。要禁用遥测采集，请执行以下操作：

选项1：环境变量

export GRAPHITI_TELEMETRY_ENABLED=false

选项2：在shell配置文件中设置

# For bash users (~/.bashrc or ~/.bash_profile)
echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.bashrc

# For zsh users (~/.zshrc)
echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.zshrc

选项3：为特定的Python会话设置

import os

os.environ['GRAPHITI_TELEMETRY_ENABLED'] = 'false'

# Then initialize Graphiti as usual
from graphiti_core import Graphiti

graphiti = Graphiti(...)

遥测在测试运行期间自动禁用（当 pytest 被检测到）。

技术细节

• Telemetry使用PostHog进行匿名分析收集
• 所有遥测操作都设计为无声失败，它们永远不会中断您的应用程序或影响Graphiti

功能

• 匿名ID存储在本地，与任何个人信息无关

现状和路线图

Graphiti正在积极开发中。我们的目标是保持API的稳定性，同时致力于：

• \[x\] 支持自定义图形模式：

- 允许开发人员在摄取剧集时提供自己定义的节点和边缘类 - 实现针对特定用例量身定制的更灵活的知识表示

• \[x\] 通过更强大和可配置的选项增强检索能力
• \[x\] Graphiti MCP服务器
• \[\]扩大测试覆盖范围以确保可靠性并抓住边缘情况

贡献

我们鼓励并感谢所有形式的贡献，无论是代码、文档、解决GitHub问题，还是 在Graphiti Discord频道回答问题。有关代码贡献的详细指南，请参阅 向 贡献.

支持

加入 Zep Discord服务器 然后前往 #图形 频道！