getzep/graphiti · 上手攻略

  • 仓库：getzep/graphiti
  • 链接：https://github.com/getzep/graphiti
  • 分类：ai
  • 作者：Jay
  • 更新：2026-07-13

这是什么

Graphiti 是由 Zep 团队开源的时序上下文图谱框架（Temporal Context Graph Engine），专为 AI Agent 设计。与传统的静态知识图谱或 RAG 方案不同，Graphiti 能持续追踪实体和关系随时间的变化——每条事实都有"有效期窗口"，信息更新时旧事实被标记失效而非删除，保留完整历史。这使得 Graphiti 特别适合构建长期记忆和动态知识更新的 AI 应用。

Graphiti 底层支持 Neo4j、FalkorDB、Amazon Neptune 等图数据库，LLM 调用默认使用 OpenAI，同时也支持 Anthropic、Gemini、Groq 等多提供商。它还提供 MCP Server 实现，方便通过 Model Context Protocol 接入 Claude、Cursor 等主流 AI 工具。

解决什么问题

  • RAG 静态切片失效：传统 RAG 用文档 chunk 检索，无法追踪信息变化，旧知识污染回答
  • Agent 记忆缺失：Agent 在长对话或多轮任务中，缺乏结构化的、可溯源的上下文记忆
  • 知识图谱无时效：普通知识图谱无法表达"某人在某时间是某公司员工，后来离职了"这类时序事实
  • 上下文窗口不足：Agent 需要更结构化、更浓缩的上下文，而非直接把聊天历史塞进 prompt

快速安装

基本安装（Python 3.10+）

pip install graphiti-core
# 或
uv add graphiti-core

⚠️ Graphiti 默认使用 OpenAI API 进行 LLM 推理和 embedding，请确保 OPENAI_API_KEY 环境变量已设置。

支持多后端图数据库

Neo4j（推荐生产使用）：

# 通过 Docker Compose 快速启动
git clone https://github.com/getzep/graphiti.git
cd graphiti
docker compose up

FalkorDB（轻量，支持嵌入式）：

pip install graphiti-core[falkordb]
# 或嵌入式版本（需要 Python 3.12+）
pip install graphiti-core[falkordblite]

# 快速启动 FalkorDB Docker
docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest

Amazon Neptune：

pip install graphiti-core[neptune]

Kuzu（已废弃）：

pip install graphiti-core[kuzu]
# 上游已不再维护，新项目不推荐使用

可选 LLM Provider

# Anthropic 支持
pip install graphiti-core[anthropic]

# Google Gemini 支持
pip install graphiti-core[google-genai]

# Groq 支持
pip install graphiti-core[groq]

# 组合安装
pip install graphiti-core[falkordb,anthropic,google-genai]

核心用法

基础概念

Graphiti 的核心数据结构是上下文图谱，包含四类组件：

组件 说明
Entity（实体节点） 人、产品、政策、概念等，随时间更新摘要
Fact/Relationship（边） 三元组（实体→关系→实体），带时序有效期窗口
Episode（溯源） 原始摄入数据，每条派生事实都可追溯到 Episode
Custom Types 通过 Pydantic 模型自定义实体和边的类型（可选）

完整示例代码（Neo4j）

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

# 设置环境变量
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"

# 创建驱动并初始化 Graphiti
driver = Neo4jDriver(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
)
graphiti = Graphiti(graph_driver=driver)

# 初始化索引和约束
await graphiti.initialize_indices()

# 添加文本 Episode
episode = await graphiti.add_episode(
    text="Kendra loves Adidas shoes (as of March 2026). "
         "She previously preferred Nike until 2024.",
    source_name="user_preferences",
)
# 或添加结构化 JSON Episode
structured_episode = await graphiti.add_episode(
    data={
        "customer": "Kendra",
        "preference": "Adidas shoes",
        "period": "2024-present"
    },
    source_name="structured_data",
)

# 搜索关系（边）— 混合语义+关键词检索
results = await graphiti.search_edges(
    query="What does Kendra like?",
    top_k=5,
)

# 基于图距离重排搜索结果
for result in results:
    reranked = await graphiti.search_edges(
        query="Kendra preferences",
        center_node_uuid=result.source_node_uuid,
        top_k=3,
    )

# 搜索实体节点（使用预定义 Recipe）
from graphiti_core.search.search_config_recipes import NODE_HYBRID_SEARCH_RRF
node_results = await graphiti.search_nodes(
    query="Kendra",
    recipe=NODE_HYBRID_SEARCH_RRF,
    top_k=5,
)

