企业官网建设流程全解析

LlamaIndex 这个名字，这两年在大模型应用开发圈子里出现频率越来越高。我一开始接触它是因为一个很实际的痛点：模型调用已经很成熟了，API 封装的层数都快比业务代码还厚，但真正把企业内部那几千份 PDF、Markdown、数据库里的业务数据喂给模型时，问题一个接一个冒出来——文本切得不对、检索结果答非所问、上下文塞不下。LlamaIndex 就是冲着这些痛点来的。它不是教你调模型，而是帮你把“数据到模型”这最后一公里打通。如果你正打算做一个文档问答、知识库助手、私有数据 RAG 系统，那这条学习路径应该能让你少走很多弯路。这篇内容不只讲概念，我会把核心组件、动手步骤、检索策略、真实项目骨架和那些踩过的坑一次性梳理清楚。

1. 为什么是 LlamaIndex：核心定位与设计思路

1.1 它解决的不是“调用模型”，而是“喂数据”

很多新手容易误解 LlamaIndex 的性质，以为它是和 OpenAI SDK 类似的东西——实际上它更像是一个数据框架。区别在哪里？用一句话概括：OpenAI SDK 解决的是“怎么把 prompt 发给模型”，LlamaIndex 解决的是“怎么从一堆杂乱数据里找到该进 prompt 的那几段内容”。

举个我实际遇到的例子。当时要做一个面向公司内部的规章制度问答系统，原始材料有 Word 文档、Excel 表格、扫描版 PDF。直接把这些文件丢给模型，结果必然是：文档太长超出上下文窗口；PDF 扫描件识别出来之后文字错乱；表格数据被切得支离破碎，检索出来的内容牛头不对马嘴。LlamaIndex 的做法是把这些原始数据先加载成标准化的 Document，再切分成语义完整的 Node，每段文本算好向量和索引，查询进来后先做检索，再把最相关的片段组装成上下文给模型。整个过程像一条数据流水线：原始文件进入，经过拆解、加工、索引，最终产出模型可以直接使用的结构化知识。

它真正擅长的是异构数据的统一接入。不管是本地文件、数据库、API、网页，还是云盘上的共享文档，框架都提供对应的 Reader 或者加载器。这也是我后来坚持选它而不是自己手写脚本的原因——数据源的类型太多了，每类都自己去写解析逻辑，工作量根本扛不住。

1.2 和 LangChain 的边界在哪里

那个经典的“LlamaIndex 和 LangChain 怎么选”问题，我自己的定位是这样：LangChain 更像个瑞士军刀，它什么都能干，链、代理、工具调用、记忆管理一应俱全，整个生态覆盖面很宽；LlamaIndex 则像一把专门打磨过的凿子，专注做知识和数据索引这一件事，尤其是 RAG 场景，它的抽象更贴合这个领域。

实际项目里可以这样搭配使用：用 LangChain 管理 Agent 的整个执行流程和工具调度，用 LlamaIndex 承担数据加载、索引构建、检索和问答这一核心环节。两个框架之间有官方集成包llama-index-integrations-langchain，可以把 LlamaIndex 的查询引擎包装成 LangChain 的 Tool 来调用。我给团队做技术选型时的判断标准很简单：如果你的核心产品就是一个知识库问答系统，那直接用 LlamaIndex 就够了，不用引入额外的复杂度；如果你的产品要做多步骤任务编排，比如先查天气再订酒店再写行程，那 LangChain 会更合适。

2. 学习的第一站：核心概念对象模型

2.1 Document 与 Node：从“整份文件”到“最小知识单元”

LlamaIndex 里有两个最基础的数据对象，几乎绕不开。Document 是原始数据的载体，你可以理解为“一整份文件”，里面包含text文本内容和一组metadata元数据，比如文件名、页数、作者、日期等。因为数据源五花八门，Doc 文档可能是一份 PDF 里的全部文字，也可能是一个数据库表的查询结果。

