agentic_huge_data_base / wiki
页面 Graphiti · 3.1 知识图谱数据模型·DeepWiki 中文全文译文
DeepWiki 中文译文 / Graphiti / 3.1

3.1 · 知识图谱数据模型（Knowledge Graph Data Model）

时序知识图谱与动态事实记忆 · 聚焦本章的模块关系、源码依据与实现要点。

项目Graphiti 章节3.1 状态全文译文 模块图谱与关系、界面与交互、系统架构、存储与持久化
项目要点页2.5 参考项目 项目章节目录Graphiti DeepWiki 原始章节Knowledge Graph Data Model 上一章3 下一章3.2
源码线索
  • graphiti_core/edges.py
  • graphiti_core/models/__init__.py
  • graphiti_core/models/edges/__init__.py
  • graphiti_core/models/edges/edge_db_queries.py
  • graphiti_core/models/nodes/__init__.py
  • graphiti_core/models/nodes/node_db_queries.py
  • graphiti_core/nodes.py
  • graphiti_core/utils/maintenance/community_operations.py
  • graphiti_core/utils/maintenance/graph_data_operations.py
模块标签
  • 图谱与关系
  • 界面与交互
  • 系统架构
  • 存储与持久化
  • 记忆与上下文

章节正文

知识图谱数据模型

原始 DeepWiki 页面https://deepwiki.com/getzep/graphiti/3.1-knowledge-graph-data-model

知识图谱数据模型

相关源文件

本章引用的主要源码文件：

  • graphiti_core/edges.py
  • graphiti_core/models/__init__.py
  • graphiti_core/models/edges/__init__.py
  • graphiti_core/models/edges/edge_db_queries.py
  • graphiti_core/models/nodes/__init__.py
  • graphiti_core/models/nodes/node_db_queries.py
  • graphiti_core/nodes.py
  • graphiti_core/utils/maintenance/community_operations.py
  • graphiti_core/utils/maintenance/graph_data_operations.py

本文档详细介绍了构成 Graphiti 时序知识图谱的核心数据结构和模式。它涵盖了图数据库中的节点类型、边类型、它们的属性以及它们之间的关系。

有关这些数据结构如何处理和维护的信息，请参阅数据处理管线。有关时序推理和有效期细节，请参阅时序感知与双时模型。

概述

Graphiti 的知识图谱实现了一个时序、多层的数据模型，包含四种节点类型（EpisodicNode、EntityNode、CommunityNode、SagaNode）和五种边类型（EpisodicEdge、EntityEdge、CommunityEdge、HasEpisodeEdge、NextEpisodeEdge）。所有数据结构都继承自定义在 graphiti_core/nodes.py:93-109 和 graphiti_core/edges.py:49-57 中的抽象 Pydantic BaseModel 类（Node、Edge）。该模型在保留原始片段内容的同时，提取结构化的实体和关系，并具备完整的时序追踪能力，通过 Saga 片段链支持叙事组织。

来源：graphiti_core/nodes.py:93-109、graphiti_core/edges.py:49-57

图模式架构

下图展示了包含所有节点和边类型的完整数据模型：

时序知识图谱模式

Graphiti · 图模式架构 · 图 1
Graphiti · 图模式架构 · 图 1

来源：graphiti_core/nodes.py:93-99、graphiti_core/nodes.py:307-318、graphiti_core/nodes.py:450-456、graphiti_core/nodes.py:618-621、graphiti_core/nodes.py:798-817、graphiti_core/edges.py:49-55、graphiti_core/edges.py:143-144、graphiti_core/edges.py:228-247、graphiti_core/edges.py:503-504、graphiti_core/edges.py:586-587、graphiti_core/edges.py:719-720

节点类型

EpisodicNode

EpisodicNode 类表示原始片段数据。定义在 graphiti_core/nodes.py:307-351 中，它作为实体和关系提取的源材料。

属性类型描述
uuidstr通过 uuid4() 生成，主键
namestr片段标识符
group_idstr多租户分区键
labelslist[str]从 Node 继承，默认为空列表
created_atdatetime通过 utc_now() 生成的系统创建时间
valid_atdatetime片段时间戳（事件发生时间）
sourceEpisodeType枚举：message、json、text 或 fact_triple
source_descriptionstr关于来源的元数据
contentstr原始片段内容
entity_edgeslist[str]从该片段提取的 EntityEdge 实例的 UUID 列表

关键方法：

  • async save(driver: GraphDriver) - 使用 get_episode_node_save_query() 持久化节点 graphiti_core/nodes.py:319-344
  • async get_by_uuid(driver, uuid) - 检索单个片段 graphiti_core/nodes.py:346-367
  • async get_by_group_ids(driver, group_ids, limit, uuid_cursor) - 分页支持 graphiti_core/nodes.py:390-427

EpisodeType 枚举：

定义在 graphiti_core/nodes.py:54-91 中，该枚举指定输入格式：

  • message - 参与者前缀格式："user: Hello"
  • json - 结构化 JSON 字符串
  • text - 纯文本内容
  • fact_triple - 主语-谓语-宾语结构 graphiti_core/nodes.py:77-77

来源：graphiti_core/nodes.py:307-427、graphiti_core/nodes.py:54-91

EntityNode

EntityNode 类表示带有语义嵌入向量的提取实体。定义在 graphiti_core/nodes.py:450-615 中，它存储具有动态类型的结构化知识。

属性类型描述
uuidstr通过 uuid4() 生成，主键
namestr实体名称（为语义搜索嵌入）
group_idstr分区键
labelslist[str]动态实体类型（例如 ["Person", "Engineer"]）
created_atdatetime系统创建时间
summarystr大语言模型（LLM）生成的上下文摘要
attributesdict[str, Any]标签特定属性
name_embeddinglist[float] | None向量嵌入

