graphiti

用途

Graphiti 与 Zep 知识图谱技能用于帮助开发者构建具备时序知识图谱能力的 AI 智能体。Graphiti 是一个开源框架，用于构建和查询面向动态环境中 AI 智能体的时间感知知识图谱；Zep 是构建于 Graphiti 之上的生产级上下文工程平台，用于组装个性化上下文（包括用户偏好、特征与业务数据），以支撑可靠的智能体应用。

该技能适用于以下场景：构建需要跨对话持久记忆的 AI 智能体；为智能体应用实现知识图谱；创建具备上下文感知的个性化用户体验；管理不断演变的关系与历史上下文；将企业数据与智能体系统集成；构建 Graph RAG（检索增强生成）应用；追踪用户偏好、特征与交互历史；以时间点精度查询时序数据；通过结构化上下文减少幻觉；实现具备独立记忆的多用户智能体系统；使用 Zep 上下文工程平台；与 LangGraph、CrewAI、Autogen 或其他智能体框架集成。

主要能力

Graphiti（时序知识图谱框架）

关键特性：

时序性：双时序数据模型，同时追踪事件发生时间（Valid Time）与数据摄入时间（Transaction Time）。
增量性：实时数据集成，无需批量重新处理。
混合搜索：结合语义嵌入、BM25 关键词匹配与图遍历。
低延迟：亚秒级查询性能，不依赖 LLM 摘要。
灵活性：通过 Pydantic 模型自定义实体定义。
可扩展性：企业级并行处理。

核心概念：

时序知识图谱：创建带时间戳的关系网络，维护历史上下文、追踪随时间的变化、支持时间点查询、保留关系演变。
实体与关系：实体是知识图谱中的对象或概念（用户、产品、概念、位置等），可通过 Pydantic 模型自定义，可带属性，并带时间戳用于历史追踪；关系是实体之间的连接，具有类型（如“likes”“purchased”“mentioned”）、方向性，可带权重、属性与元数据，并追踪关系变化的时间。
事实与摘要：事实是从对话与数据中自动提取的信息，来源于聊天历史或结构化/非结构化业务数据，构成知识图谱的基础，带时间戳并归属来源；摘要是交互的浓缩表示，随对话展开生成，捕捉要点与主题，支持高效上下文检索并保持时序一致性。
混合搜索：语义搜索（向量嵌入用于概念相似度）、关键词搜索（BM25 传统文本匹配）、图遍历（沿实体关系发现关联信息）。

Zep（上下文工程平台）

Zep 提供：智能体记忆管理、Graph RAG 优化、用户与会话管理、开发者仪表盘与监控、企业级功能（RBAC、BYOK、BYOLLM）、与主流智能体框架的集成。

使用方式

安装

Graphiti（开源）：

# Install from PyPI
pip install graphiti-core

# Or from source
git clone https://github.com/getzep/graphiti.git
cd graphiti
pip install -e .

Zep（平台）：

# Python SDK
pip install zep-cloud

# TypeScript SDK
npm install @getzep/zep-cloud

# Go SDK
go get github.com/getzep/zep-go

数据库要求

Graphiti 支持多种图数据库后端：

Neo4j（推荐）：

docker run -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  neo4j:5.26

FalkorDB：

docker run -d \
  --name falkordb \
  -p 6379:6379 \
  falkordb/falkordb:1.1.2

Kuzu：pip install kuzu
Amazon Neptune（企业版）：与 OpenSearch Serverless 配合使用，设置参见 AWS 文档。

LLM 配置

Graphiti 支持多种 LLM 提供商，通过环境变量配置：OpenAI（默认，OPENAI_API_KEY）、Anthropic Claude（ANTHROPIC_API_KEY）、Google Gemini（GOOGLE_API_KEY）、Azure OpenAI（AZURE_OPENAI_API_KEY 与 AZURE_OPENAI_ENDPOINT）。

Graphiti 快速开始

基础设置：

from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType

# Initialize Graphiti with Neo4j
graphiti = Graphiti(
    neo4j_uri="bolt://localhost:7687",
    neo4j_user="neo4j",
    neo4j_password="password"
)

# Initialize the graph
await graphiti.build_indices_and_constraints()

添加 Episode（消息/事件）：可通过 graphiti.add_episode 添加对话消息（EpisodeType.message）、业务数据（EpisodeType.json）、文档/文件内容（EpisodeType.text），参数包括 name、episode_body、source_description、reference_time、episode_type。

查询图谱：使用 graphiti.search(query=..., num_results=...) 搜索相关上下文；支持时间点查询，通过 reference_time 参数传入历史时间获取当时的数据。

自定义实体类型：通过 Pydantic 的 BaseModel 定义实体（如 Product、Customer），使用 graphiti.register_entity_type(...) 注册，并在 add_episode 时通过 entity_types 参数使用。

使用 Zep 平台

Python SDK：通过 AsyncZep(api_key=...) 初始化，使用 zep.user.add 创建用户、zep.memory.add_session 创建会话、zep.memory.add_memory 添加消息构建记忆、zep.memory.get_memory 获取记忆（含 facts 与 summary）、zep.memory.search_memory 在用户图谱中搜索。

TypeScript SDK：通过 new ZepClient({ apiKey }) 初始化，使用 zep.user.add、zep.memory.addMemory、zep.memory.getMemory、zep.memory.searchMemory 等对应方法。

高级功能

批量数据摄入：构造多个 episode 字典并逐个调用 add_episode 并行处理。
自定义本体（Ontology）：定义领域特定的实体与关系（如 Customer、Product、Order、Support Ticket 及 purchased、contains、created、related_to 等关系），在 add_episode 时通过 ontology 参数使用。
图遍历查询：使用 GraphTraversal 指定起始实体、关系类型与最大深度进行遍历；使用 find_similar_entities 查找相似实体。
上下文组装：通过 zep.memory.get_memory 获取包含完整用户图谱的记忆，将 summary、facts、relevant_facts 组装进智能体系统提示词。
时序查询：通过 reference_time 查询特定时间点已知的信息，并对比不同时间的上下文演变。

与智能体框架集成

LangGraph：定义 AgentState（messages、user_id、session_id、context），构建 get_context 节点（从 Zep 获取记忆）与 call_llm 节点（带上下文调用 LLM），用 StateGraph 连接并编译运行。
CrewAI：通过 @tool 定义 get_user_context 工具从 Zep 检索用户上下文，创建带该工具的 Agent 与 Task，组成 Crew 并 kickoff 执行。

适用场景

电商个性化：追踪客户行为（浏览商品、加入购物车等），检索个性化推荐上下文供推荐智能体使用。
跨对话持久记忆的智能体。
Graph RAG 应用。
多用户智能体系统与独立记忆。
时序数据的时间点查询与知识演变追踪。
通过结构化上下文降低幻觉。

限制

资料中未提供关于收费、价格、平台可用性、性能基准或效果保证的具体说明。部分高级功能（如 Amazon Neptune 企业版设置）需参考 AWS 官方文档。