企业官网建设流程全解析

1. 从“零散笔记”到“RAG 落地手册”：我在 all-in-rag 里记下的那些事

先说说这标题是怎么来的。算起来，我接触 RAG（检索增强生成）差不多一年半了，从最早拿开源框架跑 demo，到后来给团队搭了一套能接生产流量的问答系统，中间踩过的坑、翻过的车、想明白的道理，全都零零碎碎记在一个叫 all-in-rag 的笔记库里。这个笔记库不是什么成型产品，也没有漂亮文档，就是我自己持续往里丢东西的地方——今天记录一个检索参数调优的细节，明天贴一段线上故障排查的日志，后天又补一条对某个新框架的试用感受。时间久了，我发现自己翻这些笔记的频率，比翻任何官方文档都高。

所以这篇文章，说白了就是把 all-in-rag 里那些散装经验重新串一遍，按“为什么要 RAG、检索怎么做、生成怎么配、系统怎么调、坑怎么避”这条主线整理成一份能直接上手参考的东西。适合谁看？两类人：一类是刚接触 RAG、正准备搭第一个原型的技术同学，你可以把它当路线图，知道每一步该关注什么；另一类是已经跑通 demo、但总觉得效果不够稳的开发者，我记录的很多线上问题复盘和参数踩坑，可能正好对应你现在的困惑。我不打算写成一堂理论课，更想用记笔记的口吻，聊聊我在 all-in-rag 里沉淀下来、并且反复验证过的东西。

需要先说明一点，这篇文章里提到的所有项目、数据、场景，都来自我平时工作里的模拟项目和实验室验证，不涉及任何具体业务细节。我会尽量把每个结论背后“为什么这么选”讲清楚，而不是直接甩给你一堆配置项。毕竟，RAG 这东西，参数照抄永远调不出好效果，理解它每一步在干什么，才是真正能复用的能力。

2. 为什么我最终选择了“all-in-rag”这条路

2.1 从纯大模型到 RAG：一次被现实教育的选型

最早的时候，我以为只要把大模型的上下文窗口拉长，就能解决知识更新和私有数据的问题。于是我用了一个支持超长上下文的模型，把几十页产品手册直接塞进 prompt，跑出来的效果简直灾难——模型确实“读”到了所有文字，但回答的时候它分不清哪些信息是当前问题真正需要的，经常抓着一句无关紧要的背景介绍展开长篇大论，真正关键的参数反而被漏掉。后来我才想明白一个类比：大模型就像一个知识渊博但有点“泛读”的顾问，你把整本书丢给他，他记住的是整体印象，而不是你问他某个具体条款时应该精准定位到的那一页。

RAG 的思路完全不同，它先把“查资料”和“写答案”拆成两个步骤。查询阶段，系统像一个图书管理员，根据你的问题去索引里精确找到最相关的几段内容；生成阶段，再把这几段内容连同问题一起交给大模型，让它在限定素材的基础上组织回答。这样做的直接好处是：模型不需要记住所有资料，它只需要理解当前检索到的这几段文字。幻觉率明显下降，答案的可解释性也大幅提升——用户追问“你这个结论是从哪来的”，我可以直接给出检索到的原文片段。

我之所以把所有相关实践都归到一个叫“all-in-rag”的笔记库，就是因为这个方向值得系统性地投入。它不是某个框架的附属功能，也不是临时的应急方案，而是从数据预处理、向量检索、重排序、prompt 编排到大模型调用、评估反馈的一整条链路。每个环节都有独立的优化空间，把它们拆开研究，才会真正理解 RAG 的上限在哪里。

2.2 RAG 系统的整体链路：笔记库里的架构图

我在 all-in-rag 里画过一张很朴素的链路图，没有用任何 fancy 的工具，就是文字加缩进：

数据接入 → 文档解析 → 分块（Chunking）→ 向量化（Embedding）→ 写入向量库 用户查询 → 查询改写 → 向量检索 → 重排序（Rerank）→ 组装 Prompt → 大模型生成 → 答案+引用

这张图看起来简单，但每个环节都有一堆“魔鬼细节”。我给自己定的笔记规则是：任何一个环节出了问题，都要回到这张图，先定位是“资料没存好”还是“查不出来”还是“生成不对”，而不是一上来就调大模型参数。后面几个章节，我就按这条链路的顺序，把每个环节里记过的实践经验和踩坑记录展开讲。

