LlamaIndex入门：从零搭建RAG文档问答系统

我前阵子帮朋友做一个内部文档问答的小工具，需求不复杂：把一堆PDF和Markdown丢进一个文件夹，用户能像聊天一样问“报销流程有哪几步”“合同审批找谁”这类问题。我第一次动手时满脑子都是“这不得先做文本切分、再调嵌入模型、写检索逻辑、还要拼接Prompt？”结果发现LlamaIndex已经把这条路走通了大半。今天这篇是基于我实际踩坑整理出来的入门笔记，重点说清楚LlamaIndex是什么、为什么RAG场景要选它、核心概念怎么理解，然后直接带你把一个能用的文档问答跑起来。

如果你刚接触RAG或者被LangChain里各种概念绕晕过，这篇就是为你写的。你不需要懂很深的机器学习原理，只要会Python基础语法，能执行pip install，就能跟着走完全程。文章前半部分是概念铺垫，后半部分是实操和排错，看完你能从头写一个带本地索引持久化的问答工具，也能知道后续往哪个方向深入。

1. 5分钟理解LlamaIndex到底解决了什么问题

1.1 大模型与私有数据之间的“最后一公里”

先说一个很现实的问题：大语言模型虽然能聊会写，但它的知识截止到训练数据那一天，而且它没见过你的企业文档、个人笔记、数据库里的记录。你可以把Prompt写到天花乱坠，模型也不会“记得”你上个月那份合同里写了什么条款。所以当我们需要大模型去回答基于私有数据的问题时，常见思路就一条——把相关资料找出来，拼进Prompt里，让模型基于这些材料作答。这个思路就是检索增强生成，英文简称RAG。

道理听着简单，真做起来全是细节。数据格式五花八门，有PDF、Word、纯文本，文档长度从天差地别，短的几十个字，长的几百页。怎么把长文档拆成适合喂给模型的小片段？怎么把“找相关片段”这件事做得又快又准？Embedding用什么模型？向量存在哪里？检索出来之后怎么组织Prompt？如果这些全部手写，项目还没开始，光基建就够忙一个月。LlamaIndex就是把这些环节封装成一套统一接口的工具，让“私有数据+大模型”这条路从手工作坊变成标准化流水线。

打个比方，如果没有这类框架，你要自己种小麦、磨面、揉馒头；有了LlamaIndex，你只需要把面粉和水交给它，它按固定流程帮你把馒头蒸出来，至于面粉粗细（切块大小）、蒸多久（检索的策略）都可以按口味调节。

1.2 它到底做了什么：从文档到可检索的知识库

LlamaIndex本质上是个数据框架，核心职责是连接你的数据和你的大模型。你提供一份文档，它帮你完成这条链路：读取文件 → 分成若干片段 → 为每个片段生成向量表示 → 把向量和原文一起存入索引 → 当用户提问时，把问题转成向量 → 在索引里找最相似的片段 → 把这些片段连同问题交给大模型 → 得到回答。

这一条链路上的每一步都有可替换的组件。读文件时可以用不同的Reader；分块可以用内置的多种Parser；向量化可以用OpenAI的Embedding接口，也可以用开源的本地嵌入模型；存储可以只用内存，也可以落到磁盘；大模型可以用OpenAI，也可以换其他兼容接口的模型。这正是LlamaIndex值得学的地方——不是逼你用一套死方案，而是把RAG流程拆成积木，你想换哪块就换哪块。

实际操作中我见过很多朋友拿RAG当黑盒，文档丢进去能回答就万事大吉，效果差了不知道怎么调。这也是我写这篇笔记的核心目的：先带你建立全链路的心智模型，知道每个环节在干什么，后面排查和优化才有方向感。只停留在“会用”层面，一旦遇到文档读不完、回答乱引用、重启就丢索引这些问题，很容易卡死。

2. 第一次接触LlamaIndex：核心概念逐个拆解

2.1 Document、Node 与 Metadata

LlamaIndex里最常碰到的两个对象是Document和Node。你把一个文件丢进去，框架会把它包装成一个Document。Document可以是一份PDF、一个网页、一段JSON，甚至是一张表格。但Document在LlamaIndex里不是最小处理单元，因为它往往太大、内容太杂，直接拿去做向量化和检索，相关性会非常差。

