用LlamaIndex一条命令跑通RAG全链路：建库、召回、重排、生成

在本地跑了几个月RAG项目，我越来越觉得，大多数人第一次接触 LlamaIndex 时不是被模型难倒，而是被“建库、召回、重排、生成”这四个环节之间的脱节搞崩溃。你辛辛苦苦写完 Embedding 和建库逻辑，到了查询阶段又得处理 Retriever 返回的节点，还要为了效果再挂一层 Rerank，最后手动拼接 Prompt 调用 LLM。每一步单独看都不复杂，可串起来却总在细节上翻车。折腾过几次之后，我把这套流程收敛成了一个脚本，一行命令直接跑完：先判断索引存不存在，不存在就自动建库，存在就直接进入召回→重排→生成，整个过程每一步都有日志输出。如果你正在做文档问答、私有知识库、技术客服这类项目，这篇东西应该能帮你少走不少弯路。

1. RAG 全链路的核心矛盾与一条命令的价值

1.1 建库→召回→重排→生成，四个环节到底在做什么

先别急着写代码，把四个词拆开看清楚。

建库解决的是“知识在哪里”的问题。原始文档是一堆散文、表格、标题，模型不能直接理解整本书。你需要先按一定策略把文档切成文本块，给每块文本算一个向量，然后把向量和原始文本一起存到索引里。这一步决定了后续所有链路的上限。很多人把建库想得太简单，以为扔给框架就行，实际上切分粒度、元数据、存储方式都会直接影响最终回答质量。

召回解决的是“找哪些内容”的问题。用户提问后，系统把问句向量化，在向量索引里找最相似的 K 个文本块。这里的关键是“速度快、别漏”：宁可多召回一些不相关的，也不能漏掉真正包含答案的片段。这个过程类似海选，标准可以宽松一点。

重排解决的是“哪些内容真正有用”的问题。向量召回基于embedding相似度，但语义相似不等于能回答问题。比如“年假怎么算”和“年假的申请流程”向量距离很近，但后者可能根本不包含答案。重排模型会更精细地计算“查询-片段”的相关性，把真正有用的片段排到最前。海选之后做一轮复试，过滤掉噪音，这是RAG效果质变的关键。

生成解决的是“如何有依据地说人话”的问题。把重排后的少量片段按模板拼进Prompt，交给大模型生成答案。同时要求模型引用片段中的内容，能显著降低幻觉。如果少做或跳过重排，Prompt里塞进去的噪音太多，大模型就容易被带偏。

这四个环节缺一不可。但传统的做法是四个环节各自独立脚本，开发者既要管中间产物，又要小心不同脚本里模型配置不一致。我实际遇到过的案例：建库脚本里用的 Embedding 模型是英文版，查询脚本里换成了中文模型，向量维度都没变，运行不报错，结果检索结果莫名其妙。一条命令把全流程串起来，至少能减少这类低级错误。

1.2 为什么选择 LlamaIndex，而不是从零轮子

如果你只是做原型，手动用 SentenceTransformer 算向量再加 sklearn 的余弦相似度也能跑通，但那仅限于几十个文本块的 Demo。一旦进入真实场景，你很快会遇到这些问题：文档格式多种多样，有 PDF、Word、Markdown、HTML；一个文档可能几百页，切分策略需要定制；你需要保存中间状态，下次启动不能全部重新算；你还可能要接不同的向量库、不同的大模型接口。

LlamaIndex 最核心的价值不是某个单一算法多强，而是把“文档加载→文本解析→索引构建→检索→后处理→生成”整条链路抽象成了统一接口。它的数据连接器能读一堆文件格式，节点解析器负责切分，VectorStoreIndex 负责向量化与存储，Retriever 负责召回，NodePostprocessor 负责重排，最后通过 Query Engine 或者自定义流程交给 LLM。传入同样的数据，你可以在不改变主流程的情况下切换不同的 Embedding 模型、向量数据库和后端大模型。