Node 才是真正被索引和检索的最小单元。它是由 Document 切分出来的“知识片段”。为什么不能直接用 Document 来检索？这个道理其实很生活化：你要在一本 300 页的书里找“合同审批流程”，直接把整本书丢给模型是不现实的，你得先通过目录或者页码定位到相关章节，再把那几页内容拿过来。Node 就是那个“章节”或“页面”。切分质量直接决定检索质量，这一点我会在后面的实操部分重点展开。

创建 Node 最典型的两种方式：一种是直接用SentenceSplitter之类的文本切分器把 Document 切成多个 Node；另一种是手写代码逐段构建TextNode对象，把文本、元数据手动塞进去。框架还支持“父子节点”关系，比如一个 Node 是概述性摘要，它的子 Node 才是详细段落——这在做精炼摘要式回答时很实用。

2.2 Index：数据的组织结构

Index 是整个框架里最核心的概念，也可以理解为“书前面的目录页”。之所以叫索引，是因为它不只存了文本，还存了文本对应的向量表示、关键词映射、摘要关系等结构，让后续检索可以在“索引”上而不是“原始数据”上操作。

LlamaIndex 内置了多种索引类型，每种适合不同的场景。我用一个表格帮你快速建立心智模型：

我个人的使用比重是：VectorStoreIndex 占了日常项目 80% 以上，其余索引类型大半是在特定场景里作为补充。初学者不用一上来就全部掌握，先把向量索引吃透，其他的知道有这个东西、遇到相应场景时回来查用法就够了。

2.3 Retriever 与 QueryEngine：查询链路的核心

Index 构建好之后，查询不会直接访问索引，而是要经过两个环节：Retriever 负责“找”，QueryEngine 负责“答”。

Retriever是检索器，它接收一个查询文本，在索引里找出最相关的若干 Node。不同索引会有默认的 retriever，例如向量索引默认用VectorIndexRetriever，会在嵌入空间里找余弦相似度最高的 Top-K 个节点。你也可以自定义 retriever，比如先按关键词过滤，再在过滤结果里做向量排序，这种“粗筛+精排”的方式在业务数据很脏、噪声很大的时候非常有效。

QueryEngine是查询引擎，它在 retriever 拿到候选节点后，把这些节点的文本拼装成上下文模板，连同用户的原始问题一起交给 LLM 生成回答。这里有个关键点：QueryEngine 的“检索 → 拼装 → 生成”链路不是黑盒，每一段都可以替换。你可以在RetrieverQueryEngine里传入自定义 retriever，也可以换一个 response synthesizer 来改变答案的生成方式（比如只取最相关的一段做精炼回答，还是把所有上下文全塞给模型做扩展回答）。

整个链路我在团队内部用最通俗的比喻来讲：Index 是图书馆的书架分类系统，Retriever 是图书管理员——他根据你的问题去书架上抽几本书出来，QueryEngine 是阅读助理——他翻开这几本书，把相关内容整合成一段回答给你。

3. 动手第一步：环境准备与第一个 RAG 示例

3.1 依赖安装与版本选择

环境准备没有太多花哨的内容，但版本坑不少。LlamaIndex 的包名从 0.6 版本之后做了比较大规模的重构，早期的from llama_index import ...在新版本里往往变成了from llama_index.core import ...。我建议直接装最新稳定版，避免照着老教程装旧包结果 API 对不上。

核心安装命令是这个：

pip install llama-index

这个命令会把llama-index-core和一堆默认集成插件一起装上。如果你的项目里用了特定的向量数据库、特定的大模型 API，还需要另装对应的集成包，比如用 OpenAI 做嵌入和生成时：

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

使用 Chroma 做向量存储的话：

pip install llama-index-vector-stores-chroma

你还需要在环境变量里配置 API Key。我习惯用.env文件管理，避免把密钥写进代码库：

export OPENAI_API_KEY="sk-..."