3. 数据接入与预处理：RAG 效果的上限，其实在这里

3.1 文档解析：被大多数人低估的第一道坎

我见过不少团队，兴致勃勃地搭好了检索和生成，结果测试时发现答案质量很差，查了一圈，问题出在最开始——PDF 解析出来全是乱码和错位文本。这个环节太容易被忽视了，因为 demo 阶段大家用的都是排版干净的 Markdown 或 TXT，一旦换到真实场景里的扫描件、双栏排版 PDF、带页眉页脚的 Word，解析质量立刻天差地别。

我在 all-in-rag 里记过一条原则：解析阶段的目标不是“把文字提取出来”，而是“把文档的语义结构保留下来”。举个具体例子，一份技术规格书，表格里有“工作电压：5V”这样的关键信息，如果解析时表格结构丢失，文本变成一行行散乱的字段，后续分块和向量化都会出问题——检索时可能只匹配到“工作电压”这个词，却不知道它对应的值是 5V。

我实际用的方案是分层处理：对 PDF，先用开源解析库提取文本和坐标信息，再用规则把页眉页脚、页码过滤掉；对 Word 和 HTML，优先保留标题层级和表格结构；遇到扫描件，先走 OCR，但 OCR 之后一定要做一轮基于关键词的校对，因为常见的识别错误（比如把“100Ω”识别成“100Q”）会直接影响检索命中。这些处理逻辑，我都写成了可复用的脚本，放在笔记库的preprocess/目录下，每次接入新类型文档，第一件事就是跑一遍解析质量抽检，抽检不合格就直接打回，不进入下一步。

3.2 分块策略：决定检索精度的“切菜刀法”

分块是 RAG 里最像“手艺人”的环节。块切大了，语义完整但检索粒度太粗，一个问题可能命中一大段无关内容，稀释掉关键信息；块切小了，定位精准但语义容易不完整，经常出现“答案在上一块结尾”的尴尬。我在 all-in-rag 里做过一组对比实验，固定其他条件不变，只变换分块大小，结果如下：

所以我最后的生产配置，并不是最复杂的动态分块，而是“按段落优先，段落过长时按句子边界二次切割，每个块控制在 300 到 500 字之间”。这个策略代码好写、效果稳定，尤其适合技术文档和问答库这类段落边界清晰的场景。

另外必须记录一个新手常踩的坑：不要把所有文件都用一个固定分块参数。我在笔记里加了一条规则——先对文档类型做分类，FAQ 类用较小的块（一个问题配一个答案），长文技术手册用较大的块（保持章节完整），表格类数据则单独走“表格结构保留”的分支。分块策略跟着内容形态走，而不是一个参数打天下，这是我从大量实验里得出的最深教训。

3.3 向量化选型：Embedding 模型不是越贵越好

Embedding 模型的选择，对检索效果的影响是决定性的，但“选哪个”并没有标准答案。我在 all-in-rag 里比较过通用中英文模型、开源领域微调模型、商用 API 模型，最后得出的结论是：先看检索任务的语言和领域，再看可部署性和成本。

我的选择逻辑是这样的：如果知识库以中文技术文档为主，我会优先用一个在中文语料上表现好的开源 Embedding 模型，因为它对中文长文本的语义理解更稳，而且可以本地部署，数据不用出内网。如果知识库涉及大量英文论文或跨语言查询，通用多语言模型会更合适——虽然单条成本高一些，但跨语言检索的准确率提升是实打实的。

这里有一个非常容易忽略的细节：Embedding 模型是有“输入长度上限”的。我之前踩过一次坑，用某个模型时忘记看最大输入长度，结果分块超过 512 token 的文本被静默截断，检索效果莫名其妙变差。排查了很久才发现是截断导致向量只编码了前半段语义。所以参数配置表里一定得记一条：分块最大长度不能只按字数算，还要换算成 token 数，确保不超过 Embedding 模型的输入上限。

4. 检索链路：从向量到混合检索再到重排序

4.1 向量检索的相似度算法与召回率平衡

