agentic_huge_data_base / wiki
页面 Graphiti · 10.2 检索配置与 Tuning·DeepWiki 中文全文译文
DeepWiki 中文译文 / Graphiti / 10.2

10.2 · 检索配置与 Tuning（Search Configuration and Tuning）

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

项目Graphiti 章节10.2 状态全文译文 模块图谱与关系、检索、召回与索引、测试、发布与运维、界面与交互
项目要点页2.5 参考项目 项目章节目录Graphiti DeepWiki 原始章节Search Configuration and Tuning 上一章10.1 下一章10.3
源码线索
  • examples/podcast/podcast_runner.py
  • graphiti_core/prompts/prompt_helpers.py
  • graphiti_core/search/search.py
  • graphiti_core/search/search_config.py
  • graphiti_core/search/search_config_recipes.py
  • graphiti_core/search/search_filters.py
  • graphiti_core/search/search_helpers.py
  • graphiti_core/search/search_utils.py
  • tests/test_graphiti_int.py
模块标签
  • 图谱与关系
  • 检索、召回与索引
  • 测试、发布与运维
  • 界面与交互
  • 配置治理

中文译文

检索配置与 Tuning（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/getzep/graphiti/10.2-search-configuration-and-tuning
翻译时间：2026-05-27T08:45:00.449Z
翻译模型：deepseek-chat
原文字符数：14401
项目：Graphiti (graphiti)

---

搜索配置与调优

相关源文件

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

  • examples/podcast/podcast_runner.py
  • graphiti_core/prompts/prompt_helpers.py
  • graphiti_core/search/search.py
  • graphiti_core/search/search_config.py
  • graphiti_core/search/search_config_recipes.py
  • graphiti_core/search/search_filters.py
  • graphiti_core/search/search_helpers.py
  • graphiti_core/search/search_utils.py
  • tests/test_graphiti_int.py

本文档涵盖了 Graphiti 混合搜索系统的配置与调优。它详细介绍了 SearchConfig 类层次结构、可用的搜索方法、重排序策略以及用于优化搜索性能的调优参数。有关搜索过滤器和时间查询的信息，请参阅 SearchFilters 和 Temporal Queries。有关搜索系统的架构总览，请参阅 搜索与检索系统。

SearchConfig 架构

搜索系统使用分层配置模型，其中顶层 SearchConfig 包含针对边、节点、片段和社区的实体特定配置。每个实体类型都可以独立配置，拥有自己的搜索方法和重排序策略。

配置类层次结构
graph TB
    SearchConfig["SearchConfig<br/>主配置容器"]

    EdgeSearchConfig["EdgeSearchConfig<br/>边特定搜索"]
    NodeSearchConfig["NodeSearchConfig<br/>节点特定搜索"]
    EpisodeSearchConfig["EpisodeSearchConfig<br/>片段特定搜索"]
    CommunitySearchConfig["CommunitySearchConfig<br/>社区特定搜索"]

    EdgeSearchMethod["EdgeSearchMethod<br/>bm25, cosine_similarity, bfs"]
    NodeSearchMethod["NodeSearchMethod<br/>bm25, cosine_similarity, bfs"]
    EpisodeSearchMethod["EpisodeSearchMethod<br/>bm25"]
    CommunitySearchMethod["CommunitySearchMethod<br/>bm25, cosine_similarity"]

    EdgeReranker["EdgeReranker<br/>rrf, node_distance, episode_mentions, mmr, cross_encoder"]
    NodeReranker["NodeReranker<br/>rrf, node_distance, episode_mentions, mmr, cross_encoder"]
    EpisodeReranker["EpisodeReranker<br/>rrf, cross_encoder"]
    CommunityReranker["CommunityReranker<br/>rrf, mmr, cross_encoder"]

    SearchConfig --> EdgeSearchConfig
    SearchConfig --> NodeSearchConfig
    SearchConfig --> EpisodeSearchConfig
    SearchConfig --> CommunitySearchConfig

    EdgeSearchConfig --> EdgeSearchMethod
    EdgeSearchConfig --> EdgeReranker

    NodeSearchConfig --> NodeSearchMethod
    NodeSearchConfig --> NodeReranker

    EpisodeSearchConfig --> EpisodeSearchMethod
    EpisodeSearchConfig --> EpisodeReranker

    CommunitySearchConfig --> CommunitySearchMethod
    CommunitySearchConfig --> CommunityReranker

来源： graphiti_core/search/search_config.py:32-78, graphiti_core/search/search_config.py:112-119

SearchConfig 类结构

SearchConfig 类是主要的配置容器：

字段类型默认值描述
edge_config`EdgeSearchConfig \None`None边搜索的配置
node_config`NodeSearchConfig \None`None节点搜索的配置
episode_config`EpisodeSearchConfig \None`None片段搜索的配置
community_config`CommunitySearchConfig \None`None社区搜索的配置
limitint10每个实体类型的最大结果数。由 DEFAULT_SEARCH_LIMIT 定义 graphiti_core/search/search_config.py:29。
reranker_min_scorefloat0重排序器输出的最低分数阈值

