企业官网建设流程全解析

写AI Agent，RAG（检索增强生成）是你迟早要面对的关卡，向量模型则是整个链路的基石。这一篇我会把RAG的内部结构和向量模型的实战用法，从原理到落地完整过一遍，不绕弯子，直接给你可以照着写进代码的东西。

这篇内容更适合两类人：一类是Agent已经跑通了简单对话，但发现模型知识不足或胡说八道，想接私有知识库的开发者；另一类是听说过RAG，但被文本切分、向量化、召回这些词绕晕，需要一条清晰主线带着上手的新手。我会先讲为什么要做RAG，再拆解链路每一环，最后给出一套能直接跑起来的实战方案和踩坑记录。

1. Agent为什么绕不开RAG

1.1 纯靠模型参数的三个致命问题

很多做Agent的人一开始都抱有一个念头：模型这么强，什么都知道，直接让它回答不就行了？实测跑过几个真实项目后，你会发现这个想法靠不住。模型的参数里确实塞进了海量知识，但它本质上是在做"根据上下文预测下一个词"，不是在查数据库。

第一个问题是知识截止。模型训练完之后，它对世界的认知就固定了。你今天给知识库里新增了一份产品文档，模型在没有RAG的情况下永远不知道里面写了什么。哪怕你问它"当前版本新增了哪个参数"，它也能面不改色地给你编一个，而且编得很像真的。

第二个问题是细节幻觉。模型对高频知识掌握得还可以，但一旦涉及某个具体数字、某个特定编号、某段合同条款，它就开始自由发挥了。我见过一个最典型的例子：问某个框架的配置项，模型给出了一个看起来完全合理的键名，但这个键名在真实系统里根本不存在。这种错误比"直接说不知道"危险得多。

第三个问题是私有知识完全不可见。企业内部文档、个人笔记、特定领域的研究资料，这些内容永远不会出现在通用模型的训练数据里。你不可能靠提示词把几百篇文档塞进上下文，模型也背不下来。这个问题的本质是：模型把记忆放在参数里，而你的知识在外部文档里，两者需要一座桥。

1.2 RAG的本质：从闭卷考试变成开卷考试

RAG做的事情，就是把原本靠模型大脑记忆的"闭卷考试"，变成可以先翻资料再作答的"开卷考试"。它把知识从模型参数里搬出来，放到一个外部知识库中，然后在你提问的时候，先去知识库里检索相关片段，把片段和问题一起交给模型，让它基于这些资料作答。

这个转变解决了一件非常关键的事：模型不再需要"记住"你的知识，只需要"理解并使用"你给的资料。你的文档更新了，知识库跟着更新，模型下次回答就是新内容；文档里没有的内容，模型不会被诱导去编造，因为它看到的是空检索结果，可以老老实实说不知道。

用一个生活化的类比来解释：RAG像是一个配备了资料库的研究助理。老板问一个问题，助理不是凭印象回答，而是先翻出相关文件，再看看文件里的内容，综合出一个答案。文件里有就回答，文件里没有就明说资料缺失。你的Agent配上RAG之后，就相当于雇了这样一个助理。

1.3 明确边界：不是所有场景都该上RAG

RAG不是银弹，它解决的是"知识补充"问题，不是"能力提升"问题。我建议你在动手之前，先判断自己的场景适不适合。

适合上RAG的场景很清晰：需要基于某个特定知识库回答问题（比如产品手册问答、内部制度咨询、学术文献综述）；知识内容会动态变化（比如实时更新的运营数据、不断修改的需求文档）；对回答准确性要求高，不能接受编造的场景。这些场景有一个共同点：正确答案已经存在于文档里，只是需要被找出来。

不太适合的场景也有两类：一类是纯逻辑推理任务，比如代码Debug、数学计算、复杂规划，这类任务需要的不是知识，而是推理能力，把一堆文档检索给模型反而分散注意力；另一类是模型本身就擅长的事情，比如常识问答、开放闲聊，RAG不仅没帮助，还白白增加延迟。