当然，LlamaIndex 并不强制你用 OpenAI 系产品。你可以通过Settings.llm和Settings.embed_model注入任何你选中的本地模型或第三方 API。国内用本地化部署的场景越来越多，比如接入 Qwen、GLM 这类兼容 OpenAI 接口的模型，在Settings里做好替换就行。

3.2 加载数据并构建向量索引

环境就绪后，我们跑一个最经典的例子：对本地一个目录里的 PDF 和 Markdown 文件构建向量索引。第一步是加载数据，框架提供了SimpleDirectoryReader，一行代码就能把整个目录扫进来。

from llama_index.core import SimpleDirectoryReader documents = SimpleDirectoryReader("./data").load_data() print(f"共加载 {len(documents)} 份文档")

SimpleDirectoryReader会根据文件扩展名自动选择对应解析器，PDF、DOCX、MD、TXT 这类常规格式是开箱即用的。但这里要注意，它只是把文本抽出来，扫描版 PDF 不会自动做 OCR——遇到这种情况需要先在外面用 OCR 工具把图像转成文本层，再来加载。

接着把 documents 交给索引：

from llama_index.core import VectorStoreIndex index = VectorStoreIndex.from_documents(documents)

这句话背后做的事远比你看到的复杂：框架先把 Document 切分 Node，然后调用嵌入模型给每个节点生成向量，再把这些向量和文本一起写入默认的向量存储（内存中的SimpleVectorStore）。整个过程封装得很干净，第一次跑起来你会觉得“就这？”——但要有意识地去替换底层组件，后面才不会被默认实现的简易程度卡住。

3.3 构造查询引擎并对话

索引建好后，查询就很简单了：

query_engine = index.as_query_engine() response = query_engine.query("我们公司对请假的审批流程是怎么规定的？") print(response)

response对象里不仅有答案文本response.response，还附带了检索来源节点response.source_nodes。这个特性在开发调试时非常受用：如果答案不对，第一件事就是看检索到的节点是不是正确的。如果检索到的文本本身就牛头不对马嘴，那问题出在检索端；如果检索到的文本对了但答案还是不对，那问题出在生成端。这个排查思路贯穿我写过的所有 RAG 系统的调试过程。

我还建议把检索过程的明细打印出来，看看每个命中的 node 的相似度分数和原文片段：

for node in response.source_nodes: print(f"相似度: {node.score:.4f}") print(node.node.get_text()[:200]) print("---")

这一步能帮你快速定位系统选错了还是答错了。新手上路，最怕上来就调大模型 promopt，真正的病根十有八九在检索质量上。

4. 进阶之路：持久化存储、检索策略与工作流

4.1 索引持久化与增量更新

内存里的索引重启就没，这在开发环境还能接受，上线后肯定不行。LlamaIndex 提供了持久化能力，把索引和文档保存到磁盘或向量数据库。

from llama_index.core import StorageContext storage_context = StorageContext.from_defaults(persist_dir="./storage") index.storage_context.persist(persist_dir="./storage")

之后从磁盘重新加载：

from llama_index.core import load_index_from_storage storage_context = StorageContext.from_defaults(persist_dir="./storage") index = load_index_from_storage(storage_context)

在真实生产环境里，我更推荐直接用外部向量数据库（FAISS、Chroma、Milvus、Qdrant 等）作为索引存储，而不是框架内置的SimpleVectorStore。原因很简单：SimpleVectorStore 每次重新加载都要把所有向量读进内存，数据量一大就卡。切换到向量数据库的写法也很顺，以 Chroma 为例：

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

增量更新索引时，不推荐把新文档全都塞进VectorStoreIndex.from_documents()重新构建一遍，那相当于全量重建。更合适的做法是对已有索引调用insert()或add_nodes()：

index.insert(document)

