为什么大模型总是答不出你内部文档里的内容？答案通常不在于模型不够聪明，而在于它根本接触不到你的数据。LlamaIndex正是为解决这个问题而生的数据框架，它负责把你的文档、数据库、API数据接入大模型，并在此基础上构建能自主检索、自主决策的智能体。本文从安装讲起，一步步完成数据索引的构建，最后搭建一个可以自主选择数据源的数据索引Agent。
一、LlamaIndex安装与基础环境配置
LlamaIndex对Python版本有一定要求，建议使用Python 3.9以上的版本，配合虚拟环境使用可以避免依赖冲突。官方推荐通过pip安装，最简单的方式是安装核心包加上OpenAI集成包：
# 创建虚拟环境 python -m venv venv source venv/bin/activate # 安装核心包和OpenAI集成 pip install llama-index pip install llama-index-llms-openai llama-index-embeddings-openai
LlamaIndex从0.10版本之后采用了模块化设计，核心包非常精简，各个模型和向量库的集成都拆成了独立的包。比如你要使用Ollama本地模型，需要额外安装llama-index-llms-ollama；要对接Hugging Face嵌入模型，则安装llama-index-embeddings-huggingface。这种设计的好处是依赖干净，坏处是新手容易遇到ModuleNotFoundError，遇到这种报错时按提示补装对应包即可。
安装完成后需要配置模型。LlamaIndex默认使用OpenAI的模型，所以要先设置环境变量。下面是标准的初始化代码：
import os from llama_index.llms.openai import OpenAI from llama_index.embeddings.openai import OpenAIEmbedding from llama_index.core import Settings os.environ["OPENAI_API_KEY"] = "sk-你的密钥" # 配置全局使用的模型 Settings.llm = OpenAI(model="gpt-4o-mini", temperature=0.1) Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")
这里用Settings对象做全局配置，之后构建索引时会自动复用这两个模型，不需要重复传入。如果不想依赖OpenAI的付费接口，把Settings.llm换成Ollama实例即可，整体流程完全一致。
二、数据加载与向量索引构建
LlamaIndex把一切输入数据抽象为Document对象，再用数据连接器读取各种来源。SimpleDirectoryReader是最常用的读取器，支持txt、PDF、Word、Markdown等常见格式：
from llama_index.core import SimpleDirectoryReader, VectorStoreIndex
# 读取目录下的所有文档
documents = SimpleDirectoryReader(input_dir="./data").load_data()
print(f"共加载 {len(documents)} 个文档片段")
# 构建向量索引
index = VectorStoreIndex.from_documents(documents)这一行from_documents背后发生了不少事情：框架先把Document切分成更小的Node（默认1024个token一段），然后调用嵌入模型把每个Node转成向量，最后存入默认的内存向量索引。理解Node的概念很重要，它是检索的基本单位，切分粒度直接影响检索质量。切得太碎会丢失上下文，切得太大则召回不精准，可以通过Settings.chunk_size调整，一般256到1024之间根据文档结构调整。
索引构建过程会大量调用嵌入接口，如果每次运行都重建，既慢又费钱，所以持久化很有必要：
# 保存索引到本地 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)
注意一旦更换了嵌入模型，旧索引就不能复用了，因为向量维度和语义空间都变了，这一点在项目迭代时要特别留意。
三、从查询引擎到数据索引Agent
有了索引之后，最直接的用法是查询引擎：index.as_query_engine()会把用户问题转成向量做相似度检索，再把召回的内容交给大模型生成回答。但查询引擎是被动的，而Agent的核心价值在于自主决策，它能根据问题性质选择不同的工具。假设你有两个索引，一个存产品手册，一个存财报数据，让Agent自动路由：
from llama_index.core.tools import QueryEngineTool
from llama_index.core.agent import ReActAgent
# 把查询引擎包装成工具
tool1 = QueryEngineTool.from_defaults(
query_engine=index1.as_query_engine(),
description="用于回答公司产品使用手册相关的问题",
)
tool2 = QueryEngineTool.from_defaults(
query_engine=index2.as_query_engine(),
description="用于回答公司财务报告相关的问题",
)
# 创建ReAct智能体
agent = ReActAgent.from_tools([tool1, tool2], verbose=True)
response = agent.chat("去年营收最高的产品线是哪一条？")
print(response)ReActAgent的工作方式是思考、行动、观察的循环：模型先分析问题决定调用哪个工具，观察返回结果后判断是否需要继续调用其他工具，直到信息足够才给出最终答案。description字段写得越准确，路由正确率越高，这是实践中最值得花心思的地方。开启verbose=True可以看到完整的推理轨迹，调试时非常方便。
如果只想要轻量的路由能力而不需要完整推理循环，也可以用RouterQueryEngine配合LLMSingleSelector，它只做一次工具选择然后直接执行，速度更快、token消耗更少，适合场景固定、问题类型单一的应用。
四、常见问题与调优建议
实践中最常见的问题有三类。第一类是依赖报错，报ModuleNotFoundError时根据提示安装对应的集成包即可。第二类是API Key配置问题，建议把密钥放在环境变量而不是代码里，避免泄露。第三类是检索效果差，回答总是答非所问，这时可以从三个方向排查：调大similarity_top_k提高召回数量、优化切分参数、更换更强的嵌入模型。
另外一个进阶技巧是为检索加上重排序器。默认的向量检索只看相似度，而LLMRerank会用大模型对召回结果二次筛选，在文档量大的场景下提升明显。数据量进一步增大后，再把默认内存索引迁移到Chroma、Milvus等向量数据库，架构上就是一条平滑的演进路径。整体来说，LlamaIndex把RAG和Agent的门槛降到了几行代码的级别，剩下的功夫主要花在数据质量和检索调优上。
LlamaIndexAI智能体数据索引修改时间：2026-09-05 23:57:28