我的建议是：先做最小验证，拿自己的真实文档跑通一遍全流程，评估效果后再决定是否完整落地。这一篇接下来讲的内容，就是支撑这个最小验证所需要的全部核心知识。

2. RAG架构拆解：一条链路五个关卡

2.1 完整流程里的每一环在干什么

一条标准的RAG链路，从原始文档到最终回答，要经历五个关卡：加载、切分、向量化、召回、生成。很多人以为RAG就是"文档转向量存起来，然后查一下"，但每一环做得好不好，都直接决定最终效果的上限。

• 加载：把PDF、Word、Markdown、HTML等不同格式的文档内容提取成纯文本。这一步的坑在于格式解析质量，PDF里的表格、双栏排版、扫描件经常提取出乱序内容。
• 切分：把长篇文档切成适合检索的片段。这个过程会决定"被检索到的最小信息单位"有多大，切得太粗容易混入无关内容，切得太细容易丢失上下文。
• 向量化：把每个文本片段通过向量模型转化成一组数字。这组数字在数学上代表这个片段的语义位置，语义相近的文本，数字越接近。
• 召回：把你的问题也转成向量，在库里找到最相近的K个片段。召回阶段追求的不是"精确匹配关键词"，而是"语义相关性最高的资料先被捞出来"。
• 生成：把召回的片段和原始问题按一定格式组装成提示词，交给大模型，让它结合资料内容生成最终答案。

我最初做RAG的时候，犯过一个典型错误：花了很多时间调提示词，希望模型回答得更准，却发现效果一直不稳定。后来才意识到，问题根本不在生成环节，而是切分和召回的参数没调好，资料本身就没找对。你提示词写得再漂亮，喂进去的资料是错的，答案不可能对。RAG的瓶颈往往在最前面几环。

2.2 切分策略：最容易被低估的一环

文本切分是RAG链路里最不起眼、但对效果影响最大的环节。切分没有绝对的最优解，只有适合你场景的解。

最朴素的做法是固定长度切分：比如每512个字切一段，相邻段之间重叠128个字。这种做法的优点是简单、稳定，缺点是它完全不懂语义边界，可能在句子的中间硬切一刀，把一个完整的意思切成两段，检索的时候谁也找不到全貌。

更聪明的做法是语义切分：按段落标题、换行符、句子结束符等自然边界来切。我在实际项目中用的比较多的是递归切分策略——先用大块的分隔符切，切完发现还太大，再用次级分隔符继续切，直到每个块的大小落在目标范围。这样切出来的片段基本能保持语义完整性。

还有一类做法是按文档结构切分。比如产品手册，先按一级标题切成大章节，再按二级标题切小章节，每个二级标题下的内容作为一个片段。这种方式的优点是片段本身就带有层级信息，你可以把"标题路径"存进元数据，检索结果里能直接看出内容出自哪个章节。

切分里还有一个经常被忽略的参数：chunk_size和overlap。overlap是相邻片段之间重叠的内容长度，作用是防止重要信息恰好被切分点切断。比如一段话在两块各占一半，如果不重叠，两块单独都看不懂，检索时会同时漏掉。设了重叠之后，这段完整的话至少会完整地出现在某个片段里。

2.3 召回之后别急着生成，重排能救命

基础RAG链路到生成就结束了，但实际项目中你会发现一个问题：向量召回的前K个结果，并不一定按质量从高到低排好。语义相似的文本，可能在背景知识、信息密度、与问题的契合度上差别很大。直接把这K个片段无差别塞给模型，模型容易被低质量的片段带偏。

解决办法是在召回和生成之间加一步重排（Re-ranking）。先用向量检索快速从几万条数据里捞出几百条候选，再用一个更强的模型（通常是交叉编码器结构，把问题和片段拼接起来计分）做精细排序，最终取Top-K进入生成环节。

这其实是两阶段检索的思路：第一阶段是粗筛，要快，要让潜在相关的资料不漏网；第二阶段是精排，要准，要在覆盖度已经足够的情况下把真正有用的放最前面。向量检索擅长粗筛，重排模型擅长精排，两者配合的效果远好于任何一方单打独斗。

