LlamaIndex：面向 RAG 的 LLM 数据框架

为什么需要 LlamaIndex：把模型变成「有数据可用」的系统

大模型本身只拥有训练截止日期前的知识，无法访问企业内部文档、数据库和实时网页。直接把长文档塞进 prompt 会撞上上下文窗口，成本高且关键信息被稀释；微调重训则周期长、费用高，知识一更新又要重来。

RAG 的思路是“先检索、后生成”：从知识库中捞取相关片段，再让模型基于片段回答，知识可随时增删，模型本身保持不变。LlamaIndex 把这条链路工程化：数据加载（官方连接器市场 LlamaHub 提供 400+ 数据源）、文本切分为节点、构建索引、top_k（检索返回的前 k 条最相似片段）召回、答案合成，每一步都是可替换的组件。官方示例十几行代码就能跑通一个知识库问答服务。

与 LangChain 的“通用编排”气质不同，LlamaIndex 把索引与查询当作一等公民，开箱即用的 RAG 组件（查询引擎、聊天引擎、子问题查询）更贴近知识库问答场景；与 Haystack 的生产化管道相比，它 API 演进快、社区示例多，适合快速验证与深度定制。

安装与环境配置：3 步就绪

步骤一 · 创建虚拟环境并安装：建议使用 Python 3.9+。开发体验直接安装全家桶；生产环境推荐安装核心包加按需集成包，避免依赖膨胀。

步骤二 · 配置大模型：默认使用 OpenAI 接口，通过环境变量注入 API Key；也可以切换到 Ollama 等本地模型（llama-index-llms-ollama 集成包）。

步骤三 · 验证安装：导入 Settings 并打印确认，能成功导入即表示安装完成。

# 1) 创建并激活虚拟环境python -m venv .venvsource .venv/bin/activate          # Windows: .venv\Scripts\activate # 2) 安装 LlamaIndex（全家桶，含常用集成）pip install llama-index # 3) 配置大模型 API Key（以 OpenAI 为例）export OPENAI_API_KEY="sk-xxx"     # Windows PowerShell: $env:OPENAI_API_KEY="sk-xxx" # 4) 验证安装python -c "from llama_index.core import Settings; print('LlamaIndex 就绪')"

快速上手：5 分钟跑通第一个 RAG 问答

核心思路只有三步：把文档放进 data 目录 → 用 VectorStoreIndex.from_documents 自动完成加载、切分、向量化 → 用 as_query_engine 提问。

1. 在项目根目录创建 data 文件夹，放入一份 PDF 或 TXT（产品手册、合同文本均可）。

2. 新建 demo.py，写入下方示例代码。

3. 运行 python demo.py，终端会输出模型基于文档内容生成的回答。

进阶技巧：设置 similarity_top_k 控制召回数量，或改用 Ollama 本地模型（llama-index-llms-ollama）在无外网环境运行。

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader # 1. 加载 data 目录下的所有文档documents = SimpleDirectoryReader("data").load_data() # 2. 构建向量索引：自动切分节点、生成 embedding 并入库index = VectorStoreIndex.from_documents(documents) # 3. 创建查询引擎，完成「检索 + 合成」一次问答query_engine = index.as_query_engine()response = query_engine.query("文档中提到的核心结论是什么？")print(response) # 4. 升级为多轮聊天引擎，支持追问chat_engine = index.as_chat_engine()print(chat_engine.chat("再解释一下第 2 点为什么成立？"))

核心能力详解：5 大支柱

支柱一 · 数据连接与解析（LlamaHub）。SimpleDirectoryReader 只能读本地文件，真实企业数据分散在 PDF、Word、Notion、数据库、API 网关中。LlamaHub（llamahub.ai）是官方维护的连接器市场，提供 400+ 加载器与工具节点，覆盖常见 SaaS、数据库与文件格式；配合 LlamaParse 还能把含表格、多栏的复杂 PDF 解析为结构化文本。所有连接器统一暴露 load_data() 接口，切换数据源不改动下游代码。

支柱二 · 文档处理与节点化。加载后的 Document 会按切分器拆成 Node（节点）——Node 是索引与检索的最小单元，携带文本、元数据（文件名、页码、标题）与 embedding。默认 SentenceSplitter 按 1024 字符切分、相邻块重叠 200 字符；也可以按标题结构（MarkdownHeaderNodeParser）切分以提升分段质量，或编写自定义切分器。元数据会被自动注入检索结果，供过滤、重排与引用溯源使用。

