LightRAG 双层检索如何选择查询模式并验证结果

LightRAG 的查询结果取决于检索模式、实体关系和原始文本的共同作用，不能只看最后一句回答。本文拆解双层检索和常见查询模式，说明如何用同一问题集比较结果、记录证据位置，并区分知识图谱缺失、关键词不匹配和生成阶段的问题。文中只讨论可复现的步骤，不把单次结果扩展成产品承诺；每个结论都标注前提、证据和无法覆盖的边界。读者可以先完成最小验证，再按自己的版本、权限和数据补充实验。

项目地址：HKUDS/LightRAG

上一期我们把 LightRAG 跑起来了。

但只会打开 WebUI，不代表你真的理解它。你问一句“项目 A 的负责人是谁”，它可能很快回答；你问“过去三年这个项目为什么从自研转向采购，以及这个变化影响了哪些团队”，问题马上就变了。

前一个问题偏局部事实，后一个问题需要跨文档、跨实体和跨时间的关系。

LightRAG 的关键不在“多了一个图数据库”，而在它把局部文本召回和图结构召回放在同一套查询参数里。仓库当前支持 naive、local、global、hybrid、mix 五种模式，默认是 mix。

如果你的模型请求通过上游 API 或企业 API 网关进入，还可以把抽取、关键词、最终回答和视觉分析分配给不同的模型与 Key。这样做的目的不是堆模型，而是让不同阶段各自承担合适的成本。

一、为什么普通向量检索会丢关系

假设知识库里有三份文件：

会议纪要：项目 Atlas 于 2024 年由研发部负责
采购合同：2025 年开始由供应商 Beta 提供核心模块
组织调整通知：项目负责人改为产品部的林某

向量检索能找到和“项目 Atlas 负责人是谁”相似的片段，但当问题换成“Atlas 为什么从研发自研变成供应商提供，负责人变化和这件事有什么关系”，相关信息可能被分散在三个文本块里。

如果只是把三个文本块一起塞进上下文，模型还要自己判断：Atlas、核心模块、供应商 Beta、林某之间的关系是什么，时间顺序是什么，哪些句子是事实，哪些句子只是推测。

LightRAG 在索引阶段会从文本中抽取实体和关系，形成类似下面的结构：

项目 Atlas --由研发部负责--> 2024 年
项目 Atlas --核心模块供应商--> Beta
项目 Atlas --负责人--> 林某
组织调整 --生效时间--> 2025 年

这不是一个人工维护的事实数据库。实体名称、关系描述、来源文档和摘要仍然由模型抽取，可能有漏项、合并错误和时间理解错误。所以知识图谱是更好的检索结构，不是自动生成的真相层。

二、LightRAG 的双层检索是什么

可以把它理解成两张互相配合的地图。

第一张地图，文本块和向量

原始文档会被切成若干文本块，文本块进入 Embedding 模型，保存为向量。它擅长找到用词相近、语义相似、能直接支撑回答的原文片段。

这部分对应传统 RAG，naive 模式主要使用它。

第二张地图，实体和关系

LLM 从文本块里抽取实体、关系、描述、关键词和来源 ID。实体会成为图节点，关系会成为图边；实体和关系本身也可以拥有向量，方便通过语义相似度找到候选节点或边。

这部分支撑 local 和 global 模式：前者从具体实体周围展开，后者从关系和更广的主题展开。

查询阶段不是一次搜索

一个完整查询通常包括：

理解问题，生成高低层关键词
  -> 用向量找到候选文本、实体或关系
  -> 按模式组织局部或全局上下文
  -> 可选 rerank 重排文本块
  -> 控制实体、关系、文本块的 token 预算
  -> 交给 QUERY 角色模型生成回答和引用

第一个容易误解的地方是，conversation_history 只用于给最终 LLM 提供对话上下文，仓库文档明确说明它不参与检索。也就是说，上一轮聊天说过什么，不会自动改变本轮召回的实体和关系，除非你把必要信息写进当前查询或关键词。

第二个容易误解的地方是 user_prompt。它主要用于指导召回完成以后如何组织回答，不是用来改变检索问题的。比如让结果用 Mermaid 表达，可以放在用户 Prompt，而不是把“画成 Mermaid”当成检索关键词。

三、五种查询模式怎么选

1. `naive`，传统向量 RAG

它不使用知识图谱，直接从原始文本块做向量相似度检索。

适合：

资料量小、结构简单的问答。
只想验证分块和 Embedding 是否工作。
需要尽量贴近原文的局部答案。

不适合：

跨多份文件追踪关系。
需要概括一个领域的共同主题。
问题里的实体名称和原文表达差异很大。

它是很有价值的基线。很多人一上来只看 mix 的效果，出了问题不知道是图谱抽取错了还是向量召回错了。先用 naive 对照，反而更容易定位。

2. `local`，围绕具体实体查细节

local 聚焦局部上下文和具体实体，检索候选实体及其直接关联的属性。