我写这篇博文的经验来自自己做过的一个模拟项目X，规模不算大，几百份技术文档，最后线的效果和三方评测结果都验证了这个判断：加上重排之后，回答准确率提升了接近两成，而且幻觉出现的频率明显下降。接下来我详细讲向量模型的实战，这是整条链路里数学味道最重、也最值得花时间琢磨的部分。

3. 向量模型实战：从原理到选型

3.1 向量模型到底在做什么

先把最基础的问题讲透：向量模型（也叫Embedding模型）做的事情，是把一段文本映射成一个固定长度的数字列表，比如768维或者1024维。这些数字不是随便生成的，它们经过训练后被安排在一个高维空间里，语义上相近的文本在这个空间里距离也近。

"苹果"和"水果"的向量会靠得很近，"苹果"和"iPhone"的向量也会靠得很近，但要区分"苹果"在这两句话里指的是水果还是手机，就得看上下文。所以实际使用时，你往往不是把单个词输入模型，而是把一个完整的句子或文本片段输入进去，让模型基于上下文生成向量。

你可以在代码里打印出向量内容，它看起来就是一串没有任何直观含义的浮点数。但正是这串数字，让计算机可以计算两个文本之间的语义距离。常见的相似度计算方式有三种：余弦相似度、点积、欧氏距离，它们的数学定义不同，适用场景也有区别。

3.2 相似度计算：选对公式才不会被坑

• 余弦相似度：计算两个向量在多维空间中的夹角的余弦值，范围是-1到1，越接近1越相似。它只关心方向，不关心长度，对文本长度差异不敏感，是文本检索场景中最常用的方式。
• 点积：两个向量对应位置相乘后求和。点积同时受方向和长度影响，向量越长结果越大。使用点积时通常要求向量先做归一化（长度变成1），归一化后的点积就等于余弦相似度。
• 欧氏距离：两个向量在多维空间中的直线距离，值越小越相似。它受向量绝对位置影响较大，文本检索中用得相对少，但在某些经过专门训练的模型里也能配合得很好。

实战中大多数人用的是余弦相似度，这是最不容易出错的默认选择。需要留意的一点是：有些向量模型本身在训练时就是用内积优化的，官方推荐用点积计算。如果你用了这类模型却用余弦相似度，会损失一部分检索效果。判断方法很简单，看模型文档里的推荐用法，别自己凭感觉定。

我习惯的做法是，在代码里把向量先做L2归一化，然后用点积计算。这样既稳定又高效，而且归一化之后的点积就是余弦相似度，两个口径都说得通。

3.3 选型关键参数：维度、语言、能力定位

向量模型选型，核心看三个参数：向量维度、支持语言、模型定位。

向量维度直接影响存储成本和计算速度。768维的向量，一百万分片大概需要几GB的存储，而1024维或更高的模型会更占资源。在效果差别不大的情况下，优先选维度更低的模型，可以让检索在数据量增大时依然保持可接受的性能。实际项目里，768维是一个比较折中的选择。

支持语言是另一个容易踩坑的点。很多优秀的向量模型以英文为主，直接拿来做中文文本会效果打折。中文场景优先选择专门做中文优化的模型，或者至少是声明支持中英双语能力的模型。实测下来，同一份中文文档，专用模型和通用模型召回效果差距可能达到两倍。

模型定位也很关键。把模型按能力分成三类：通用模型，质量均衡覆盖面广，适合大部分场景；领域模型，针对代码、医疗、金融等垂直领域训练过，对特定术语理解更好；小型加速模型，适合资源受限的生产环境，性能稍弱但速度快。0基础起步、还没搞清楚自己到底要什么的时候，先无脑选通用模型跑通链路，后面再根据瓶颈决定是否需要换。

3.4 一个更实在的判断标准：拿你自己的数据测

