3.4 · 时序知识 Graphs（Temporal Knowledge Graphs）

时序知识 Graphs

时序知识图谱

相关源文件

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

• .github/workflows/distributed_test.yml
• .github/workflows/temporal_graph_tests.yml
• cognee/modules/engine/utils/__init__.py
• cognee/modules/engine/utils/generate_event_datapoint.py
• cognee/modules/engine/utils/generate_node_name.py
• cognee/modules/engine/utils/generate_timestamp_datapoint.py
• cognee/modules/graph/utils/resolve_edges_to_text.py
• cognee/tasks/codingagents/__init__.py
• cognee/tasks/documents/__init__.py
• cognee/tasks/temporal_awareness/__init__.py
• cognee/tasks/temporal_awareness/build_graph_with_temporal_awareness.py
• cognee/tasks/temporal_awareness/search_graph_with_temporal_awareness.py
• cognee/tasks/temporal_graph/__init__.py
• cognee/tasks/temporal_graph/add_entities_to_event.py
• cognee/tasks/temporal_graph/enrich_events.py
• cognee/tasks/temporal_graph/extract_events_and_entities.py
• cognee/tasks/temporal_graph/extract_knowledge_graph_from_events.py
• cognee/tests/test_temporal_graph.py
• deployment/helm/Dockerfile
• deployment/setup_ubuntu_instance.sh
• distributed/Dockerfile
• tools/check-lockfile.py

时序知识图谱通过添加时间感知的事件提取、时间戳处理和专门的检索功能，扩展了 Cognee 标准知识图谱的能力。该系统支持查询事件"何时"发生、实体之间的时序关系，以及对图谱数据进行基于时间的过滤。

如需了解不带时序功能的标准知识图谱生成，请参阅知识图谱生成（cognee.cognify）。如需了解基于时序的搜索策略，请参阅高级检索策略。

概述

时序知识图谱能够捕获带有时间戳的事件，从而支持基于时间的查询，例如"1992 年发生了什么？"或"显示 2010 年之后的教练变动"。该系统使用专门的管线从文档中提取时序信息，并在检索过程中支持时间范围查询。

主要特性：

• 事件提取：从非结构化文本中识别具体事件及其描述。
• 时间戳检测：为提取的事件分配精确的日期或时间区间。
• 时序检索：使用大语言模型（LLM）从自然语言查询中解析时间范围，以过滤图谱数据。
• 混合搜索：将时序过滤与向量相似度相结合，用于事件排序。

来源：cognee/tasks/temporal_graph/__init__.py:1-7、cognee/tasks/temporal_awareness/__init__.py:1-7、cognee/tests/test_temporal_graph.py:15-42

时序 Cognify 管线

管线架构

时序管线通过在 cognify() 函数中设置 temporal_cognify = True 来激活。这会用一系列专注于事件和时序元数据的任务替换标准实体提取。

时序管线任务流程：

来源：cognee/tasks/temporal_graph/extract_events_and_entities.py:12-13、cognee/tasks/temporal_graph/enrich_events.py:8-34、cognee/tasks/documents/__init__.py:9-10

事件与实体提取

时序管线的核心包含两个主要的提取阶段：

1. 事件提取：extract_events_and_timestamps 任务使用 extract_event_graph cognee/tasks/temporal_graph/extract_events_and_entities.py:27-29 处理 DocumentChunk 对象。它识别事件并通过 generate_event_datapoint cognee/tasks/temporal_graph/extract_events_and_entities.py:33-33 将其映射到 Event 数据点，然后追加到片段（chunk）的 contains 列表中。
2. 实体丰富：enrich_events 函数接收提取的事件，将其序列化为 JSON（包含 event_name 和 description）cognee/tasks/temporal_graph/enrich_events.py:25-29，并使用 extract_event_entities 识别与这些事件关联的特定实体 cognee/tasks/temporal_graph/enrich_events.py:32-32。

代码实体映射：

• extract_events_and_timestamps：cognee/tasks/temporal_graph/extract_events_and_entities.py:13-36
• enrich_events：cognee/tasks/temporal_graph/enrich_events.py:8-34
• generate_event_datapoint：cognee/modules/engine/utils/generate_event_datapoint.py
• EventList 和 EventWithEntities：cognee/tasks/temporal_graph/models.py

