Zep Graphiti 知识图谱与语义检索技术栈深度解析

本文深入拆解 Zep 的知识图谱持久化方案，其底层引擎是开源项目 Graphiti。我们将从存储、检索、抽取、时序管理四个维度，完整还原其技术架构。

背景

在使用 Zep Cloud SDK 构建智能体应用时，ZepToolsService 负责对接知识图谱的存取能力。其核心流程为：

自动抽取 — 从对话/文档中提取实体和关系
图谱存储 — 以节点+边的形式持久化，不丢失
语义检索 — Agent 需要上下文时，从图谱中检索相关知识返回

这一能力的底层实现来自 Graphiti —— 一个开源的时序知识图谱框架。

什么是 Graphiti

Graphiti 是 Zep 团队开源的时序上下文图引擎（GitHub: getzep/graphiti），专门为 AI Agent 构建可演化的知识图谱。与传统静态知识图谱不同，Graphiti 的上下文图追踪事实随时间的变化，维护数据溯源，同时支持预定义本体和学习本体。

核心论文：Zep: A Temporal Knowledge Graph Architecture for Agent Memory

技术栈全景

┌─────────────────────────────────────────────────┐
│                  应用层 (Zep Cloud)               │
│         SDK (Python / TypeScript / Go)           │
├─────────────────────────────────────────────────┤
│                  Graphiti 引擎                    │
│  ┌──────────┐  ┌───────────┐  ┌───────────────┐ │
│  │ 实体抽取  │  │ 时序管理   │  │  本体定义      │ │
│  │ (LLM)    │  │(valid_at) │  │ (Pydantic)    │ │
│  └──────────┘  └───────────┘  └───────────────┘ │
├─────────────────────────────────────────────────┤
│               混合检索层                          │
│  ┌──────────┐  ┌───────────┐  ┌───────────────┐ │
│  │ 语义向量  │  │ BM25 关键词│  │  图遍历        │ │
│  │ Embedding│  │ Full-text │  │ Traversal     │ │
│  └──────────┘  └───────────┘  └───────────────┘ │
│          ┌──────────────────────┐                │
│          │  Graph Distance      │                │
│          │  Reranking (重排序)   │                │
│          └──────────────────────┘                │
├─────────────────────────────────────────────────┤
│                存储层                             │
│  ┌──────────────────────────────────────────┐   │
│  │ 图数据库 (Neo4j / FalkorDB / Kuzu /      │   │
│  │           Amazon Neptune)                │   │
│  │ + 全文索引 (内置 / OpenSearch)            │   │
│  └──────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘

存储层：图数据库

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

后端	版本要求	特点
Neo4j	5.26+	默认推荐，生态成熟
FalkorDB	1.1.2+	基于 Redis，Docker 一键启动
Kuzu	0.11.2+	嵌入式图数据库
Amazon Neptune	Database Cluster / Analytics	云托管，需配合 OpenSearch

上下文图的数据模型包含四类核心对象：

组件	存储内容
Entity（实体/节点）	人物、产品、策略、概念 — 带随时间演化的摘要
Fact / Relationship（事实/边）	三元组（实体→关系→实体），带时间有效性窗口
Episode（溯源）	原始输入数据流，每个衍生事实都可追溯到此处
Custom Types（本体）	开发者通过 Pydantic 模型定义的自定义实体和边类型

检索层：三路混合检索

这是 Graphiti 最核心的设计。检索不依赖单一方法，而是三种路径并行、结果融合：

1. 语义向量检索（Semantic Embedding）

嵌入模型：默认使用 OpenAI Embedding
原理：将实体、关系描述转为向量，查询时计算向量相似度
优势：能捕获语义层面的相关性，即使关键词不完全匹配

2. BM25 关键词检索（Full-text Search）

后端：Neo4j 内置全文索引 / Amazon OpenSearch Serverless
原理：经典的 TF-IDF 变体，基于词频和文档频率打分
优势：对精确关键词匹配（人名、产品名、术语）效果最好

3. 图遍历检索（Graph Traversal）

后端：图数据库原生的图遍历能力（Cypher / OpenCypher）
原理：从匹配的种子节点出发，沿边扩展到关联实体和关系
优势：发现间接关联，捕获关系链路中的隐含知识

融合与重排序

三路检索的结果合并后，通过 Graph Distance Reranking（图距离重排序）进行二次排序：

计算候选结果在图中的拓扑距离
距离更近（更紧密关联）的结果排名更高
最终输出按相关性排序的实体和关系列表