将实体配置设置为 None 会禁用该实体类型的搜索。位于 graphiti_core/search/search.py:98-108 的 search 函数会检查这些配置。它会评估哪些搜索范围（边、节点、片段或社区）已启用，并使用 semaphore_gather 并行执行它们 graphiti_core/search/search.py:173-222。

来源： graphiti_core/search/search_config.py:112-119, graphiti_core/search/search.py:156-222, graphiti_core/search/search_config.py:29

实体特定配置类

每个实体类型都有自己的配置类，用于指定搜索方法和重排序行为。

EdgeSearchConfig

定义于 graphiti_core/search/search_config.py:80-86，此类配置对表示事实和关系的 EntityEdge 对象的搜索：

字段类型默认值描述
search_methodslist[EdgeSearchMethod]必需要组合的搜索方法列表
rerankerEdgeRerankerEdgeReranker.rrf重排序策略
sim_min_scorefloat0.6余弦搜索的最低相似度分数。由 DEFAULT_MIN_SCORE 定义 graphiti_core/search/search_utils.py:65。
mmr_lambdafloat0.5MMR 多样性参数（0=最大多样性，1=最大相关性）。由 DEFAULT_MMR_LAMBDA 定义 graphiti_core/search/search_utils.py:66。
bfs_max_depthint3BFS 的最大图遍历深度。由 MAX_SEARCH_DEPTH 定义 graphiti_core/search/search_utils.py:67。
NodeSearchConfig

定义于 graphiti_core/search/search_config.py:88-94，此类配置对表示实体的 EntityNode 对象的搜索。它与 EdgeSearchConfig 共享相似的参数，但应用于节点名称和摘要索引。

EpisodeSearchConfig

定义于 graphiti_core/search/search_config.py:96-102，此类配置对 EpisodicNode 对象的搜索。片段目前仅支持 EpisodeSearchMethod.bm25 graphiti_core/search/search_config.py:44-45。

CommunitySearchConfig

定义于 graphiti_core/search/search_config.py:104-110，此类配置对表示实体集群的 CommunityNode 对象的搜索。它同时支持 BM25 和余弦相似度搜索方法。

来源： graphiti_core/search/search_config.py:80-110, graphiti_core/search/search_config.py:44-45, graphiti_core/search/search_utils.py:65-67

搜索方法

搜索方法会并行组合，其结果由重排序器合并。

按实体划分的搜索方法类型
graph LR
    subgraph "边搜索方法"
        EdgeBM25["EdgeSearchMethod.bm25<br/>Lucene 全文搜索"]
        EdgeVector["EdgeSearchMethod.cosine_similarity<br/>基于 fact_embedding 的向量相似度"]
        EdgeBFS["EdgeSearchMethod.breadth_first_search<br/>从原始节点开始的图遍历"]
    end

    subgraph "节点搜索方法"
        NodeBM25["NodeSearchMethod.bm25<br/>Lucene 全文搜索"]
        NodeVector["NodeSearchMethod.cosine_similarity<br/>基于 name_embedding 的向量相似度"]
        NodeBFS["NodeSearchMethod.breadth_first_search<br/>从原始节点开始的图遍历"]
    end

    subgraph "片段搜索方法"
        EpisodeBM25["EpisodeSearchMethod.bm25<br/>Lucene 全文搜索"]
    end

    subgraph "社区搜索方法"
        CommunityBM25["CommunitySearchMethod.bm25<br/>Lucene 全文搜索"]
        CommunityVector["CommunitySearchMethod.cosine_similarity<br/>基于 name_embedding 的向量相似度"]
    end

来源： graphiti_core/search/search_config.py:32-51

BM25 全文搜索

BM25 使用数据库的全文索引进行基于关键词的检索。位于 graphiti_core/search/search_utils.py:85-113 的 fulltext_query 辅助函数处理特定于提供商的语法：

  • Kuzu：简单的查询字符串 graphiti_core/search/search_utils.py:88-92。
  • FalkorDB：使用 driver.build_fulltext_query graphiti_core/search/search_utils.py:93-94。
  • Neo4j：带有 group_id 过滤的 Lucene 语法 graphiti_core/search/search_utils.py:95-111。
余弦相似度搜索

余弦相似度计算查询嵌入向量与存储嵌入向量之间的向量距离。系统使用 numpy 通过 calculate_cosine_similarity 计算此值 graphiti_core/search/search_utils.py:71-82。 位于 graphiti_core/search/search.py:137-152 的搜索函数会自动触发通过 EmbedderClient 进行的查询嵌入向量生成，前提是 SearchConfig 中请求了任何相似度搜索方法或 MMR 重排序器。

BFS 图遍历

广度优先搜索从原始节点开始遍历图。

  • 边 BFS：实现于 edge_bfs_search graphiti_core/search/search_utils.py:52。
  • 节点 BFS：实现于 node_bfs_search graphiti_core/search/search_utils.py:61。

来源： graphiti_core/search/search_utils.py:85-113, graphiti_core/search/search.py:137-152, graphiti_core/search/search_utils.py:52, graphiti_core/search/search_utils.py:61

重排序策略

重排序器会合并来自多个搜索方法的结果并重新评分。

