10 · 高级用量（Advanced Usage）

高级用量

高级用法

相关源文件

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

• 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。

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

来源： 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 检索之前的上下文，并创建结构化的边来维护链式关系。

详情请参见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