来源：cognee/tasks/temporal_graph/extract_events_and_entities.py:1-37、cognee/tasks/temporal_graph/enrich_events.py:1-35

时序检索系统

TemporalRetriever 逻辑

TemporalRetriever（通过 SearchType.TEMPORAL 调用）实现了一个多步骤的检索过程，优先进行基于时间的过滤。

来源：cognee/modules/retrieval/temporal_retriever.py:19-167、cognee/tests/test_temporal_graph.py:125-155

基于时间的查询处理

系统将自然语言解析为结构化的 Timestamp 对象。例如，提及"2011"的查询会使用 date_to_int cognee/modules/engine/utils/generate_timestamp_datapoint.py:11-11 进行转换，以实现高效的数据库范围比较。

• 时间戳模型：cognee/tasks/temporal_graph/models.py:6-6
• 日期转换：cognee/modules/engine/utils/generate_timestamp_datapoint.py:11-11

来源：cognee/tests/test_temporal_graph.py:6-11、cognee/modules/engine/utils/generate_timestamp_datapoint.py

实现细节

边解析为文本

检索到图谱数据后，需要将其转换回大语言模型（LLM）可读的格式。resolve_edges_to_text 函数通过以下步骤处理：

1. 通过 _extract_nodes_from_edges cognee/modules/graph/utils/resolve_edges_to_text.py:33-58 从检索到的 Edge 对象中提取节点。
2. 使用 _create_title_from_text cognee/modules/graph/utils/resolve_edges_to_text.py:26-30 为节点生成标题，该方法将前几个词与最频繁出现的词（排除 DEFAULT_STOP_WORDS cognee/modules/graph/utils/resolve_edges_to_text.py:6-6）组合在一起。
3. 格式化连接关系（例如，节点：名称 \n 连接：源 --[标签]--> 目标）cognee/modules/graph/utils/resolve_edges_to_text.py:87-99。

来源：cognee/modules/graph/utils/resolve_edges_to_text.py:1-100

使用 Graphiti 实现时序感知

对于高级时序建模，Cognee 集成了 Graphiti 库，以"剧集"序列的形式构建图谱 cognee/tasks/temporal_awareness/build_graph_with_temporal_awareness.py:33-39。这在 build_graph_with_temporal_awareness 任务中使用。

# 使用 Graphiti 构建带时序剧集的图谱示例
async def build_graph_with_temporal_awareness(data: List[Data]):
    graphiti = Graphiti(url, "neo4j", password)
    for i, text in enumerate(text_list):
        await graphiti.add_episode(
            name = f"episode_{i}",
            episode_body = text,
            source = EpisodeType.text,
            reference_time = datetime.now(timezone.utc),
        )

来源：cognee/tasks/temporal_awareness/build_graph_with_temporal_awareness.py:15-42

使用与调用

运行时序 Cognify

时序模式在 cognify 步骤中启用。该系统支持多种数据库组合，这些组合在持续集成（CI）工作流中使用 test_temporal_graph.py .github/workflows/temporal_graph_tests.yml:55-55 进行验证。

import cognee
from cognee.api.v1.search import SearchType

# 添加数据
await cognee.add(biography_text, dataset_name = "biographies")

# 运行时序 cognify 以提取事件和时间戳
await cognee.cognify(temporal_cognify = True)

# 使用时序感知进行搜索
search_results = await cognee.search(
    SearchType.TEMPORAL,
    query = "2009 年 Attaphol 发生了什么？"
)

来源：cognee/tests/test_temporal_graph.py:1-155、cognee/api/v1/search.py:7-7

数据库提供商

时序图谱在多个后端上均受支持，通过持续集成（CI）中的环境变量进行配置：

• 图数据库：kuzu、neo4j .github/workflows/temporal_graph_tests.yml:52-60
• 向量数据库：lancedb、pgvector .github/workflows/temporal_graph_tests.yml:53-147
• 关系数据库：sqlite、postgres .github/workflows/temporal_graph_tests.yml:54-148

来源：.github/workflows/temporal_graph_tests.yml:22-155