LlamaIndex 深度实战:用《长安的荔枝》学会构建智能问答系统

读者导航

大家好!这篇文章兼顾了 RAG 的科普与 LlamaIndex 的实战。无论你处在哪个阶段,都能找到适合自己的阅读路径:

1. 如果你是 RAG 或 AI 新手(👋 欢迎!)

  • 建议从第一部分:原理篇开始。这部分会用一个生动的比喻,帮你建立 RAG 的核心概念,理解 AI 是如何"读书"的。

  • 然后,你可以直接跳到第二部分:实战篇,快速体验用 30 行代码构建一个问答系统的乐趣。

  • 第三部分:优化篇和第四部分:架构篇 可以先收藏,等有概念后再来深入。

2. 如果你熟悉 RAG,想深入 LlamaIndex(🚀 进阶!)

  • 你可以快速浏览第一部分:原理篇,回顾一下核心概念。

  • 第二部分:实战篇值得一看,LlamaIndex 的 API 非常简洁高效。

  • 第三部分:优化篇是本文的精华。我们通过真实实验,展示了 chunk_size 和 top_k 等参数对结果的具体影响,这对于生产环境调优至关重要。

  • 第四部分:架构篇将帮你理解 LlamaIndex 的内部机制,为你的二次开发或深入定制打好基础。

第一部分:原理篇 - AI 如何像人一样"读书"

1.1 一个真实的需求

假设你手上有一本 170 页的小说《长安的荔枝》,你想快速了解:

  • 主角是谁?

  • 故事讲了什么?

  • 荔枝最后是怎么送到长安的?

但你没时间读完整本书。这时候,你会怎么做?

人类的做法:

1.翻到目录,找到相关章节

2.快速浏览这些章节

3.找到关键信息

4.用自己的话总结答案

AI 能不能也这样做呢? 答案是:可以!这就是我们今天要探讨的技术。

1.2 从"搜索"到"理解"

传统搜索的局限

你可能会想:用 Ctrl+F 搜索关键词不就行了?

让我们试试:

搜索"主角" → 可能搜不到(书中可能用"李善德"而不是"主角")搜索"李善德" → 找到 50 处,但哪句话说明他是主角?

问题:传统搜索只能做精确匹配,不能理解语义。

直接问 ChatGPT?

你可能又想:直接问 ChatGPT 不就行了?

问题:

  • ChatGPT 没读过《长安的荔枝》

  • 它可能会"编造"一个答案

  • 无法引用原文,不可追溯

1.3 理想的解决方案

我们需要一个系统,它能:

1."读"过这本书 - 理解书中的内容

2.找到相关段落 - 像人一样快速定位

3.理解并回答 - 用自然语言给出答案

4.可以追溯 - 告诉你答案来自哪里

这就是 RAG(检索增强生成) 系统要做的事情。

1.4 工作原理:三个关键步骤

让我用一个类比来解释:

步骤 1:建立"索引卡片"(Indexing)

想象你在读书时做笔记:

卡片 1:李善德是上林署的监事...卡片 2:他接到了一个艰巨的任务...卡片 3:荔枝必须新鲜送达长安......

AI 的做法:

1.把书切成一段段(比如每段 500 字),这叫 Chunking。

2.为每段生成一个"数字指纹"(向量),这叫 Embedding。

3.把这些"指纹"(向量)和原文(段落)存起来,放入向量数据库。

段落 1 → [0.1, 0.3, -0.2, ...] (1536 个数字)段落 2 → [0.2, -0.1, 0.4, ...]段落 3 → [-0.1, 0.2, 0.1, ...]

这个过程叫做向量化(Embedding)。

步骤 2:找到相关段落(Retrieval)

当你问"主角是谁?"时:

1.AI 把你的问题也转成"数字指纹"

"主角是谁?" → [0.15, 0.25, -0.15, ...]

2.对比所有段落的"指纹",找最相似的

问题指纹 vs 段落1指纹 → 相似度 0.95 ✓问题指纹 vs 段落2指纹 → 相似度 0.60问题指纹 vs 段落3指纹 → 相似度 0.85 ✓

3.挑出最相似的 3-5 段

