agentic_huge_data_base / wiki
页面 Graphiti · 10 高级用量·DeepWiki 中文全文译文
DeepWiki 中文译文 / Graphiti / 10

10 · 高级用量（Advanced Usage）

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

项目Graphiti 章节10 状态全文译文 模块图谱与关系、测试、发布与运维、检索、召回与索引、配置治理
项目要点页2.5 参考项目 项目章节目录Graphiti DeepWiki 原始章节Advanced Usage 上一章9.3 下一章10.1
源码线索
  • examples/podcast/podcast_runner.py
  • graphiti_core/graphiti.py
  • graphiti_core/search/search.py
  • graphiti_core/search/search_config.py
  • graphiti_core/search/search_config_recipes.py
  • graphiti_core/search/search_utils.py
  • tests/test_graphiti_int.py
模块标签
  • 图谱与关系
  • 测试、发布与运维
  • 检索、召回与索引
  • 配置治理
  • 工作流与编排

中文译文

高级用量（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/getzep/graphiti/10-advanced-usage
翻译时间：2026-05-27T08:44:49.452Z
翻译模型：deepseek-chat
原文字符数：8427
项目：Graphiti (graphiti)

---

高级用法

相关源文件

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

  • examples/podcast/podcast_runner.py
  • graphiti_core/graphiti.py
  • graphiti_core/search/search.py
  • graphiti_core/search/search_config.py
  • graphiti_core/search/search_config_recipes.py
  • graphiti_core/search/search_utils.py
  • tests/test_graphiti_int.py

本文档面向 Graphiti 的高级用户，涵盖高级功能和优化技术。它是复杂主题（包括社区检测、搜索调优、自定义模式和时序推理）的高级入口点。

关于基本设置，请参见入门指南。关于核心系统架构，请参见系统架构。

社区检测与聚类

Graphiti 实现了自动化的社区检测功能，用于识别相关实体的集群，从而实现层级化知识表示和知识图谱的全局摘要。

标签传播与摘要

系统使用 label_propagation 算法 graphiti_core/utils/maintenance/community_operations.py:93-138 来识别社区，该算法根据实体的关系密度对实体进行聚类。通过 get_community_clusters graphiti_core/utils/maintenance/community_operations.py:30-90 识别出集群后，Graphiti 会执行基于大语言模型（LLM）的层级化摘要，生成 CommunityNode 实例 graphiti_core/nodes.py:52-52。

graph TB
    subgraph "代码实体空间：社区管线"
        BC["build_communities()"]
        GCC["get_community_clusters()"]
        LP["label_propagation()"]
        BUILD["build_community()"]
        UC["update_community()"]
    end

    subgraph "自然语言空间：概念"
        ENT["EntityNode"]
        CLUST["实体集群"]
        SUMM["层级化摘要"]
        COMM["CommunityNode"]
    end

    ENT --> GCC
    GCC --> LP
    LP --> CLUST
    CLUST --> BUILD
    BUILD --> SUMM
    SUMM --> COMM
    COMM -.-> UC

详情请参见社区检测与聚类。

来源： graphiti_core/utils/maintenance/community_operations.py:30-138、graphiti_core/utils/maintenance/community_operations.py:174-211、graphiti_core/nodes.py:52-52

搜索配置与调优

Graphiti 提供了一套复杂的混合搜索系统，结合了 BM25、向量相似度和图遍历。高级用户可以使用 SearchConfig 类 graphiti_core/search/search_config.py:112-119 和实体特定配置来调优搜索行为。

配置组件
  • 搜索方法：为节点 graphiti_core/search/search_config.py:38-42 和边 graphiti_core/search/search_config.py:32-36 选择 bm25、cosine_similarity 或 breadth_first_search。
  • 重排序策略：使用 reciprocal_rank_fusion（rrf）、mmr（最大边际相关性）或 cross_encoder graphiti_core/search/search_config.py:53-59 来获得高精度结果。
  • 配置模板：预定义的配置（如 COMBINED_HYBRID_SEARCH_CROSS_ENCODER graphiti_core/search/search_config_recipes.py:81-108）为常见用例提供了优化后的默认值。

详情请参见搜索配置与调优。

来源： graphiti_core/search/search_config.py:32-119、graphiti_core/search/search_config_recipes.py:81-108

自定义实体类型与属性

除了通用实体外，Graphiti 还允许使用 Pydantic 模型定义领域特定的模式。这可以实现结构化属性提取。

模式集成