于是框架会做切分，把Document按某种策略拆成Node。Node可以理解为“语义上相对完整的一小块文本”，比如一两段话，或者一个标题下的小节。每个Node除了正文内容之外，还能挂Metadata（元数据），比如来源文件名、页码、章节号。这一步的价值在回答问题时特别明显——模型能根据元数据告诉你“这个结论来自第12页”，这是RAG系统里非常实用的能力。

第一次自己切分时，我犯过把整章内容作为Node的毛病，检索效果惨不忍睹。后来换成了更小粒度，每个Node保持在几百个token以内，准确率立刻就上来了。就像查字典，如果你把整本字典作为一个词条，翻到哪页都得从头读到尾，那效率根本没救；把每个字拆成独立词条，查一个字才快。

2.2 索引类型怎么选

LlamaIndex里有几类索引，最常用的是VectorStoreIndex（向量索引），也是最典型的RAG索引。它的逻辑是：把每个Node生成一个向量，用户提问时也生成一个向量，然后计算向量之间的相似度，把最接近的一批Node捞出来。

除了向量索引，还有SummaryIndex（列表索引/摘要索引）、TreeIndex（树索引）、KeywordIndex（关键词索引）。我分别说一下它们的适用场景：列表索引会把所有Node挨个塞进上下文，适合文本量不大、需要全局理解的情况；树索引会先把Node构建成树状结构，再逐层递归摘要，适合处理超大文档但需要“先总后分”的问答；关键词索引通过关键词匹配定位Node，适合检索词非常明确的场景。

新手不要贪多，先把VectorStoreIndex玩明白，它覆盖了绝大多数使用需求。等以后遇到“文档很长，答案分散在多个章节”“需要先给个全局总结再深入到细节”这类需求，再回头研究TreeIndex和SummaryIndex。我见过不少人一开始就堆了五六个索引，最后发现实际项目里90%场景一个向量索引就解决了。

2.3 Retriever 与 QueryEngine 的分工

理解了Document和Node，再看Retriever就简单了。Retriever负责“从索引里找出相关内容”，它接收查询，返回一组相关的Node。QueryEngine则是更高层的封装，把“检索”和“生成”合在一起：先调用Retriever，再把检索到的Node和用户问题组装成Prompt，最后调用大模型生成回答。

在这个架构里，大多数初学者其实想用的就是QueryEngine。一句话“把索引变成查询接口”，就是as_query_engine()做的事。但理解Retriever这个层级的价值在于，你可以中途拦截、替换它的行为。比如默认Retriever返回前2个Node，你可以把similarity_top_k调到5，让它返回更多候选；你也可以把Retriever替换成自定义实现，比如先做关键词过滤、再向量检索，这种组合玩法在复杂项目里非常实用。

我个人是建议你把query_engine.query()返回的Response对象里的source_nodes字段打开看看。它告诉你这个问题最终命中了哪几个Node，每个Node来自哪个文件。这个字段是排查“为什么这么答”的一手证据，也是后面调优的重要依据。

3. 装包与配密钥：动手前的关键准备

3.1 安装命令与版本选择

安装这一步看似简单，其实坑不少。现在LlamaIndex已经从原本一个包拆成了多个子包，比如llama-index-core、llama-index-llms-openai、llama-index-embeddings-openai。如果你只装最上层的llama-index，它会自动把核心包和常见依赖一起拉下来，适合新手。我建议你直接用这条命令：

pip install llama-index

如果想确认装好没有，可以跑一个短脚本：

import llama_index print(llama_index.__version__)

由于子包拆分的关系，不同模块的导入路径也有讲究。现在的主流写法是下面的方式：

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader from llama_index.core.node_parser import SentenceSplitter from llama_index.llms.openai import OpenAI from llama_index.embeddings.openai import OpenAIEmbedding

这里llama_index.core是所有核心抽象所在的地方，llama_index.llms.openai这类是具体的模型适配器。如果你在旧教程里看到from llama_index import VectorStoreIndex这种写法，多半是早期版本，建议直接用当前版本的新写法，逻辑更清晰，也不容易踩导入坑。

3.2 配置模型密钥与基础验证

LlamaIndex默认用的是OpenAI的模型，Embedding和文本生成都需要API Key。动手前先把环境变量设置好。Linux和macOS下执行：