这个过程叫做语义检索。

步骤 3:生成答案(Generation)

AI 拿到相关段落后:

输入给 AI:---相关段落(上下文):1. 李善德是上林署的监事,从九品下...2. 他在长安城南买了一座宅子...3. 这天,他接到了一个艰巨的任务...
问题:主角是谁?---
AI 输出:主角是李善德。他是上林署的监事,从九品下的官职...

这个过程叫做增强生成。

1.5 关键参数的作用

在这个过程中,有几个重要的"旋钮"可以调节。让我们用《长安的荔枝》中的实际文本来理解它们的作用。

参数 1:段落大小(chunk_size)

类比:做笔记时,每张卡片写多少字?

让我们看看同一段文本在不同 chunk_size 下的效果:

小卡片示例(约 300 字,适合 chunk_size=512):

李善德是上林署的监事,从九品下。他在长安城南买了一座宅子,虽然不大,但也算是有了自己的家。这天早上,他刚到上林署,就被叫到了上司的房间。
"李监事,有个任务交给你。"上司开门见山地说。
"请上司吩咐。"李善德恭敬地回答。
"圣人想吃新鲜荔枝,你去岭南采办,十天内送到长安。"
李善德愣住了。从岭南到长安,路程遥远,荔枝又极易腐烂,这几乎是不可能完成的任务。

大卡片示例(约 600 字,适合 chunk_size=1024):

李善德是上林署的监事,从九品下。他在长安城南买了一座宅子,虽然不大,但也算是有了自己的家。这天早上,他刚到上林署,就被叫到了上司的房间。
"李监事,有个任务交给你。"上司开门见山地说。
"请上司吩咐。"李善德恭敬地回答。
"圣人想吃新鲜荔枝,你去岭南采办,十天内送到长安。"
李善德愣住了。从岭南到长安,路程遥远,荔枝又极易腐烂,这几乎是不可能完成的任务。但他知道,这不是可以拒绝的。
回到自己的小房间,李善德开始思考。荔枝,这种南方的水果,离开树枝后很快就会变色变味。从岭南到长安,即使日夜兼程,也要七八天。如何让荔枝保持新鲜?
他想起了一些传闻:有人用冰窖,有人用蜜浸,还有人用特制的木盒。但这些方法都没有经过验证。更重要的是,他需要计算成本。上林署给的预算有限,每一文钱都要精打细算。
李善德拿出纸笔,开始列清单:采购荔枝的费用、运输工具、人工、沿途驿站的开支……数字越算越大,他的眉头皱得越来越紧。

效果对比:

  • 小卡片:精确定位到"接到任务"这个事件,适合回答"李善德接到了什么任务?"

  • 大卡片:包含任务的来龙去脉和李善德的思考,适合回答"李善德面临什么困难?"

参数 2:检索数量(top_k)

类比:找几张相关的卡片?

假设用户问:"李善德是个怎样的人?"

检索 3 张卡片(top_k=3):

卡片 1: 李善德是上林署的监事,从九品下。他做事谨慎,       从不出错...
卡片 2: 面对上司的质疑,李善德没有辩解,只是默默地       继续工作...
卡片 3: 他知道这个任务几乎不可能完成,但还是决定       尽全力去做...

→ AI 回答:"李善德是个谨慎、踏实、有责任心的人。"

检索 10 张卡片(top_k=10):

(包含上面 3 张,还有:)
卡片 4: 李善德在计算成本时,精确到每一文钱...
卡片 5: 他想起了家乡的荔枝树,那时候他还是个孩子...
卡片 6: 面对老兵的嘲讽,李善德没有生气,反而虚心请教...
卡片 7: 深夜,他还在研究地图,寻找最快的路线...
...

→ AI 回答:"李善德是个谨慎、踏实、有责任心的人。他精于计算, 注重细节,同时也有着温情的一面。面对困难,他不轻言放弃, 而是积极寻找解决方案。他谦逊好学,愿意向他人请教。"

效果对比:

  • top_k=3:快速回答,但信息有限;

  • top_k=10:全面深入,但耗时更长;

参数 3:重叠大小(overlap)

类比:相邻卡片之间重复多少内容?