但要注意，如果你用的是from_documents()构建的索引，调用insert()之前你必须先显式地创建StorageContext并且拿到离线索引本身——不能对上一步from_documents返回的临时索引直接 insert 之后就当持久化完成了。这里的坑我返工过两次，建议把 storage_context 单独管理，需要增量更新时始终复用同一个 storage 实例。

4.2 检索策略：从单路召回到底层定制

向量检索是默认方案，但在真实业务里完全不够用。比如用户问“2024年第一季度销售数据”，如果前期切分时把“一季度”和“销售”分散在不同的块，向量检索的相似度排序可能给出极其零散的内容。这时要用混合检索，把向量相似度和关键词匹配结合起来，让命中关键词的节点优先浮上去。

LlamaIndex 里的 Hybrid Retriever 可以融合 BM25 和向量召回：

from llama_index.core.retrievers import QueryFusionRetriever from llama_index.retrievers.bm25 import BM25Retriever from llama_index.core import VectorStoreIndex vector_retriever = index.as_retriever(similarity_top_k=5) bm25_retriever = BM25Retriever.from_defaults(docstore=index.docstore, similarity_top_k=5) fusion_retriever = QueryFusionRetriever( [vector_retriever, bm25_retriever], similarity_top_k=5, num_queries=1, mode="reciprocal_rerank", )

mode="reciprocal_rerank"是 RRF 融合排序策略，会在多个召回来源之间取排名倒数的加权和，效果通常比较稳。这个方法尤其适应那些术语很明确的场景，比如系统报错信息、工单标题、产品名称，关键词的作用比语义更大。

除了融合检索，还可以做“查询改写”。也就是先让 LLM 把用户的原始问题转成几个不同角度的子问题，再分别检索、汇总结果。代码里用QueryFusionRetriever并设置num_queries大于 1，它就会自动做这个扩展。代价是多几次大模型调用，但检索覆盖率提升非常明显，推荐在内容噪声大、问题又很口语化的场景里尝试。

4.3 Workflow 与 Agent：从“一问一答”走向复杂任务

框架一直在迭代，在 0.10 之后的版本里，workflow取代了过往很多CustomRetriever的零散方案，成为构建复杂多步骤逻辑的更统一的方式。我第一次用 workflow 是在做一个“文档问答 + 数据汇总”的需求：用户先问一句，系统要决定是去企业知识库检索，还是去查询实时数据库，或者两个都要，最后把多个来源的结果汇到一起回答。

Workflow 的设计模式简单说就是：定义若干步骤（step），每个步骤有关键字标记，通过ctx（上下文对象）在步骤之间传递数据，用@step装饰器把逻辑挂进工作流。核心代码如下：

from llama_index.core.workflow import ( Context, Workflow, StartEvent, StopEvent, step, ) class MyWorkflow(Workflow): @step async def retry_if_empty(self, ev: StartEvent) -> StopEvent: query = ev.query results = await some_retriever.aretrieve(query) if not results: return StopEvent(result="没找到相关内容") return StopEvent(result=str(results)) w = MyWorkflow(timeout=60, verbose=False) result = await w.run(query="你的问题")

Workflow 里有超时、重试、并发这些可配置项，适合承载生产级逻辑。Agent 则更像一个“自主决策的大脑”，它判断用户需要哪些工具、按什么顺序调用，然后执行工具、观察结果、继续决策。如果你已经掌握了 QueryEngine，下一步建议学 Agent，因为很多复杂任务可以组合成若干工具，Agent 来调度它们是比硬编码 workflow 更可扩展的方案。

5. 实战复盘：一个企业知识库问答系统的完整骨架

5.1 需求定义与整体架构

用前面这些思路，我把一个真实项目串起来给你看。需求不复杂：把公司内部的《产品手册》《FAQ 文档》《售后记录》三类资料整合成一个能回答用户问题的系统，要求答案必须附可靠来源，最好能定位到具体章节。

整体架构分为四层：

