【学习记录】LlamaIndex 核心模块详解：从数据连接到智能代理，构建生产级 RAG 系统

LlamaIndex 是当前最流行的 RAG（检索增强生成）框架之一。它将数据连接、索引、查询和代理等环节抽象为可组合的模块。本文系统梳理了四大核心模块：数据连接器、数据索引、查询引擎、数据代理，并提供大量代码示例、策略对比和最佳实践。读完本文，你就能独立搭建一套完整的 RAG 应用。

---

📌 目录

1. Data Connectors（数据连接器）
2. Data Indexes（数据索引）
3. Engines（查询引擎）
4. Data Agents（数据代理）
5. 总结对照表

---

一、数据连接器（Data Connectors）

1.1 作用

数据连接器负责从各种数据源读取原始数据，并将其转换成 LlamaIndex 能够处理的 Document 对象（包含文本和元数据）。

1.2 支持的数据源及代码示例

数据源类型	说明	示例代码
本地文件	支持 .txt, .pdf, .csv, .md, .json, .docx 等	documents = SimpleDirectoryReader("./data").load_data()
数据库	PostgreSQL, MySQL, SQLite, MongoDB 等	sql_db = SQLDatabase(engine)
Web 爬取	静态网页、Notion、Google Drive、Slack 等	documents = BeautifulSoupWebReader().load_data(urls=[...])
API	任意 REST API	doc = Document(text=response.text)
Llama Hub	官方集成中心，上百种现成加载器	loader = download_loader("GoogleDocsReader")
Llama Cloud	托管式文档解析（擅长复杂 PDF）	parser = LlamaParse(api_key=..., result_type="markdown")

1.3 PDF 解析全流程（深度解析）

挑战	LlamaIndex / LlamaParse 解决方式
OCR 识别图片文字	LlamaParse 云端版自动调用 OCR 引擎；本地可用 PDFReader + pytesseract 组合。
图表提取	解析为 Markdown 表格或结构化文本，保留行列关系。
跨越断行（hyphenation）	自动合并被连字符分割的单词，例如 “inter-\n national” → “international”。
多栏文本	按阅读顺序重组文本，而非简单按坐标切分。
表格跨页	自动拼接跨页表格。

代码示例：

# 本地简单读取
from llama_index.core import SimpleDirectoryReader
documents = SimpleDirectoryReader(input_dir="./data", recursive=True).load_data()

# 使用 LlamaParse 处理复杂 PDF
from llama_parse import LlamaParse
parser = LlamaParse(api_key="your_key", result_type="markdown")
documents = parser.load_data("./paper.pdf")

1.4 图解：数据连接器工作流

原始数据源 (本地文件/数据库/API/Web)
        │
        ▼
  Data Connector
        │
        ▼
   Document 对象列表 (text + metadata)

---

二、数据索引（Data Indexes）

2.1 作用

将 Document 列表转换为可检索的向量索引。核心步骤：文本切分 → 向量化 → 存储到向量数据库。

2.2 Chunk 切分策略（Node Parser）

策略	说明	适用场景
固定长度	按字符或 token 数切分，可设 chunk_overlap	通用，简单高效
段落	按 \n\n 切分	文章、报告
滑动窗口	相邻 chunk 包含重叠内容	防止信息割裂
语义切分	使用嵌入模型计算相邻句子相似度，低相似处切分	技术文档、法律条文
实体关系保留	尽量不切断命名实体（如“机器学习”）	中文、专有名词多的文本

from llama_index.core.node_parser import SimpleNodeParser

parser = SimpleNodeParser.from_defaults(chunk_size=512, chunk_overlap=20)
nodes = parser.get_nodes_from_documents(documents)

2.3 模型设置

LlamaIndex 需要两个模型：

模型类型	作用	配置示例
嵌入模型	将文本块和用户问题转换为向量	Settings.embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-en-v1.5")
大语言模型	生成最终答案	Settings.llm = OpenAI(model="gpt-4", temperature=0)

2.4 向量数据库设置（以 FAISS 为例）

from llama_index.core import VectorStoreIndex, StorageContext
from llama_index.vector_stores.faiss import FaissVectorStore
import faiss

# 创建 FAISS 索引（维度需与嵌入模型一致，如 384）
faiss_index = faiss.IndexFlatL2(384)
vector_store = FaissVectorStore(faiss_index=faiss_index)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# 构建索引
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)

# 创建检索器（只返回节点）
retriever = index.as_retriever(similarity_top_k=3)
nodes = retriever.retrieve("你的问题")
for node in nodes:
    print(node.text[:100], node.score)

# 创建查询引擎（检索+生成）
query_engine = index.as_query_engine()
response = query_engine.query("你的问题")

2.5 图解：索引流程

