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

时序知识图谱与动态事实记忆 · 本章是 Graphiti DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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

翻译时间：2026-05-27T08:45:03.248Z

翻译模型：deepseek-chat

原文字符数：16385

项目：Graphiti (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

图模式架构

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

时序知识图谱模式

erDiagram
    "EpisodicNode" ||--o{ "MENTIONS" : "source"
    "MENTIONS" }o--|| "EntityNode" : "target"
    "EntityNode" ||--o{ "RELATES_TO" : "source/target"
    "EntityNode" ||--o{ "HAS_MEMBER" : "target"
    "CommunityNode" ||--o{ "HAS_MEMBER" : "source"
    "SagaNode" ||--o{ "HAS_EPISODE" : "source"
    "HAS_EPISODE" }o--|| "EpisodicNode" : "target"
    "EpisodicNode" ||--o{ "NEXT_EPISODE" : "source"
    "NEXT_EPISODE" }o--|| "EpisodicNode" : "target"

    "EpisodicNode" {
        string uuid "PK, uuid4()"
        string name "片段标识符"
        string group_id "分区键"
        datetime created_at "系统时间戳"
        datetime valid_at "片段时间戳"
        string source "message|json|text|fact_triple"
        string source_description
        string content "原始数据"
        list_string entity_edges "EntityEdge UUID列表"
    }

    "EntityNode" {
        string uuid "PK, uuid4()"
        string name "实体名称"
        string group_id "分区键"
        datetime created_at "系统时间戳"
        list_string labels "动态类型"
        string summary "上下文摘要"
        dict attributes "标签特定属性"
        list_float name_embedding "向量"
    }

    "CommunityNode" {
        string uuid "PK, uuid4()"
        string name "社区描述"
        string group_id "分区键"
        datetime created_at "系统时间戳"
        string summary "聚合摘要"
        list_float name_embedding "向量"
    }

    "SagaNode" {
        string uuid "PK, uuid4()"
        string name "Saga标识符"
        string group_id "分区键"
        datetime created_at "系统时间戳"
    }

    "MENTIONS" {
        string uuid "PK, uuid4()"
        string group_id "分区键"
        datetime created_at "系统时间戳"
        string source_node_uuid "Episodic UUID"
        string target_node_uuid "Entity UUID"
    }

    "RELATES_TO" {
        string uuid "PK, uuid4()"
        string group_id "分区键"
        datetime created_at "系统时间戳"
        string source_node_uuid "Entity UUID"
        string target_node_uuid "Entity UUID"
        string name "关系类型"
        string fact "自然语言描述"
        list_float fact_embedding "向量"
        list_string episodes "片段UUID列表"
        datetime valid_at "事实开始时间"
        datetime invalid_at "事实结束时间"
        datetime expired_at "废弃时间"
        dict attributes "关系特定属性"
    }

    "HAS_MEMBER" {
        string uuid "PK, uuid4()"
        string group_id "分区键"
        datetime created_at "系统时间戳"
        string source_node_uuid "Community UUID"
        string target_node_uuid "Entity UUID"
    }

    "HAS_EPISODE" {
        string uuid "PK, uuid4()"
        string group_id "分区键"
        datetime created_at "系统时间戳"
        string source_node_uuid "Saga UUID"
        string target_node_uuid "Episodic UUID"
    }

    "NEXT_EPISODE" {
        string uuid "PK, uuid4()"
        string group_id "分区键"
        datetime created_at "系统时间戳"
        string source_node_uuid "Episodic UUID"
        string target_node_uuid "Episodic UUID"
    }

来源：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 中，它作为实体和关系提取的源材料。

属性	类型	描述
`uuid`	`str`	通过 `uuid4()` 生成，主键
`name`	`str`	片段标识符
`group_id`	`str`	多租户分区键
`labels`	`list[str]`	从 `Node` 继承，默认为空列表
`created_at`	`datetime`	通过 `utc_now()` 生成的系统创建时间
`valid_at`	`datetime`	片段时间戳（事件发生时间）
`source`	`EpisodeType`	枚举：`message`、`json`、`text` 或 `fact_triple`
`source_description`	`str`	关于来源的元数据
`content`	`str`	原始片段内容
`entity_edges`	`list[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 中，它存储具有动态类型的结构化知识。

属性	类型	描述
`uuid`	`str`	通过 `uuid4()` 生成，主键
`name`	`str`	实体名称（为语义搜索嵌入）
`group_id`	`str`	分区键
`labels`	`list[str]`	动态实体类型（例如 `["Person", "Engineer"]`）
`created_at`	`datetime`	系统创建时间
`summary`	`str`	大语言模型（LLM）生成的上下文摘要
`attributes`	`dict[str, Any]`	标签特定属性
`name_embedding`	`list[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 中，它提供层次化摘要。

属性	类型	描述
`uuid`	`str`	通过 `uuid4()` 生成，主键
`name`	`str`	大语言模型（LLM）生成的社区描述
`group_id`	`str`	分区键
`created_at`	`datetime`	系统创建时间
`summary`	`str`	成员的聚合摘要
`name_embedding`	`list[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 中，它支持将片段组织成连贯的故事线。

属性	类型	描述
`uuid`	`str`	通过 `uuid4()` 生成，主键
`name`	`str`	Saga 标识符
`group_id`	`str`	分区键
`created_at`	`datetime`	系统创建时间

来源：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 中。

属性	类型	描述
`uuid`	`str`	通过 `uuid4()` 生成，主键
`group_id`	`str`	分区键
`created_at`	`datetime`	系统创建时间
`source_node_uuid`	`str`	`EpisodicNode.uuid`
`target_node_uuid`	`str`	`EntityNode.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 中。

属性	类型	描述
`uuid`	`str`	通过 `uuid4()` 生成，主键
`group_id`	`str`	分区键
`created_at`	`datetime`	事务时间
`source_node_uuid`	`str`	源 `EntityNode.uuid`
`target_node_uuid`	`str`	目标 `EntityNode.uuid`
`name`	`str`	关系类型
`fact`	`str`	自然语言描述
`fact_embedding`	`list[float] \	None`	向量嵌入
`episodes`	`list[str]`	支持的片段 UUID 列表
`valid_at`	`datetime \	None`	事实开始时间
`invalid_at`	`datetime \	None`	事实结束时间
`expired_at`	`datetime \	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 模型层次结构

classDiagram
    class "BaseModel" {
        <<Pydantic>>
    }

    class "Node" {
        <<abstract BaseModel>>
        +str uuid
        +str name
        +str group_id
        +list[str] labels
        +datetime created_at
        +save(driver: GraphDriver)* async
        +delete(driver: GraphDriver) async
    }

    class "EpisodicNode" {
        +EpisodeType source
        +str source_description
        +str content
        +datetime valid_at
        +list[str] entity_edges
        +save(driver) async
    }

    class "EntityNode" {
        +list[float] | None name_embedding
        +str summary
        +dict[str, Any] attributes
        +generate_name_embedding(embedder) async
        +save(driver) async
    }

    class "Edge" {
        <<abstract BaseModel>>
        +str uuid
        +str group_id
        +str source_node_uuid
        +str target_node_uuid
        +datetime created_at
        +save(driver: GraphDriver)* async
        +delete(driver: GraphDriver) async
    }

    "BaseModel" <|-- "Node"
    "BaseModel" <|-- "Edge"
    "Node" <|-- "EpisodicNode"
    "Node" <|-- "EntityNode"
    "Node" <|-- "CommunityNode"
    "Node" <|-- "SagaNode"
    "Edge" <|-- "EpisodicEdge"
    "Edge" <|-- "EntityEdge"
    "Edge" <|-- "CommunityEdge"
    "Edge" <|-- "HasEpisodeEdge"
    "Edge" <|-- "NextEpisodeEdge"

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

数据持久化流程

片段到图持久化管线

flowchart TB
    Input["原始输入"] --> add_episode["Graphiti.add_episode()"]

    add_episode --> EpisodicNode_save["EpisodicNode.save()<br/>graphiti_core/nodes.py"]

    EpisodicNode_save --> EntityNode_save["EntityNode.save()<br/>graphiti_core/nodes.py"]
    EpisodicNode_save --> EntityEdge_save["EntityEdge.save()<br/>graphiti_core/edges.py"]

    EntityNode_save --> DB_Query["driver.execute_query()<br/>graphiti_core/models/nodes/node_db_queries.py"]
    EntityEdge_save --> DB_Query_Edge["driver.execute_query()<br/>graphiti_core/models/edges/edge_db_queries.py"]

    subgraph Storage["物理存储"]
        Graph_Nodes["节点：<br/>(:Episodic)<br/>(:Entity)<br/>(:Community)<br/>(:Saga)"]
        Graph_Edges["关系：<br/>[:MENTIONS]<br/>[:RELATES_TO]<br/>[:HAS_MEMBER]"]
    end

    DB_Query --> Graph_Nodes
    DB_Query_Edge --> Graph_Edges

来源：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