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 PyMuPDFReaderreader = 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 VectorStoreIndexindex = 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 SentenceSplitterSettings.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_storagestorage_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 个最相关的 chunks3. 构建 Prompt上下文:chunk1 + chunk2 + chunk3问题:主角是谁?4. 调用 LLMLLM 基于上下文生成答案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)
李善德在整个故事中的心理变化是非常明显的。一开始,他在与赵欣宁的交锋中表现出迷茫和无奈,不知如何回应对方的挑衅。随着故事的发展,他开始展现出决心和勇气,决定尝试新的商业合作方式,并且毫不犹豫地接受了这个挑战。在接受了试验的过程中,他经历了挫折和困惑,甚至产生了放弃的念头。然而,在一次偶然的机会下,他突然领悟到为官之道,表现出了谄媚之态,展现出了一种转变和妥协的心态。最终,他选择了放下过去的一切,成为一个荔枝老农,专心致志地照料果园,过着平静的生活。整个过程中,李善德的想法经历了从迷茫到决心,再到妥协和放下的转变,展现出了一个复杂而丰富的内心世界。
⭐⭐⭐⭐ 更详细,提到"妥协"、"…