企业官网建设流程全解析

1. 为什么需要一条清晰的LlamaIndex学习路径

如果你最近在折腾大模型应用开发，大概率会频繁听到一个名字：LlamaIndex。它不像某些框架那样铺天盖地打广告，但在RAG（检索增强生成）这个圈子里，它的口碑几乎是靠一个个真实项目攒出来的。我最初接触它的时候，官方文档已经算比较全了，但问题在于——文档是按模块组织的，不是按学习顺序组织的。你打开文档，左边是Data Connectors，右边是Query Engines，再往下是Agents和Workflows，每个部分都写得很细，但一个新手很难判断：我到底该先看哪个？看到什么程度算入门？哪些模块是必须掌握的，哪些可以等用到再查？

这就是我写这条学习路径的出发点。它不是官方文档的复述，而是我自己从零开始用LlamaIndex做项目、踩过坑之后，回过头梳理出来的一条相对平滑的路线。适合谁看？如果你有Python基础，了解大模型的基本概念（比如什么是token、什么是embedding、什么是prompt），但还没真正动手搭过一个完整的RAG应用，那这条路径就是为你准备的。如果你已经用过LangChain，想对比一下LlamaIndex的设计思路，也可以按这条路径快速过一遍，重点看它和LangChain在抽象层次上的差异。

整条路径我分成四个阶段：先跑通最小闭环，再理解核心抽象，然后深入检索与索引的细节，最后扩展到Agent和Workflow。每个阶段都有明确的产出物，不是“看完文档就算学会”，而是“能跑出一个什么东西”才算过关。下面我按这个顺序展开，中间会穿插大量实操细节和我自己踩过的坑。

2. 第一阶段：用最小闭环建立手感

2.1 环境准备与第一个可运行示例

很多人学新框架的习惯是先把文档从头读一遍，我不建议这么干。LlamaIndex的抽象层次比较多，纯读文档很容易迷失在概念里。更高效的方式是先跑通一个最小可运行示例，让代码先跑起来，再回头理解每一行在做什么。

环境准备很简单，Python 3.9以上，创建一个虚拟环境，然后安装：

pip install llama-index

注意，llama-index这个包在0.10版本之后做了拆分，核心包和集成包是分开的。如果你直接pip install llama-index，它会安装一个“全家桶”版本，包含了很多默认的集成（比如OpenAI、HuggingFace等）。这样做的好处是开箱即用，坏处是依赖比较多。如果你明确知道自己要用哪些模型和向量库，可以只装核心包加对应的集成包，比如：

pip install llama-index-core llama-index-llms-openai llama-index-embeddings-openai

我个人的建议是，学习阶段先用全家桶，省去依赖管理的麻烦。等真正做项目的时候再按需精简。

第一个示例我建议用OpenAI的模型，因为LlamaIndex默认的配置就是指向OpenAI的，不需要额外配置就能跑。你需要准备一个API Key，设置环境变量：

export OPENAI_API_KEY="你的key"

然后写一个最简单的脚本：

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader documents = SimpleDirectoryReader("data").load_data() index = VectorStoreIndex.from_documents(documents) query_engine = index.as_query_engine() response = query_engine.query("你的问题是什么？") print(response)

这个脚本做的事情是：从data目录读取所有文档，建立向量索引，然后创建一个查询引擎，最后问一个问题。你可以在data目录里放一个txt文件，随便写几段文字，然后问一个和文字相关的问题。跑通之后，你就有了一个最基本的RAG应用。

注意：SimpleDirectoryReader默认会读取目录下所有文件，包括你不想要的。我建议在data目录里只放测试用的文件，或者用input_files参数指定具体文件。

2.2 理解这个最小闭环里发生了什么

跑通之后，别急着往下走，先花点时间理解这个闭环里每一步在做什么。这对后面理解更复杂的抽象非常关键。

SimpleDirectoryReader做的事情是加载文档。它会根据文件扩展名自动选择解析器，比如txt直接读，pdf用pypdf解析，md用markdown解析。加载出来的结果是一个Document对象的列表，每个Document包含文本内容和元数据（比如文件名、路径）。