向量检索的核心是“给你一个问题，从向量库里找出最相似的 Top-K 个文本块”。相似度算法最常见的是余弦相似度和内积，我在实践中绝大多数场景用余弦相似度，因为它对向量模长不敏感，更适合 Embedding 模型生成的归一化向量。

但只做向量检索，召回率一定会遇到瓶颈。我印象最深的一次：用户问“设备在低温环境下是否可以正常工作”，知识库里相关段落写的是“工作温度范围：-20℃ 至 60℃”，向量检索确实能召回这段话，但排名并不靠前，因为问题里的“低温”和文档里的“-20℃”在语义空间里距离较远。如果只取 Top-3，这段话很可能被挤出结果集，生成阶段就拿不到关键信息。

面对这种情况，我把检索策略升级成了混合检索：向量检索负责语义召回，关键词检索（BM25）负责精确匹配。两者各自召回一批候选，再合并去重，送进重排序阶段。实测下来，混合检索能把“精确术语型”问题的召回率提升 15 到 20 个百分点。这也解释了为什么很多生产级 RAG 系统都不再是“纯向量”架构——纯向量适合语义泛化查询，但在专有名词、型号、代码片段这些场景里，精确匹配依然不可替代。

4.2 重排序（Rerank）为什么是检索质量的胜负手

很多入门资料会把 RAG 简化为“向量检索 + 大模型生成”，但实际上线之后你会发现，向量检索出来的 Top-K 里，真正与问题强相关的可能只有两三条，剩下都是“看着像、实际不相关”的干扰项。如果把这些干扰项直接塞给大模型，它很容易被带偏——它不知道哪些内容是可信的，只会把所有上下文都当作参考依据。

所以我从第一版原型开始就给链路加上了重排序环节。重排序模型的输入是“问题 + 候选文本”，输出是相关度打分，本质上是用一个更精细的模型，对粗排结果做一次精排。它和向量检索的差异在于：向量检索是在一个巨大的库里快速筛出几百条候选，重排序是在这几百条里挑出最精准的十条。

我在 all-in-rag 里记录了重排序的配置经验：候选集数量一般取 50 到 100，重排序之后保留 Top-5 给生成阶段。这个数字不是拍脑袋定的——候选太少，漏掉相关段落；候选太多，重排序模型的计算成本成倍上升，而且长尾的低相关文本可能引入噪声。我还特地对重排序模型做了领域微调实验：用几百条模拟问答对，让模型学会“技术文档里什么算相关”。微调之后的效果提升非常明显，尤其在“问题包含型号但文档用全称”这类语义匹配场景里，重排序模型的判断比通用模型准得多。

4.3 查询改写：用户不会用检索的语言提问

这是我在 all-in-rag 里后补的一个环节，最初版链路里压根没有它。后来发现，用户实际提问的方式和知识库的表述习惯经常对不上。比如知识库里写的是“如何重置设备”，用户却问“我搞坏了设置怎么恢复出厂”，这两句话在语义上相关，但向量检索的效果取决于 Embedding 模型对口语化表达的泛化能力，不一定稳定。

查询改写就是解决这个问题的：在大模型生成答案之前，先用一个轻量模型对用户原始问题进行扩展和改写。改写方向包括：把口语转书面语、补充同义词、拆解复合问题、识别并规范化专有名词。我实际使用的一个策略是：同时生成原始问题和改写后的多个查询变体，分别检索再合并结果，这样既不丢失原始查询的原意，又能通过改写扩大召回覆盖面。

当然，查询改写不是无脑加。它增加了一次额外的大模型调用，延迟和成本都要考虑。我在生产环境里的做法是加了一个开关：对短查询（比如少于 10 个字）不做改写，对长查询或检索结果置信度偏低的查询才触发改写。这样既保证了大部分查询的低延迟，又能在疑难问题上提升召回质量。

5. 生成阶段：Prompt 编排与上下文管理

5.1 给大模型的 Prompt，不是把检索结果拼进去就行

很多人以为生成阶段就是把“问题 + 检索到的段落”拼接起来发给大模型，我在实践中发现这个做法效果很差，原因在于大模型分不清哪些段落是可信依据，哪些只是沾边的背景信息。它可能引用一段过时文档里的说法，完全忽略新文档里的更新条款。