选型文档写得再漂亮，也不如在自己数据上跑一次评测来得实在。我建议你整理二十到三十个真实存在的问答对，每个问答对包含一个问题和它对应的正确答案片段，然后做一次开挖测试：把问题和片段都向量化，计算相似度排名，看正确答案是不是排在前五，甚至前二。

第一步，把二十个问题的正确答案片段混入一批随机片段里，作为检索底库。第二步，逐个问题做向量检索，记下正确答案的排名位置。第三步，把排名太靠后的问题挑出来，分析原因，大概率发现是切分太粗或者查询词太短。

这套办法成本很低，二十分钟就能做完，但收益远高于看评测榜单。我见过有人根据一份看起来很有说服力的榜单选了模型，结果在自己的垂直领域语料上表现很差，原因就是榜单评测的数据分布和你的场景根本不同。一定要用自己的数据说话。

4. 向量数据库与检索优化实操

4.1 向量数据库选型：本地开发与生产环境的差异

向量化之后的产物就是向量数据库里的一条条记录。选型逻辑和传统数据库类似，无非是考虑功能完整度、性能、运维成本三件事。

本地开发阶段，一个嵌入式向量库就够用了，不需要单独部署服务，直接在你的应用进程内运行，数据落盘在本地文件里。这种方式启动快、代码简单，非常适合跑通流程和做小规模验证。缺点是性能上限有限，不能支撑大规模并发。

到了生产环境，就要考虑独立部署的向量数据库或具备向量能力的数据库服务。独立的向量数据库通常在索引算法上更专业，支持分布式、水平扩展、混合检索、标量过滤等功能；而传统数据库增加向量扩展则是复用了成熟的存储和事务能力，团队已有的运维经验可以直接延续使用。

选型的核心逻辑是：数据量到百万级以上，或者需要高并发低延迟检索的时候，放弃嵌入式的方案，用独立服务。数据量小、访问量少的时候，忠实于最简单方案就好，别为不存在的性能问题买单。

库和表的设计上也有一点需要注意：每条记录里除了向量本身，一定要存原始文本和元数据。有人为了省存储只存向量，结果检索出了高相似度片段却无法反查原文，最后还要重新加载文档跑一遍切分和向量化，白白浪费时间。原始文本至少要有，元数据（来源文件名、章节路径、更新时间）也强烈建议存下来，后面过滤和溯源都靠它。

4.2 索引算法：为什么检索不用全量暴力计算

向量数据库能在大规模数据上做到毫秒级检索，靠的是一种叫做近似最近邻（ANN，Approximate Nearest Neighbor）的索引算法。它牺牲了一部分"一定能找到最优结果"的保证，换来了检索速度的大幅提升。

最常见的索引算法是HNSW（分层小世界图）。它的思路是构建一个多层图网络，上层节点稀疏，负责快速定位到大致区域；下层节点稠密，负责精细查找。检索时从顶层开始逐层下行，大大减少需要计算距离的节点数量。HNSW的优点是查询速度快、召回率也高，缺点是建索引时内存占用大，插入数据后索引更新成本较高。

IVF（倒排文件）是另一种常见算法。它先把所有向量聚类成若干簇，检索时先找到最相关的几个簇，只在这几个簇内部做精确计算。IVF的优势是内存占用相对可控，适合数据量非常大的场景，但召回率不如HNSW稳定，聚类质量会影响效果。

实践的默认选择是：数据量在十万到百万级别，首选HNSW；上千万级别，考虑IVF或者分布式方案。需要注意，索引参数里"HNSW的邻居个数"（M值）和"检索时搜索的候选节点数"（ef_search）直接决定了召回质量和查询速度的平衡。M值越大，图越稠密，召回越准，但内存和建索引时间也越高；ef_search越大，查询越慢但结果越准。新手建议先用默认参数跑通，再根据数据情况调节。

4.3 元数据过滤和混合检索：召回质量的两大杠杆

只用纯向量检索做召回，在很多场景下是不够的。一个经典问题是：你有一批多语言文档，用户问的是中文，向量检索却把一堆英文相似片段也召回来了，这些片段可能语义相关但语言不匹配，放到提示词里反而干扰生成。