更关键的是，LlamaIndex 在工程上留了持久化机制：索引构建好之后，向量、文档映射、索引元数据都能存到本地目录。下次启动直接从磁盘加载，而不是每次从零建模。这一条直接让“一条命令跑全流程”成为可能——建库是一次性工作，之后每次启动都只是加载索引并查询。

1.3 “一条命令”不是炫技，而是工程化的基石

为什么不写多个脚本，比如build_index.py和query.py，而非要合并成一个命令？因为“入口单一”本身就是一种工程约束。在团队协作中，新同事拿到仓库后只需要跑一条命令，不用去翻 README“先执行 A 再执行 B”；在自动化任务中，定时重建索引也只需要在 Cron 里写一行；在排障时，我们只需要看一条命令的日志流，中间不会出现“上次重建索引用的模型和这次不一致”的诡异问题。

有人会觉得“一条命令”意味着参数被写死、扩展性差，其实恰恰相反。一个设计良好的 CLI 入口，可以通过参数控制文档目录、索引目录、Top K 值、重排数量、是否强制重建，默认值满足大多数场景，同时开放自定义。这也是我推荐大家照着这个思路去搭建自己项目的核心原因。

2. 环境准备与组件选型

2.1 依赖清单与安装命令

在开始写代码前，先把环境准备好。我建议用 Python 3.10 或更高版本，开一个干净的虚拟环境，避免和项目依赖冲突。以下是我在这套流程里实际使用的核心依赖：

pip install llama-index-core pip install llama-index-readers-file pip install llama-index-embeddings-huggingface pip install llama-index-llms-ollama pip install sentence-transformers

llama-index-core是 LlamaIndex 的核心库，提供文档加载、索引、检索等主流程；llama-index-readers-file让 SimpleDirectoryReader 支持更多文档格式；llama-index-embeddings-huggingface负责接入 Hugging Face 上的 Embedding 模型；llama-index-llms-ollama用于连接本地部署的推理服务；sentence-transformers是我们自定义重排器时要用到的 CrossEncoder 工具包。

如果你后面打算用 Chroma、Qdrant 或者 Milvus，需要再装对应的扩展包。但在起步阶段，我强烈建议先用 LlamaIndex 自带的SimpleVectorStore，它不需要额外启动服务，索引可以直接持久化到本地目录，足够跑通整条链路。

2.2 Embedding、Rerank、LLM 三个模型的选型

Embedding 模型：这个环节决定文本向量化的质量。中文场景下，我优先推荐 BGE 系列，尤其BAAI/bge-small-zh-v1.5，维度 512，对 CPU 和内存都比较友好，效果也能满足大多数场景。如果机器条件更好，可以换BAAI/bge-base-zh-v1.5，维度 768，准确率会更高一些。再往上还有BAAI/bge-m3，支持多语言和长文本，但资源占用也大很多。记住一个原则：建库和查询必须使用同一个 Embedding 模型，换模型就必须重新建库。

Rerank 模型：我用的是BAAI/bge-reranker-base。它和bge-reranker-large相比，速度更快，效果差距并没有想象中那么大。重排模型通常比 Embedding 模型大不少，如果内存紧张，建议用量化版本或者放在 GPU 上。还有一个无法回避的现实：重排是逐对计算的，性能和 Top K 直接相关，所以不要一开始就把重排数量设成好几十。

LLM 模型：为了隐私和成本控制，我优先用本地 Ollama 部署的开源模型，比如qwen2.5:7b。你只需要在代码里替换成你自己的服务地址和模型名就行。如果公司内部有其他兼容 OpenAI 协议的统一推理平台，也完全可以接入，LlamaIndex 的 LLM 抽象层会帮你统一处理。

2.3 存储方案与向量检索的直观理解

起步阶段，默认的SimpleVectorStore是最合适的。它本质上就是把向量存在内存里，然后序列化到本地目录。你不需要去装一个 Vector Database，也不用配置连接字符串。等你索引条目到了几十万级，或者需要多人并发查询、复杂过滤、动态更新时，再迁移到 Chroma 或 Milvus 也不迟。