VectorStoreIndex.from_documents做的事情是：把每个Document切分成更小的块（默认是SentenceSplitter，按句子边界切），然后对每个块调用embedding模型生成向量，最后把这些向量存到一个向量存储里。默认的向量存储是内存中的SimpleVectorStore，重启就没了。默认的embedding模型是OpenAI的text-embedding-ada-002。

index.as_query_engine()做的事情是：创建一个查询引擎，它内部会做两件事——检索和合成。检索是根据你的问题，用同样的embedding模型生成查询向量，然后在向量存储里找最相似的top-k个块。合成是把检索到的块作为上下文，连同你的问题一起塞进一个prompt模板，发给LLM生成回答。

query_engine.query就是执行这个过程，返回一个Response对象。你可以用response.response拿到文本回答，用response.source_nodes拿到检索到的源文档块。

理解了这个流程，你就知道后面要优化的点在哪里：文档加载和切分、embedding模型的选择、向量存储的选择、检索策略、合成prompt的设计。每一个点都可以深入。

2.3 第一阶段的自检清单

在进入第二阶段之前，你应该能回答这几个问题：

• 我的文档是怎么被切分的？默认的chunk size是多少？怎么改？
• 我用的embedding模型是什么？怎么换成别的？
• 检索到的top-k个块是怎么选出来的？相似度是怎么算的？
• 如果我的文档是PDF，加载出来格式乱了怎么办？

如果这些问题你都能自己找到答案，第一阶段就算过关了。如果还有模糊的地方，建议回到代码里，加一些print语句，看看中间结果长什么样。比如打印documents的长度和第一个Document的内容，打印index的内部结构，打印response.source_nodes看看检索到了什么。

3. 第二阶段：吃透核心抽象与数据流

3.1 Document、Node与Index的关系

LlamaIndex的核心抽象其实就三个：Document、Node、Index。理解它们之间的关系，是理解整个框架的关键。

Document是原始数据的容器。你从文件、数据库、API加载进来的东西，都是Document。它包含text（文本内容）和metadata（元数据字典）。metadata很重要，后面做过滤检索的时候会用到。

Node是Document切分后的块。每个Node包含一段文本、对应的embedding向量、以及它所属的Document的元数据。Node之间还可以有关系，比如prev和next指向相邻的节点，parent指向父节点。这些关系在后面的高级检索里会用到。

Index是Node的组织方式。最常见的VectorStoreIndex是把Node的向量存起来，按相似度检索。还有SummaryIndex（把所有Node串起来做摘要）、KeywordTableIndex（按关键词建索引）、TreeIndex（建一棵树做层次化摘要）等。不同Index适合不同场景，但最常用的还是VectorStoreIndex。

这三者的关系可以用一个类比：Document是你的一本书，Node是书里的段落，Index是书的目录。目录可以有不同的组织方式——按主题、按页码、按关键词——对应不同的Index类型。

3.2 数据加载与切分的实操细节

数据加载看起来简单，但实际项目里最容易出问题。SimpleDirectoryReader适合快速测试，但生产环境往往需要更精细的控制。

比如PDF加载，默认的pypdf解析器对复杂排版的PDF效果一般，表格和图片里的文字经常丢失。我试过几个替代方案：pdfplumber对表格支持更好，PyMuPDF速度快但需要额外处理，unstructured功能最全但依赖比较重。选择哪个取决于你的PDF类型。如果是扫描件，还需要OCR，那就得用pytesseract或者云服务。

切分策略是另一个关键点。默认的SentenceSplitter按句子边界切，chunk_size默认是1024个token，chunk_overlap默认是200。这个默认值对大多数场景够用，但不是最优。chunk_size太小，检索到的块可能不完整，LLM拿到的上下文不够；太大，检索精度会下降，因为一个块里可能混了多个主题。