解决方式是元数据过滤。建库的时候，把文档的语言、类型、来源、时间等作为标量字段存进每条记录；检索的时候，先限定好这些字段的取值，再在满足条件的子集里做向量检索。比如只搜索语言等于中文的文档、只搜索时间晚于某个日期的公告、只搜索技术文档不搜索售后工单。这个操作能显著提高召回精度，而且实现成本很低。

另一个提升召回质量的重要手段是混合检索：向量检索负责语义召回，关键词检索（比如经典的BM25算法）负责精确匹配。为什么需要它？因为向量检索本质上是"模糊语义匹配"，它可能无法很好处理专有名词和短代码的问题。比如一个产品编号"AGT-2024-0717"，向量模型把它编码时很难理解这是一个必须精确匹配的标识符，而关键词检索能精确命中。

混合检索的标准做法是同时对两种检索结果做归一化，然后按加权合并排序。权重的调法看你的内容倾向：如果文档中术语、名称很多，关键词的权重要调高；如果文档以自然语言为主，语义检索的权重要调高。这个参数没有固定答案，需要你用自己的测试集调几轮才能找到平衡点。

4.4 重排序：让最终的Top-K更可信

向量检索和关键词检索都属于"快速但粗糙"的召回手段，它们的排序依据不是"这个片段对回答当前问题有多关键"，而是"这个片段和当前问题在语义或词汇上有多接近"。

重排序是把候选片段按真实质量重新排列的一步。做法是把"问题和候选片段拼接成一句话"输入一个专门的交叉编码器模型，模型输出一个相关性分数。和向量检索那种先把问题和片段分别编码再计算相似度的方式不同，交叉编码器让模型在打分前能同时看到问题和片段的全貌，对细微语义的把握更强，准确率更高但速度也慢得多，所以要放在粗筛之后，只对几十条候选做精排。

重排之后，你可以做两件额外的事情：把相关性低于阈值的片段直接丢弃，避免低质量片段进提示词；对被选中的片段做位置调整，让最相关的排在前面。这个操作有两个实际作用，一是提示词的质量更高了，二是能够让模型更多关注有用信息，减少跑题。

我在自己的项目里对召回策略做了一轮完整对比：纯向量召回、向量加关键词混合召回、混合召回加重排三档。结果是第三档的效果明显好于前两档，特别是在处理包含大量专有名词的技术文档时，关键词检索补上了向量召回的盲区，重排则保证进入提示词的片段是真正对回答有贡献的，这一步值得每一个想认真做RAG的人加上。

5. 完整Agent接入流程：一个真实项目的实现

5.1 工程结构设计与配置

前面讲了原理和组件，现在把它们拼装成一个完整的Agent问答服务。我以一个模拟的技术文档问答Agent项目X为例，展示可落地的流程。工程结构沿用常见的最佳实践：一个入口文件负责启动和串联流程，几个模块分别负责文档加载、向量建库、检索、提示词组装。

agent_rag_demo/ ├── config.py # 配置：模型路径、向量库路径、切分参数 ├── loader.py # 文档加载与切分模块 ├── embedder.py # 向量化模块 ├── store.py # 向量库操作模块 ├── retriever.py # 检索与重排模块 ├── generator.py # 生成模块，组装提示词并调用大模型 └── main.py # 入口，串联全部流程

配置项集中放在config.py里，包括向量模型路径、向量维度、切分块大小、重叠长度、检索Top-K、重排Top-N、生成的温度参数等。这样设计的好处是：你后续做参数调优时，只需要改配置文件，不需要动业务代码，可以很方便地做多组实验对比。

# config.py 关键配置示意 EMBED_MODEL_PATH = "models/your_embedding_model" COLLECTION_NAME = "project_x_docs" CHUNK_SIZE = 512 # 切分块的字符数 CHUNK_OVERLAP = 128 # 相邻块重叠字符数 TOP_K_CANDIDATES = 50 # 第一阶段粗筛数量 TOP_K_RERANK = 5 # 第二阶段精排后保留数量 SIMILARITY_THRESHOLD = 0.42 # 相似度下限（根据实测调整）