export OPENAI_API_KEY="你的key"

Windows PowerShell下执行：

$env:OPENAI_API_KEY="你的key"

配置好之后，建议先做一个最小验证，确认密钥没问题再往下走。你可以写一行代码试试调用Embedding模型：

from llama_index.embeddings.openai import OpenAIEmbedding embed_model = OpenAIEmbedding() result = embed_model.get_text_embedding("你好，测试一下") print(len(result))

如果能打印出一个几百维的向量，说明接口通了。我第一次配置时漏了环境变量，结果框架报错提示网络鉴权失败，排查了半天才发现是Key没设置上。所以这块建议提前验证，别等代码写完了才回头查环境问题。

另外提醒一下，如果你的网络环境访问OpenAI接口不稳定，可以按框架的说明配置自定义API地址。LlamaIndex的模型对象支持传入api_base这类参数，指向你实际可用的网关，这个在团队协作和大陆网络环境里几乎是刚需。

4. 30行代码跑通你的第一个LlamaIndex问答系统

4.1 准备一份“能跑起来”的测试数据

正式动手之前，先准备一个干净的测试目录，别一上来就用几百页的大文档。我在测试阶段用的是一个十来页的Markdown文件，内容是一份“模拟项目X的运维手册”，里面有节点清单、故障恢复流程、告警规则三部分。选Markdown有好处：文本结构清楚、没有PDF解析的编码问题、切分后的Node语义相对完整。等你把整个流程跑通以后，再换成PDF或Word测试。

目录结构大致像这样：

data/ 运维手册.md

里面写上几段内容，比如：

# 节点清单 系统共包含3个节点，分别为主节点、备节点与监控节点。主节点负责请求分发，备节点负责状态同步，监控节点只读采集指标。 # 故障恢复流程 当主节点不可用时，备节点在30秒后自动接管。接管期间请勿手动重启主节点，恢复由调度系统自动完成。 # 告警规则 当任何节点连续3次心跳丢失，会触发告警。告警等级分为警告、严重、紧急三级。

这种内容的好处是，后面测问题时你能马上判断回答到底对不对——你对材料了如指掌，才能快速验证系统的检索是否准确。

4.2 完整代码与逐步拆解

现在写核心代码。新建一个demo.py：

from llama_index.core import SimpleDirectoryReader, VectorStoreIndex # 第一步：读取目录下的所有文档 documents = SimpleDirectoryReader("data").load_data() # 第二步：构建向量索引 index = VectorStoreIndex.from_documents(documents) # 第三步：创建查询引擎并提问 query_engine = index.as_query_engine() response = query_engine.query("主节点不可用时应该怎么处理？") print(response)

这份代码是LlamaIndex最经典的骨架，三步走：读文档、建索引、做问答。不要嫌它简单，RAG所有复杂配置最终都是围绕这三步在做文章。

SimpleDirectoryReader("data")会扫描目录下支持的文本类文件，常见格式有txt、md、pdf、docx、csv等。load_data()把所有文件转成Document列表。这里有一点值得记住：加载PDF时，它内部用的是解析库，面对扫描版PDF会白费力气，因为里面没有文字层。如果你手里的PDF是图片扫描件，得先做OCR，否则检索结果一定是空的。

VectorStoreIndex.from_documents(documents)是整个流程中最重的一步。它内部会做几件事：把Document按默认策略切成Node、调用Embedding模型把每个Node变成向量、把向量和原文放进索引。默认切分策略对中文文本效果还行，但如果你的文档里有很多表格、代码块，可能需要自定义切分规则，这一点后面单独说。

as_query_engine()返回QueryEngine对象，调用query()传入用户问题，它会在索引里找相关Node，再组织Prompt交给大模型。我在测试时问了一句“主节点不可用怎么办”，返回的结果引用了“故障恢复流程”这一段，回答内容基本正确。首次跑通看到这样的结果，整条链路就算通了。

4.3 参数调整：chunk_size、相似度TopK与温度系数

跑通之后，再往下走就是调参。最容易影响效果的是三个参数：切分大小、检索数量、模型温度。