向量检索是怎么工作的？简单说，每个文本块被 Embedding 模型映射成一个高维向量，查询时同样把问句映射成向量，然后计算两个向量之间的余弦相似度。余弦相似度公式是向量点积除以模长乘积，结果区间在 -1 到 1 之间，越接近 1 表示方向越一致、语义越相关。比如二维向量 [1,0] 和 [0,1] 的余弦相似度是 0，它们正交，可以理解成完全不相关；[1,0] 和 [0.99,0.01] 的余弦相似度接近 1，则方向非常接近。

这也是为什么 RAG 要配合重排——余弦相似度衡量的是语义分布是否接近，但无法直接判断“这段文字是否包含问题的答案”。重排器会以更精细的交互方式（把查询和候选文本拼起来）重新打分，把相似但无用的内容压下去。

3. 从零搭建：索引构建与核心参数取舍

3.1 文档加载与常见格式坑

LlamaIndex 里最简单的方式是用SimpleDirectoryReader读取一个目录下的所有文件。它的实现足够聪明，能根据文件扩展名自动选择解析器。但实际项目里，文档格式往往是最大的坑。

先说 PDF。很多 PDF 是从打印系统导出的，没有文本层，直接解析会得到一堆乱码或者大量空白。即便有文本层，复杂的表格和排版也会被打乱顺序。我的建议是：PDF 优先转成 Markdown 或者纯文本再喂给索引器，如果 PDF 是扫描件，先走一层 OCR 转换，否则后续无论检索还是重排都会受到极大影响。

再说 Word。SimpleDirectoryReader对 docx 的支持不错，但前提是你安装了对应的依赖。如果你遇到“文件存在但读取不到内容”的情况，先检查是不是缺少解析库，比如读取 docx 需要安装python-docx。

表格数据是另一类麻烦。如果文档里全是表格，直接按段落切分会把表格拆得七零八落。我建议在进入 RAG 之前，把表格转换为 Markdown 表格格式，因为 Markdown 表格在文本切分时还能保留结构语义。标题、列表、注释也同理，尽量保留结构信息，有助于后续检索时区分主次。

3.2 文本切分参数：chunk_size、overlap、metadata

文本切分是建库环节最值得花时间调的部分。LlamaIndex 默认的SentenceSplitter已经能处理大多数情况，但你需要理解两个关键参数：chunk_size和chunk_overlap。

chunk_size控制每个文本块的最大字符数。我实测下来，中文场景下512是一个比较稳的起步值。这个数字太小，比如 128，一个完整的技术方案会被切成好几块，回答问题时就容易找不到完整上下文；数字太大，比如 2048，一个块里包含太多段落，向量语义会被稀释，而且最终 Prompt 塞进去也容易超长。当然，这不是死的，如果你的文档本身逻辑块很大，可以适当调大。

chunk_overlap控制相邻文本块之间的重叠字符数。为什么要重叠？因为切分点很可能落在一个句子或概念中间，有了重叠，后半段文档的起始部分会在前一个块里再出现一次，避免关键信息正好被切掉。我通常设置为50到100，大约控制在chunk_size的 10% 到 20%。如果你的文档里天然有清晰的 Markdown 标题分级，也可以考虑用MarkdownNodeParser，它会更智能地按标题层级切分，而不是硬切长度。

还有一个容易被忽略但非常重要的点：给文本块挂 metadata。比如file_path或page_number，这样生成答案时可以通过node.metadata拿到来源，在 Prompt 里展示“参考来源”，或者在 UI 上高亮对应的 PDF 页码。没有来源的 RAG 很难让人信任。

3.3 向量化与索引持久化

文档切好之后，就到了 Embedding 和索引构建环节。LlamaIndex 的VectorStoreIndex会逐块调用 Embedding 模型，把文本块向量化，然后写入存储。如果你有 1 万个文本块，每个块在 CPU 上做 Embedding 大约需要 0.1 到 0.5 秒，全量建库可能就得半小时以上。耐心等，不要在中途频繁打断进程，否则容易写出不完整的向量文件。

持久化其实很简单，核心代码如下：