我在 all-in-rag 里沉淀的 Prompt 模板，核心是明确划分“角色、任务、依据、约束”四个部分。角色设定让模型知道自己是知识库助手，不是通用聊天机器人；任务说明让它明确要基于提供的上下文回答，而不是自由发挥；依据部分是检索到的段落，每段前面带上序号和来源标识；约束部分则明确：如果上下文里找不到答案，直接说不知道，不要编造。

这个 Prompt 模板看起来简单，但里面的细节都是踩坑踩出来的。比如“依据部分”，我一开始把整段文本原样塞进去，结果大模型经常被长段落里的冗余信息带偏。后来我改成“每个依据先提炼成一句话摘要，再附上原始段落”，模型生成的答案明显更聚焦。再比如“来源标识”，我在生成结果里要求模型在关键结论后面用方括号标注来源编号，这样前端展示引用来源时，可以直接对应到检索到的原文位置，可解释性大大增强。

5.2 控制注入上下文的长度与布局

大模型对上下文不同位置的内容敏感程度不一样，这一点被很多人忽略了。我在实验中发现，把关键依据放在靠近问题的地方（而不是放在一大段上下文的最前面），模型对它的关注度明显更高。这和人类阅读的注意力模式类似——你给一个人一大段背景资料，再在末尾抛出一个问题，他往往需要回头去翻资料；如果把最相关的几条依据压缩精简后紧贴着问题放，回答质量会更稳定。

所以我的 Prompt 布局是：开头放系统指令，紧接着放“当前问题”，然后是“重排序后最相关的 Top-3 到 Top-5 条依据”，最后才是完整检索上下文。依据部分每条不超过 150 字，超长内容先做摘要压缩。这样既保证了模型有足够素材，又不会让干扰信息稀释重点。

另外，上下文长度还直接影响生成延迟。我把注入的总 token 数控制在一个合理范围内（根据模型上下文窗口而定，一般保留 30% 余量给生成部分），超过阈值的检索结果直接丢弃，而不是全部塞进 Prompt。这个策略极大地稳定了生成延迟，避免了“检索结果多的时候响应突然变慢”的线上抖动问题。

5.3 生成参数的调优记录：温度、Top-P、重复惩罚

大模型的生成参数，我在 all-in-rag 里专门建了一个记录页，因为在不同的 RAG 场景下，参数的最优值真不一样。我的默认配置是温度 0.2、Top-P 0.9，用于知识问答。这个配置的意图很明确：知识问答要求确定性，宁可答案平淡，也不要为了“多样”而引入幻觉。温度调高到 0.7 以上时，我观察到回答的措辞更丰富，但事实性错误率同步上升，在需要严谨的技术问题上完全不可接受。

重复惩罚我也踩过坑。早期为了让回答更简洁，我把重复惩罚调得比较高，结果遇到长答案时模型会出现“说到一半突然结束”的情况，因为它在生成过程中不断回避重复表达，最后把自己逼进了死胡同。后来我把重复惩罚降到一个温和值，只在回答确实有明显重复时才起到抑制作用，长答案的完整性立刻恢复了。

需要特别提醒的是，生成参数应该放在所有检索和重排序优化做完之后再调。如果你检索出来的内容本身就不准，生成端无论怎么调温度都是治标不治本。正确的调优顺序，永远是先让检索准起来，再谈生成风格。

6. 评估与迭代：没有评测体系的 RAG 都是“感觉流”

6.1 离线评估集：让每一次改动都有据可依

RAG 系统最大的问题是“感觉好像变好了”，但说不清哪里变好了。我在 early 阶段也犯过这个错误——手工测试几个问题，觉得回答还不错就上线，结果用户的反馈完全不一样。后来我花了一整周时间，从知识库里挑出 100 个代表性的模拟问题，组成一个离线评估集。

这 100 个问题不是随便选的，我按几个维度做了分类：短查询和长查询、术语密集型问题、口语化改写问题、跨段落信息组合问题、知识库里没有答案的负例问题。每个问题都标注了期望命中的文档和期望答案的要点。有了这个评估集，每次改动后我都能跑一遍完整的离线评测，用召回率、命中位置、答案相关度等指标量化对比前后差异。