适合：

“产品 X 支持哪些功能”。
“某个客户的合同金额和服务期限是什么”。
“这篇手册里提到的错误码对应哪个模块”。

它不是“只查一段文本”，而是从实体邻域找相关描述，再结合文本块。实体名称如果被错误拆分或同名合并，local 的结果会直接受到影响。

3. `global`，从主题和关系链看全局

global 关注跨文档主题、宏观关系和更大的语义依赖。

适合：

“这个行业的主要变化是什么”。
“多个团队在过去一年有什么共同问题”。
“项目从自研到采购的决策链条是什么”。

它更像从一张关系地图上寻找主题，而不是找一个具体段落。资料库越大，关系抽取和摘要质量越重要。global 的答案未必包含最多原句，但应该能帮助你看到不同文件之间的连接。

4. `hybrid`，局部和全局一起找

hybrid 合并 local 和 global 的召回结果，同时保留具体实体和宏观关系。

当你既要知道“项目 Atlas 的负责人是谁”，又要知道“这个负责人变化和组织调整之间有没有关系”，hybrid 是更自然的起点。

它适合多数需要结构化理解的问答，但不是所有问题都应该强制使用。简单的原文查找，用 naive 可能更快；单个对象的属性问答，用 local 更容易解释召回来源。

5. `mix`，最全面的默认模式

mix 合并 local、global 和 naive 的结果，目标是提供更全面的上下文。当前 README 将它作为默认查询模式，并说明它通常比 naive 稍慢，其他模式的延迟大体相近。

它适合：

初次探索一个不熟悉的知识库。
问题同时包含事实和跨文档关系。
需要尽量减少单一召回路线漏掉信息的情况。

代价是召回上下文更多，模型输入和重排成本可能增加，答案也可能把不够相关的材料一起带进来。mix 不是“永远质量最高”，而是一个覆盖面更大的默认起点。

四、用 QueryParam 明确控制查询

Core SDK 里通过 QueryParam 控制查询。最小调用：

from lightrag import QueryParam

answer = await rag.aquery(
    "项目 Atlas 为什么改变供应商？",
    param=QueryParam(mode="hybrid"),
)

常用参数可以分为四组：

查询路线

mode，选择五种模式。
top_k，控制主要实体或关系的数量。
chunk_top_k，控制文本块初始召回和 rerank 后保留数量。
hl_keywords，高层关键词。
ll_keywords，低层关键词。

如果高低层关键词为空，系统可以让关键词角色模型生成；你也可以在评测时固定关键词，减少每次测试的变量。

上下文预算

max_entity_tokens，实体上下文预算。
max_relation_tokens，关系上下文预算。
max_total_tokens，整次查询的总上下文预算。

max_total_tokens 不是越大越好。上下文太长会增加 QUERY 模型成本，也可能把真正关键的证据淹没在大量描述里。先根据模型上下文、延迟目标和回答类型设预算，再用数据评测调整。

输出控制

response_type，例如多段、单段或要点。
stream，是否流式输出。
only_need_context，只返回召回上下文。
only_need_prompt，只返回准备发给模型的 Prompt。
user_prompt，指导最终回答形式。
conversation_history，为最终生成提供历史对话。

调试时可以先用 only_need_context，确认召回内容，再打开 only_need_prompt，看模板和上下文是否符合预期，最后才调用 QUERY 模型生成回答。

引用和评测

REST API 的 /query 和 /query/stream 支持 include_references。需要核验召回时，可以打开 include_chunk_content，让引用里带实际文本块。/query/data 始终返回结构化引用，更适合做召回评测、上下文精度检查和自己的回答层。

五、为什么要给不同阶段配不同模型

LightRAG 当前支持四类角色：

角色	主要工作	选择方向
`EXTRACT`	文档插入时抽取实体、关系和摘要	快、稳定、非思考模式，承担大量重复调用
`KEYWORD`	查询前生成高低层关键词	延迟敏感，优先轻量非思考模型
`QUERY`	根据召回上下文写最终回答	质量优先，可使用更强或思考模型
`VLM`	分析文档中的图片、表格或公式	需要真正支持图片输入的模型

把四个角色都接到最贵的模型上，通常是最简单、也最浪费预算的配置。实体关系抽取会在很多文本块上重复发生，EXTRACT 更需要稳定输出而不是长链路推理；KEYWORD 负责缩短查询路径，不应该被慢模型拖住；QUERY 才是最值得投入更强模型的地方。

六、通过上游 API 做角色级模型路由

如果上游 API 或企业 API 网关提供 OpenAI-compatible endpoint，可以先设置一个基础模型，再针对角色覆盖模型、地址或 Key：

LLM_BINDING=openai
LLM_MODEL=<fast-extract-model>
LLM_BINDING_HOST=<provider-openai-compatible-endpoint>
LLM_BINDING_API_KEY=<base-project-key>