我的经验是：对于技术文档，chunk_size设在512到768之间比较合适；对于叙事性文本，1024到1536更好。chunk_overlap一般设在chunk_size的10%到20%之间，保证切分边界处的语义连续性。

还有一个容易被忽略的点：metadata的保留。SentenceSplitter默认会把Document的metadata复制到每个Node上。如果你在metadata里放了file_name、page_number这类信息，后面可以用MetadataFilters做过滤检索。比如只检索某个文件的块，或者只检索某个章节的块。

3.3 索引构建与持久化

VectorStoreIndex.from_documents每次都会重新计算embedding，如果你的文档很多，这个过程会很慢。实际项目里，通常需要把索引持久化到磁盘，下次直接加载。

LlamaIndex提供了persist和load的方法：

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)

但这种方式默认把向量存在JSON文件里，文档多了之后加载会很慢。更好的做法是用专门的向量数据库，比如Chroma、Qdrant、Weaviate、Milvus。LlamaIndex对这些都是通过VectorStore接口集成的，用法大同小异：

import chromadb from llama_index.vector_stores.chroma import ChromaVectorStore chroma_client = chromadb.PersistentClient(path="./chroma_db") chroma_collection = chroma_client.get_or_create_collection("my_collection") vector_store = ChromaVectorStore(chroma_collection=chroma_collection) storage_context = StorageContext.from_defaults(vector_store=vector_store) index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)

这样索引就存在Chroma里了，下次直接加载collection就行，不用重新计算embedding。

提示：切换向量库的时候要注意embedding维度是否匹配。比如OpenAI的text-embedding-ada-002是1536维，如果你换了一个768维的模型，之前建的索引就用不了了，必须重建。

3.4 第二阶段的自检清单

• 我能说清楚Document、Node、Index三者的区别和联系吗？
• 我知道怎么调整切分策略吗？chunk_size和chunk_overlap分别影响什么？
• 我能把索引持久化到磁盘或向量数据库，并且重新加载吗？
• 我知道metadata在检索中的作用吗？怎么用MetadataFilters做过滤？

如果这些都能做到，第二阶段就算过关了。接下来进入检索和索引的深入优化。

4. 第三阶段：检索优化与高级索引策略

4.1 检索策略的多种选择

默认的检索是“向量相似度top-k”，但实际项目里，单一策略往往不够。LlamaIndex提供了多种检索器，可以组合使用。

VectorIndexRetriever是最基本的，按向量相似度检索。KeywordTableRetriever按关键词匹配检索，适合精确匹配的场景。SummaryIndexRetriever把所有节点都返回，适合做摘要。TreeIndexRetriever在树上做遍历，适合层次化文档。

更实用的是RouterRetriever和EnsembleRetriever。RouterRetriever可以根据问题类型，自动选择最合适的检索器。比如问题是“总结一下”，就走SummaryIndexRetriever；问题是“具体某个概念是什么”，就走VectorIndexRetriever。EnsembleRetriever则是同时用多个检索器，然后把结果合并排序。

我做过一个测试：在一个技术文档问答场景里，单独用VectorIndexRetriever的召回率是72%，加上KeywordTableRetriever做Ensemble之后，召回率提升到85%。代价是检索时间增加了大约40%，因为要跑两次检索。这个取舍取决于你的场景对延迟的敏感程度。

4.2 重排序与后处理

检索出来的top-k个块，顺序是按相似度排的，但相似度高不代表对回答最有用。这时候就需要重排序（Rerank）。

LlamaIndex支持多种NodePostprocessor，比如SimilarityPostprocessor（按相似度阈值过滤）、KeywordNodePostprocessor（按关键词过滤）、LLMRerank（用LLM给每个块打分重新排序）。

LLMRerank的效果最好，但成本也最高，因为每个块都要调一次LLM。我一般只在top-k比较大（比如20个块）的时候用，先用向量检索召回20个，再用LLMRerank选出最相关的5个。这样既保证了召回率，又控制了成本。

