10.5 · Saga 事件链

Saga 事件链

传奇剧集链

相关源文件

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

• graphiti_core/edges.py
• graphiti_core/graphiti.py
• graphiti_core/nodes.py
• graphiti_core/prompts/summarize_sagas.py
• graphiti_core/utils/maintenance/community_operations.py
• graphiti_core/utils/maintenance/graph_data_operations.py

传奇剧集链提供了一种将剧集组织成具有显式顺序的连续叙事的机制。一个传奇将相关剧集分组在一起，并通过链接边维护它们的时间进展，从而支持跨对话或数据流检索剧集序列和上下文连续性。

关于一般剧集处理，请参见剧集处理工作流。关于跨所有剧集的时间查询，请参见搜索过滤器与时间查询。

概述

传奇系统由三个核心组件组成：

1. SagaNode（传奇节点）：命名容器，用于分组相关剧集 graphiti_core/nodes.py:783-832。
2. HasEpisodeEdge（拥有剧集边）：将传奇连接到其每个剧集 graphiti_core/edges.py:681-812。
3. NextEpisodeEdge（下一剧集边）：链接传奇内连续的剧集 graphiti_core/edges.py:814-878。

这种结构使应用程序能够维护对话线程、文档修订版或任何需要有序剧集检索和处理的连续叙事。

来源：graphiti_core/graphiti.py:31-37，graphiti_core/nodes.py:57，graphiti_core/nodes.py:783-832，graphiti_core/edges.py:681-878

数据模型

传奇与剧集之间的关系通过图中的特定节点和边类型建立。

代码实体关系图

标题：传奇数据模型关系

来源：graphiti_core/nodes.py:783-832，graphiti_core/edges.py:681-812，graphiti_core/edges.py:814-878

SagaNode（传奇节点）

SagaNode 类表示一个命名的剧集集合。每个传奇通过其名称和 group_id 组合进行标识，确保在分区内的唯一性 graphiti_core/nodes.py:783-832。

属性：

• uuid：唯一标识符。
• name：人类可读的传奇名称。
• group_id：图分区标识符。
• labels：节点标签（默认为 ['Saga']）。
• created_at：传奇创建的时间戳。

来源：graphiti_core/nodes.py:783-832

HasEpisodeEdge（拥有剧集边）

HasEpisodeEdge 将传奇连接到其每个成员剧集。这提供了传奇容器与所有属于它的剧集之间的直接关联 graphiti_core/edges.py:681-812。

NextEpisodeEdge（下一剧集边）

NextEpisodeEdge 在传奇内连续剧集之间建立时间顺序。每个剧集指向序列中的下一个剧集 graphiti_core/edges.py:814-878。

创建和管理传奇

传奇创建工作流

传奇在添加带有 saga 参数的剧集时隐式创建，也可以通过内部的 _get_or_create_saga 方法进行管理 graphiti_core/graphiti.py:325-373。

标题：传奇解析逻辑

来源：graphiti_core/graphiti.py:325-373，graphiti_core/nodes.py:783-832

查找现有传奇

系统执行以下查询以查找现有传奇 graphiti_core/graphiti.py:344-352：

MATCH (s:Saga {name: $name, group_id: $group_id})
RETURN s.uuid AS uuid, s.name AS name,
       s.group_id AS group_id, s.created_at AS created_at

向传奇添加剧集

add_episode 方法接受两个与传奇相关的参数 graphiti_core/graphiti.py:775-823：

剧集关联过程

当添加带有传奇参数的剧集时，_process_episode_data 处理链接 graphiti_core/graphiti.py:517-560：

1. 传奇解析：获取或创建 SagaNode。
2. 前一剧集查找：查找传奇中最新的剧集（除非提供了 saga_previous_episode_uuid）。
3. 创建 NEXT_EPISODE 边：通过 NextEpisodeEdge 将前一剧集链接到新剧集。
4. 创建 HAS_EPISODE 边：通过 HasEpisodeEdge 将传奇链接到新剧集。

来源：graphiti_core/graphiti.py:517-560，graphiti_core/edges.py:814-878

使用 saga_previous_episode_uuid 进行优化

当按顺序添加多个剧集时，提供 saga_previous_episode_uuid 可以跳过对链中最后一个剧集的数据库查找 graphiti_core/graphiti.py:775-823。

# 第一个剧集
result1 = await client.add_episode(
    name="消息 1",
    episode_body="...",
    saga="podcast_1"
)

# 后续剧集 - 传递前一 UUID 以避免查找
result2 = await client.add_episode(
    name="消息 2",
    episode_body="...",
    saga="podcast_1",
    saga_previous_episode_uuid=result1.episode.uuid
)

来源：graphiti_core/graphiti.py:775-823

检索传奇剧集

使用传奇过滤器的 retrieve_episodes

retrieve_episodes 方法允许按传奇名称进行过滤 graphiti_core/utils/maintenance/graph_data_operations.py:67-128。

参数：

来源：graphiti_core/utils/maintenance/graph_data_operations.py:67-128

传奇过滤查询实现

当提供传奇名称时，系统执行一个专门的查询来遍历 HAS_EPISODE 关系 graphiti_core/utils/maintenance/graph_data_operations.py:104-125：

MATCH (s:Saga {name: $saga_name, group_id: $group_id})-[:HAS_EPISODE]->(e:Episodic)
WHERE e.valid_at <= $reference_time
RETURN e.*
ORDER BY e.valid_at DESC
LIMIT $num_episodes

来源：graphiti_core/utils/maintenance/graph_data_operations.py:104-125

传奇摘要

Graphiti 支持使用 SagaSummary 模型和 summarize_saga 提示生成整个传奇链的密集事实摘要 graphiti_core/prompts/summarize_sagas.py:26-84。

摘要过程：

1. 检索现有摘要（如果可用）。
2. 从传奇中追加新剧集内容。
3. 使用 summarize_saga 提示生成一个单一的事实知识简报，长度在 MAX_SUMMARY_CHARS（通常为 2000 个字符）以内 graphiti_core/prompts/summarize_sagas.py:21-30。

提示指令特别要求避免使用“讨论”或“提到”等元语言，而应使用直接的事实陈述 graphiti_core/prompts/summarize_sagas.py:72-80。

来源：graphiti_core/prompts/summarize_sagas.py:26-84，graphiti_core/graphiti.py:61，graphiti_core/prompts/summarize_sagas.py:21-30

实现参考

关键方法和类

约束与注意事项

• 传奇唯一性：传奇在 (name, group_id) 组合上是唯一的 graphiti_core/graphiti.py:344-352。
• 排序：系统主要按 valid_at（剧集时间戳）排序，并回退到 created_at（入库时间）graphiti_core/graphiti.py:528-541。
• 组隔离：传奇链中的所有节点和边必须属于同一个 group_id graphiti_core/graphiti.py:325-373。

来源：graphiti_core/graphiti.py:325-373，graphiti_core/graphiti.py:528-541，graphiti_core/utils/maintenance/graph_data_operations.py:67-128