LLMs之Agents：Graphiti(为 AI 代理构建实时知识图谱)的简介、安装和使用方法、案例应用之详细攻略

知识图谱是一个由相互关联的事实组成的网络，例如"Kendra Adidas的鞋子"。每个事实都是一个"三元关系组"，由两个实体（节点，如"Kendra"和"Adidas Shoes"）及其（边，如"loves"）表示。Graphiti的独特之处在于它能够喜欢构建知识图谱，同时处理不断变化的关系图谱并维护背后的历史。

Github地址 ：https://github.com/getzep/graphiti

与 Zep 的关系：

Graphiti 是 Zep（一个为 AI 代理提供下游工程的交接平台）的核心驱动力。Zep 提供代理记忆、用于动态数据的图谱 RAG（Graph RAG）以及下游检索和构建功能。该项目团队表示，通过使用 Graphiti，Zep 在代理记忆方面达到了前沿水平（State of the Art）。他们开源 Graphiti 是因为相信其潜力远远超出了 AI 记忆应用。

1、特点

Graphiti旨在解决传统RAG方法在处理间隙变化数据时效率低下的问题，其主要特点如下：

>> 实时增量更新（Real-Time Incremental Updates） ：能够即时整合新的数据片段（episodes），消耗进行批量处理或重新计算整个图谱。
>> 双时间数据模型（Bi-Temporal Data Model） ：明确追踪事件的发生时间（事件发生时间）和数据入库时间（摄取时间），允许进行精确的"时间点"查询。
>> 高效的混合检索（Efficient Hybrid Retrieval） ：结合了语义嵌入（semantic embeddings）、关键词搜索（BM25）和图遍历（graph traversal）消解方式，实现了低延迟查询，且不依赖于LLM进行摘要生成。
>> 实体定义（自定义实体定义） ：允许开发者通过简单的Pydantic模型创建灵活的本体（ontology）并支持自定义实体，以适应需求特定。
>> 高可扩展性（Scalability） ：通过批量处理有效管理大规模数据集，非常适合企业级环境。
>> 高认知与低延迟 ：与主要用于静态文档摘要、延迟延迟秒数的GraphRAG不同，Graphiti专为动态数据管理设计，查询延迟通常在亚秒级。
>> 矛盾处理（Contraction Handling） ：通过时间性的边失效（temporal edge invalidation）来处理信息中的，而不是依赖LLM的抽象判断。

Graphiti的安装和使用方法

1、安装

(1)、系统要求

Python: 3.10 或更高版本。

图数据库：Neo4j 5.26 / FalkorDB 1.1.2 / Kuzu 0.11.2 / Amazon Neptune 数据库集群或 Neptune Analytics Graph + Amazon OpenSearch Serverless 集合。

API键：默认 OpenAI API 密钥（用于 LLM 推理和嵌入需要）。

可选：Google Gemini、Anthropic、或 Groq 的 API 密钥。

重要提示： Graphiti 在支持格式输出（Structured Output）的 LLM 服务（如 OpenAI 和 Gemini）上表现最佳。使用其他服务可能会导致输出模式不正确和数据导入失败。

(2)、安装步骤

安装基础：

复制代码

# 使用pip或uv进行安装。
pip install graphiti-core

# 或者
uv add graphiti-core

根据数据库安装：

FalkorDB 支持：

复制代码

pip install graphiti-core[falkordb]
pip install graphiti-core[kuzu]
pip install graphiti-core[neptune]
pip install graphiti-core[anthropic]
pip install graphiti-core[groq]
pip install graphiti-core[google-genai]

组合安装：

您可以将多个选项组合在一起进行安装。

复制代码

# 安装 FalkorDB 和多个 LLM 提供商
pip install graphiti-core[falkordb,anthropic,google-genai]

(3)、算术设置

Graphiti 的数据输入库管道为高梯度设计，但默认梯度数较低，LMM 的429梯度限制误差很大。您可以通过环境变量SEMAPHORE_LIMIT来调整：

默认值10。

如果遇到429错误，可以降低此值。

如果您的LLM能够允许更高的吞吐量，可以增加此值以提高性能。

2、使用方法

(1)、快速上手

项目在examples目录下提供了一个完整的快速上手示例（快速入门示例）。该示例演示了：

连接到 Neo4j、Amazon Neptune、FalkorDB、或 Kuzu 数据库。

初始化 Graphiti 的索引和约束。