storage_context = StorageContext.from_defaults(persist_dir="./storage") index = VectorStoreIndex.from_documents(documents, storage_context=storage_context) storage_context.persist()

持久化之后，storage目录里会出现多个 JSON 文件，分别存向量、文档关系、索引元数据。以后加载索引只需要：

storage_context = StorageContext.from_defaults(persist_dir="./storage") index = load_index_from_storage(storage_context)

这里有一个很重要的工程经验：索引和 Embedding 模型是绑定在一起的。如果你升级了 Embedding 模型，或者改变了切分参数，必须强制重建索引，否则旧索引和新查询向量无法对齐。这也是为什么我的脚本里保留了一个--force-rebuild参数，专门用于这种“配置变更后的重建”。

4. 一条命令跑通全流程：完整的可复现工程

4.1 工程目录与 CLI 设计

我做这套脚本时，目录约定如下：

rag_pipeline/ ├── data/ # 放原始文档 ├── storage/ # 索引持久化目录 └── local_rag.py # 主脚本

主脚本接收以下参数：

我不建议一开始设计一堆花哨的接口，上面这几个参数已经覆盖绝大多数场景。top-k和rerank-top-n是你在做效果评测时最常调整的两个旋钮，后面会细讲。

4.2 完整代码：从建库到生成一步到位

下面是完整的local_rag.py。我把流程拆成了四个子步骤，并且用日志打印每一步，方便排查。这段代码基于 LlamaIndex 0.10.x 的 API 编写，如果你用的是其他版本，可能需要小幅适配。

