GraphRAG Local Search局部搜索完全指南基于实体的知识图谱推理与源码级解析【免费下载链接】graphragA modular graph-based Retrieval-Augmented Generation (RAG) system项目地址: https://gitcode.com/GitHub_Trending/gr/graphrag本指南系统讲解 GraphRAG 查询引擎中的 Local Search局部搜索方法——一种以知识图谱实体为核心入口、融合结构化图数据与原始文档文本块来回答问题的实体级检索生成方案。读者将掌握 Local Search 的完整方法论与数据流、LocalSearch与LocalSearchMixedContext的全部可调参数及默认值、内置 prompt 的引用规范并能够结合源码在已完成索引的 GraphRAG 数据上独立实现与调优一个局部搜索引擎。Local Search 是什么基于实体的推理Entity-based ReasoningLocal Search 是 GraphRAG 查询引擎Query Engine提供的检索方式之一它在查询时将知识图谱中的结构化数据与输入文档中的非结构化数据相结合为 LLM 上下文补充与问题相关的实体信息。它尤其适合回答需要对输入文档中具体提到的某个或某几个实体有深入理解的问题例如“甘菊chamomile有哪些治疗功效”这类问题关心的是特定实体的属性、关联关系与证据来源。与 Global Search面向整库的社区报告 map-reduce 摘要和 DRIFT Search结合社区洞察的扩展版局部搜索不同Local Search 的出发点是「把用户问题映射到一小批实体」再以这些实体为图上的入口向下挖掘细节因此计算开销相对可控回答颗粒度更细、证据更贴近原文。GraphRAG 还内置了一版基础的向量检索Basic Search用于对照便于开发者根据问题类型比较不同检索策略的输出差异参见 Query Engine 总览。Methodology从查询到答案的完整数据流Local Search 的整体数据流可以概括为「实体映射 → 多路候选召回 → 排序过滤 → 单上下文窗口组装 → LLM 生成」。官方文档给出的数据流图如下结合源码实现该流程图对应的实际步骤为输入组装给定用户查询query与可选的对话历史conversation_history。若存在对话历史Local Search 会先取出最近若干轮的用户提问由conversation_history_max_turns控制拼接在当前查询之后一起参与实体映射从而把上下文中的指代带入本次检索。见 mixed_context.py。查询到实体的语义映射用文本嵌入模型将「拼接后的查询」编码在与索引阶段生成的entity description embedding向量库中做相似度检索映射出语义相关的实体集合selected_entities。映射逻辑map_query_to_entities位于 entity_extraction.py。多路候选召回与排序过滤以上述实体为图入口通过「实体—文本单元」「实体—社区报告」「实体—实体关系」「实体—协变量」等多条映射召回五类候选数据再分别按相关性打分、截断Prioritized Text Units候选原始文本块先按所属实体的命中顺序、再按块内关系数量降序排列后装入上下文mixed_context.pyPrioritized Community Reports把命中实体按「关联实体命中数」与社区rank双重排序后选取的社区报告同上文件 L224-L304Prioritized Entities / Relationships / Covariates由_build_local_context逐步把实体及其关系、协变量累加进上下文直到 token 预算耗尽同上文件 L377-L493。组装上下文将「实体上下文 关系/协变量上下文 社区上下文 文本单元上下文 会话历史」拼接成一个字符串context_chunks并保证其总 token 数不超出预设的单上下文窗口预算。生成答案把拼接结果作为数据表塞进 system prompt 的{context_data}槽位与用户问题一起送入 LLM生成带引用标注的回答。整个过程源码位于 search.py 的LocalSearch.search()第 24 步全部收敛在context_builder.build_context()一次调用内完成。上下文预算机制三类数据的占比分配Local Search 的上下文预算分配是其核心工程细节直接在LocalSearchMixedContext.build_context()中实现三个比例参数共同约束上下文community_prop社区报告占比、text_unit_prop文本单元占比其余local_prop 1 - community_prop - text_unit_prop留给实体/关系/协变量mixed_context.py。约束条件community_prop text_unit_prop必须 ≤ 1否则build_context会直接抛出ValueError提示 The sum of community_prop and text_unit_prop should not exceed 1.。因此真正进入 context 的还有「local」这一隐藏通道这是 DRIFT 等场景调参时最容易踩坑的点。每个通道的实际 token 预算为int(max_context_tokens * prop)其中max_context_tokens是单个上下文窗口的总体上限。例如默认community_prop0.15、text_unit_prop0.5时约 65% 的窗口预算会留给原始文本单元15% 留给社区报告剩余约 35% 用于实体—关系—协变量而完整的窗口还包含会话历史占用的空间——会话历史上下文会先从max_context_tokens中扣除见 mixed_context.py。若return_candidate_contextTruecontext builder 会额外返回所有候选记录不限于被选入窗口的并为每条记录附加in_context布尔标记方便事后分析哪些数据被真正送入了 prompt——这是开发者在做召回质量评估时的有力工具。LocalSearch 类配置参数详解官方文档给出LocalSearch的核心参数清单对照当前仓库 search.py 的实现逐一说明如下参数说明仓库默认值 / 依据model用于生成回答的 LLM chat completion 对象必填类型为LLMCompletiongraphrag_llm.completion中定义由工厂方法创建context_builder负责从知识模型对象集合中准备上下文数据的对象必填类型为LocalContextBuilderLocal Search 的标准实现是LocalSearchMixedContexttokenizer用于 token 计数的分词器可选默认取model.tokenizer见 base.pysystem_prompt生成回答所用的 prompt 模板可选缺省使用 local_search_system_prompt.py 中的LOCAL_SEARCH_SYSTEM_PROMPTresponse_type期望回答类型与格式的自由文本描述缺省为multiple paragraphs官方建议示例Multiple Paragraphs、Multi-Page Reportmodel_params传给 LLM 调用的额外参数temperature、max_tokens 等可选 dict最终以**self.model_params展开传给completion_async。注意官方文档写作llm_params但当前仓库__init__中实际参数名为model_params二者语义一致对接时以源码签名为准context_builder_params传给context_builder.build_context()的额外参数字典可选 dict见下文「核心参数与默认值」一节callbacks可选回调函数集合用于自定义 LLM 流式输出的on_llm_new_token等事件处理可选可为空列表核心context_builder_params与默认值上下文构建的绝大多数调优点都通过context_builder_params传入。下表汇总了参数、作用与当前仓库使用的默认配置工厂方法在 factory.py 中的实际接线也即LocalSearchConfig各字段的落地位置参数作用默认值max_context_tokens单个上下文窗口的最大 token 数应结合所选模型的上下文上限设定如 8k 模型建议设为约 500012_000text_unit_prop文本单元在窗口中的占比0.5community_prop社区报告在窗口中的占比与text_unit_prop之和必须 ≤ 10.15conversation_history_max_turns参与检索/生成的对话历史最大轮数5conversation_history_user_turns_only仅取用户提问轮作为对话历史上下文True工厂固定传入top_k_mapped_entities映射出的候选实体数量上限映射时先按oversample_scaler2超采样再精选去重10top_k_relationships每个实体可纳入的关系数量上限10include_entity_rank是否在实体表输出中附带 rank工厂设为Trueinclude_relationship_weight是否在关系表输出中附带权重工厂设为Trueinclude_community_rank是否在社区报告输出中附带 rank工厂设为Falsereturn_candidate_context是否返回全部候选数据并附in_context标记Falseembedding_vectorstore_key实体向量库的 key 类型EntityVectorStoreKey.ID或.TITLE取决于向量库以实体 id 还是 title 为键EntityVectorStoreKey.ID关于response_type它不会改变检索流程而是被直接写入 system prompt 的---Target response length and format---槽位见 search.py因此你可以在不改 prompt 的情况下通过它精确控制输出的篇幅与体裁。settings.yaml 中的 Local Search 配置与默认值在使用 CLI 或配置文件驱动查询时以上参数通过配置文件的local_search段暴露。LocalSearchConfiglocal_search_config.py定义了以下可配置字段其默认值集中定义在 defaults.py 的LocalSearchDefaults中settings.yaml 字段说明默认值prompt自定义 local search prompt覆盖内置模板Nonecompletion_model_id用于生成回答的模型 ID指向 models 段中的配置DEFAULT_COMPLETION_MODEL_IDembedding_model_id用于实体/查询嵌入的模型 ID需与索引阶段使用的嵌入模型保持一致DEFAULT_EMBEDDING_MODEL_IDtext_unit_prop文本单元占比0.5community_prop社区报告占比0.15conversation_history_max_turns对话历史最大轮数5top_k_entities映射出的 top-k 实体数10top_k_relationshipstop-k 关系数10max_context_tokens上下文窗口 token 上限12_000示例如下字段均可省略省略时使用上表默认值local_search: prompt: # 留空使用内置 LOCAL_SEARCH_SYSTEM_PROMPT text_unit_prop: 0.5 community_prop: 0.15 top_k_entities: 10 top_k_relationships: 10 max_context_tokens: 12000对配置文件的整体结构与加载方式感兴趣的读者可进一步参考 Query 配置说明 与 models.md。运行时调用链与流式接口从源码看一次 Local Search 的完整调用链为LocalSearch.search(query, conversation_history, ...) └─ context_builder.build_context(...) # LocalSearchMixedContext纯检索侧 ├─ map_query_to_entities(...) # 实体映射含嵌入检索 ├─ conversation_history.build_context() # 会话历史占用 token 计算 ├─ _build_community_context() # 社区报告通道 ├─ _build_local_context() # 实体/关系/协变量通道 └─ _build_text_unit_context() # 原始文本块通道 └─ system_prompt.format(context_data..., response_type...) # prompt 组装 └─ model.completion_async(messages, streamTrue, **model_params) # LLM 生成 └─ 汇总为 SearchResult含 token / 耗时 / 调用次数统计LocalSearch.search()返回的是SearchResult定义于 base.py除response外还携带结构化指标completion_time、总llm_calls、prompt_tokens、output_tokens以及按阶段拆分的llm_calls_categories/prompt_tokens_categories/output_tokens_categories——其中build_context阶段与response阶段的 token 消耗被分别记录方便你精确核算「上下文构建开销」与「生成开销」异常时也会返回一条response的统计型SearchResult而非直接中断。LocalSearch还实现了stream_search()search.py通过 async generator 逐 token 产出文本便于做打字机式流式输出配合callbacks中的on_llm_new_token/on_context钩子可以构建自定义事件处理如打印中间上下文。内置 System Prompt 与数据引用规范默认的LOCAL_SEARCH_SYSTEM_PROMPTlocal_search_system_prompt.py为模型设定了三条重要行为准则只基于输入数据表作答不知道就直说禁止编造每条陈述必须附带数据引用格式为[Data: dataset name (record ids); ...]例如[Data: Sources (15, 16), Reports (1), Entities (5, 7); Relationships (23); Claims (2, 7, 34, 46, 64, more)]其中 id 是数据记录的真实 id而非下标单条引用最多列 5 个记录 id超出部分用more表示避免引用过长撑爆输出。模板中的{response_type}与{context_data}两个槽位分别由构造函数参数与build_context()结果填充数据表以多段文本Sources、Reports、Entities、Relationships、Claims 等命名拼接而成这些命名与mixed_context.py中的context_name如Sources、Reports一一对应。若你的业务需要自定义引用格式或输出风格可通过LocalSearchConfig.prompt或get_local_search_engine(system_prompt...)整体替换。How to Use如何在代码中运行 Local Search方式一官方 Notebook 逐行体验GraphRAG 提供了完整可运行的示例 Notebooklocal_search.ipynb其中同时演示了 Local Search 的上下文构建与问答。其输入数据operation dulce数据集与 Lancedb/Parquet 索引产物均位于 examples_notebooks/inputs 目录便于直接对照索引输出理解各数据表来源。相关配套代码可参考 api_overview.ipynb 与 local_search.ipynb 中查询引擎的初始化部分。方式二通过工厂方法编程接入在高阶 API 中仓库提供了统一的引擎工厂 factory.pyfrom graphrag.query.factory import get_local_search_engine engine get_local_search_engine( configconfig, # GraphRagConfig含 local_search / models 段 reportsreports, # list[CommunityReport] text_unitstext_units, # list[TextUnit] entitiesentities, # list[Entity] relationshipsrelationships, # list[Relationship] covariatescovariates, # dict[str, list[Covariate]] response_typeMultiple Paragraphs, description_embedding_storeembedding_store, # 实体描述嵌入向量库 system_promptNone, # 留空使用内置模板 ) result await engine.search(What are the healing properties of chamomile?) print(result.response)工厂内部按config.local_search段自动完成根据completion_model_id/embedding_model_id创建 LLM 与嵌入模型、从model_settings.call_args提取model_params、实例化LocalSearchMixedContext并把各配置项组装成context_builder_params。前置条件是数据entities、relationships、community reports、text_units、covariates已从索引中读出、且 entity description embedding 向量库已就绪——这部分在 Query Engine 中由query.indexer_adapters与各类 input retrieval 模块负责参见 query/indexer_adapters.py这也是为何 Local Search 只能运行在已完成 GraphRAG 索引的数据之上。API 层的用法可参考 query.py。从源码看 Local Search 的适用边界与调优建议结合 local_search.md 与源码实现可总结出如下工程要点适用场景定位Local Search 面向「理解特定实体」型问题。若问题需要纵观全局如这些数据中最显著的主题是什么应改用 Global Search若希望在局部搜索基础上引入社区洞察以扩大事实覆盖广度应评估 DRIFT Search——后者内部正是复用LocalSearchMixedContext来初始化局部上下文见 drift_context.py。连 Question Generation问题生成也复用同一套上下文构建机制来生成候选追问见 question_gen/local_gen.py三者的检索底座是相通的。实体映射质量决定上限查询到实体的映射依赖「实体描述嵌入」向量库因此检索所用的embedding_model_id必须与索引阶段一致否则会出现语义空间不匹配导致的召回偏差。上下文预算再确认community_prop与text_unit_prop之和不得大于 1三者间的比例直接决定答案是更贴近原文证据提高text_unit_prop还是更高层概括提高community_prop同时务必为会话历史留出 token 空间。与模型窗口对齐max_context_tokens默认12_000使用 8k 等小窗口模型时必须下调源码注释建议约 5000并可通过response_type控制输出长度防止总 token 超限。证据可追溯内置 prompt 强制模型输出[Data: ...]引用且SearchResult中保留了context_records结构化记录与context_text实际进入窗口的文本可用于核对答案的每一条论断是否有据可依。Local Search 是 GraphRAG 知识图谱能力中最贴近实体级问答的检索组件理解其上下文预算模型与参数语义是将其应用于事实密集型问答、可溯源分析等真实业务的前提。【免费下载链接】graphragA modular graph-based Retrieval-Augmented Generation (RAG) system项目地址: https://gitcode.com/GitHub_Trending/gr/graphrag创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考