• 数据层：原始文件集中在docs/目录，格式包含 Markdown 和三份大型 Excel 结构化的 FAQ。
• 处理层：用 Reader 加载，用SentenceSplitter切分，嵌入模型生成向量。
• 索引层：向量索引存到 Chroma，持久化在本地。
• 服务层：用 FastAPI 暴露查询接口，内部调用 QueryEngine。

5.2 数据加载与预处理

加载时最需要留意的是 Excel 和 Markdown。SimpleDirectoryReader 对大部分文本格式都好用，但对 Excel 的处理经常出现“一整张表变成一个超大文本块”的情况。我的做法是先把 Excel 按行拆开，每一行转成一条带业务语义的文本，再构造 Document。这一段“脏活”没办法完全靠框架自动完成，属于常见的数据预处理工程。

import pandas as pd from llama_index.core import Document df = pd.read_excel("docs/faq.xlsx") documents = [] for _, row in df.iterrows(): text = f"问题：{row['question']}\n答案：{row['answer']}" metadata = {"category": row.get("category", "FAQ"), "source": "faq.xlsx"} documents.append(Document(text=text, metadata=metadata))

再强调一次元数据的重要性。给每个节点打上来源文件名、分类标签之后，你可以按类别过滤、按来源追溯，非常实用。没有元数据，出错了都不知道这个结论是哪份文档里来的。

切分参数也是反复调出来的。我用的是SentenceSplitter：

from llama_index.core.node_parser import SentenceSplitter splitter = SentenceSplitter(chunk_size=512, chunk_overlap=64, separator=" ")

chunk_size 512、overlap 64 这组参数是我在绝大多数文档类场景的默认起点。chunk_size 太小，句子被切得七零八落，检索时语义不完整；chunk_size 太大，相近节点内容高度重复，检索时容易找到一堆重复片段还挤占上下文窗口。chunk_overlap 的作用是让切分边界附近的语义尽量连贯——你可以理解为：两段内容之间留有重叠区域，就像两个人传递接力棒时，两只手必须重合那么一小段才不至于掉落。

5.3 构建查询链路与 API 封装

数据处理好后，构建索引并封装成服务：

from llama_index.core import VectorStoreIndex, StorageContext, Settings from llama_index.embeddings.openai import OpenAIEmbedding from llama_index.llms.openai import OpenAI from llama_index.vector_stores.chroma import ChromaVectorStore import chromadb Settings.llm = OpenAI(model="gpt-4o-mini", temperature=0.1) Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small") client = chromadb.PersistentClient(path="./chroma_db") collection = client.get_or_create_collection("knowledge_base") vector_store = ChromaVectorStore(chroma_collection=collection) storage_context = StorageContext.from_defaults(vector_store=vector_store) index = VectorStoreIndex.from_documents(documents, storage_context=storage_context, show_progress=True)

之后服务层直接用 FastAPI 暴露：

from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() query_engine = index.as_query_engine(similarity_top_k=5) class QueryBody(BaseModel): question: str @app.post("/query") async def query(body: QueryBody): resp = query_engine.query(body.question) sources = [{"text": n.node.get_text()[:200], "score": n.score} for n in resp.source_nodes] return {"answer": str(resp), "sources": sources}

实际的问答效果还算理想，但有两个额外的小改动让表现提升明显。第一个是给查询引擎加了 system prompt 约束，严格限定“只能基于检索内容回答，检索不到时直接说不知道”，避免模型编造。第二个是对用户输入先做了一遍敏感词和敏感内容的过滤，不是模型能力的问题，而是企业数据需要更高的内容合规控制。这一步在任何企业级系统里都不要省。

6. 高频问题与排查经验实录

6.1 检索结果质量差，怎么排查