关键方法：

  • async generate_name_embedding(embedder: EmbedderClient) - 创建嵌入向量 graphiti_core/nodes.py:457-464
  • async save(driver: GraphDriver) - 使用 get_entity_node_save_query() 持久化 graphiti_core/nodes.py:504-535

数据库提供者处理：

  • Kuzu：将 attributes 序列化为 JSON，存储 labels 数组 graphiti_core/nodes.py:514-520、graphiti_core/models/nodes/node_db_queries.py:150-163
  • Neo4j/FalkorDB/Neptune：将 attributes 展平为属性，使用多标签语法 graphiti_core/nodes.py:522-531、graphiti_core/models/nodes/node_db_queries.py:142-149

来源：graphiti_core/nodes.py:450-615、graphiti_core/models/nodes/node_db_queries.py:137-163

CommunityNode

CommunityNode 类表示通过图算法发现的实体集群。定义在 graphiti_core/nodes.py:618-755 中，它提供层次化摘要。

属性类型描述
uuidstr通过 uuid4() 生成，主键
namestr大语言模型（LLM）生成的社区描述
group_idstr分区键
created_atdatetime系统创建时间
summarystr成员的聚合摘要
name_embeddinglist[float] | None名称的向量嵌入

关键方法：

  • async save(driver: GraphDriver) - 使用 get_community_node_save_query() graphiti_core/nodes.py:622-640
  • build_community() - 使用层次化大语言模型（LLM）调用生成社区摘要 graphiti_core/utils/maintenance/community_operations.py:174-212
  • get_community_clusters() - 使用 label_propagation 识别集群 graphiti_core/utils/maintenance/community_operations.py:30-90

来源：graphiti_core/nodes.py:618-755、graphiti_core/utils/maintenance/community_operations.py:30-212

SagaNode

SagaNode 类表示叙事序列。定义在 graphiti_core/nodes.py:798-941 中，它支持将片段组织成连贯的故事线。

属性类型描述
uuidstr通过 uuid4() 生成，主键
namestrSaga 标识符
group_idstr分区键
created_atdatetime系统创建时间

来源：graphiti_core/nodes.py:798-941、graphiti_core/models/nodes/node_db_queries.py:47

边类型

EpisodicEdge（MENTIONS 关系）

EpisodicEdge 类在 EpisodicNode 和 EntityNode 之间创建 MENTIONS 关系。定义在 graphiti_core/edges.py:143-226 中。

属性类型描述
uuidstr通过 uuid4() 生成，主键
group_idstr分区键
created_atdatetime系统创建时间
source_node_uuidstrEpisodicNode.uuid
target_node_uuidstrEntityNode.uuid

来源：graphiti_core/edges.py:143-226、graphiti_core/models/edges/edge_db_queries.py:19-27

EntityEdge（RELATES_TO 关系）

EntityEdge 类表示实体之间带有双时追踪的事实关系。定义在 graphiti_core/edges.py:228-501 中。

属性类型描述
uuidstr通过 uuid4() 生成，主键
group_idstr分区键
created_atdatetime事务时间
source_node_uuidstr源 EntityNode.uuid
target_node_uuidstr目标 EntityNode.uuid
namestr关系类型
factstr自然语言描述
fact_embeddinglist[float] | None向量嵌入
episodeslist[str]支持的片段 UUID 列表
valid_atdatetime | None事实开始时间
invalid_atdatetime | None事实结束时间
expired_atdatetime | None软删除时间戳

来源：graphiti_core/edges.py:228-501、graphiti_core/models/edges/edge_db_queries.py:63-122

CommunityEdge（HAS_MEMBER 关系）

CommunityEdge 类从社区到成员实体创建 HAS_MEMBER 关系。定义在 graphiti_core/edges.py:503-584 中。

来源：graphiti_core/edges.py:503-584、graphiti_core/models/edges/edge_db_queries.py:40

HasEpisodeEdge 和 NextEpisodeEdge
  • HasEpisodeEdge：将 SagaNode 链接到 EpisodicNode graphiti_core/edges.py:586-717。
  • NextEpisodeEdge：链接连续的 EpisodicNode 实例以形成序列 graphiti_core/edges.py:719-852。

来源：graphiti_core/edges.py:586-852

类层次结构和方法

Pydantic 模型层次结构

Graphiti · 类层次结构和方法 · 图 2
Graphiti · 类层次结构和方法 · 图 2

来源：graphiti_core/nodes.py:93-109、graphiti_core/edges.py:49-57

数据持久化流程

片段到图持久化管线

Graphiti · 数据持久化流程 · 图 3
Graphiti · 数据持久化流程 · 图 3

来源：graphiti_core/nodes.py:319-344、graphiti_core/nodes.py:504-535、graphiti_core/edges.py:304-339、graphiti_core/models/nodes/node_db_queries.py:30-66、graphiti_core/models/edges/edge_db_queries.py:63-122

分区和组管理

所有节点和边都包含一个 group_id 字段，用于实现多租户的图分区。

  • Node.delete_by_group_id()：对特定分区的节点及其关系执行批量删除 graphiti_core/nodes.py:178-226。
  • Edge.delete_by_uuids()：跨提供者按 UUID 批量删除边 graphiti_core/edges.py:93-130。
  • clear_data()：维护函数，用于从图中清除所有数据或特定 group_ids 的数据 graphiti_core/utils/maintenance/graph_data_operations.py:34-65。

来源：graphiti_core/nodes.py:178-226、graphiti_core/edges.py:93-130、graphiti_core/utils/maintenance/graph_data_operations.py:34-65