倒数排名融合（RRF）

RRF 是所有实体类型的默认重排序器。它使用基于排名位置的倒数分数来合并来自多个搜索方法的排名。实现位于 graphiti_core/search/search_utils.py:65 的 rrf 中。

最大边际相关性（MMR）

MMR 平衡相关性和多样性。mmr_lambda 参数（默认值为 0.5）控制权衡。实现位于 graphiti_core/search/search_utils.py:60 的 maximal_marginal_relevance 中。它用于边、节点和社区 graphiti_core/search/search_config.py:57, 65, 76。

交叉编码器

使用通过 CrossEncoderClient graphiti_core/cross_encoder/client.py:24 的神经模型直接对查询-文档对进行评分，以获得高精度。

  • 片段：对查询与片段内容进行评分。
  • 边/节点：对查询与事实或名称进行评分。
节点距离和片段提及
  • 节点距离：根据与 center_node_uuid 的图距离对结果进行重排序。实现位于 node_distance_reranker graphiti_core/search/search_utils.py:62。
  • 片段提及：根据实体或边在特定片段中被提及的频率对其进行重排序。实现位于 episode_mentions_reranker graphiti_core/search/search_utils.py:56。

来源： graphiti_core/search/search_utils.py:60-65, graphiti_core/search/search_config.py:57-76, graphiti_core/cross_encoder/client.py:24, graphiti_core/search/search_utils.py:62, graphiti_core/search/search_utils.py:56

调优参数

参数默认值位置效果
limit10graphiti_core/search/search_config.py:29每个实体类型的最终结果数量。
sim_min_score0.6graphiti_core/search/search_utils.py:65向量相似度的最低阈值。
mmr_lambda0.5graphiti_core/search/search_utils.py:66多样性（0）与相关性（1）的权衡。
bfs_max_depth3graphiti_core/search/search_utils.py:67BFS 搜索的最大遍历跳数。
MAX_QUERY_LENGTH128graphiti_core/search/search_utils.py:68全文查询的最大 Token 长度。

来源： graphiti_core/search/search_config.py:29, graphiti_core/search/search_utils.py:65-68

预构建配置配方

search_config_recipes.py 文件为常见用例提供了经过测试的配置。

  • COMBINED_HYBRID_SEARCH_RRF：使用 RRF 对所有实体类型进行标准混合搜索 graphiti_core/search/search_config_recipes.py:34-53。
  • COMBINED_HYBRID_SEARCH_CROSS_ENCODER：使用 BM25、余弦和 BFS 以及交叉编码器重排序的高精度配置 graphiti_core/search/search_config_recipes.py:81-108。
  • EDGE_HYBRID_SEARCH_NODE_DISTANCE：根据与特定节点的接近程度对边事实进行重排序 graphiti_core/search/search_config_recipes.py:127-132。
  • NODE_HYBRID_SEARCH_RRF：使用 RRF 重排序对节点执行混合搜索 graphiti_core/search/search_config_recipes.py:156-161。此配方在播客示例中用于搜索节点 examples/podcast/podcast_runner.py:182-186。

来源： graphiti_core/search/search_config_recipes.py:34-132, graphiti_core/search/search_config_recipes.py:156-161, examples/podcast/podcast_runner.py:182-186

性能与数据流

搜索管线流程
flowchart TB
    subgraph "自然语言空间"
        Query["用户查询字符串"]
        QueryVector["查询向量<br/>(search.py:145-149)"]
    end

    subgraph "代码实体空间"
        BM25["fulltext_query()<br/>BM25 索引<br/>(search_utils.py)"]
        Sim["node_similarity_search()<br/>向量索引<br/>(search_utils.py)"]
        BFS["node_bfs_search()<br/>图遍历<br/>(search_utils.py)"]
    end

    subgraph "重排序逻辑"
        RRF["rrf()<br/>(search_utils.py)"]
        MMR["maximal_marginal_relevance()<br/>(search_utils.py)"]
        CE["CrossEncoderClient.rank()<br/>(cross_encoder/client.py)"]
    end

    Query --> QueryVector
    QueryVector --> Sim
    Query --> BM25

    BM25 --> RRF
    Sim --> RRF
    BFS --> RRF

    RRF --> Results["SearchResults<br/>(search_config.py:121)"]

可以使用 search_results_to_context_string graphiti_core/search/search_helpers.py:27-72 将搜索结果格式化为供大语言模型（LLM）提示使用的上下文字符串。此辅助函数会将 EntityEdge、EntityNode、EpisodicNode 和 CommunityNode 对象转换为结构化的 XML 块，例如 <FACTS>、<ENTITIES>、<EPISODES> 和 <COMMUNITIES> graphiti_core/search/search_helpers.py:53-69。to_prompt_json 工具 graphiti_core/prompts/prompt_helpers.py:23-40 用于将数据序列化为适合提示的 JSON 格式。

来源： graphiti_core/search/search.py:145-149, graphiti_core/search/search_config.py:121, graphiti_core/search/search_helpers.py:27-72, graphiti_core/search/search_helpers.py:53-69, graphiti_core/prompts/prompt_helpers.py:23-40