这个问题得从三个方向逐步排查。先看数据源——加载出来的文本是不是正确的？PDF 扫描件没有 OCR、Excel 解析错位、HTML 里的广告噪声被一起加载进来，这些都属于源头问题。再看切分粒度——节点过小导致语义断裂，或者节点过大导致多个主题混在一起，这些在查询结果里会表现为命中的片段“看起来沾边但就是不对”。最后看检索策略——单路向量召回打不过复杂问题，换成混合检索或查询改写通常会有显著提升。

我分享一个高效的做法：不用等整个服务搭好，直接在 Jupyter 里把每个中间层的输出都摆出来，看到加载出的文本 → 切分后的节点 → 查询命中的片段，每层都问一句“如果我是人，看到这些内容能回答问题吗”。如果一个中间层已经错了，后面再怎么调模型都是白费力气。

6.2 向量检索的本地模型与长文档性能

有些朋友在离线或隐私要求高的环境里无法调用在线嵌入 API。LlamaIndex 接入本地模型并不复杂，但有一个明显的性能坑：本地 embedding 模型的维度、速度、显存占用差异很大。维度太低的模型在语义细节上容易吃瘪，维度高的模型又会让向量检索变慢。我的做法是先用开源模型跑一个小规模验证，把维度压到可控区间，再根据业务数据量评估是否需要上 GPU 推理服务。

长文档处理性能也容易翻车。几千页的 PDF 全部切分并生成向量，耗时主要集中在嵌入生成和向量写入。不要一次性全塞进内存；大量文档在本地跑的时候，我习惯先逐文件切分，再分批调用index.insert()，并且开启show_progress=True观察进度。索引建好之后再查一次，速度通常就回到毫秒级了，慢的只是构建阶段。

6.3 元数据与来源引用的缺失问题

使用SimpleDirectoryReader加载时，每个节点默认会带上file_path和file_name这些来源信息。但如果你像我一样手动从 Excel 构造 Document，很容易把元数据字段漏掉。没有元数据的后果是：回答结果里无法定位到具体来源，整个系统的可信度掉一大截。

补救做法是在构造 Document 时强制写好元数据：

doc.metadata["source_file"] = "faq.xlsx" doc.metadata["row_index"] = str(idx)

然后在查询时通过MetadataFilters做文件和分类级别的过滤，这也是给数据“上权限”的基础。如果你要做一个不同部门只能查询各自资料的系统，这部分必须提前规划，否则后期改索引结构会很痛苦。

6.4 上下文窗口不够用怎么办

查询时命中的节点太多，全部拼接后 prompt 超长，这种情况很常见。办法有几种：调小similarity_top_k，比如从 5 降到 3；在 response synthesizer 里用 “compact” 模式，让程序自动压缩和裁剪上下文；对检索节点先做一次摘要再拼进上下文。我更推荐最后一种，因为它既保留关键信息又能大幅削减 token 占用。

如果数据本身太大，另一个思路是搭多级检索：先用摘要索引对文档做全局概览，再依据概览下钻到具体节点。这种“先粗后细”的方式在处理长文档问答时稳定性和效果都远超单纯加大 chunk 的做法。

学习路径最后的一点点建议

在做 LlamaIndex 相关项目时，我个人的体会是：框架的学习曲线并不陡，真正的难度在于你对自己数据的理解。很多人在网上找了一大堆教程、项目模板，上来就仿照别人的代码把索引堆起来，但最后生产效果差，往往是因为没有认真想清楚自己的文档该怎样切分、元数据该怎样组织、检索策略该怎样调整。技术方案永远要围绕内容形态来设计。

关于后续扩展，我强烈建议在掌握基础索引和查询引擎之后，把精力投入到检索策略和 Agent 工作流上。前者决定你回答质量的上限，后者决定你能承接的业务复杂度。如果你有具体的项目场景，别怕从最简单的版本开始，跑通之后再一层层加策略。LlamaIndex 这框架最友好的地方就是组件高度可替换，你今天用默认的 SimpleVectorStore，明天换成 Milvus，代码改动量很小。先把最小闭环做出来，比憋一个大而全的架构要实用得多。