import argparse import os import time from typing import List # LlamaIndex 核心 from llama_index.core import ( SimpleDirectoryReader, VectorStoreIndex, StorageContext, load_index_from_storage, Settings, ) from llama_index.core.schema import BaseNode from llama_index.core.schema import QueryBundle from llama_index.core.node_parser import SentenceSplitter from llama_index.core.postprocessor.types import BaseNodePostprocessor # Embedding 和 LLM from llama_index.embeddings.huggingface import HuggingFaceEmbedding from llama_index.llms.ollama import Ollama # 重排模型 from sentence_transformers import CrossEncoder # 配置全局模型 Settings.embed_model = HuggingFaceEmbedding( model_name="BAAI/bge-small-zh-v1.5" ) # 根据你的本地推理服务修改 model 和 base_url Settings.llm = Ollama( model="qwen2.5:7b", request_timeout=120.0, ) # 自定义重排后处理器 class LocalReranker(BaseNodePostprocessor): def __init__(self, model_name: str = "BAAI/bge-reranker-base", top_n: int = 5): super().__init__() self._model = CrossEncoder(model_name) self._top_n = top_n @property def _node_type(self) -> str: return "Node" def postprocess_nodes( self, nodes: List[BaseNode], query_bundle: QueryBundle, **kwargs ) -> List[BaseNode]: if not nodes: return nodes pairs = [(query_bundle.query_str, node.get_content()) for node in nodes] scores = self._model.predict(pairs) scored_nodes = list(zip(scores, nodes)) scored_nodes.sort(key=lambda x: x[0], reverse=True) return [node for _, node in scored_nodes[: self._top_n]] def build_index(data_dir: str, index_dir: str, force_rebuild: bool): """建库：读取文档→切分→向量化→持久化""" if os.path.exists(index_dir) and not force_rebuild: print("[建库] 检测到已有索引，跳过建库步骤") storage_context = StorageContext.from_defaults(persist_dir=index_dir) return load_index_from_storage(storage_context) print(f"[建库] 开始读取目录: {data_dir}") documents = SimpleDirectoryReader( input_dir=data_dir, required_exts=[".md", ".txt", ".docx", ".pdf"], recursive=True, ).load_data() print("[建库] 开始切分文本...") splitter = SentenceSplitter(chunk_size=512, chunk_overlap=50) nodes = splitter.get_nodes_from_documents(documents) print(f"[建库] 共切分 {len(nodes)} 个文本块，开始向量化...") storage_context = StorageContext.from_defaults(persist_dir=index_dir) index = VectorStoreIndex(nodes, storage_context=storage_context) storage_context.persist() print("[建库] 索引构建完成并已持久化") return index def retrieve(index, query: str, top_k: int): """召回：从索引中获取候选节点""" print(f"[召回] 开始向量召回 top {top_k} ...") retriever = index.as_retriever(similarity_top_k=top_k) nodes = retriever.retrieve(query) print(f"[召回] 得到 {len(nodes)} 个候选片段") return nodes def rerank(nodes, query: str, rerank_top_n: int): """重排：用 CrossEncoder 对候选片段二次打分""" print(f"[重排] 开始精排，保留 top {rerank_top_n} ...") processor = LocalReranker( model_name="BAAI/bge-reranker-base", top_n=rerank_top_n, ) query_bundle = QueryBundle(query_str=query) filtered_nodes = processor.postprocess_nodes(nodes, query_bundle) print(f"[重排] 最终保留 {len(filtered_nodes)} 个片段") return filtered_nodes def generate(query: str, nodes): """生成：拼接 Prompt 并调用 LLM""" print("[生成] 拼接上下文，调用大模型...") context = "\n\n".join( f"[片段{i+1}]\n{node.get_content()}" for i, node in enumerate(nodes) ) prompt = f"""请根据下面的参考片段回答用户问题。 参考片段： {context} 用户问题：{query} 要求： 1. 优先使用参考片段中的信息回答 2. 如果参考片段中没有相关内容，请直接回答“未在资料中找到相关信息” 3. 回答尽量简洁、准确 回答：""" response = Settings.llm.complete(prompt) print("\n" + "=" * 40) print("问答结果：") print(response.text) print("=" * 40) return response.text def run_pipeline(): parser = argparse.ArgumentParser(description="一条命令跑完 RAG 全流程") parser.add_argument("--query", required=True, help="用户提问") parser.add_argument("--data-dir", default="./data", help="原始文档目录") parser.add_argument("--index-dir", default="./storage", help="索引持久化目录") parser.add_argument("--force-rebuild", action="store_true", help="强制重建索引") parser.add_argument("--top-k", type=int, default=20, help="召回候选数") parser.add_argument("--rerank-top-n", type=int, default=5, help="重排后保留数") args = parser.parse_args() # 步骤 1：建库 time_start = time.time() index = build_index(args.data_dir, args.index_dir, args.force_rebuild) # 步骤 2：召回 nodes = retrieve(index, args.query, args.top_k) # 步骤 3：重排 filtered_nodes = rerank(nodes, args.query, args.rerank_top_n) # 步骤 4：生成 generate(args.query, filtered_nodes) time_end = time.time() print(f"\n[完成] 总耗时: {time_end - time_start:.2f} 秒") if __name__ == "__main__": run_pipeline()

4.3 执行效果与预期输出

假设你的data目录里放了几份员工手册，然后执行：

python local_rag.py \ --query "新员工的年假天数是怎么计算的？" \ --data-dir ./data \ --top-k 20 \ --rerank-top-n 5

第一次运行时，如果storage目录不存在，会自动进入建库流程。你会看到类似这样的日志：

[建库] 开始读取目录: ./data [建库] 开始切分文本... [建库] 共切分 128 个文本块，开始向量化... [建库] 索引构建完成并已持久化 [召回] 开始向量召回 top 20 ... [召回] 得到 20 个候选片段 [重排] 开始精排，保留 top 5 ... [重排] 最终保留 5 个片段 [生成] 拼接上下文，调用大模型... ================================ 问答结果： 根据员工手册，新员工的年假天数根据入职时间按比例折算，具体为…… ================================ [完成] 总耗时: 18.23 秒

第二次再执行同一条命令时，建库步骤会直接跳过，总耗时通常能降到 5 秒以内（取决于重排模型和 LLM 的速度）。这就是“一条命令跑完全流程”的直观体验。

4.4 参数调节建议表

调参是 RAG 的日常。下面这张表列出的默认值，是我在多个文档问答项目里反复试出来的起点，但最终取值一定要基于你自己的文档做评测。