这套结构有一点值得说明：粗筛和精排的数量参数被刻意分开了。粗筛数量设得大，是为了保证召回不漏；精排数量设得小，是为了保证生成环节的提示词足够精简。两者并不冲突——粗筛负责覆盖，精排负责收敛。

5.2 核心代码实现

文档切分我用递归切分策略，和前面讲到的语义边界逻辑一致。先把文档内容按标题层级拆开，再检查每个块的长度是否超过设定值，超了就继续向下拆。这是一个典型的"尝试、检查、再尝试"的递归过程。

# loader.py 核心逻辑 def split_document(text, chunk_size=512, overlap=128): sections = [] # 按自然边界粗切 for sep in ["\n\n", "\n", "。", "；"]: parts = text.split(sep) # 如果切完的片段仍然太大，用下一个分隔符继续切 if all(len(p) <= chunk_size for p in parts): sections = [p.strip() for p in parts if p.strip()] break chunks = [] for section in sections: if len(section) <= chunk_size: chunks.append(section) else: for i in range(0, len(section), chunk_size - overlap): chunks.append(section[i:i + chunk_size]) return chunks

向量化模块的接口设计得很简单：输入文本，输出向量。需要留意的是模型的加载是一次性的，不要在每次请求时重复加载，否则延迟会高到无法接受。

# embedder.py 核心逻辑 class Embedder: def __init__(self, model_path): # 加载向量模型并切到评估模式 self.model = load_model(model_path) self.dimension = 768 def embed(self, texts): # texts 可以是单个字符串或字符串列表 # 返回归一化后的向量列表 vectors = self.model.encode(texts, normalize_embeddings=True) return vectors

向量库这边，核心操作就是建集合、插入、检索三个动作。插入的时候把原始文本和元数据也一起存进去，保证检索后能拿到可用内容。

# retriever.py 核心逻辑 def retrieve(query, top_k=50): query_vector = embedder.embed([query])[0] candidates = vector_store.search( query_vector, top_k=top_k, filter={"language": "zh"} # 元数据过滤：只查中文 ) # 第一轮：向量召回 semantic_scores = normalize_scores(candidates) # 第二轮：关键词召回 keyword_scores = bm25_search(query, top_k=top_k) # 合并排序（加权） fused_scores = 0.6 * semantic_scores + 0.4 * keyword_scores top_candidates = rank(fused_scores)[:top_k] # 第三阶段：重排精筛 reranked = reranker.rerank(query, top_candidates)[:5] return reranked

生成环节的提示词，我习惯用一套固定的模板：先说明你是客服助手，只基于提供的资料回答；再把检索到的片段按序号列出，标注来源；最后强调如果资料里没有答案，直接说不知道，严禁编造。模板需要多测多调，重要的是开头的角色设定和末尾的限制语气，一个负面的例子能有效降低幻觉率。

5.3 关键参数的选择逻辑

为一个已跑通的系统做参数调优时，我一般从切分块大小入手。第一次先用512字符试跑，如果发现答案经常"答非所问"且检索出来的片段明显不完整，再把块调大到768甚至1024。如果发现检索结果太长、包含了很多无关句子，再把块调小到384或者256。块大小对效果的直接影响大于其他所有参数之和。

Top-K的选择也有一套思路。粗筛阶段我建议从50往上调，直到复杂问题也能被召回到为止；精排阶段从3到5起试，先用3保证提示词精简，如果模型反馈信息不够再逐步增加到5。精排的数量不宜超过5，否则提示词太长，模型在生成时容易捡了芝麻丢了西瓜。

相似度阈值是另一个容易被忽略的参数。阈值设太高，明明有相关资料却被过滤掉，模型只能回答"不知道"；阈值设太低，大量无关片段混进提示词，模型被误导的概率大大增加。我的方法是用二三十个测试问题跑一遍，统计正确答案的最低相似度，再把阈值设在比这个值稍低的位置，留出安全余量。

