LightRAG Query Pipeline 核心架构与源码设计分析报告
1. 报告概述
1.1 报告目的
在完成 LightRAG 整体系统架构、Document Index Pipeline、Storage 抽象以及 Query Pipeline 总体流程的分析之后，本阶段开始进入 LightRAG 查询链路的核心源码。
本阶段的目标并不是继续扩大源码阅读范围，也不是逐行阅读 operate.py 等大型文件，而是沿着一条真实 Query 调用链，识别 LightRAG 查询系统中的核心编排函数、检索策略、数据流和抽象边界。
本阶段重点分析以下调用链：
POST /query
↓
QueryParam
↓
aquery_llm()
↓
kg_query()
↓
Keyword Extraction
↓
_build_query_context()
↓
_perform_kg_search()
↓
Local / Global / Mix Retrieval
↓
Token Truncation
↓
Chunk Merge
↓
Context Building
↓
Prompt
↓
Query LLM
↓
QueryResult通过这一阶段的学习，应逐渐具备以下能力：
面对一个陌生 AI 项目
↓
快速找到核心入口
↓
识别编排层与执行层
↓
画出核心数据流
↓
识别关键抽象
↓
发现可替换边界
↓
只深入真正重要的函数这比单纯记住 LightRAG 某个函数位于哪个文件、哪一行更具有长期价值。
2. Query Pipeline 的总体定位
LightRAG 查询过程不能简单理解为：
Question
↓
Vector Search
↓
TopK
↓
LLM更准确的 Query Pipeline 是：
Question
↓
Query Understanding
↓
Retrieval Strategy
↓
Multi-source Retrieval
↓
Candidate Knowledge
↓
Truncation / Merge / Rerank
↓
Context Selection
↓
Prompt Construction
↓
LLM Generation
↓
Answer + References其中，用户输入的自然语言 Question 并不会直接成为所有 Retrieval 模块的最终检索条件。
在 Graph-based RAG 场景下，系统首先需要将自然语言问题转化为更加适合不同知识结构的查询信号。
因此 LightRAG Query Pipeline 中存在几个明显的阶段：
Query Understanding
Retrieval
Candidate Processing
Context Engineering
Generation这是理解后续源码的基础。
3. aquery_llm()：Query Pipeline 的 Strategy Router
查询请求进入 LightRAG Core 后，会经过：
aquery_llm()该函数不应理解为简单的：
调用一次 LLM其核心职责实际上是：
对整个 Query Pipeline 进行入口级编排，并根据
QueryParam.mode选择对应的查询策略。
其整体逻辑可以抽象为：
Question
│
▼
aquery_llm()
│
读取 QueryParam
│
判断 Query Mode
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
naive graph-based bypass
│ │ │
▼ ▼ ▼
naive_query() kg_query() Direct LLM对于不同 Mode：
local
global
hybrid
mix通常进入：
kg_query()而：
naive进入传统 Chunk-oriented Retrieval：
naive_query()bypass 则绕过 Retrieval。
因此可以将 aquery_llm() 定义为：
LightRAG Query Pipeline 的 Strategy Router 和核心编排入口。
它本身不负责实现所有检索算法，而负责决定：
当前 Query
应该交给哪一条 Retrieval Pipeline4. 从架构角度判断函数角色
阅读大型 AI 项目源码时，一个非常重要的问题不是：
这个函数有多少行？而是：
这个函数究竟属于 Orchestration，
还是 Execution？例如：
aquery_llm()明显属于：
Orchestration Layer即：
接收输入
↓
读取配置
↓
选择策略
↓
调用具体执行逻辑
↓
整理结果而真正执行 Entity Retrieval、Relationship Retrieval、Chunk Retrieval 等操作的函数则属于 Execution / Operation Layer。
这种区分对于未来阅读：
RAG Framework
Agent Framework
Workflow Engine
Memory Framework
Context Engineering System都具有普遍意义。
5. kg_query()：Graph-based Query Pipeline 核心编排入口
对于：
local
global
hybrid
mix等 Graph-related Query Mode，核心流程会进入：
kg_query()kg_query() 是本阶段最重要的函数之一。
需要注意：
kg_query()不能简单理解为：
查询一次 Knowledge Graph它实际上负责组织一整套 Graph-based Query Pipeline。
从其主要依赖可以观察到多个核心组件，例如：
query
knowledge_graph_inst
entities_vdb
relationships_vdb
text_chunks_db
chunks_vdb
query_param
global_config
hashing_kv这些参数实际上已经暴露了整个 Query 架构。
6. 从函数参数反推系统架构
大型项目源码阅读中，一个非常值得培养的能力是：
不进入函数实现，仅通过函数签名和依赖对象判断该函数在系统中的位置。
例如：
6.1 knowledge_graph_inst
代表：
Graph Storage主要用于：
Entity
Relationship
Graph Neighborhood
Graph Structure等结构化知识访问。
6.2 entities_vdb
代表：
Entity Vector Storage负责：
Query Signal
↓
Semantic Search
↓
Relevant Entity6.3 relationships_vdb
代表：
Relationship Vector Storage用于根据高层语义搜索相关 Relationship。
6.4 chunks_vdb
代表：
Chunk Vector Storage主要服务于传统文本语义检索。
6.5 text_chunks_db
保存实际 Chunk 内容。
Vector Storage 通常主要负责：
Semantic Index真正的 Chunk Text 可能通过其他 Storage 获取。
6.6 query_param
属于 Query Pipeline 的控制参数。
可以影响：
Query Mode
TopK
Chunk TopK
Rerank
Context Return
Prompt Return
Token Budget等行为。
6.7 global_config
用于向 Query Pipeline 提供系统级能力，例如：
LLM
Embedding
Tokenizer
Model Configuration
其他运行配置7. Storage Abstraction 在 Query Pipeline 中的体现
从 kg_query() 的依赖可以进一步看到 LightRAG 一个重要的工程设计：
Retrieval Logic 并不直接绑定具体数据库。
上层面对的是类似：
Graph Storage
Vector Storage
KV Storage这样的抽象能力。
因此架构更接近：
Query Logic
│
▼
Storage Interface
│
┌────────────┼────────────┐
▼ ▼ ▼
Milvus Qdrant PostgreSQL而不是：
def query():
milvus.search(...)
neo4j.run(...)
postgres.execute(...)将具体基础设施硬编码到算法逻辑中。
这种设计带来的优势包括：
基础设施可以替换
核心 Query Logic 保持稳定
Retrieval Strategy 可以复用
Storage Adapter 可以独立演进
算法逻辑与数据库技术选型解耦这是 LightRAG 中非常值得学习的工程设计思想。
8. kg_query() 的第一阶段：Query Understanding
进入 kg_query() 后，第一个非常关键的操作并不是直接 Retrieval。
而是：
Keyword Extraction典型入口为：
get_keywords_from_query()最终得到两类关键词：
High-Level Keywords
Low-Level Keywords这里体现了一个非常重要的 Query Pipeline 思想：
自然语言 Question 与 Retrieval Query 并不是完全相同的东西。
9. Low-Level Keywords
Low-Level Keywords 更偏向具体对象。
例如用户询问：
Redis 在项目中如何保存 Session？
它和 Lettuce 有什么关系？Low-Level Signal 可以理解为可能包含：
Redis
Session
Lettuce这类关键词通常对应：
Entity
Technical Term
Component
Product
Person
Organization
具体概念因此 Low-Level Keywords 比较适合：
Entity-oriented Retrieval10. High-Level Keywords
High-Level Keywords 更偏向：
主题
概念
意图
关系
问题类型
高层语义例如同样的问题：
Redis 在项目中如何保存 Session？
它和 Lettuce 有什么关系？可以从理解层面形成类似：
Session Management
Connection Mechanism
Component Relationship等高层 Query Signal。
具体内容最终仍由实际 Keyword Model 输出。
其意义在于：
High-Level Keywords
↓
Relationship-oriented Retrieval11. Query Understanding 的本质
因此：
Keyword Extraction并不是单纯：
从句子里挑几个词它在整个 Pipeline 中承担的是：
Natural Language Question
↓
Retrieval-oriented Query Signal这个转换过程。
完整思路可以表示为：
Question
│
▼
Query Analysis
│
┌───────────┴───────────┐
│ │
▼ ▼
Low-Level Signal High-Level Signal
│ │
▼ ▼
Entity Search Relation Search这是成熟 RAG 系统中非常重要的设计。
12. 为什么不能直接进行 Question Embedding？
最简单的 RAG 往往执行：
Question
↓
Embedding
↓
Vector Search这种方式适用于：
Chunk Retrieval但是 LightRAG 同时拥有：
Entity
Relationship
Chunk三种不同的知识形态。
因此不同知识源适合使用不同 Query Signal。
例如：
具体实体名称
↓
Entity Retrieval
主题 / 关系语义
↓
Relationship Retrieval
完整自然语言 Question
↓
Chunk Retrieval因此 LightRAG 首先执行 Query Understanding。
这使整个系统从：
Question → Search升级为：
Question
↓
Understand
↓
Generate Retrieval Signals
↓
Multi-Retrieval13. _perform_kg_search()：Retrieval 执行层
完成关键词分析后，真正 Retrieval 的关键函数之一是：
_perform_kg_search()该函数从系统职责上可以理解为：
执行 Search，产生 Raw Retrieval Candidates。
需要特别注意：
它并不负责：
最终 Token 截断
最终 Context 拼装
最终 Prompt
最终 LLM Answer也就是说：
_perform_kg_search()主要负责：
Search而不是：
Everything After Search这种职责划分非常重要。
14. Local Mode：Entity-oriented Retrieval
对于：
mode = localLightRAG 更偏向使用：
Low-Level Keywords进行 Entity-oriented Retrieval。
其核心路径可以抽象为：
Low-Level Keywords
↓
Entity Vector Search
↓
Relevant Entity
↓
Knowledge Graph
↓
Related Relationships
↓
Local Knowledge关键函数之一为：
_get_node_data()15. _get_node_data() 的核心职责
从架构角度可以将 _get_node_data() 理解为：
Input:
Low-Level Retrieval Signal
↓
Entity Vector Search
↓
Relevant Entity Candidates
↓
Graph Expansion
↓
Related Relationship / Node Data
Output:
Local Graph Knowledge其中非常关键的一点是：
Local Retrieval 并不是直接拿自然语言 Question 去图数据库搜索。
而是首先进行：
Semantic Retrieval16. Local Retrieval 的第一阶段：Entity Vector Search
假设用户输入：
项目里 Redis 用什么客户端连接？实际 Knowledge Graph 中的某个 Entity 可能是：
Lettuce用户可能没有精确输入：
Lettuce因此如果系统只依赖：
entity_name = ?这种精确匹配，Retrieval 会非常脆弱。
LightRAG 可以先执行：
Query Signal
↓
Embedding
↓
Entity Vector Search
↓
Relevant Entity解决：
用户大概在说哪个 Entity？
17. Local Retrieval 的第二阶段：Graph Expansion
找到相关 Entity 后，再进入：
Graph Storage查询：
这个 Entity
与哪些 Entity 有关系？
有哪些 Relationship？因此完整模式为：
Semantic Retrieval
+
Graph Expansion而不是：
Question
↓
Graph Database
↓
Answer这一设计非常重要。
18. Local Mode 的真正含义
因此以后不能只简单记：
Local = Entity Retrieval更准确应该理解为：
Low-Level Query Signal
↓
Entity Semantic Retrieval
↓
Entity Candidates
↓
Graph Neighborhood Expansion
↓
Local Knowledge即：
从与当前问题高度相关的 Entity 作为入口，在 Knowledge Graph 中获取局部相关知识。
19. Global Mode：Relationship-oriented Retrieval
Global Mode 与 Local Mode 在设计上形成了一种近似对称结构。
Local：
Entity
→
Relationship而 Global：
Relationship
→
EntityGlobal Mode 通常使用：
High-Level Keywords进入：
_get_edge_data()20. _get_edge_data() 的核心职责
其整体过程可以抽象为：
High-Level Keywords
↓
Relationship Vector Search
↓
Relevant Relationships
↓
Knowledge Graph
↓
Source Entity
+
Target Entity
↓
Global Knowledge也就是说：
第一阶段：
relationships_vdb.query(...)通过语义搜索找到相关 Relationship。
第二阶段：
根据：
src_id
tgt_id回到 Knowledge Graph 获取关系两端的 Entity。
21. Local 与 Global 的对称结构
最终可以形成下面的架构对比：
| Query Mode | Semantic Retrieval Entry | Graph Expansion |
|---|---|---|
| Local | Entity Vector | Entity → Relationship |
| Global | Relationship Vector | Relationship → Entity |
这个表比简单记忆：
local = entity
global = relation更加准确。
本质上：
Local
=
从具体对象进入 Graph
Global
=
从关系 / 主题进入 Graph22. Hybrid Mode
既然：
Local
=
Low-Level
→
Entity
→
Relationship而：
Global
=
High-Level
→
Relationship
→
Entity那么 Hybrid Mode 就非常容易理解。
其核心思想是：
Question
│
┌─────────┴─────────┐
│ │
▼ ▼
Low-Level High-Level
│ │
▼ ▼
Entity Relation
Retrieval Retrieval
│ │
└─────────┬─────────┘
▼
Merge因此 Hybrid 可以理解为：
同时从 Entity 和 Relationship 两个语义入口进入 Knowledge Graph。
23. Mix Mode
Mix 是 LightRAG Query Pipeline 中尤其值得理解的 Retrieval Strategy。
其基本思想可以表示为：
Hybrid Graph Retrieval
+
Chunk Vector Retrieval即：
Entity Retrieval
+
Relationship Retrieval
+
Chunk Retrieval完整结构为：
Question
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
Low-Level High-Level Raw Query
│ │ │
▼ ▼ ▼
Entity Vector Relation Vector Chunk Vector
│ │ │
▼ ▼ │
Graph Graph │
│ │ │
└──────────────┼──────────────┘
▼
Fusion这就是 Mix Mode 的核心。
24. 为什么 Knowledge Graph 不能替代 Chunk？
这一点对于理解 Mix 非常重要。
假设原始文档中存在：
Lettuce 默认使用 Netty 实现异步非阻塞网络通信，
并提供线程安全的 RedisConnection。经过 Knowledge Extraction 后，可能只形成：
Redis
│
connected_by
│
▼
LettuceKnowledge Graph 非常擅长保存：
Entity
Relationship
Structure但是在知识抽取过程中，可能损失：
具体实现细节
参数
完整描述
上下文
限制条件
代码示例
原始证据这些内容仍然保存在 Chunk 中。
因此：
Knowledge Graph并不能完全替代：
Raw Text25. Mix Mode 的设计思想
所以现代 Graph RAG 更合理的方向不是：
Graph
替代
Vector而是：
Graph
+
Vector
+
TextGraph 更擅长：
结构
关系
连接
知识网络Chunk 更擅长：
细节
完整描述
原始证据
上下文因此 Mix Mode 的本质是：
将结构化知识与原始文本证据同时纳入 Retrieval。
26. _build_query_context()：Query Pipeline 的核心 Context 构造器
完成多路 Retrieval 后，需要进入：
_build_query_context()这是整个 Query Pipeline 中非常值得深入理解的函数。
从架构上，可以将该函数压缩为四个主要阶段：
1. Search
2. Truncate
3. Merge Chunks
4. Build LLM Context也就是：
Search
↓
Candidate Knowledge
Truncate
↓
Selected Knowledge
Merge
↓
Unified Chunks
Build Context
↓
LLM-readable Context27. 第一阶段：Search
Search 阶段负责：
Entity Retrieval
Relationship Retrieval
Chunk Retrieval最终获得大量候选资料。
这部分可以理解为：
Candidate Generation其核心目标是：
尽可能不要漏掉相关知识。
此时数据仍然属于：
Raw Retrieval Candidates而不是最终 Context。
28. Candidate Retrieval 与 Final Context 的区别
这是理解现代 RAG 必须建立的概念。
假设 Search 得到：
50 Entity
80 Relationship
20 Chunk并不意味着：
50 Entity
+
80 Relationship
+
20 Chunk都会进入 Prompt。
必须区分：
Retrieved Candidates和：
Final Context完整流程更接近：
Retrieval
↓
Candidate Knowledge
↓
Rerank
↓
Filter
↓
Deduplicate
↓
Token Budget
↓
Context Selection
↓
Final Context29. 第二阶段：Truncate
Retrieval 结束后，系统需要考虑 Token Budget。
如果不进行控制：
Candidate Knowledge
↓
全部进入 Prompt就可能造成：
Token Cost 上升
Latency 上升
Context Window 被大量占用
噪声增加
模型注意力被分散
真正重要的知识反而被淹没因此系统需要执行：
Token Truncation30. Token Budget
LightRAG 中可以针对不同知识类型设置 Token Budget，例如：
Entity Token Budget
Relationship Token Budget
Total Context Token Budget这意味着系统面对的是：
有限 Context 资源需要决定：
哪些知识最值得占据这些 Token？
这已经不再只是传统意义上的 Prompt Engineering。
更准确属于：
Context Engineering31. 动态 Chunk Token Budget
最终 Chunk 可以使用的 Token 数量也不一定是固定值。
整体思路可以理解为：
Total Context Budget
-
System Prompt Tokens
-
Question Tokens
-
Knowledge Graph Context Tokens
-
Safety Buffer
=
Available Chunk Tokens例如：
总 Budget：12000
System Prompt：1000
Question：200
Entity + Relationship：3000
Buffer：200那么剩余 Chunk Token：
12000
-
1000
-
200
-
3000
-
200
=
7600因此 Chunk Budget 实际上需要和其他 Context 共同协调。
32. 第三阶段：Chunk Merge
Query Pipeline 中的 Chunk 并不一定只来自：
Chunk Vector Search可能还来自：
Entity-related Chunks
Relationship-related Chunks
Vector-retrieved Chunks因此系统需要执行：
_merge_all_chunks()进行统一整合。
33. Multi-source Chunk
例如：
Vector Retrieval
C1
C4
C7Entity Retrieval 关联：
C2
C1
C5Relationship Retrieval 关联：
C3
C2
C8最终需要进行：
Merge
+
Deduplicate形成类似：
C1
C2
C3
C4
C5
C7
C8具体顺序由实际实现策略决定。
34. 为什么必须 Deduplicate？
同一个 Chunk 完全可能同时满足：
Vector Search 命中
Entity 引用了该 Chunk
Relationship 也来源于该 Chunk如果简单拼接：
Vector Chunks
+
Entity Chunks
+
Relation Chunks就可能导致：
同一个 Chunk
重复三次进入 Context造成：
Token 浪费
信息重复
上下文质量下降因此：
Deduplication是 Candidate Processing 中的重要步骤。
35. 第四阶段：Build LLM Context
完成：
Retrieval
Truncation
Merge
Deduplication以后，系统才真正进入：
Context BuildingContext Builder 的职责并不是简单执行：
"\n".join(results)而是需要解决：
Entity 怎么表达？
Relationship 怎么表达？
Chunk 怎么表达？
来源信息怎么保存？
不同来源按照什么顺序排列？
重复信息怎么处理？
Token 如何控制？
哪些信息进入最终 Prompt？因此 Context Builder 实际上承担了 Retrieval 与 Generation 之间非常关键的转换作用。
36. 为什么 Search 不应该负责 Context？
如果整个 Query Pipeline 被写成一个巨大函数：
Search Entity
↓
Search Relation
↓
Search Chunk
↓
Merge
↓
Rerank
↓
Token Truncate
↓
Build Context
↓
Build Prompt
↓
Call LLM系统会非常难维护。
更合理的 Pipeline 是：
Search
↓
Raw Candidates
Candidate Processing
↓
Selected Knowledge
Context Builder
↓
LLM-readable Context
Prompt Builder
↓
Model Input
LLM
↓
Answer这样可以让不同问题分别定位到不同阶段。
37. Pipeline 分层带来的调试能力
例如系统 Answer 不好时：
如果：
相关资料没有召回问题可能在：
Query Analysis
Retriever
Embedding
TopK
Graph Retrieval如果：
资料召回正确
但错误资料排在前面问题可能在：
Fusion
Reranker
Filter如果：
资料都正确
但最终进入 Prompt 的内容不好问题可能在：
Token Budget
Context Selection
Context Builder如果：
Context 已经正确
但 Answer 仍然错误问题才更可能在：
Prompt
LLM
Generation Configuration这种分层会大幅提高 AI 系统的可调试性。
38. only_need_context 的工程价值
LightRAG Query Pipeline 中存在一个非常适合调试 Retrieval 的能力：
only_need_context正常流程：
Question
↓
Retrieval
↓
Context
↓
Prompt
↓
LLM
↓
Answer开启后：
Question
↓
Retrieval
↓
Context
↓
Stop这意味着开发人员可以直接观察：
系统究竟找到了什么资料？而无需受到 LLM 最终生成结果影响。
39. only_need_prompt 的工程价值
同样：
only_need_prompt允许流程停在：
Question
↓
Retrieval
↓
Context
↓
Prompt
↓
Stop可以直接检查：
Context 是如何组织的？
哪些资料进入了 Prompt？
Question 与 Context 如何组合？
System Instruction 是什么？
有没有 Token 截断问题？这种设计非常适合 RAG Debugging。
40. Generation 阶段
只有当：
Context已经构建完成以后，系统才真正进入：
Prompt Construction
↓
Query LLM完整过程可以表示为：
Selected Knowledge
↓
Context
↓
Prompt
↓
Query Model
↓
Answer
↓
QueryResult最终结果可能包含：
Answer
References
Context / Metadata等信息。
因此：
kg_query()整体职责可以最终压缩为：
Question
↓
Query Understanding
↓
Retrieval
↓
Context Building
↓
Prompt
↓
Generation
↓
QueryResult41. Query Pipeline 源码级架构图
经过本阶段分析后，可以将 LightRAG Query Pipeline 表示为：
POST /query
│
▼
aquery_llm()
│
▼
Mode Routing
│
▼
kg_query()
│
▼
get_keywords_from_query()
│
├──────────── Low-Level Keywords
│
└──────────── High-Level Keywords
│
▼
_build_query_context()
│
▼
_perform_kg_search()
│
├──────────────────────────────────────┐
│ │
│ Local │
│ │
│ Low-Level Keywords │
│ ↓ │
│ Entity Vector Search │
│ ↓ │
│ Relevant Entity │
│ ↓ │
│ Graph Relationship Expansion │
│ │
├──────────────────────────────────────┤
│ │
│ Global │
│ │
│ High-Level Keywords │
│ ↓ │
│ Relationship Vector Search │
│ ↓ │
│ Relevant Relationship │
│ ↓ │
│ Source / Target Entity │
│ │
├──────────────────────────────────────┤
│ │
│ Mix │
│ │
│ Local Retrieval │
│ + │
│ Global Retrieval │
│ + │
│ Chunk Vector Retrieval │
│ │
└───────────────────┬──────────────────┘
│
▼
Raw Candidates
│
▼
Token Truncation
│
▼
Chunk Merge
│
▼
Deduplication
│
▼
Context Building
│
▼
Prompt
│
▼
Query Role LLM
│
▼
QueryResult这张图是本阶段最重要的学习成果。
42. 本阶段需要掌握的五个核心函数
现阶段没有必要继续扩展源码阅读范围。
只需要重点认识以下函数。
42.1 kg_query()
职责：
Graph-based Query Pipeline 总编排主要负责：
Query Understanding
↓
Context Retrieval
↓
Prompt
↓
Generation42.2 get_keywords_from_query()
职责：
Natural Language Question
↓
High-Level / Low-Level Retrieval Signal属于：
Query Understanding阶段。
42.3 _perform_kg_search()
职责：
根据 Query Mode 执行不同 Retrieval Strategy主要产生：
Raw Retrieval Candidates属于：
Retrieval阶段。
42.4 _get_node_data()
职责：
Low-Level Keywords
↓
Entity Vector Search
↓
Relevant Entity
↓
Graph Expansion属于：
Local Retrieval阶段。
42.5 _get_edge_data()
职责：
High-Level Keywords
↓
Relationship Vector Search
↓
Relevant Relationship
↓
Graph Entity Expansion属于：
Global Retrieval阶段。
43. 从"源码阅读"提升到"架构阅读"
本阶段真正需要训练的并不是记住：
_get_node_data 在哪一行而是在看到一个函数以后能够快速判断四件事。
第一：输入是什么？
例如：
Query
Keywords
QueryParam
Storage第二：输出是什么？
例如：
Entity Candidates
Relationship Candidates
Chunks
Context
QueryResult第三：属于 Pipeline 哪一步？
例如：
Query Understanding
Retrieval
Candidate Processing
Context Building
Generation第四：依赖哪些抽象？
例如：
BaseVectorStorage
BaseGraphStorage
LLM
Embedding
Reranker
Tokenizer这四个问题是未来阅读其他 AI 项目时可以直接复用的。
44. 陌生 AI 项目的五问分析法
面对一个完全没有见过的 AI 项目，可以优先回答以下五个问题。
44.1 系统入口在哪里？
例如：
HTTP API
CLI
SDK
Queue Consumer
Workflow Trigger44.2 谁负责 Orchestration？
寻找：
哪个类 / 函数负责组织 Pipeline？例如 LightRAG 中：
LightRAG
aquery_llm()
kg_query()都具有明显的编排属性。
44.3 核心数据流是什么？
例如：
Input
↓
Analysis
↓
Retrieval
↓
Context
↓
Generation
↓
Output必须优先画出数据流，而不是优先画目录树。
44.4 核心抽象是什么？
例如：
Storage
Model
Retriever
Reranker
Prompt
Embedding
Tool
Memory观察系统是否：
依赖抽象还是：
依赖具体实现44.5 哪些模块可以替换？
例如：
LLM
Embedding Model
Vector Storage
Graph Storage
Reranker
Chunk Strategy
Prompt
Retrieval Strategy如果一个模块替换后，其余系统仍然能够基本保持稳定，那么这里通常就是一个重要的：
Architecture Boundary45. 本阶段的核心设计思想总结
通过 Query Pipeline 的深入分析，本阶段应重点形成以下认识。
45.1 Query Understanding 与 Retrieval 分离
不是：
Question
↓
Search而是：
Question
↓
Understand
↓
Retrieval Signal
↓
Search45.2 Semantic Retrieval 与 Graph Expansion 结合
Graph Retrieval 不一定直接从 Graph DB 开始。
可能是：
Semantic Search
↓
找到 Graph Entry
↓
Graph Expansion45.3 Multi-Retrieval
现代 Retrieval 可以同时包含：
Entity Retrieval
Relationship Retrieval
Chunk Retrieval而不是单一 Vector Search。
45.4 Graph 与 Text 是互补关系
Graph擅长：
Structure
Relationship
Connection而：
Chunk擅长：
Evidence
Detail
Context
Original Meaning因此两者不应简单互相替代。
45.5 Candidate Retrieval 与 Context Selection 分离
找到了什么不等于：
最终给 LLM 什么中间必须考虑：
Fusion
Rerank
Filter
Deduplication
Token Budget
Context Selection45.6 Context 是一种有限资源
LLM Context Window 应被理解为：
有限计算资源系统需要决定：
哪些知识值得占用 Token？这是 Context Engineering 的核心问题之一。
45.7 Orchestration 与 Algorithm 分离
例如：
aquery_llm()主要负责：
Routing而：
_get_node_data()
_get_edge_data()承担更加具体的 Retrieval 操作。
这种设计有利于：
扩展
调试
替换
测试
维护46. 当前源码阅读任务
本阶段暂时不要继续打开更多文件。
只进入：
lightrag/operate.py依次搜索：
kg_query
get_keywords_from_query
_perform_kg_search
_get_node_data
_get_edge_data对于每个函数，只回答四个问题：
1. 输入是什么？
2. 输出是什么？
3. 属于 Query Pipeline 哪一步？
4. 依赖了哪些核心抽象？例如：
_get_node_data()可以整理为：
输入：
Low-Level Keywords
主要依赖：
Entity Vector Storage
Graph Storage
Pipeline 阶段：
Local Retrieval
职责：
首先通过 Entity Semantic Search 找到与 Query 相关的实体，
然后利用 Knowledge Graph 扩展这些实体周围的关系信息。
输出：
与当前 Query 相关的 Entity Candidates
以及相应的 Graph Relationship 信息。如果能够独立用这种方式解释其他四个函数，则说明已经真正理解这一阶段的 Query Pipeline。
47. 阶段总结
经过本阶段学习，LightRAG Query Pipeline 不应再被理解为一个神秘的：
kg_query()函数。
它实际可以被拆解为：
Question
↓
Query Understanding
↓
High-Level / Low-Level Signal
↓
Multi-Retrieval
↓
Entity / Relationship / Chunk Candidates
↓
Graph Expansion
↓
Fusion
↓
Truncate
↓
Merge
↓
Deduplicate
↓
Context Selection
↓
Prompt
↓
Query LLM
↓
Answer真正需要培养的能力也不是：
"我读过 LightRAG 的 operate.py。"而是：
面对复杂 AI 系统
↓
找到入口
↓
识别 Orchestration
↓
划分 Pipeline
↓
追踪数据流
↓
识别关键抽象
↓
寻找可替换边界
↓
深入少量核心函数这种分析能力能够进一步迁移到：
RAG
Agent
LangGraph
LlamaIndex
Memory System
Tool Calling
MCP
Context Engineering
AI Workflow等其他 AI 应用系统中。
48. 下一阶段学习内容
下一阶段无需继续扩大 LightRAG 的源码阅读范围。
建议继续围绕：
_build_query_context()深入理解其四阶段设计：
Search
↓
Truncate
↓
Merge Chunks
↓
Build Context重点解决以下问题：
为什么 Retrieval Candidate 不能直接进入 Prompt？
Rerank 应该处在 Pipeline 的哪个位置？
多路 Retrieval 结果如何进行 Fusion？
Token Budget 为什么属于 Context Engineering？
Context Builder 怎样决定最终给 LLM 什么？
Retrieval Quality 与 Context Quality 为什么是两个不同问题？这一阶段完成后，学习重点将从：
"LightRAG 如何检索"进一步进入：
"现代 RAG 如何管理 Context"也就是从 Retrieval Architecture 进入真正的 Context Engineering 阶段。