我自己的习惯是：先固定chunk_size=512和chunk_overlap=50，然后用一组真实问题做评测。如果发现答案没找到，先把top_k从 20 升到 40，看是不是召回阶段漏了；如果召回候选里能找到正确答案但最终答案不对，那就把rerank_top_n从 5 调到 8，或者检查重排模型是否与领域匹配；如果整体延迟太高，优先降top_k和rerank_top_n。

5. 实测遇到的高频问题和排查技巧

5.1 召回结果为空或根本检索不到

最典型的症状是：索引构建成功，日志也提示得到了候选片段，但生成出的答案胡编乱造，或者压根没有用上参考内容。

首先检查 Embedding 模型是否加载成功。如果 Hugging Face 模型第一次下载失败，Settings.embed_model可能变成空对象，LlamaIndex 不会直接报错，而是用默认的模拟模型，结果检索结果全部是随机序。我踩过这个坑，花费大量时间排查后才发现是模型文件没下全。解决办法是启动时打印Settings.embed_model的关键属性，或者单独跑一次embedding = Settings.embed_model.get_text_embedding("测试")，看维度是否正常。

其次检查文档切分是否成功。如果原始文档里全是图片扫描件，文本切分之后可能一个有效节点都没有。你可以临时打印建库后的节点内容和数量，确认至少有一个完整句子级的文本块。我见过某项目把扫描版 PDF 直接扔进去，索引建了但节点里全是空行，最后召回一堆空白。

还有几种低概率原因：查询语言与文档语言不一致，比如文档是中文，查询用了英文模块；文本切分后只有寥寥几个块，向量空间上的区分度不够；又或者你有多个storage目录，命令行参数--index-dir指错了位置。排查时先看日志里的索引路径，再打印几个召回节点的node.get_content()开头 100 个字符，基本就能定位。

5.2 重排阶段超时、内存爆炸

CrossEncoder 是逐对计算的，当top_k=20时，一次查询要做 20 次模型推理，这比 Embedding 一次查询要多得多。如果你把top_k设成 100，单次重排耗时可能长达十几秒，在 CPU 机器上甚至可能把内存打满。

解决办法有三个方向：把top_k控制在合理区间，比如 20 到 50；使用更小的重排模型，比如bge-reranker-base而不是large；对重排模型做量化，或者干脆跑在 GPU 上。如果业务场景对首字延迟特别敏感，可以考虑把重排模型做成独立服务，批量异步处理，但这就超出了单命令的范畴，属于上线架构问题。

另外，sentence_transformers在predict的时候默认会使用你本机最大的 batch size，如果显存或内存不够，可以在调用时加一个batch_size=16参数：

scores = self._model.predict(pairs, batch_size=16)

这个参数并不影响结果，只是限制同时处理的样本数，能明显降低内存尖峰。

5.3 生成结果乱说、引用错误

RAG 最大的风险是 LLM 无视参考片段自由发挥。我的排查经验是，先看 Prompt 模板有没有做强约束。如果直接写“根据以下内容回答问题”，模型自由度太高。更稳的写法是明确要求“如果参考片段中没有对应信息，请直接回答未找到”，同时给片段编号，让答案中带上[片段1]这样的引用标记。

下面是我常用的 Prompt 约束：

1. 优先使用参考片段中的信息回答 2. 如果参考片段中没有相关内容，请直接回答“未在资料中找到相关信息” 3. 回答中引用内容时，请标注来源编号

第二个常见原因是没有做好重排，噪声片段被塞进上下文。某个片段虽然和问题有较高的向量相似度，但内容其实是另一个部门的制度，LLM 看到一堆相似但不相关的片段，很容易被带偏。建议把重排后的片段打印到一个调试日志里，人工检查每个片段是否真的回答问题，再决定是否调rerank_top_n。

第三个原因是 LLM 上下文被截断。如果rerank_top_n=8且每个片段 512 字符，上下文很容易超过 4000 字符，模型在长上下文中容易“遗忘”靠后的内容。解决办法是减小chunk_size或rerank_top_n，或者在 Prompt 中让模型优先关注前几个片段。

