时序感知与双时态模型（中文译文）
原始 DeepWiki 页面：https://deepwiki.com/getzep/graphiti/3.2-temporal-awareness-and-bi-temporal-model
翻译时间：2026-05-27T08:44:55.134Z
翻译模型：deepseek-chat
原文字符数：12135
项目：Graphiti (graphiti)
---
时间感知与双时间模型
相关源文件
以下文件被用作生成此 Wiki 页面的上下文：
README.mdexamples/quickstart/README.mdgraphiti_core/edges.pygraphiti_core/nodes.pygraphiti_core/utils/__init__.pygraphiti_core/utils/datetime_utils.pygraphiti_core/utils/maintenance/community_operations.pygraphiti_core/utils/maintenance/graph_data_operations.py
本页介绍 Graphiti 的时间数据模型，该模型同时追踪事实进入系统的时间（created_at）以及它们在现实世界中成立的时间（valid_at、invalid_at）。这种双时间设计支持时间点查询、历史推理以及自动失效被矛盾的事实。
时间模型概述
Graphiti 在其数据模型中维护四个时间维度，以支持系统时间和有效时间推理：
| 时间属性 | 应用于 | 用途 |
|---|---|---|
created_at | 所有节点和边 | 实体进入图数据库的时间 |
valid_at | EpisodicNode、EntityEdge | 事实/事件在现实中发生的时间 |
invalid_at | EntityEdge | 事实在现实中不再成立的时间 |
expired_at | EntityEdge | 边因新信息而失效的时间 |
这种设计将系统时间（我们了解到某事的时间）与有效时间（实际发生的时间）分离，支持诸如"系统在日期 X 对发生在日期 Y 的事件了解什么？"之类的查询。
来源：graphiti_core/nodes.py:98-98、graphiti_core/nodes.py:311-313、graphiti_core/edges.py:54-54、graphiti_core/edges.py:271-279
时间维度详解
created_at：系统录入时间
标题：系统录入时间可视化
graph LR
A["片段已入库<br/>2024-01-15 10:00"] -->|创建| B["节点 (created_at: 2024-01-15 10:00)"]
A -->|创建| C["边 (created_at: 2024-01-15 10:00)"]
D["同一实体被提及<br/>2024-01-20 14:00"] -->|检索| B
D -->|不修改| E["created_at 保持不变"]
created_at 时间戳记录节点或边首次添加到图数据库的时间。它代表系统时间，在实体创建时设置一次。该属性存在于所有节点（通过 Node 基类）和边（通过 Edge 基类）上。
关键行为：
- 在创建时自动设置为
utc_now()graphiti_core/nodes.py:98-98、graphiti_core/edges.py:54-54。 - 初始创建后永不修改。
- 用于系统操作的时间顺序排序。
- 与事件实际发生的时间无关。
来源：graphiti_core/nodes.py:98-98、graphiti_core/edges.py:54-54、graphiti_core/utils/datetime_utils.py:20-22
valid_at：现实世界事件时间
标题：事件时间与入库时间
graph TB
subgraph "片段表示"
A["EpisodicNode<br/>name: 'Q4 规划会议'<br/>valid_at: 2024-09-15 14:00<br/>created_at: 2024-09-20 10:00"]
end
subgraph "提取的事实"
B["EntityEdge<br/>fact: 'Alice 领导项目 X'<br/>valid_at: 2024-09-15 14:00<br/>created_at: 2024-09-20 10:00"]
C["EntityEdge<br/>fact: '预算已批准：50万美元'<br/>valid_at: 2024-09-15 14:00<br/>created_at: 2024-09-20 10:00"]
end
A -->|提取| B
A -->|提取| C
Note1["事件与入库之间<br/>有5天的间隔"]
valid_at 时间戳记录事件或事实在现实世界中成立的时间。这与 created_at（我们了解到它的时间）不同。
应用场景：
EpisodicNode.valid_at：片段内容最初创建的时间（例如，消息时间戳、文档日期）graphiti_core/nodes.py:311-313。EntityEdge.valid_at：关系成立的时间。该时间由大语言模型（LLM）从片段内容中提取graphiti_core/edges.py:274-276。
大语言模型（LLM）提取： 在边提取过程中，大语言模型（LLM）使用片段的 valid_at 作为参考，将相对日期解析为绝对时间戳。在 retrieve_episodes 中，valid_at 用于过滤在特定 reference_time 之前发生的片段 graphiti_core/utils/maintenance/graph_data_operations.py:80-82。
来源：graphiti_core/nodes.py:311-313、graphiti_core/edges.py:274-276、graphiti_core/utils/maintenance/graph_data_operations.py:67-90
invalid_at：事实过期时间
标题：时间失效时间线
graph TB
subgraph "时间线"
T1["2024-01-01<br/>Alice 以工程师身份加入"]
T2["2024-06-01<br/>Alice 晋升为经理"]
end
subgraph "晋升后的图状态"
E1["EntityEdge<br/>fact: 'Alice 是工程师'<br/>valid_at: 2024-01-01<br/>invalid_at: 2024-06-01<br/>expired_at: 2024-06-02"]
E2["EntityEdge<br/>fact: 'Alice 是经理'<br/>valid_at: 2024-06-01<br/>invalid_at: null<br/>expired_at: null"]
end
T1 -.->|创建| E1
T2 -.->|使失效| E1
T2 -.->|创建| E2
invalid_at 时间戳记录事实在现实中不再成立的时间。该时间主要通过边解析过程中的时间矛盾检测来设置。
关键行为：
- 大多数边初始为
Nonegraphiti_core/edges.py:277-279。 - 当新信息明确与现有事实矛盾时设置。
- 表示有效时间的终止。
- 与
valid_at一起用于定义事实的有效性区间，以支持历史推理。
来源：graphiti_core/edges.py:277-279
expired_at：系统失效时间
标题：系统失效过程
graph LR
A["新边已提取<br/>2024-06-02 15:30"] -->|触发| B["resolve_edge_contradictions"]
B -->|检测到冲突| C["现有边<br/>valid_at: 2024-01-01<br/>invalid_at: null"]
B -->|设置| D["invalid_at: 2024-06-01<br/>expired_at: 2024-06-02 15:30"]
D -.->|系统时间| E["失效被记录的时间"]
D -.->|有效时间| F["事实不再成立的时间"]
expired_at 时间戳记录系统确定边应失效的时间。这代表失效操作的系统时间。
与 invalid_at 的区别：
invalid_at：事实不再成立的时间（有效时间）。expired_at：系统记录此失效的时间（系统时间）。
用法：
- 在检测到矛盾时设置为
utc_now()。 - 将边标记为逻辑删除（软删除），使其从图的"当前"视图中移除。
- 支持系统知识随时间演变的审计追踪。
来源：graphiti_core/edges.py:271-273
时间数据结构
EpisodicNode 时间属性
标题：EpisodicNode 模型
classDiagram
class EpisodicNode {
+str uuid
+str name
+datetime created_at
+datetime valid_at
+EpisodeType source
+str content
+list~str~ entity_edges
}
class TemporalSemantics {
created_at: "系统录入时间"
valid_at: "原始文档时间戳"
}
EpisodicNode ..> TemporalSemantics
EpisodicNode 表示离散的事件或文档：
valid_at：事件本身的时间戳（例如，消息发送时间）graphiti_core/nodes.py:311-313。created_at：节点持久化到 Graphiti 的时间graphiti_core/nodes.py:98-98。entity_edges：从该特定片段中提取的边 UUID 列表，用于建立来源追踪graphiti_core/nodes.py:314-317。
来源：graphiti_core/nodes.py:307-317、graphiti_core/nodes.py:98-98
EntityEdge 时间属性
标题：EntityEdge 模型
classDiagram
class EntityEdge {
+str uuid
+str fact
+list~str~ episodes
+datetime created_at
+datetime? valid_at
+datetime? invalid_at
+datetime? expired_at
}
class TemporalLifecycle {
created_at: "图插入时间"
valid_at: "事实成立时间"
invalid_at: "事实不再成立时间"
expired_at: "系统失效时间"
}
EntityEdge ..> TemporalLifecycle
EntityEdge 追踪事实的生命周期：
episodes：支持或提及此事实的片段 UUID 列表graphiti_core/edges.py:267-270。created_at：边首次创建的时间graphiti_core/edges.py:54-54。valid_at、invalid_at：事实在现实世界中成立的时期graphiti_core/edges.py:274-279。expired_at：系统将事实标记为不再活跃的时间graphiti_core/edges.py:271-273。
来源：graphiti_core/edges.py:263-279、graphiti_core/edges.py:54-54
时间点查询
Graphiti 通过 SearchFilters 系统和数据库级别的时间过滤来支持时间查询。像 retrieve_episodes 这样的函数允许通过使用 reference_time 参数过滤 EpisodicNode.valid_at 来查询图在特定时间点的状态 graphiti_core/utils/maintenance/graph_data_operations.py:67-90。
时间搜索过滤器
SearchFilters 系统支持在所有四个时间维度上过滤搜索结果。它支持针对 created_at、valid_at、invalid_at 和 expired_at 的操作符。
标题：SearchFilters 结构
graph TB
subgraph "SearchFilters 时间约束"
A["DateFilter 对象"] -->|按条件过滤| B["created_at"]
A -->|按条件过滤| C["valid_at"]
A -->|按条件过滤| D["invalid_at"]
A -->|按条件过滤| E["expired_at"]
end
subgraph "比较操作符"
F["equals（等于）"]
G["less_than（小于）"]
H["greater_than（大于）"]
I["less_than_equal（小于等于）"]
J["greater_than_equal（大于等于）"]
end
A -.-> F
A -.-> G
A -.-> H
A -.-> I
A -.-> J
来源：graphiti_core/nodes.py:98-98、graphiti_core/edges.py:271-279、graphiti_core/utils/maintenance/graph_data_operations.py:80-82
片段来源追踪
EntityEdge 上的 episodes 数组
标题：边来源追踪
graph TB
subgraph "片段时间线"
E1["片段 A<br/>uuid: aaa-111<br/>valid_at: 2024-01-15"]
E2["片段 B<br/>uuid: bbb-222<br/>valid_at: 2024-03-20"]
E3["片段 C<br/>uuid: ccc-333<br/>valid_at: 2024-06-10"]
end
subgraph "EntityEdge 来源追踪"
Edge["EntityEdge<br/>fact: 'Alice 在项目 X 上工作'<br/>episodes: ['aaa-111', 'bbb-222', 'ccc-333']<br/>valid_at: 2024-01-15<br/>invalid_at: null"]
end
E1 -->|首次提及| Edge
E2 -->|确认| Edge
E3 -->|再次引用| Edge
Note["追踪所有提及<br/>此事实的片段"]
EntityEdge 上的 episodes 数组记录哪些片段提及了此事实 graphiti_core/edges.py:267-270。这允许系统将任何事实追溯回其原始来源。
来源：graphiti_core/edges.py:267-270、graphiti_core/nodes.py:314-317
EpisodicNode 上的 entity_edges 数组
EpisodicNode 上的 entity_edges 数组提供反向关系，列出从该片段中提取的所有边 graphiti_core/nodes.py:314-317。
标题：片段提取来源追踪
graph LR
subgraph "片段"
E["EpisodicNode<br/>uuid: episode-123<br/>entity_edges: ['edge-1', 'edge-2', 'edge-3']"]
end
subgraph "提取的边"
E1["EntityEdge<br/>uuid: edge-1"]
E2["EntityEdge<br/>uuid: edge-2"]
E3["EntityEdge<br/>uuid: edge-3"]
end
E -->|引用| E1
E -->|引用| E2
E -->|引用| E3
Note["反向来源追踪：<br/>此片段产生了<br/>哪些事实？"]
来源：graphiti_core/nodes.py:314-317、graphiti_core/edges.py:267-270