3 · 核心概念（Core Concepts）

核心概念

核心概念

相关源文件

以下文件为本维基页面的生成提供了上下文：

• README.md
• examples/quickstart/README.md
• graphiti_core/edges.py
• graphiti_core/graphiti.py
• graphiti_core/nodes.py
• graphiti_core/utils/maintenance/community_operations.py
• graphiti_core/utils/maintenance/graph_data_operations.py

目的与范围

本页面介绍 Graphiti 设计中的基本架构概念和心智模型。内容涵盖三层知识图谱架构、事件处理管线、时序数据模型，以及事件数据与实体数据的区别。Graphiti 被设计为面向 AI 智能体的时序上下文图谱框架，能够追踪事实随时间的变化，同时维护与源数据的溯源关系 README.md:42-49。

关于具体组件的实现细节：

• 数据模型模式与节点/边类型：参见知识图谱数据模型
• 双时序时间戳处理：参见时序感知与双时序模型
• 基于大语言模型（LLM）的提取过程：参见实体与关系提取
• 去重策略：参见去重与解析

关于这些概念在系统架构层面的实现细节，参见系统架构。

来源：graphiti_core/graphiti.py:137-151，README.md:42-74

三层知识图谱架构

Graphiti 实现了一种三层图谱架构，每一层在知识表示和检索中承担不同的职责。

层级架构

第一层：事件记忆 - EpisodicNode 实例存储带有时序上下文的原始事件内容。content 字段保留原始数据，valid_at 标记事件发生的时间，source 指示 EpisodeType（消息、JSON、文本或事实三元组）graphiti_core/nodes.py:54-78。关系类型为 :MENTIONS 的 EpisodicEdge 将事件与提取的实体连接起来 graphiti_core/edges.py:143-158。

第二层：实体知识 - EntityNode 实例表示经过去重的实体，并带有语义嵌入向量。name 字段存储规范化的实体名称，labels 包含实体类型分类 graphiti_core/nodes.py:93-104。类型为 :RELATES_TO 的 EntityEdge 在 fact 字段中存储自然语言事实，同时包含双时序字段（valid_at、invalid_at、expired_at、created_at）graphiti_core/edges.py:32-43。

第三层：社区聚类 - CommunityNode 实例使用 label_propagation 算法对语义相关的实体进行分组 graphiti_core/utils/maintenance/community_operations.py:93-138。社区根据成员实体生成名称和摘要 graphiti_core/utils/maintenance/community_operations.py:174-200。类型为 :HAS_MEMBER 的 CommunityEdge 表示聚类成员关系 graphiti_core/edges.py:33-33。

节点与边类

所有节点类都继承自抽象的 Node 基类 graphiti_core/nodes.py:93-104，该基类提供了 uuid、name、group_id、labels 和 created_at 字段。所有边类都继承自 Edge graphiti_core/edges.py:49-58，提供了 uuid、group_id、source_node_uuid、target_node_uuid 和 created_at 字段。

来源：graphiti_core/nodes.py:54-104，graphiti_core/edges.py:49-158，graphiti_core/utils/maintenance/community_operations.py:93-200

事件类型与格式特定提取

Graphiti 处理由 EpisodeType 枚举定义的不同事件格式 graphiti_core/nodes.py:54-88：

EpisodeType 枚举与提示路由

事件类型详情

EpisodeType 用于对输入数据进行分类，并将其路由到特定的提取逻辑 graphiti_core/nodes.py:54-78。

来源：graphiti_core/nodes.py:54-88，graphiti_core/graphiti.py:60-61

事件处理管线概览

该管线通过多个阶段将原始事件转换为结构化的知识图谱数据。

管线阶段

处理阶段

阶段一：上下文检索 - retrieve_episodes() 获取相对于 reference_time 的最后 EPISODE_WINDOW_LEN（默认值为 3）个事件，为提取提供时序上下文 graphiti_core/utils/maintenance/graph_data_operations.py:67-100。

阶段二：节点解析 - 使用 resolve_extracted_nodes() 对实体进行去重，该函数采用多层级策略：精确匹配、模糊相似度匹配和大语言模型（LLM）推理 graphiti_core/utils/maintenance/node_operations.py:104-104。

阶段三：边解析与矛盾检测 - 通过 extract_edges() 提取关系，并使用 resolve_extracted_edges() 检查矛盾。如果新事实与现有事实矛盾，则会应用时序失效处理 graphiti_core/utils/maintenance/edge_operations.py:93-95。

阶段四：社区更新 - 使用 build_communities() 更新社区，该函数利用 label_propagation 算法根据节点之间的连接关系对节点进行聚类 graphiti_core/utils/maintenance/community_operations.py:86-87，graphiti_core/utils/maintenance/community_operations.py:93-138。

来源：graphiti_core/graphiti.py:86-105，graphiti_core/utils/maintenance/community_operations.py:93-138，graphiti_core/utils/maintenance/node_operations.py:104，graphiti_core/utils/maintenance/edge_operations.py:93-95

时序数据模型

Graphiti 实现了一种双时序数据模型，在两个时间维度上追踪时间戳：事件时间和系统时间。

EntityEdge 上的时序字段

事件时间维度 - 追踪事实在现实中为真的时间。EpisodicNode 使用 valid_at 标记事件发生的时间 graphiti_core/utils/maintenance/graph_data_operations.py:80-82。

系统时间维度 - 追踪数据在数据库中被修改的时间。created_at 在初始化时自动为所有节点和边设置 graphiti_core/nodes.py:98，graphiti_core/edges.py:54。

来源：graphiti_core/nodes.py:98，graphiti_core/edges.py:54，graphiti_core/graphiti.py:85

用于多租户的分组分区

所有节点和边都包含一个 group_id: str 字段，用于对图谱进行分区，从而实现多租户和数据隔离。

分组隔离

诸如 delete_by_group_id graphiti_core/nodes.py:178-199 和 get_by_group_ids graphiti_core/nodes.py:218-243 等操作使用 group_id 来确保数据隔离。社区检测也按组独立运行，仅获取指定组 ID 的聚类 graphiti_core/utils/maintenance/community_operations.py:30-53。

来源：graphiti_core/nodes.py:96，graphiti_core/edges.py:51，graphiti_core/utils/maintenance/community_operations.py:30-53

与子页面的关系

• 知识图谱数据模型 - EpisodicNode、EntityNode、CommunityNode、SagaNode 及其各自边的详细模式。
• 时序感知与双时序模型 - 四个时间维度的解释以及时间点查询支持。
• 实体与关系提取 - 大语言模型（LLM）如何从原始事件中提取结构化数据的详细信息。
• 去重与解析 - 用于解析节点和检测边矛盾的三层策略。