抽取层：LLM 驱动的结构化

Graphiti 使用 LLM 从非结构化文本中自动提取实体和关系：

支持的 LLM

提供商	说明
OpenAI	默认，支持 Structured Output
Google Gemini	支持 Structured Output
Anthropic	可用
Groq	可用
其他	通过 OpenAI 兼容 API 接入

⚠️ 重要：Graphiti 强依赖 LLM 的 Structured Output 能力。使用不支持该功能的小模型可能导致输出 Schema 错误和抽取失败。

本体定义方式

Graphiti 支持两种本体策略：

预定义本体（Prescribed）：通过 Pydantic 模型提前定义实体和边的类型结构
学习本体（Learned）：让结构从数据中自然涌现

两者可以混合使用——先简单定义，随着数据积累再演化。

时序管理：事实的时间窗口

Graphiti 最独特的设计是时序感知。每个 Fact 都有两个时间戳：

python

class Fact:
    valid_at: datetime    # 事实生效时间
    invalid_at: datetime | None  # 事实失效时间（None 表示仍然有效）

核心机制

新数据到达：立即增量合并，不需要全量重算
事实变更：旧事实标记 invalid_at，但不删除，保留完整历史
矛盾处理：自动检测矛盾事实，用时间窗口标记版本更迭
历史查询：支持查询"某个时间点上什么为真"

溯源（Provenance）

每个 Entity 和 Fact 都可追溯到产生它的 Episode（原始数据）。这意味着：

完整的从衍生事实到原始输入的溯源链
可验证知识的来源和可靠性
支持数据纠正时的影响范围分析

Zep Cloud vs Graphiti 开源版

维度	Zep Cloud	Graphiti 开源版
定位	托管式上下文图基础设施	开源时序上下文图引擎
图管理	大规模每用户/实体图 + 治理	单图构建和查询
用户管理	内置用户、线程、消息存储	需自行实现
检索性能	预配置，生产就绪，<200ms 延迟	自行实现，性能取决于部署
开发者工具	Dashboard 可视化、调试日志、API 日志	需自行构建
部署	全托管或私有云部署	仅自托管

实际使用场景

1. Agent 长期记忆

用户对话 → Graphiti 抽取实体/关系 → 存入图谱
Agent 回复时 → 混合检索 → 获取相关上下文 → 生成更准确的回复

2. 社交仿真知识管理

结合 CAMEL-AI + camel-oasis 做社交仿真时：

仿真对话流 → Graphiti 构建人物关系图 → 查询人物偏好/关系演化

3. 企业知识库

文档/邮件/工单 → Graphiti 增量构建知识图谱 → 语义+关键词+图遍历检索

技术选型建议

快速验证：FalkorDB（Docker 一行命令启动）+ OpenAI
生产部署：Neo4j 5.26+ + OpenAI，或 Zep Cloud 托管
云原生：Amazon Neptune + OpenSearch Serverless
嵌入场景：Kuzu（嵌入式，无独立服务）

总结

Zep 的知识图谱持久化方案，本质上是 Graphiti 引擎驱动的时序知识图谱系统：

存储：Neo4j 等图数据库，节点存实体、边存事实
检索：Embedding 向量 + BM25 关键词 + 图遍历，三路混合 + 图距离重排序
抽取：LLM（要求 Structured Output）自动提取实体和关系
时序：每个事实带时间窗口，增量构建，旧事实不删除仅标记失效
溯源：所有知识可追溯到原始 Episode

这一设计使得 AI Agent 不再依赖简单的向量检索，而是拥有了一个真正可演化、可追溯、可精准查询的知识图谱作为长期记忆。

Zep Graphiti 知识图谱与语义检索技术栈深度解析 ​

背景 ​

什么是 Graphiti ​

技术栈全景 ​

存储层：图数据库 ​

检索层：三路混合检索 ​

1. 语义向量检索（Semantic Embedding） ​

2. BM25 关键词检索（Full-text Search） ​

3. 图遍历检索（Graph Traversal） ​

融合与重排序 ​

抽取层：LLM 驱动的结构化 ​

支持的 LLM ​

本体定义方式 ​

时序管理：事实的时间窗口 ​

核心机制 ​

溯源（Provenance） ​

Zep Cloud vs Graphiti 开源版 ​

实际使用场景 ​

1. Agent 长期记忆 ​

2. 社交仿真知识管理 ​

3. 企业知识库 ​

技术选型建议 ​

总结 ​

参考资源 ​