5.4 实验结果与过程记录

我在项目X上做过一次完整的参数对比实验，记录如下：使用默认的512字符切分、重叠128字符时，一个二十问题的测试集准确率只有六成左右。把切分块调成768并采用标题感知的语义切分后，同样的测试集准确率提到了七成五。加上混合检索和重排两步之后，准确率稳定在八成五以上。

这个提升轨迹印证了一个观点：RAG的每一环都可能成为瓶颈，先提升短板最明显的环节，收益最大。第一次提升来自切分策略优化，说明原来的块太小把关键上下文切散了；第二次提升来自检索质量优化，说明单纯的向量召回覆盖度不够。判断短板的方法也很简单，逐环查看中间输出：如果召回的片段本身就不完整，问题在切分；如果片段完整但排序靠后，问题在检索；如果片段正确但模型没用上，问题在生成提示词。

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

6.1 十个高频问题排查速查表

以下这些问题是RAG实践中几乎每个人都会遇到的，我按症状、可能原因、排查方向整理成了一张速查表，适合贴在工位旁边随时对照。

6.2 三个最典型的踩坑案例

第一个坑是我早期踩过的：把分块大小设成256，美其名曰"检索更精准"，结果大量长段落被拦腰截断，一段完整的技术描述散落成两三个碎片，每个碎片单独看都缺乏上下文。模型拿到这些碎片，完全无法理解完整逻辑。解决办法是改用标题感知的语义切分，保证每个碎片至少是一个完整小节，同时对边界做重叠处理。

第二个坑和查询改写有关。用户在使用Agent过程中会自然地带上下文提问，比如上一句问"怎么部署"，下一句问"那数据库呢"。如果不做改写，第二句检索得到的可能是一堆和"数据库"无关的结果。我后来加了一个查询预处理步骤：先把带上下文的提问压缩成一句完整独立的话，再做检索和后续流程，效果立竿见影。

第三个坑是提示词组织方式。最初我把所有检索片段一股脑拼在问题后面，模型经常抓不到重点。后来把片段按格式规范排列，每个片段标注来源序号，并在提示词中明确指出"优先参考靠前的片段"。这一步不需要引入复杂机制，但实测对回答质量的影响非常大，很多幻觉其实是碎片信息杂乱导致模型理解错位。

6.3 一套值得执行的排查流程

当你发现RAG效果不符合预期时，建议按下面的顺序排查，不要像无头苍蝇一样东改西试：

第一步，检查输入侧。把用户问题、切分后的片段、检索到的结果、最终输入给模型的提示词完整打印出来，逐环查看。这一步就拦住了八成以上的问题，因为你大概率会发现要么检索结果不对，要么片段质量太差，要么提示词组装有误。

第二步，控制变量验证。一次只改动一个参数，比如只改chunk_size或只改Top-K，记录测试集上的效果变化。如果同时改了三个参数效果变好了，你不知道是哪个参数起了作用，后续也没法做泛化优化。

第三步，用定量指标替代主观感受。维护一组固定的测试问答对，每次改动后用同一套标准评估准确率和召回率。没有这套数据支撑，所有的"感觉好了一点"都是不可靠的。我建议至少准备三十个覆盖不同难度的测试问题，效果评估才有统计意义。

7. 我实际用下来的几点体会

最后分享几个我自己在实践中的心得。第一点，RAG项目一定不要等到全流程完美才开始用，先把最简单的版本跑起来，再接真实数据，你会在实际使用中发现单靠阅读文档永远发现不了的问题。第二点，所有的调参决策都要建立在"自己数据上的测试结果"之上，不要迷信任何预设的参数组合和第三方评测结论。

第三点，调试检索质量时，先想办法把中间过程可视化出来，我用的方法是把每个查询的检索片段按相似度分数排列打印，直接观察召回的内容是否相关、排序是否正确。见过反馈的直觉，比看任何日志数字都可靠。最后，准备好投入时间维护知识库本身，文档更新频率决定了Agent回答的时效性，这是RAG系统中只有人工能完成的环节。