Document 列表
      │
      ▼ (Node Parser)
   Node 列表 (chunks)
      │
      ▼ (Embedding Model)
   向量 + 原始文本
      │
      ▼ (Vector Store)
   向量数据库 (FAISS/Chroma/Pinecone...)
      │
      ▼
   VectorStoreIndex

---

三、查询引擎（Engines）

3.1 作用

接收用户问题，执行检索，并将检索结果与问题一起提交给 LLM，最终返回答案。

3.2 Query Routing（查询路由）

根据问题类型将请求分发到不同的子引擎。

from llama_index.core.tools import QueryEngineTool
from llama_index.core.query_engine import RouterQueryEngine

tool1 = QueryEngineTool.from_defaults(query_engine=engine1, name="policy", description="公司政策")
tool2 = QueryEngineTool.from_defaults(query_engine=engine2, name="benefits", description="员工福利")
router = RouterQueryEngine.from_defaults(tools=[tool1, tool2])
response = router.query("年假怎么计算？")

3.3 Query Rewriting（查询重写）

将用户原始问题改写成更易于检索的形式。
例如：“它什么时候发布？” → “iPhone 15 发布日期”

3.4 Query Planning（查询规划）

对于多步骤复杂问题，自动拆解并依次查询。
例如：“比较去年和今年的销售额” → 先查去年，再查今年，最后比较。

3.5 自定义回答格式

chat_engine（对话引擎）

支持多轮对话，保持上下文。

chat_engine = index.as_chat_engine()
response = chat_engine.chat("介绍一下自己")
print(response)

# 流式输出
response = chat_engine.stream_chat("那你的优点呢？")
for token in response.response_gen:
    print(token, end="")

summary_index（摘要索引）

对整个文档集合进行摘要生成，而非按片段检索。

from llama_index.core.indices.summary import SummaryIndex

summary_index = SummaryIndex.from_documents(documents)
summary_engine = summary_index.as_query_engine()
summary = summary_engine.query("总结这篇文章")

3.6 图解：查询引擎流程

用户问题
   │
   ▼ (可选: 路由/重写/规划)
   Query Engine
   │         │
   │         ▼ (检索)
   │    相关 Nodes
   │         │
   │         ▼ (LLM 生成)
   │     最终答案
   │
   └─→ 返回用户

---

四、数据代理（Data Agents）

4.1 作用

Agent 是比 Query Engine 更高级的智能体，它可以使用多个工具，并自主决定调用顺序。

4.2 query_engine 作为工具

from llama_index.core.tools import QueryEngineTool, ToolMetadata
from llama_index.core.agent import ReActAgent

tool = QueryEngineTool(
    query_engine=index.as_query_engine(),
    metadata=ToolMetadata(name="search_docs", description="在文档中搜索信息")
)
agent = ReActAgent.from_tools([tool], llm=Settings.llm)
response = agent.chat("总结文档中关于深度学习的部分")

4.3 predict_and_call（自动工具选择）

Agent 可以根据用户需求自动选择并调用合适的工具。例如用户问“今天天气如何，然后发邮件给老板”，Agent 会依次调用天气查询工具和邮件发送工具。

# 假设已定义 weather_tool, email_tool, search_tool
agent = ReActAgent.from_tools([weather_tool, email_tool, search_tool])
agent.chat("今天北京天气怎么样？顺便把这个信息发给 boss@example.com")

4.4 Agent 的工作流程

1. 解析用户意图
2. 规划步骤（选择工具及顺序）
3. 执行工具并获取结果
4. 综合结果并生成最终回答

4.5 图解：Agent 工作流

用户复杂请求
      │
      ▼
   Agent (ReActAgent)
      │
      ├─→ 调用 Tool 1 (如查天气) → 结果
      ├─→ 调用 Tool 2 (如发邮件) → 结果
      │
      ▼
   综合结果 + 生成最终回答

---

五、总结对照表

模块	核心职责	常用类/方法
Data Connectors	从各种源读取数据 → Document	SimpleDirectoryReader, LlamaParse, 各类 Reader
Data Indexes	切分、向量化、存储	NodeParser, Settings.embed_model, VectorStoreIndex, FaissVectorStore
Engines	检索 + 生成答案	as_query_engine(), as_chat_engine(), RouterQueryEngine, SummaryIndex
Data Agents	多工具自主决策	ReActAgent, OpenAIAgent, QueryEngineTool

---

🎯 学习心得

LlamaIndex 的设计哲学是：让 RAG 应用的每个环节都可插拔、可定制。不需要从零搭建 RAG 流水线，只需根据数据源、检索策略、生成模型去替换对应的组件。

• 起步阶段：直接用 SimpleDirectoryReader + VectorStoreIndex + as_query_engine() 就能跑通。
• 优化阶段：调整切分策略（语义切分）、换用更好的嵌入模型、加入路由或重写。
• 进阶阶段：构建 Agent，让系统自主调用多个工具，完成复杂任务。