支柱三 · 索引与存储抽象。索引是 LlamaIndex 的核心抽象。VectorStoreIndex 走文本相似度检索，是 RAG 默认选择；SummaryIndex 适合小文本的全量摘要；PropertyGraphIndex 保留实体与关系，适合知识图谱问答。索引背后是 40+ 向量数据库实现（Qdrant、PGVector、Milvus、Chroma 等），通过统一的 VectorStore 接口可插拔替换：开发用内存存储，生产切换持久化存储，业务代码不变。

支柱四 · 检索与答案合成。query_engine.query() 内部是“检索器 + 后处理器 + 合成器”的组合。检索器决定召回方式（向量 top_k、混合检索、BM25 融合）；后处理器做去重、相似度阈值过滤、重排序；合成器把命中的节点拼进提示词让模型生成答案。复杂问题可用 SubQuestionQueryEngine 拆成子问题分别检索再汇总；多轮场景用 as_chat_engine 维护对话记忆。

支柱五 · Workflows 与 Agent 编排。0.11 起官方推荐用事件驱动的 Workflows 编排复杂流程：用 @step 装饰异步函数，通过事件传递数据，框架自动解析依赖、支持并行步骤与超时控制。相比串行拼装，Workflows 天然适合“解析→校验→检索→生成→人工确认”这类带分支与并行的业务流。上层 Agent 可通过 function calling 调用查询引擎或工具，把知识库接入对话系统。

生产部署与监控：从上线到运维

部署方式一 · 持久化向量库。默认 from_documents 使用内存向量存储，进程重启即丢失。生产第一步是把索引落到独立向量库：先启动 Qdrant 服务，再用 QdrantVectorStore 替换默认存储，查询路径其余不变。LLM 与嵌入模型统一通过全局 Settings 配置，避免业务代码里到处传参。

部署方式二 · 服务化与托管。把查询引擎封装成 FastAPI 接口对外提供 /query REST 服务，用 Docker 打包镜像，配合前端页面构成知识库产品。不想自建向量库与解析服务时，可使用官方托管 LlamaCloud：托管索引、托管解析（LlamaParse），通过 API 远程查询；文档增量更新用 insert/delete 接口，无需全量重建。

可观测性。生产环境必须能回答“这轮回答依据了哪些片段、得分多少”。通过 CallbackManager 把检索节点、LLM 调用、耗时等事件上报到 Langfuse、Arize Phoenix 等追踪平台；开启日志记录每次查询的检索节点与相似度分数。上线后用 FaithfulnessEvaluator（回答是否忠于原文）与 RelevancyEvaluator（检索内容是否相关）定期抽评，据此调整切分参数与 top_k。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>默认内置内存向量库，进程重启所有索引丢失；生产环境第一步就是接入 Qdrant/PGVector 等持久化向量库并保存 storage_context。</li><li>pip install llama-index 是全家桶安装，会拉取大量集成包导致依赖膨胀；生产环境建议安装 llama-index-core，再按需装 llms/embeddings/vector-stores 对应集成包，降低版本冲突风险。</li><li>0.11 之后 ServiceContext 已废弃，统一用全局 Settings 配置 LLM 与嵌入模型；网上大量旧教程仍在用已移除的写法，运行报错先查版本再查 API。</li></ul>

import qdrant_clientfrom llama_index.core import StorageContext, VectorStoreIndexfrom llama_index.vector_stores.qdrant import QdrantVectorStore client = qdrant_client.QdrantClient(url="http://localhost:6333")vector_store = QdrantVectorStore(client=client, collection_name="company_kb")storage_context = StorageContext.from_defaults(vector_store=vector_store) # 构建时指定 storage_context，索引写入 Qdrantindex = VectorStoreIndex.from_documents(documents, storage_context=storage_context)

版本迭代

LlamaIndex 从 GPT Index 起步，经历单包时代（0.x 早期）→ 0.9 的 Agent 化 → 0.10 的模块化重构 → 0.11 引入 Workflows → 0.12 统一配置与回调 API，主线是把 RAG 从玩具代码变成可维护的生产框架（截至训练数据，可能已有更新版本）。

AI 应用场景

常见误区

面试题

参考来源

• webpageLlamaIndex 官网产品首页与 LlamaCloud 托管入口