在向 add_episode graphiti_core/graphiti.py:625-630 提供 entity_types 或 edge_types 时，提取管线会使用这些模型为大语言模型（LLM）生成特定的提示词，从而确保生成的图符合领域要求。系统会使用 validate_entity_types graphiti_core/utils/ontology_utils/entity_types_utils.py:106-106 对这些类型进行校验。

详情请参见自定义实体类型与属性。

来源： graphiti_core/graphiti.py:625-630、graphiti_core/utils/ontology_utils/entity_types_utils.py:106-106

搜索过滤器与时序查询

SearchFilters 系统 graphiti_core/search/search_filters.py:69-69 提供了一种强大的方式，可以根据节点标签、属性和复杂的时序逻辑来限制搜索结果。

时序感知

Graphiti 的双时序模型使用了 created_at、valid_at 和 invalid_at 等维度 graphiti_core/nodes.py:95-95、graphiti_core/edges.py:54-54。retrieve_episodes 函数 graphiti_core/utils/maintenance/graph_data_operations.py:67-90 使用 reference_time 来过滤在历史特定时间点有效的片段。可以使用 search_results_to_context_string graphiti_core/search/search_helpers.py:27-72 将结果格式化为适合大语言模型（LLM）消费的上下文字符串。

详情请参见搜索过滤器与时序查询。

来源： graphiti_core/search/search_filters.py:69-69、graphiti_core/utils/maintenance/graph_data_operations.py:67-90、graphiti_core/nodes.py:95-95、graphiti_core/search/search_helpers.py:27-72

Saga 片段链

Saga 允许创建结构化的叙事序列。通过使用 SagaNode graphiti_core/nodes.py:57-57、HasEpisodeEdge graphiti_core/edges.py:36-36 和 NextEpisodeEdge graphiti_core/edges.py:37-37，可以维护一系列相关事件的严格顺序和上下文。

片段管理

Graphiti.add_episode 方法接受一个 saga 参数 graphiti_core/graphiti.py:633-633，该参数会自动通过 retrieve_episodes graphiti_core/utils/maintenance/graph_data_operations.py:100-129 检索之前的上下文，并创建结构化的边来维护链式关系。

graph LR
    subgraph "代码实体空间：Saga 结构"
        SN["SagaNode"]
        HEE["HasEpisodeEdge"]
        NEE["NextEpisodeEdge"]
        EN["EpisodicNode"]
    end

    subgraph "自然语言空间：叙事"
        STORY["叙事序列"]
        EP1["片段 1"]
        EP2["片段 2"]
    end

    SN -- "HasEpisodeEdge" --> EN
    EN -- "NextEpisodeEdge" --> EN
    STORY --> SN
    EP1 --> EN

详情请参见Saga 片段链。

来源： graphiti_core/graphiti.py:633-633、graphiti_core/nodes.py:57-57、graphiti_core/edges.py:36-37、graphiti_core/utils/maintenance/graph_data_operations.py:100-129

并发与速率限制管理

为了处理高吞吐量的入库和搜索，Graphiti 使用了基于信号量的并发模型。

信号量控制

SEMAPHORE_LIMIT 环境变量或 Graphiti 构造函数中的 max_coroutines 参数 graphiti_core/graphiti.py:148-151 控制并发操作的数量。系统使用 semaphore_gather graphiti_core/helpers.py:45-45 来执行批量任务（如社区构建 graphiti_core/utils/maintenance/community_operations.py:10-10），同时保持在提供商的限制范围内。

详情请参见并发与速率限制管理。

来源： graphiti_core/graphiti.py:148-151、graphiti_core/helpers.py:45-45、graphiti_core/utils/maintenance/community_operations.py:10-10

OpenTelemetry 追踪与可观测性

Graphiti 内置了对 OpenTelemetry 分布式追踪的支持，可以监控提取和检索管线的性能。

可观测性栈
  • 追踪器接口：用于记录 Span 的抽象接口 graphiti_core/tracer.py:75-75。
  • 实现方式：系统支持将自定义追踪器传递给 Graphiti 构造函数 graphiti_core/graphiti.py:149-149。
  • 遥测：通过 capture_event graphiti_core/telemetry.py:74-74 实现的可选匿名遥测，用于系统健康监控。

详情请参见OpenTelemetry 追踪与可观测性。

来源： graphiti_core/graphiti.py:149-149、graphiti_core/tracer.py:75-75、graphiti_core/telemetry.py:74-74