FalkorDB 示例

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

driver = FalkorDriver(
    host="localhost",
    port=6379,
    database="default_db",
)
graphiti = Graphiti(graph_driver=driver)
await graphiti.initialize_indices()

Azure OpenAI 配置

from openai import AsyncOpenAI
from graphiti_core import Graphiti
from graphiti_core.llm_client.azure_openai_client import AzureOpenAILLMClient
from graphiti_core.llm_client.config import LLMConfig
from graphiti_core.embedder.azure_openai import AzureOpenAIEmbedderClient

azure_client = AsyncOpenAI(
    base_url="https://your-resource-name.openai.azure.com/openai/v1/",
    api_key="your-api-key",
)
llm_client = AzureOpenAILLMClient(
    azure_client=azure_client,
    config=LLMConfig(model="gpt-5-mini", small_model="gpt-5-mini")
)
embedder_client = AzureOpenAIEmbedderClient(
    azure_client=azure_client,
    model="text-embedding-3-small"
)
graphiti = Graphiti(
    "bolt://localhost:7687", "neo4j", "password",
    llm_client=llm_client,
    embedder=embedder_client,
)

MCP Server 部署

Graphiti 提供 MCP Server，可通过 Docker 快速部署：

cd graphiti/mcp_server
docker compose up

通过 MCP 协议，Claude Desktop、Cursor 等工具可直接调用 Graphiti 的图谱查询能力。

限流配置

LLM Provider 的 429 限流错误通过 SEMAPHORE_LIMIT 环境变量控制并发数，默认值 10。如遇到限流可降低此值，如想提升吞吐量可调高：

export SEMAPHORE_LIMIT=20

⚠️ 其他 OpenAI 兼容 Provider（DeepSeek、Together、OpenRouter 等）以及本地服务（Ollama、vLLM 等）可通过 OpenAI 兼容端点接入，具体配置参考仓库文档。

典型适用场景

  1. AI Agent 长期记忆：为 Agent 构建可查询、可溯源的上下文记忆，在多轮对话中持续追踪用户偏好和项目状态
  2. 客服系统知识管理：实时更新产品信息、用户历史，保留完整变更记录用于审计
  3. 企业知识库：整合内部文档、邮件、数据库，构建动态知识图谱，支持"某政策何时生效/失效"类时序查询
  4. 个人助手：记录用户的日程、习惯、关系网络，支持精确的历史查询（如"去年我买过什么品牌的电脑"）
  5. RAG 增强：作为 RAG 的图谱层，提供更结构化、更时效感知的检索结果

坑与注意

  • Python 3.10+ 强制要求：不支持 3.9 及以下版本
  • 强烈建议 Structured Output 支持的模型：文档明确指出，Graphiti 在使用不支持 Structured Output 的小模型时，容易出现 schema 错误和摄入失败，推荐 OpenAI、Anthropic、Gemini
  • Neo4j 默认数据库名为 neo4j：如果连接报"Database not found"错误，检查是否连接到了错误的数据库名，Neo4j Desktop 默认创建的数据库名可能不是 neo4j
  • FalkorDB vs Neo4j：开发测试用 FalkorDB 更轻量，生产环境建议 Neo4j
  • 性能依赖 LLM 调用速度：图谱构建过程涉及大量 LLM 推理，高并发场景注意限流配置
  • 图数据库本身运维成本：引入 Graphiti 意味着需要运维一套图数据库（Neo4j/FalkorDB），增加了系统复杂度

与同类对比

方案 时序支持 溯源能力 适用场景 复杂度
Graphiti ✅ 原生时序事实窗口 ✅ Episode 完整溯源 Agent 记忆、动态知识 中（需运维图数据库）
普通 RAG ❌ 静态文档切片 ❌ 无 简单文档问答 低
GraphRAG ❌ 基础时间戳 弱 文档聚类摘要 中
Zep（商业版） ✅ ✅ 生产级 Agent 记忆 低（托管服务）
MemGPT ❌ ❌ 长上下文管理 中

Graphiti 的核心差异在于时序事实管理 + 完整溯源，比 GraphRAG 更适合需要实时数据更新的 Agent 场景，比普通 RAG 提供更结构化的上下文。

一句话结论

如果你的 AI Agent 需要"记得住变化、查得出来源"的动态记忆系统，Graphiti 是目前开源社区中时序上下文图谱最成熟的解决方案；追求开箱即用的生产体验可选 Zep 商业版。