这个评估集至今还在持续更新，我每次从线上日志里发现一个“用户问了但回答不好”的新类型问题，就会把它补进去。渐渐地，评估集越来越能代表真实用户分布，评测结果也越来越能预判线上效果。我认为这是所有做 RAG 的人都应该尽早投入的一件事——它可能不产生直观的功能，但它让后续所有优化都有方向、有标准。

6.2 线上效果追踪与用户反馈闭环

离线评估能解决“改动有没有变好”的问题，但解决不了“用户实际用起来怎么样”的问题。我在生产环境里，给每次问答都加上结构化日志：记录用户原始问题、查询改写结果、检索引中了哪些文档、重排序得分、生成答案、用户的点赞/点踩反馈。这些日志让我能在线上复现任何一个坏案例。

分析线上日志时，我发现了一个很有代表性的问题：大量用户问的是“多跳问题”，比如“A 型号和 B 型号在户外场景下哪个更合适”。这类问题需要同时命中两个型号各自的技术参数，再在生成阶段做对比。如果知识库里两个型号的参数分散在不同文档里，单路检索很容易只召回其中一个文档的片段。解决这个问题，我用了两种方式：一是查询改写阶段主动识别“对比类问题”，将其拆解为两个独立查询分别检索；二是在重排序阶段加入“对比相关性”的判断逻辑。这些改动如果没有线上日志支撑，几乎不可能定位到问题根因。

所以我给所有 RAG 项目的一条建议是：从第一天就埋日志，日志字段宁可多不可少。有了完整的链路日志，排查问题就是从“猜”变成“看现场”，效率完全不是一个量级。

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

7.1 检索召回不到相关文档，怎么查

这是 RAG 上线后最常遇到的问题。我在 all-in-rag 里的排查顺序是固定的：先看检索到的原始结果里，目标文档到底有没有出现。如果没出现，说明是“召回漏了”，原因通常集中在三个方面：Embedding 模型对当前查询的语义理解不足、分块方式导致目标文本的向量被稀释、关键词检索的词典里缺少专有名词。如果目标文档出现了但排名靠后，说明是“排序问题”，需要检查重排序模型的判断逻辑或者调节候选集大小。

排查时，我强烈建议把每一步的中间结果可视化出来。我写了一个很简单的调试脚本，输入一条查询，输出每个阶段的 Top-N 文档及打分。看到打分变化，就能判断是哪个环节把相关文档排下去了。这个排查方式比直接改参数试错高效得多。

7.2 生成答案有幻觉，是检索的问题还是模型的问题

幻觉是 RAG 绕不开的话题。我的经验是：大部分幻觉的根源不是大模型“太能编”，而是检索内容里混入了不相关或错误的段落。你给一个诚实的人一份错误资料，他也会基于资料说出错误结论，这是可以理解的。所以排查幻觉，我第一步做的永远是“看生成答案引用的那几条依据，到底靠不靠谱”。

如果依据本身是对的，但模型还是编了不在依据里的内容，那才是 Prompt 约束或模型能力的问题。这时候我会做两件事：一是强化 Prompt 里的“不基于依据不回答”约束，并明确惩罚性指令；二是尝试把生成温度进一步降低。如果依据本身就错了，那就回到检索链路去解决，而不是在生成端打补丁。

7.3 一个可复用的 RAG 调试速查表

我把日常排查看成一张速查表，放在 all-in-rag 的开头位置，每次遇到问题先查表，再动手改。

这张表不能直接解决所有问题，但它把排查思路固化成了一种肌肉记忆，让我面对新问题时不会乱了阵脚。

8. 后续想在这条路上继续做的事

all-in-rag 这个笔记库到现在还在更新，最近我在探索两个方向。一个是评估自动化，把离线评估集和线上日志打通，做成一个半自动的回归测试系统，每次改动一键跑完，直接输出效果对比报告。另一个是查询理解的深化，比如识别用户提问背后的意图类型，是“事实查询”“对比查询”还是“操作指导查询”，不同意图走不同的检索和 Prompt 策略。

说到底，RAG 不是一个“调好参数就一劳永逸”的系统，它更像一个需要持续喂养和维护的知识服务。我所有经验的核心只有一句话：理解每个环节在做什么，用数据而不是感觉来驱动决策。这条经验，大概就是 all-in-rag 这个笔记库存在的最大意义。