向图谱中添加文本并构造 JSON 数据（episodes）。

使用搜索查找关系混合（边）。

使用图距离对搜索结果进行重新排序。

使用预定义的搜索食谱（recipes）搜索。

重要提示：默认情况下，Graphiti 使用 OpenAI。请确保在您的环境中设置了OPENAI_API_KEY。

(2)、使用Docker Compose运行

您可以使用 Docker Compose 快速启动所需的服务：

启动 Neo4j 服务：docker compose up

启动 FalkorDB 服务：docker compose --profile falkordb up

(3)、自定义数据库配置

您可以实例化一个数据库驱动程序并将其传递给Graphiti构造函数，以实现自定义配置。

Neo4j（自定义数据库名）：

查看全部

python 复制代码

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

driver = Neo4jDriver(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    database="my_custom_database"  # 自定义数据库名
)
graphiti = Graphiti(graph_driver=driver)

运行
FalkorDB（自定义数据库名）：
from graphiti_core import Graphiti
from graphiti_core.driver.falkordb_driver import FalkorDriver

driver = FalkorDriver(
    host="localhost",
    port=6379,
    database="my_custom_graph"  # 自定义图谱名
)
graphiti = Graphiti(graph_driver=driver)

(4)、集成不同的LLM成功

T1、使用 Azure OpenAI：

python 复制代码

from graphiti_core.embedder.azure_openai import AzureOpenAIEmbedderClient

# 使用 Azure 的 v1 API 端点初始化客户端
azure_client = AsyncOpenAI(
    base_url="https://your-resource-name.openai.azure.com/openai/v1/",
    api_key="your-api-key",
)

# 创建 LLM 和 Embedder 客户端
llm_client = AzureOpenAILLMClient(
    azure_client=azure_client,
    config=LLMConfig(model="gpt-5-mini") # 你的 Azure 部署名称
)
embedder_client = AzureOpenAIEmbedderClient(
    azure_client=azure_client,
    model="text-embedding-3-small" # 你的 Azure 嵌入部署名称
)

# 初始化 Graphiti
graphiti = Graphiti(
    "bolt://localhost:7687", "neo4j", "password",
    llm_client=llm_client,
    embedder=embedder_client,
)

T2、使用谷歌Gemini：

python 复制代码

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

api_key = "<your-google-api-key>"

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"))
)

T3、使用Ollama（LLM）：

python 复制代码

from graphiti_core.llm_client.openai_generic_client import OpenAIGenericClient
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig

# 为 Ollama 配置 LLM 客户端
llm_config = LLMConfig(
    api_key="ollama",  # 占位符
    model="deepseek-r1:7b",
    base_url="http://localhost:11434/v1", # Ollama 的 OpenAI 兼容端点
)
llm_client = OpenAIGenericClient(config=llm_config)

# 初始化 Graphiti
graphiti = Graphiti(
    "bolt://localhost:7687", "neo4j", "password",
    llm_client=llm_client,
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            api_key="ollama",
            embedding_model="nomic-embed-text",
            embedding_dim=768,
            base_url="http://localhost:11434/v1",
        )
    ),
)

Graphiti的案例应用

Graphiti不仅是一个基础框架，还提供了一些具体的应用实现和集成案例。

泽普平台：

Graphiti是Zep平台的核心，Zep是一个面向AI代理的下游工程平台，提供企业级的代理记忆、安全性和性能。

MCP服务器（MCP服务器）：

项目中的mcp_server目录包含一个模型上下文协议（Model Context Protocol）服务器的实现。该服务器允许AI助手通过MCP协议与Graphiti的知识图谱能力进行交互，实现对数据碎片（episode）、实体、关系的管理和搜索。

REST API 服务：

server目录包含一个基于 FastAPI 构建的 API 服务，用于通过 RESTful 接口与 Graphiti API 进行交互。

与LangChain集成：

文档中提到了一个具体的指南："Use LangChain 的 LangGraph 和 Graphiti 构建代理（Building an agent with LangChain's LangGraph and Graphiti）"。这表明 Graphiti 可以与 LangChain 生态系统无缝集成，用于构建更复杂的 AI 应用。

通用应用场景：

动态数据集成：集成和维护动态的用户交互和业务数据。

代理任务自动化：促进代理进行基于状态的推理和任务自动化。

复杂数据查询：通过语义、关键词和图搜索方法查询复杂、演进的数据。