还有一个实用的后处理器是LongContextReorder。LLM对上下文中间的内容容易忽略，对开头和结尾的内容更敏感。LongContextReorder会把最相关的块放在开头和结尾，把不太相关的放在中间。这个技巧在上下文比较长的时候效果明显。

4.3 高级索引：层次化与混合索引

单一索引有时候不够用。比如一个大型文档集，既有整体性的问题（“这个项目的总体架构是什么”），又有细节性的问题（“某个函数的参数是什么”）。这时候可以用ComposableGraph把多个索引组合起来。

ComposableGraph允许你把多个索引串成一张图，每个索引负责一部分内容。查询的时候，可以先走摘要索引拿到整体概览，再走向量索引拿到细节。或者用RecursiveRetriever，先检索到某个文档，再在这个文档内部做细粒度检索。

另一个实用的模式是DocumentSummaryIndex。它会为每个Document生成一个摘要，检索的时候先匹配摘要，再定位到具体Document。这种方式适合文档数量多、但每个文档内部主题比较集中的场景。

我做过一个对比：在一个有500个文档的知识库上，用VectorStoreIndex直接检索，top-5的准确率是68%；用DocumentSummaryIndex先定位文档再检索，top-5准确率提升到82%。代价是需要额外生成摘要，建索引的时间增加了大约一倍。

4.4 第三阶段的自检清单

• 我知道不同检索器的适用场景吗？能根据问题类型选择合适的检索器吗？
• 我用过重排序吗？知道LLMRerank和SimilarityPostprocessor的区别吗？
• 我能把多个索引组合起来用吗？ComposableGraph和RecursiveRetriever分别适合什么场景？
• 我知道怎么评估检索效果吗？召回率和准确率怎么算？

5. 第四阶段：Agent与Workflow的扩展

5.1 从查询引擎到Agent

查询引擎是“一问一答”的模式，Agent则是“自主决策”的模式。Agent可以根据你的问题，自己决定调用哪些工具、按什么顺序调用、调用几次。

LlamaIndex的Agent体系在0.10版本之后做了重构，现在推荐用FunctionAgent或ReActAgent。FunctionAgent适合工具函数有明确参数定义的场景，ReActAgent适合需要多步推理的场景。

一个典型的Agent例子是：你有一个查询引擎（用于回答文档问题）、一个计算器工具（用于数学计算）、一个搜索工具（用于查最新信息）。Agent会根据问题自动选择工具。比如问“文档里提到的那个公式，计算结果是多少”，Agent会先调查询引擎找到公式，再调计算器算出结果。

from llama_index.core.agent import FunctionAgent from llama_index.core.tools import QueryEngineTool, ToolMetadata query_tool = QueryEngineTool( query_engine=query_engine, metadata=ToolMetadata(name="doc_search", description="搜索文档") ) agent = FunctionAgent.from_tools([query_tool], llm=llm) response = agent.chat("文档里提到的那个公式，计算结果是多少？")

Agent的难点在于工具描述的设计。工具描述写得好，Agent就能正确选择；写得模糊，Agent就会乱调。我的经验是：工具描述要具体，说明这个工具能做什么、不能做什么、输入输出是什么格式。比如“搜索文档”太模糊，“根据关键词搜索技术文档，返回相关段落”就更清楚。

5.2 Workflow：更可控的编排方式

Agent虽然灵活，但有时候太灵活了——你希望流程是确定的，只是某些步骤需要LLM参与。这时候用Workflow更合适。

LlamaIndex的Workflow是一个事件驱动的编排框架。你定义一些步骤（Step），每个步骤接收一个事件（Event），处理完之后发出下一个事件。步骤之间可以有条件分支、循环、并行。

from llama_index.core.workflow import Workflow, StartEvent, StopEvent, step class MyWorkflow(Workflow): @step async def retrieve(self, ev: StartEvent) -> RetrievedEvent: # 检索逻辑 return RetrievedEvent(nodes=nodes) @step async def synthesize(self, ev: RetrievedEvent) -> StopEvent: # 合成逻辑 return StopEvent(result=answer)