假设有这样一段文本:

原文:

...李善德想起了一个办法。他曾听说,岭南的果农会用特殊的方法保存荔枝。如果能找到这些果农,或许就能解决保鲜的问题。
第二天一早,李善德就出发了。他先去了市场,打听岭南商人的消息。功夫不负有心人,他终于找到了一个来自岭南的果商...

无重叠切分:

卡片 1: ...李善德想起了一个办法。他曾听说,岭南的果农会用       特殊的方法保存荔枝。如果能找到这些果农,或许就能       解决保鲜的问题。
卡片 2: 第二天一早,李善德就出发了。他先去了市场,打听       岭南商人的消息。功夫不负有心人,他终于找到了一个       来自岭南的果商...

→ 问题:如果用户问"李善德如何解决保鲜问题?",可能只检索到卡片1, 看到"想到办法"但看不到"找到果商"这个关键行动。

有重叠切分(overlap=50字):

卡片 1: ...李善德想起了一个办法。他曾听说,岭南的果农会用       特殊的方法保存荔枝。如果能找到这些果农,或许就能       解决保鲜的问题。
       第二天一早,李善德就出发了。他先去了市场...
卡片 2: ...如果能找到这些果农,或许就能解决保鲜的问题。
       第二天一早,李善德就出发了。他先去了市场,打听       岭南商人的消息。功夫不负有心人,他终于找到了一个       来自岭南的果商...

→ 两张卡片都包含了从"想法"到"行动"的完整过程,无论检索到哪张, 都能给出完整的答案。

效果对比:

  • 无重叠:存储空间小,但可能丢失跨段落的关键信息;

  • 有重叠:占用空间稍大,但保证了信息的连续性和完整性;

参数定义总结

现在让我们用一张表格总结这三个关键参数:

快速记忆:

  • chunk_size:每张卡片写多少字

  • top_k:找几张相关卡片

  • chunk_overlap:相邻卡片重复多少内容

1.6 现在,让我们引入术语

现在你已经理解了原理,让我们用专业术语重新描述一遍:

1.7 小结

核心思想:

1.把文档切成小块,每块生成"数字指纹";

2.问题也生成"指纹",找最相似的块;

3.把相关块和问题一起给 AI,让它生成答案;

关键优势:

✅ 基于你的文档(不会编造)

✅ 语义理解(不只是关键词)

✅ 可以追溯(知道答案来源)

接下来:让我们看看如何用代码实现这个系统!

第二部分:实战篇 - 用 LlamaIndex 实现问答系统

2.1 什么是 LlamaIndex?

在上一部分,我们了解了 RAG(检索增强生成)的通用原理。要将这个原理付诸实践,我们需要一个“框架”来帮我们处理所有繁琐的步骤,比如:加载文档、切割文本、调用 Embedding API、管理向量存储、检索、构建 Prompt、调用 LLM 等。

LlamaIndex 就是这样一个“数据框架”,它专门为“连接大语言模型 (LLM) 与外部数据”而生。

通俗地说,LlamaIndex 就像一个超级“图书管理员”:

  • 你给它一本(或一万本)书(外部数据)。

  • 它会帮你把书拆解、消化、并制作成一套精密的“索引卡片”(索引过程)。

  • 当你提出问题时(查询),它能迅速帮你找到所有相关的“卡片”,并让 LLM 总结成通顺的答案(检索与生成)。

我们接下来要实战的,就是如何使用 LlamaIndex 这个强大的工具,来搭建我们自己的《长安的荔枝》问答系统。

2.2 预期效果

在开始写代码前,先看看我们要实现什么效果:

# 加载《长安的荔枝》loader = DocumentLoader("长安的荔枝.pdf")
# 构建索引(建立"卡片系统")index = VectorStoreIndex.from_documents(documents)
# 开始提问query_engine = index.as_query_engine()
# 问题 1response = query_engine.query("主角是谁?")# 答案:李善德。他是上林署的监事...
# 问题 2response = query_engine.query("故事的主线是什么?")# 答案:故事围绕李善德接到运送荔枝的任务展开...
# 问题 3response = query_engine.query("荔枝最后是怎么送到长安的?")# 答案:通过快速的船运沿着水路,然后陆路运输...