EXTRACT_LLM_MODEL=<fast-extract-model>
KEYWORD_LLM_MODEL=<fast-keyword-model>
QUERY_LLM_MODEL=<strong-query-model>
QUERY_MAX_ASYNC_LLM=2

如果某个角色切换到另一个 provider，当前文档要求显式设置该角色的模型和非 Bedrock provider Key，endpoint 也建议明确写出，不要依赖默认地址。

企业环境可以进一步按角色拆 Key：

EXTRACT：高频、低单价、限制并发和每日预算
KEYWORD：低延迟、短请求、限制最大输出
QUERY：允许更强模型，但按项目计费和告警
VLM：只允许需要图像分析的项目使用

上游 API 能看见请求经过哪个模型和项目，但 LightRAG 仍然要根据召回质量判断是不是模型配置合适。模型换了，实体抽取格式、关系合并和最终回答可能都变，不能只比较账单。

七、Rerank 和 Embedding 怎么搭配

Rerank 发生在文本块召回之后，用一个专门的相关性模型重新排序。当前 README 说明，启用 Rerank 往往会增加约 1 到 2 秒延迟，但可能改善查询质量。

建议的验证顺序是：

先固定 Embedding 和查询模式
  -> 记录没有 rerank 的召回和答案
  -> 开启 rerank 重新测试
  -> 比较引用准确率、回答完整性、延迟和费用

不要只看答案更长就判定质量提高。更好的指标是：引用是否真正支持回答，关键实体是否被召回，跨文档关系是否被遗漏，重复内容是否减少。

Embedding 模型一旦用于索引，不要在同一个工作区随便换。Rerank 模型则可以在查询阶段切换，验证成本相对小一些。模型、维度和前缀配置都要记录在项目配置仓库中，避免同一知识库被不同团队用不同语义空间查询。

八、出现“图谱没用”时先这样查

先跑 `naive`

如果 naive 已经找不到关键原文，问题可能在解析、分块或 Embedding，而不是知识图谱。

再看 `local`

如果 naive 能找到，local 找不到，检查实体是否被正确抽取、命名是否一致、实体关系的来源是否存在。

再看 `global`

如果局部问答正常，主题总结很差，检查关系描述、摘要合并、跨文档来源和 max_relation_tokens，不要直接换更大的 QUERY 模型。

最后比较 `mix`

mix 结果变差，可能是不同召回路线把大量弱相关内容混在了一起。先降低 top_k、chunk_top_k 或 token 预算，再看引用是否更集中。

用 `/query/data` 看证据

不要只复制最终答案给团队讨论。/query/data 能返回实体、关系、文本块和引用，适合把“模型说了什么”拆回“系统召回了什么”。这也是建立评测集的起点。

九、安全和能力边界

知识图谱里会保存实体名称、关系描述、来源 ID 和文本引用。企业不能因为这些内容是“检索数据”就忽略原始文件的访问权限。

至少需要区分：

谁可以上传或删除文档。
谁可以查看图谱和原文块。
谁可以调用最终回答接口。
哪些项目可以使用上游 API 的强模型或 VLM。
哪些引用内容可以进入日志、评测集和对外回答。

LightRAG 的图谱抽取不是人工审核系统，引用也不等于事实绝对正确。对合同、财务、医疗和内部制度，最终回答应当回到原文、人工审批或业务系统，不要把模型生成的关系当成授权依据。

十、查询模式验收清单

模式验收

同一个问题至少用 naive、local、global、hybrid、mix 做过对照。
具体实体问题优先检查 local，跨文档主题问题检查 global。
mix 的延迟、上下文长度和费用被单独记录，没有默认当成最优。
only_need_context 或 /query/data 能看到真实召回证据。

模型验收

EXTRACT、KEYWORD、QUERY、VLM 的职责和 Key 已分开记录。
EXTRACT 和 KEYWORD 没有无意义地启用慢速思考模式。
QUERY 模型能处理长而嘈杂的召回上下文。
Embedding 模型、维度、非对称配置和索引时间已记录。
Rerank 的质量收益和 1～2 秒级延迟成本经过实测确认。

安全验收

图谱节点、关系和引用遵循原始文档权限。
上游 API 或其他 API 网关的 Key 没有写入代码和日志。
不把模型抽取结果直接当成合同、财务或合规结论。
查询接口、上下文调试接口和图谱管理接口的访问权限已分开。

总结

LightRAG 的双层检索，可以用一句话记住：

naive 找原文相似片段
local 看具体实体附近的事实
global 看跨文档的主题和关系
hybrid 把局部与全局合在一起
mix 再加上传统向量召回，覆盖面最大

真正的调优顺序不是“换一个更大的模型”，而是先确认分块、实体、关系、Embedding、查询模式和 token 预算分别出了什么问题。

结论

本文给出了问题定位、配置或创作流程的可执行路径。实际结果仍取决于当前版本、权限和运行环境，提交前应按官方文档复核可变字段，并保留失败证据和回滚边界。