切分大小对应SentenceSplitter的chunk_size和chunk_overlap。chunk_size决定每个Node包含多少字符，太大则单个Node信息太杂，太小则语义被切碎。我的经验是中文场景下500到800比较稳妥。chunk_overlap是相邻Node之间重复的字符数，设多一点点可以避免句子的后半部分被截断。你可以用下面的方式覆盖默认切分：

from llama_index.core.node_parser import SentenceSplitter splitter = SentenceSplitter(chunk_size=512, chunk_overlap=64) index = VectorStoreIndex.from_documents(documents, transformations=[splitter])

检索数量对应similarity_top_k，它决定每次拿几个Node喂给模型。默认值通常只有2，如果你的文档信息很分散，答案凑不齐，就调大一点。但也不是越大越好，Node太多会让Prompt变长、成本上涨，还会让模型被无关信息干扰。我一般先从3开始调，逐步加了看效果：

query_engine = index.as_query_engine(similarity_top_k=3)

温度系数temperature影响回答的创造性。做事实型问答时我习惯调低，比如0.1，让模型更忠实于检索到的文本而不是自由发挥。LlamaIndex里可以通过Settings统一配置：

from llama_index.core import Settings from llama_index.llms.openai import OpenAI Settings.llm = OpenAI(model="gpt-4o-mini", temperature=0.1)

这里用gpt-4o-mini是为了演示，你可以按自己的账号模型情况换名字。设置之后，后续问答都使用这个模型配置，不用每次单独传参。

5. 保存索引：让程序重启后不用重新embedding

5.1 持久化原理

跑通上面的代码，你已经拥有一个能问答的小系统。但有个问题很明显：每次运行都要重新读文件、重新生成向量。如果你的文档不多，比如就几页，倒是无感；如果文档一大，每次启动都重新embedding，既烧钱又费时间，而且数据根本不支持超大批量。

LlamaIndex对此提供了一套持久化方案，核心逻辑是：把索引数据和每个Node的文本、向量、元数据一起存到本地目录；下次启动时从目录恢复，跳过重新解析和embedding。

5.2 存储到磁盘的两种正确姿势

第一种方式：构建完索引后直接持久化。

index.storage_context.persist(persist_dir="./storage")

这样会在./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) query_engine = index.as_query_engine()

第二种方式：构建索引时显式指定存储上下文。这在你想同时自定义存储位置和向量库时更常用：

from llama_index.core import StorageContext, VectorStoreIndex storage_context = StorageContext.from_defaults(persist_dir="./storage") index = VectorStoreIndex.from_documents( documents, storage_context=storage_context, )

两种方式本质一样，我个人习惯用第一种，构建和保存分开，逻辑更直白。有一点一定要记住：持久化之后不要随便改文档内容，因为索引里的向量对应的是旧文本，如果你改了原文但没重新构建索引，检索到的东西会和实际文件对不上。每次内容更新后，老老实实重新构建一次索引。

6. LlamaIndex常见报错与检索效果排查

6.1 环境类问题：模块找不到、网络和Key报错

我实操中遇到最多的问题就是ModuleNotFoundError，比如from llama_index.core import VectorStoreIndex时提示找不到llama_index.core。这种情况基本是安装的包版本太老或只装了一个子包。解决方法是更新主包：

pip install -U llama-index

另外，Python版本也是一个因素。LlamaIndex对Python 3.9以上支持较好，我建议你在3.10或3.11环境里运行，能规避不少依赖编译问题。

其次是接口调用报错。看到“AuthenticationError”时，先查环境变量是否真的配置了，注意别把Key放在脚本里写死，或者写在会提交到仓库的配置文件中。如果确认Key没问题，再看网络是否稳定。我遇到过类似情况，换成可用的API网关地址后一切正常。

还有一类问题出现在读取文件环节。SimpleDirectoryReader能自动识别扩展名，但如果你文件本身是坏的、加密的、或者版权保护状态，它读不出来。遇到这种情况，先用简单文本文件测试，确认是文件问题再考虑对应解析方案。

6.2 回答质量问题：检索不到、答案拼接失效

如果系统能跑，但回答总是“一本正经地胡说八道”，那大概率是检索环节出了问题，而不是模型的问题。我建议你严格按下面几步排查。

第一步，看Response对象的source_nodes。打印出检索到的Node内容：

response = query_engine.query("主节点不可用怎么办") for node in response.source_nodes: print(node.node.get_content())

