Graphiti构建AI智能体实时知识图谱

Graphiti 是一款专为 AI 智能体构建动态知识图谱的创新框架。本文将系统介绍 Graphiti 的核心功能、与传统 RAG 方法相比的显著优势，并教您如何在真实项目中快速部署与应用这款强大工具。

什么是 Graphiti

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

使用 Graphiti 可以：

• 整合并维护不断变化的用户交互数据及业务信息。
• 支持智能体进行状态推理与任务自动化。
• 通过语义搜索、关键词检索、图遍历等方式，查询复杂且持续演化的数据。

知识图谱是由互相关联的事实构成的网络，例如：“Kendra 喜爱 Adidas 鞋子。”每条事实是一个“三元组”，由两个实体（或称节点，如“Kendra”和“Adidas 鞋子”）以及它们之间的关系（或称边，如“喜爱”）表示。知识图谱在信息检索领域已有广泛的研究与应用。

Graphiti 的独特之处在于，它能够自主构建知识图谱，同时处理关系变化并保留完整历史上下文。

Graphiti 的核心功能与特点

• 实时增量更新 – 新数据片段可即时融入图谱，无需批量重计算。
• 双时间数据模型 – 明确记录事件的发生时间和接收时间，支持精准的时点查询与历史追溯。
• 高效的混合检索 – 融合语义嵌入、关键词检索（BM25）和图遍历，实现低延迟查询，且无需依赖大型语言模型（LLM）摘要。
• 自定义实体定义 – 通过简洁的 Pydantic 模型，开发者可灵活创建本体论和专属实体类型。
• 优异的可扩展性 – 支持并行处理，能够高效管理大规模数据集，满足企业级应用需求。

为什么选择 Graphiti

传统 RAG 方法通常依赖批量处理和静态数据摘要，在处理频繁变化的数据时效率低下。Graphiti 针对这一挑战提供了以下核心优势：

• 实时增量更新 – 无需批量重计算，新数据即可即时整合。
• 双时间数据模型 – 明确记录事件的发生时间和接收时间，支持精确的历史查询。
• 高效的混合检索 – 结合语义嵌入、关键词搜索和图遍历，低延迟且无需 LLM 摘要。
• 自定义实体定义 – 通过 Pydantic 模型灵活定义本体结构。
• 优异的可扩展性 – 支持并行处理，适合大规模企业级应用。

Graphiti 与 GraphRAG 对比

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 提供商支持来扩展功能：

# 安装并支持 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 使用 OpenAI 进行 LLM 推理和嵌入生成。请确保你的环境中已设置 OPENAI_API_KEY。同时也支持 Anthropic 和 Groq 的 LLM 推理。其他 LLM 提供商可通过兼容 OpenAI API 的方式接入。

完整的示例请参考 examples 目录中的 Quickstart Example。该快速入门示例演示了以下内容：

• 连接到 Neo4j 数据库
• 初始化 Graphiti 的索引与约束
• 将情节（包括文本和结构化 JSON）添加到图中
• 使用混合检索方法搜索关系（边）
• 通过图距离对搜索结果进行重新排序
• 使用预定义的搜索配方搜索节点

示例中包含了每项功能的详细说明，并提供了一个完整的 README，包含环境搭建指南和后续步骤。

MCP 服务器

mcp_server 目录包含了 Graphiti 的**模型上下文协议（MCP）**服务器实现。通过 MCP 协议，AI 助手可以与 Graphiti 的知识图谱能力进行交互。

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

• 情节管理（添加、检索、删除）
• 实体管理与关系处理
• 支持语义与混合搜索
• 分组管理，用于组织相关数据
• 图谱维护操作

MCP 服务器可以通过 Docker 与 Neo4j 一起部署，这使得将 Graphiti 集成到你的 AI 助手工作流中变得非常简单。

详细的安装说明和使用示例，请参阅 MCP server 目录下的 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 平台上进行 LLM 推理和嵌入生成。如果你希望使用 Azure OpenAI，需要为 LLM 客户端和嵌入器分别配置你的 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 配置
api_key = "<你的 API 密钥>"
api_version = "<你的 API 版本>"
azure_endpoint = "<你的 Azure 终端地址>"

# 创建 Azure OpenAI 客户端（用于 LLM）
azure_openai_client = AsyncAzureOpenAI(
    api_key=api_key,
    api_version=api_version,
    azure_endpoint=azure_endpoint
)

# 使用 Azure OpenAI 客户端初始化 Graphiti
graphiti = Graphiti(
    "bolt://localhost:7687",  # Neo4j 数据库连接地址
    "neo4j",                  # Neo4j 用户名
    "password",               # Neo4j 密码
    llm_client=OpenAIClient(
        client=azure_openai_client
    ),
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            embedding_model="text-embedding-3-small"  # 使用你在 Azure 部署的嵌入模型名称
        ),
        client=azure_openai_client
    ),
    # （可选）配置 Azure OpenAI 用于交叉编码器
    cross_encoder=OpenAIRerankerClient(
        client=azure_openai_client
    )
)

# 现在，你可以使用基于 Azure OpenAI 的 Graphiti 了

请确保将示例代码中的占位符（如 <你的 API 密钥>、<你的 API 版本>、<你的 Azure 终端地址>）替换为你实际的 Azure OpenAI 认证信息，并指定正确的嵌入模型名称，该模型必须已经在你的 Azure OpenAI 服务中完成部署。

在 Graphiti 中使用 Google Gemini

Graphiti 支持使用 Google 的 Gemini 模型进行 LLM 推理与嵌入生成。要使用 Gemini，需要分别为 LLM 客户端和嵌入器配置你的 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 = ""

# 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

常见问题（FAQ）

Q1: Graphiti 必须使用 Neo4j 吗？

A: 是的，Graphiti 目前依赖 Neo4j 作为图数据库后端。建议使用 Neo4j 5.26 或更高版本，社区版即可满足开发需求。

Q2: 如果我没有 OpenAI API 密钥，还能用 Graphiti 吗？

A: 可以。Graphiti 支持 Anthropic、Groq 和 Google Gemini 作为 LLM 推理和嵌入的替代方案。你只需安装对应的扩展包并设置相应的 API 密钥即可。

Q3: Graphiti 的“双时间数据模型”是什么意思？

A: 它同时记录事件的“发生时间”（例如用户实际说出某句话的时间）和“接收时间”（系统记录该事件的时间）。这使得你可以精准查询某个时间点的知识状态，并追溯数据变化的历史过程。

Q4: 我可以自定义知识图谱中的实体类型吗？

A: 完全可以。Graphiti 通过 Pydantic 模型让你灵活定义实体类型和关系，你只需继承基础模型并添加自定义字段即可。

Q5: Graphiti 的查询延迟真的能到亚秒级吗？

A: 是的，对于大多数场景，Graphiti 的混合检索（语义 + 关键词 + 图遍历）可以在亚秒级返回结果。相比传统 GraphRAG 数秒到数十秒的延迟，这是一个显著优势。

结语

Graphiti 为 AI 智能体带来了真正的动态知识图谱能力，无论是构建智能助手、自动化任务还是企业级记忆系统，它都能大幅提升数据处理的实时性与准确性。赶快安装体验，让 Graphiti 成为你下一个 AI 项目的核心引擎吧！

你是一名 AI 行业编辑，请围绕下面这条热点输出一份资讯解读：
热点：Graphiti构建AI智能体实时知识图谱要求：
1. 先用一句话解释这条热点在讲什么
2. 再总结它为什么重要
3. 说明会影响哪些 AI 产品或内容方向
4. 最后给出 3 个适合资讯站使用的标题