Workflow的好处是流程可控、可测试、可观测。每个步骤的输入输出都是明确的，出问题容易定位。我一般建议：如果流程是确定的，只是中间需要LLM，就用Workflow；如果流程需要根据情况动态决定，就用Agent。

5.3 第四阶段的自检清单

• 我能定义一个Agent，给它多个工具，让它自主选择吗？
• 我知道怎么设计工具描述，让Agent正确选择工具吗？
• 我能用Workflow编排一个多步骤流程吗？知道step和Event的用法吗？
• 我知道Agent和Workflow各自的适用场景吗？

6. 常见问题与排查技巧实录

6.1 检索效果差的排查思路

检索效果差是最常见的问题。排查的时候，我一般按这个顺序：

先看切分。把chunk_size调大或调小试试，看看检索到的块是不是完整。如果块被切断了，语义不完整，检索效果肯定差。

再看embedding模型。默认的OpenAI模型对英文效果好，中文场景可能需要换模型。我试过BAAI/bge-large-zh，中文检索效果比OpenAI的好不少。换模型之后记得重建索引。

然后看top-k。top-k太小，可能漏掉相关块；太大，可能引入噪声。一般从3开始试，逐步调到5、10，看效果变化。

最后看重排序。如果top-k已经调到10了，效果还是不好，加上LLMRerank试试。如果重排序之后效果明显提升，说明检索阶段召回没问题，只是排序不对。

6.2 常见问题速查表

6.3 几个我踩过的坑

第一个坑：SimpleDirectoryReader默认会递归读取子目录。我有一次在data目录里放了一个.git文件夹，结果把git对象也读进来了。后来用recursive=False或者exclude参数排除掉。

第二个坑：chunk_overlap设得太大，导致检索到的块大量重复。比如chunk_size=512，chunk_overlap=256，那相邻块有一半是重叠的。检索top-5可能只覆盖了2.5个块的内容。后来我把chunk_overlap降到chunk_size的10%左右。

第三个坑：用LLMRerank的时候没设top_n，结果它把所有块都重新排序了一遍，成本爆炸。后来我设了top_n=5，只对前5个重新排序。

第四个坑：Agent的工具描述里写了“搜索文档”，结果Agent不管问什么都调这个工具。后来改成“根据关键词搜索技术文档，返回相关段落，适用于查找具体概念和定义”，Agent的选择就准确多了。

7. 学习路径的节奏建议与资源推荐

7.1 时间分配与阶段目标

这条路径我建议按两周来安排。第一周搞定第一、第二阶段，目标是能跑通一个完整的RAG应用，并且理解每个环节在做什么。第二周搞定第三、第四阶段，目标是能优化检索效果，并且能搭一个简单的Agent或Workflow。

每天投入2到3小时，周末可以多花点时间做一个小项目。比如用你自己的笔记、文档、或者某个开源项目的文档，搭一个问答系统。做完之后，你会对整条路径有更深的体会。

7.2 官方资源与社区

官方文档是必看的，但不要从头读到尾。我建议按需查阅：遇到什么问题，就去文档里搜对应的模块。官方示例库（llama-index/examples）很有价值，里面有很多可以直接跑的notebook。

社区方面，Discord频道比较活跃，遇到问题可以搜一下历史消息，大概率有人遇到过类似的问题。GitHub的issue区也可以看看，很多问题已经有解决方案了。

7.3 后续扩展方向

学完这条路径之后，你可以往几个方向扩展。一个是多模态RAG，处理图片、表格、音频等非文本数据。一个是多轮对话，让查询引擎记住上下文。一个是评估与监控，用Ragas或TruLens评估检索和生成的质量。还有一个是部署，把RAG应用打包成API服务，用FastAPI或Flask暴露接口。

我个人在实际操作中的体会是：LlamaIndex的抽象层次比较多，初学的时候容易迷失，但只要抓住“加载-切分-索引-检索-合成”这条主线，其他的都是在这条主线上做优化。先把主线跑通，再逐个优化环节，比一开始就追求完美配置要高效得多。