如果你发现检索到的Node内容里根本没有“主节点”这几个字，说明召回环节出问题了。这时候先调大similarity_top_k，从2改成5；如果还不行，把chunk_size改小，让Node粒度更细，提高命中率。

第二步，检查文档切分是否破坏了语义。代码块、表格、列表这类结构化内容，被默认切分器拦腰截断是家常便饭。我处理代码类文档时，会专门用CodeSplitter或MarkdownNodeParser这类结构感知的解析器，这样Node边界能贴合内容结构，检索质量和回答质量都会好很多。

第三步，确认Embedding模型和文本生成模型没有配置混乱。如果你的文档有一部分是英文、一部分是中文，混合内容的检索效果可能因为Embedding模型的语言能力而变差。这时候要么做好语言归一化，要么考虑更换对中文支持更好的嵌入模型。

我把常见问题整理成一张速查表，方便你对照查找：

7. 从Demo到实际项目，还能怎么折腾

7.1 面向真实场景的进阶方向

一旦跑通了最小闭环，你会发现LlamaIndex的门道远不止基础问答。我盘一下自己用下来觉得最值得深入的方向。

第一个是多文档路由。不同文档回答问题的角度完全不同，比如一个目录里既有“产品操作手册”又有“财务报销制度”，用户问“发票怎么开”和“设备怎么开机”，不应该从所有文档里捞内容。LlamaIndex里有RouterQueryEngine和SummaryIndex、KeywordIndex这类不同索引之间的路由机制，能够把问题分发给专门的索引。第二个是对话记忆。基础QueryEngine每次问答都是独立的，不记得你上一句说了什么。要做出真正“聊起来”的效果，需要引入ChatMemoryBuffer这类记忆能力，让多轮对话的上下文能累积。第三个是数据增量更新。真实文档是每天变化的，不可能每次都全量重建索引。LlamaIndex支持对已有索引做insert和delete操作，能够以Node为粒度增量更新，这才满足生产系统的要求。

如果你想做大项目，还有一个重要方向是换向量数据库。默认的内存索引适合教学，但在数据量超过几百万Node时，内存扛不住。你可以把VectorStoreIndex的底层存储换成专业的向量数据库，代码改动量很小，因为你只需要传入一个已有的collection对象。这也是LlamaIndex设计得好的一点——很多组件都是可替换的。

另外有一个在中文场景里非常普遍的问题：嵌入模型选型。如果你完全依赖OpenAI的嵌入接口，一旦网络不稳定，整个系统就瘫痪；而且部分场景下私有数据根本不允许出内网。LlamaIndex支持接入本地部署的嵌入模型，把它作为Settings.embed_model传入即可。本地模型的好处是离线可用、隐私可控，坏处是需要一定显存，首次加载也要等模型下载。我个人建议，数据量不大、无强隐私要求时可以先不做本地化，优先把业务逻辑跑通。

7.2 一些值得记住的实操体会

从我这边实际使用的感受来说，LlamaIndex并不是一个“装完就什么都会”的魔法框架，它的价值在于把RAG里的脏活累活标准化了。你真正要花时间去琢磨的，不是怎么调用API，而是数据怎么组织、切分怎么定、评估怎么做。

刚开始做的时候，我犯过一个典型错误：一上来就去研究各种高阶检索策略，结果基础链路通了之后发现，90%的失败都是因为没查source_nodes、没看Node边界长什么样。后来我调整了节奏，每次改动一个变量，跑一遍测试，盯着看检索出的Node到底变了没有，再决定下一步怎么走。这种“一个变量一个变量地动”的土办法，反而比盲目堆高级配置靠谱得多。

另一个心得是，开始就建好评估集。十来个覆盖典型问题的问答对就够了，每次改动后拿同一批问题跑一遍，把回答质量对比一下。手动跑测试虽然土，但带来的效果认知非常直接。等你积累多了，再去接触RAG评估相关的工具，会有种“这说的不就是我踩过的坑吗”的感觉。

如果你打算把这个Demo继续推进，我建议下一步给文档内容做精细的清洗和结构化，比如给Markdown加更明确的标题层级、规范段落标签。你给数据增加的结构化信息越多，LlamaIndex能利用的Metadata就越丰富，检索效果自然跟着上去。框架本身是其次，数据质量往往才是RAG系统的天花板。