目标:用不到 50 行代码实现这个功能!

2.3 最简代码清单

先看完整代码,有个整体印象:

from llama_index.core import VectorStoreIndex, Settingsfrom llama_index.llms.openai import OpenAIfrom llama_index.embeddings.openai import OpenAIEmbeddingfrom llama_index.readers.file import PyMuPDFReader
# 1. 配置 AI 服务Settings.llm = OpenAI(    model="gpt-3.5-turbo",    api_key="your_api_key")Settings.embed_model = OpenAIEmbedding(    model="text-embedding-3-small",    api_key="your_api_key")
# 2. 加载 PDFreader = PyMuPDFReader()documents = reader.load(file_path="长安的荔枝.pdf")# documents: 170 个 Document 对象,每个代表一页
# 3. 构建索引(这一步会调用 Embedding API)index = VectorStoreIndex.from_documents(documents)# 内部做了:切分 → 向量化 → 存储
# 4. 创建查询引擎query_engine = index.as_query_engine(similarity_top_k=3)# similarity_top_k=3: 检索 3 个最相关的段落
# 5. 提问response = query_engine.query("主角是谁?")# 内部做了:问题向量化 → 检索相似段落 → 调用 LLM 生成答案
print(response.response)

代码量:核心代码不到 30 行!

关键 API:

  • Settings: 全局配置(LLM 和 Embedding)

  • PyMuPDFReader: PDF 读取器

  • VectorStoreIndex: 向量索引(核心)

  • as_query_engine(): 创建查询引擎

  • query(): 提问并获取答案

2.4 核心 API 详解

API 1: Settings - 全局配置

from llama_index.core import Settingsfrom llama_index.llms.openai import OpenAIfrom llama_index.embeddings.openai import OpenAIEmbedding
# 配置 LLM(用于生成答案)Settings.llm = OpenAI(    model="gpt-3.5-turbo",      # 模型名称    temperature=0.1,             # 温度(0=确定性,1=创造性)    api_key="your_key"          # API 密钥)
# 配置 Embedding(用于向量化)Settings.embed_model = OpenAIEmbedding(    model="text-embedding-3-small",  # Embedding 模型    api_key="your_key"               # API 密钥)

作用:

  • Settings.llm: 负责理解问题和生成答案;

  • Settings.embed_model: 负责把文本转成向量;

实际例子:

# Embedding 的工作text = "李善德是上林署的监事"vector = Settings.embed_model.get_text_embedding(text)# vector: [0.123, -0.456, 0.789, ...] (1536 个数字)
# LLM 的工作prompt = "问题:主角是谁?\n答案:"answer = Settings.llm.complete(prompt)# answer: "李善德"

API 2: PyMuPDFReader - PDF 加载

from llama_index.readers.file import PyMuPDFReader
reader = PyMuPDFReader()documents = reader.load(file_path="长安的荔枝.pdf")

输入:PDF 文件路径

输出:List[Document],每个 Document 包含:

Document(    text="第一章\n\n李善德站在...",  # 页面文本    metadata={        "page_label": "1",              # 页码        "file_name": "长安的荔枝.pdf"   # 文件名    })

实际例子:

documents = reader.load("长安的荔枝.pdf")print(f"共 {len(documents)} 页")  # 共 170 页print(documents[0].text[:100])     # 第一页前 100 字# 输出:第一章\n\n李善德站在长安城南的一座宅子门前...

API 3: VectorStoreIndex - 构建索引

from llama_index.core import VectorStoreIndex
index = VectorStoreIndex.from_documents(    documents,           # 文档列表    show_progress=True   # 显示进度条)

内部流程:

1. 文本分块   170 页 → 切分 → 约 500 个 chunks(默认每个 512 tokens)
2. 向量化(调用 Embedding API)   chunk 1: "李善德是..." → [0.1, 0.3, -0.2, ...]   chunk 2: "他接到任务..." → [0.2, -0.1, 0.4, ...]   ...
3. 存储   把 (text, vector) 存到向量数据库

实际例子:

# 默认配置index = VectorStoreIndex.from_documents(documents)# - chunk_size: 512 tokens# - chunk_overlap: 20 tokens# - 约 500 个 chunks
# 自定义配置from llama_index.core.node_parser import SentenceSplitter
Settings.text_splitter = SentenceSplitter(    chunk_size=1024,      # 更大的块    chunk_overlap=128     # 更多重叠)index = VectorStoreIndex.from_documents(documents)# - 约 250 个 chunks

持久化(避免重复构建):

# 首次构建并保存index = VectorStoreIndex.from_documents(documents)index.storage_context.persist(persist_dir="./storage")
# 后续直接加载(快速)from llama_index.core import StorageContext, load_index_from_storage
storage_context = StorageContext.from_defaults(persist_dir="./storage")index = load_index_from_storage(storage_context)

API 4: as_query_engine() - 创建查询引擎

query_engine = index.as_query_engine(    similarity_top_k=3,          # 检索 3 个最相关的 chunks    response_mode="compact"      # 响应模式)

参数说明:

similarity_top_k:检索多少个相关段落

# 检索 3 个query_engine = index.as_query_engine(similarity_top_k=3)# 问"主角是谁?" → 找到 3 个最相关的段落 → 生成答案
# 检索 10 个query_engine = index.as_query_engine(similarity_top_k=10)# 问"故事主线?" → 找到 10 个相关段落 → 综合生成答案

response_mode:如何综合多个段落

# compact: 合并所有段落,一次调用 LLMquery_engine = index.as_query_engine(response_mode="compact")
# refine: 逐步精炼答案(多次调用 LLM)query_engine = index.as_query_engine(response_mode="refine")
# tree_summarize: 树形总结(适合大量段落)query_engine = index.as_query_engine(response_mode="tree_summarize")

API 5: query() - 提问

response = query_engine.query("主角是谁?")

内部流程:

1. 向量化问题   "主角是谁?" → [0.15, 0.25, -0.15, ...]
2. 检索相似段落(top_k=3)   计算相似度 → 找到 3 个最相关的 chunks
3. 构建 Prompt   上下文:chunk1 + chunk2 + chunk3   问题:主角是谁?
4. 调用 LLM   LLM 基于上下文生成答案
5. 返回结果   response.response: "李善德。他是..."   response.source_nodes: [chunk1, chunk2, chunk3]

返回值:

response = query_engine.query("主角是谁?")
# 答案文本print(response.response)# "李善德。他是上林署的监事..."
# 来源段落for i, node in enumerate(response.source_nodes):    print(f"来源 {i+1}:")    print(f"  相似度: {node.score:.3f}")    print(f"  内容: {node.text[:100]}...")

2.5 完整示例:对话式问答

from llama_index.core import VectorStoreIndex, Settingsfrom llama_index.llms.openai import OpenAIfrom llama_index.embeddings.openai import OpenAIEmbeddingfrom llama_index.readers.file import PyMuPDFReader
# 配置Settings.llm = OpenAI(model="gpt-3.5-turbo", api_key="your_key")Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small", api_key="your_key")
# 加载和索引reader = PyMuPDFReader()documents = reader.load("长安的荔枝.pdf")index = VectorStoreIndex.from_documents(documents)
# 创建聊天引擎(支持多轮对话)chat_engine = index.as_chat_engine()
# 多轮对话response1 = chat_engine.chat("这本书的主角是谁?")print(f"AI: {response1.response}")# AI: 主角是李善德...
response2 = chat_engine.chat("他的职位是什么?")print(f"AI: {response2.response}")# AI: 他是上林署的监事...(记得上一轮说的是李善德)
response3 = chat_engine.chat("他遇到了什么困难?")print(f"AI: {response3.response}")# AI: 他接到了运送荔枝的艰巨任务...
# 重置对话chat_engine.reset()

chat_engine vs query_engine:

  • query_engine: 每次独立提问,不记忆上下文;

  • chat_engine: 多轮对话,记住之前的问答;

2.6 小结

核心 API 总结:

代码量:

  • 最简实现:< 30 行

  • 完整功能:< 100 行

接下来:让我们看看不同参数配置的实际效果!

第三部分:优化篇 - 参数调优的实战效果

在开始实验之前,让我们先回顾一下关键参数的定义:

参数速查表

参数之间的关系:

  • chunk_size ↑ → 上下文更完整,但可能包含噪音;

  • chunk_overlap ↑ → 信息连续性更好,但存储空间增加;

  • top_k ↑ → 答案更全面,但耗时和成本增加;

  • temperature ↑ → 答案更有创意,但可能不够准确;

3.1 实验设计思路

为了让你真正理解参数的作用,我们设计了两类实验:

第一类:单参数影响实验(3.2节)

目标:孤立地展示每个参数的独立效果。

  • 实验1:只改变 chunk_size,观察对理解复杂信息的影响;

  • 实验2:只改变 top_k,观察对信息全面性的影响;

  • 实验3:只改变 chunk_overlap,观察对跨段落信息的保护;

第二类:组合参数优化实验(3.3节)

目标:展示在实际场景中如何组合参数。

  • 实验4:简单事实查询 - 展示基础配置的适用性;

  • 实验5:复杂情节理解 - 展示参数优化的价值;

  • 实验6:宏观主题理解 - 展示深度配置的必要性;

所有实验都使用:

  • 《长安的荔枝》全书(170页)

  • 相同的中文 Prompt 模板

  • 真实的 LlamaIndex 输出结果

3.2 单参数影响实验

实验1:chunk_size 的影响

测试问题:李善德在整个故事中的心理变化是怎样的?从开始到结束他的想法有什么转变?

为什么选这个问题:

  • 心理变化是渐进的,分散在全书各处;

  • 小 chunk 只能看到片段,难以把握整体变化;

  • 大 chunk 能够包含更完整的心理描写;

实验配置:

实验结果:

配置A(chunk_size=256)

李善德在整个故事中的心理变化是非常明显的。一开始,他在与赵欣宁的交锋中表现出迷茫和无措,不知如何回应。随后,在苏谅的提议下,他展现出了一种决断和果断的态度,愿意冒险尝试新的商业方式。他在这个阶段表现出了对未来的信心和决心。然而,随着故事的发展,他又陷入了迷茫和犹豫之中,开始怀疑自己的决定和未来的走向。最终,他选择放弃一切,成为一个荔枝老农,过着平静的生活。整个过程中,李善德的心理变化可以总结为迷茫、决断、犹豫和最终的放弃。

⭐⭐ 简短,只提到4个阶段,缺少细节。

配置B(chunk_size=512)

李善德在整个故事中的心理变化是非常明显的。一开始,他在与赵欣宁的交锋中表现出迷茫和无措,不知如何回应。但随着故事的发展,他逐渐展现出果断和决绝的一面。在与苏谅的交流中,他展现出了敢于赌博和冒险的态度,表现出对未来的信心和决心。在与韩承的对话中,他展现出了谄媚和顺从的一面,表现出对权力的敬畏和追求。最后,他选择了隐居种荔枝树,放弃了世俗的权力和利益,展现出了对过去的反思和悔悟。整个故事中,李善德的心理变化可以总结为从迷茫到果断,再到悔悟和放下世俗欲望的过程。

⭐⭐⭐ 增加了"谄媚和顺从"、"反思和悔悟"等细节。

配置C(chunk_size=1024)

李善德在整个故事中的心理变化是非常明显的。一开始,他在与赵欣宁的交锋中表现出迷茫和无奈,不知如何回应对方的挑衅。随着故事的发展,他开始展现出决心和勇气,决定尝试新的商业合作方式,并且毫不犹豫地接受了这个挑战。在接受了试验的过程中,他经历了挫折和困惑,甚至产生了放弃的念头。然而,在一次偶然的机会下,他突然领悟到为官之道,表现出了谄媚之态,展现出了一种转变和妥协的心态。最终,他选择了放下过去的一切,成为一个荔枝老农,专心致志地照料果园,过着平静的生活。整个过程中,李善德的想法经历了从迷茫到决心,再到妥协和放下的转变,展现出了一个复杂而丰富的内心世界。

⭐⭐⭐⭐ 更详细,提到"妥协"、"…

— 以上为试看内容(约 40%),开通会员后阅读全文 —