5.4 增量更新与索引失效

最简单的索引更新方式是全量重建。如果你的文档量不大，直接跑一遍--force-rebuild是最省心的，绝对不会出现新文档和旧向量混存的脏状态。如果文档量很大，全量重建的时间不可接受，就需要做增量插入。

LlamaIndex 的VectorStoreIndex本身支持插入新节点：

new_documents = SimpleDirectoryReader(input_files=["./data/new_file.md"]).load_data() new_nodes = splitter.get_nodes_from_documents(new_documents) index.insert_nodes(new_nodes) storage_context.persist()

但增量更新的难点不在于 API，而在于“去重”。如果你重复插入同一份文档，索引里会出现重复向量，检索结果就会有大量相同内容。我建议在文档层面维护一个 hash 表，用文件内容 hash 作为唯一标识，插入前先查这次是不是已经处理过。更进一步，如果你做了复杂的增量更新，最好在索引目录名里加上版本号，比如storage_v2_20250101，万一线上效果衰减还能快速回滚。

5.5 高频问题速查表

6. 影响范围与进阶方向

6.1 谁最需要这套一条命令的 RAG

很多人以为 RAG 是算法工程师的专属工具，但我在实际落地中接触到的用户，真正高频使用它的反而是技术负责人、产品经理、客服主管和知识管理专员。

技术人员拿它做内部开发文档问答，把散落在 Confluence 和 GitLab Wiki 里的资料集中成一个可查询入口；客服团队拿它接产品 FAQ，用户问“退款多久到账”，系统能从几十份客服手册里快速给出带出处的话术；产品经理拿它分析竞品文档和用户调研，减少大量翻文档的时间；个人用户则用它做论文笔记和电子书查询，本质上是一样的链路。

这套方案的门槛低到什么程度？只要你能把文档放进data目录，会运行一条命令，就能得到一个相对靠谱的问答系统。这非常符合实际团队的协作方式——不要求每个人都懂向量数据库，只需要维护入口和文档更新。

6.2 从“跑通”到“跑好”的演进方向

如果你已经能顺利跑通全流程，下一步我建议按以下顺序做优化。

第一，加入BM25 混合检索。向量召回擅长语义相似，但不擅长精确关键词匹配，比如型号编码、错误代码、合同编号这类信息。把 BM25 的关键词命中和向量召回的候选结果加权合并，可以显著提升准确率。

第二，做查询改写。复杂问题里经常有口语化表达和指代，比如“它是不是支持这个功能”中的“它”需要结合多轮对话上下文才能理解。在进入召回前先让 LLM 将用户问题改写成一个标准检索式，往往能给召回带来很大的提升。

第三，建立效果评估集。找业务方要 50 到 100 个真实问题，把参考标准答案标注好，每次调整参数后自动跑一遍，统计“检索命中率”和“答案正确率”。这套机制比任何人的主观感觉都可靠，也是项目从 Demo 走向上线的关键一步。

第四，把单命令脚本扩展为HTTP 服务。用 FastAPI 包一层，接收查询请求，复用同一个storage目录，加上缓存和流式输出，就成了一个标准的 RAG 推理服务。

第五，考虑多租户与元数据过滤。不同团队的知识库可能混在一起，通过给文本块打team_id元数据，在检索时做条件过滤，可以避免跨团队的信息串味。

我个人在实际操作中的体会是：不要一开始就追求大而全的架构。先用这一条命令把闭环跑起来，让真实业务问题驱动你去加深对每个环节的理解。踩过几次坑之后你会发现，真正决定 RAG 上限的不是用了多强的模型，而是索引构建时有没有把文档结构想清楚，Prompt 里有没有把约束写明白。最后再分享一个小技巧：给你的storage目录加上构建日期作为后缀，比如storage_20250101，这样哪怕改了切分策略，也能随时对比新旧版本的问答效果。等到你觉得当前方案的工作流已经稳定了，再往混合检索和评估体系上扩展，整个系统会越用越顺手。