agentic_huge_data_base / wiki
页面 Graphiti · 10.5 Saga Episode Chains·DeepWiki 中文全文译文
DeepWiki 中文译文 / Graphiti / 10.5

10.5 · Saga Episode Chains

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

项目Graphiti 章节10.5 状态全文译文 模块图谱与关系、界面与交互、测试、发布与运维、工作流与编排
项目要点页2.5 参考项目 项目章节目录Graphiti DeepWiki 原始章节Saga Episode Chains 上一章10.4 下一章10.6
源码线索
  • 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
模块标签
  • 图谱与关系
  • 界面与交互
  • 测试、发布与运维
  • 工作流与编排
  • 检索、召回与索引

中文译文

Saga Episode Chains（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/getzep/graphiti/10.5-saga-episode-chains
翻译时间：2026-05-27T08:44:53.116Z
翻译模型：deepseek-chat
原文字符数：10145
项目：Graphiti (graphiti)

---

传奇剧集链

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

  • 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

数据模型

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

代码实体关系图

标题：传奇数据模型关系

graph TB
    subgraph "传奇结构"
        SagaNode["SagaNode (graphiti_core/nodes.py)
        - uuid: str
        - name: str
        - group_id: str
        - created_at: datetime"]

        Episode1["EpisodicNode 1
        (最旧)"]
        Episode2["EpisodicNode 2"]
        Episode3["EpisodicNode 3
        (最新)"]
    end

    SagaNode -->|"HAS_EPISODE"| Episode1
    SagaNode -->|"HAS_EPISODE"| Episode2
    SagaNode -->|"HAS_EPISODE"| Episode3

    Episode1 -->|"NEXT_EPISODE"| Episode2
    Episode2 -->|"NEXT_EPISODE"| Episode3

    subgraph "边实现"
        HasEpisodeEdge["HasEpisodeEdge (graphiti_core/edges.py)
        - source_node_uuid (传奇)
        - target_node_uuid (剧集)
        - group_id: str"]

        NextEpisodeEdge["NextEpisodeEdge (graphiti_core/edges.py)
        - source_node_uuid (前一剧集)
        - target_node_uuid (下一剧集)
        - group_id: str"]
    end

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

标题：传奇解析逻辑

flowchart TD
    Start["Graphiti.add_episode(saga='conversation_123')"]
    Check["Graphiti._get_or_create_saga()
    查询 name='conversation_123'
    和 group_id"]

    Exists{传奇存在？}
    Return["返回现有 SagaNode"]
    Create["创建新 SagaNode
    - name: 'conversation_123'
    - group_id: group_id"]
    Save["SagaNode.save(driver)"]

    Start --> Check
    Check --> Exists
    Exists -->|是| Return
    Exists -->|否| Create
    Create --> Save
    Save --> Return

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

参数类型描述
saga`str \SagaNode \None`传奇标识符。如果是字符串且传奇不存在，则创建新传奇。
saga_previous_episode_uuid`str \None`传奇中前一剧集的 UUID，用于优化链链接。
剧集关联过程

当添加带有传奇参数的剧集时，_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。

参数：

参数类型描述
reference_timedatetime过滤 valid_at <= reference_time 的剧集。
last_nint要检索的最新剧集数量。
saga`str \None`按传奇名称过滤。

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

实现参考

关键方法和类
实体文件用途
SagaNodegraphiti_core/nodes.py:783-832表示传奇容器节点。
HasEpisodeEdgegraphiti_core/edges.py:681-812表示传奇到剧集的链接。
NextEpisodeEdgegraphiti_core/edges.py:814-878表示剧集之间的序列链接。
_get_or_create_sagagraphiti_core/graphiti.py:325-373解析或初始化传奇的逻辑。
retrieve_episodesgraphiti_core/utils/maintenance/graph_data_operations.py:67-128支持传奇感知的剧集检索逻辑。
SagaSummarygraphiti_core/prompts/summarize_sagas.py:26-33传奇摘要的 Pydantic 模型。
约束与注意事项
  • 传奇唯一性：传奇在 (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