企业官网建设流程全解析

1. 项目背景与目标定位

1.1 为什么这一周选择做 RAG 知识库问答

先说结论：在这一周之前，我花了一个多月的时间把大模型 API 调用、Prompt 工程、LangChain 基础流程、FastAPI 后端开发、React 前端这一套东西分别过了一遍，但始终有个别扭的感觉——我会调模型、会写接口，但做出来的东西没有真正"私有"的知识。换句话说，模型懂全世界的常识，却不懂我自己的文档、我团队的内部规范、我积累的几十份项目复盘。Week 5 我决定把 RAG（Retrieval-Augmented Generation，检索增强生成）知识库问答系统从零到生产环境完整做一遍，核心目的就两个：一是打通"文档上传 → 切片 → 向量化 → 检索 → 生成回答"这条完整链路，二是把之前零散学的全栈技能全部串起来，做一个能真正被团队用起来的系统。

这次项目的业务场景设定为团队内部知识库，文档类型包括 Markdown 技术文档、PDF 需求说明书、TXT 会议纪要和几十条 FAQ 问答对。周报里给这个系统提了三个硬性指标：回答准确率能达到 80% 以上、单次问答响应时间在 5 秒以内、支持同时上传多种格式文档。这三个指标直接决定了技术选型和架构设计的方向，后面很多细节都是围绕它们展开的。

1.2 这个项目适合谁来参考

如果你正在学 AI 应用开发，尤其是已经会调大模型 API、但没完整做过一个 RAG 项目的人，这篇总结会对你有帮助。我会讲清楚每一步为什么这么设计、有哪些可以"拿来就用"的参数，以及我在实际开发中踩过的坑和调整过程。同时，如果你已经在做 RAG 但觉得效果不稳定、或者想从本地脚本升级为正式服务，中间几节关于检索优化和部署实践的思路也值得一看。

必须提前说明的是，这个项目不是一个"论文级"的 RAG 框架研究，而是一个以工程落地为目标的实践记录。所以我没有在算法层面做太多创新，选用的都是目前比较成熟、社区资料丰富的组件，重点在于把它们组合好、调优好、稳定跑起来。

2. 整体架构设计与技术选型思路

2.1 RAG 系统的基本链路回顾

在做项目之前，我先把 RAG 的核心链路在脑子里过了几遍，因为它直接决定了后面的所有模块划分。一个典型的 RAG 问答系统包含两条流水线：离线索引链路和在线问答链路。

离线索引链路做的事情是：把原始文档解析成纯文本 → 按一定策略切分成若干文本块（chunk）→ 对每个 chunk 调用 Embedding 模型生成向量 → 将向量和原始文本一起存入向量数据库。在线问答链路做的事情是：接收用户问题 → 对问题做同样的 Embedding → 在向量数据库中检索最相似的 top-k 个文本块 → 将检索结果和用户问题组装成 Prompt → 调用大模型生成最终答案。

这个流程看起来简单，但每个环节都有很多"魔鬼细节"。比如分块大小怎么定、向量维度选多少、检索回来的文本块冗杂时怎么处理、用户问了意图不明确的问题怎么办，这些都是在测试阶段才会暴露出来的问题。设计时我需要提前为这些环节预留调优的空间，而不是搭完一个流水线就算完。

2.2 技术栈选型与为什么这样选

这次项目的技术栈选型原则是：不追求最新最炫，而追求稳定、资料多、自己能掌控。

这个选型里最值得说的是为什么没有用 LangChain 而选了 LlamaIndex。LangChain 确实名气更大、组件更全，但它的抽象层级太多，对于一个需要深度控制分块和检索细节的项目，LlamaIndex 的文档加载器、节点解析器、检索器设计得更贴近 RAG 本身。举个例子，LlamaIndex 里SimpleDirectoryReader可以直接读目录下所有文件，RecursiveCharacterTextSplitter分块逻辑很清晰，而我要自定义元数据（比如把文档标题注入每个 chunk）时，LangChain 需要额外写很多胶水代码，LlamaIndex 里通过配置NodeParser就能完成。当然，这不是说 LangChain 不好，如果你要做 Agent 类的复杂编排，LangChain 的优势会明显一些。

2.3 系统模块划分

我将系统拆成四个独立模块，每个模块可以单独测试和替换：

• 文档处理模块：负责文件上传、格式解析、清洗、分块。这个模块是离线索引的前置依赖。
• 向量索引模块：负责调用 Embedding 模型、批量向量化、写入 Milvus 集合。需要对增量更新和删除有支持。
• 检索问答模块：负责问题向量化、检索、重排序、Prompt 组装、调用大模型。这是在线链路的核心。
• 管理模块：负责知识库的创建、文档列表管理、问答记录的查看。直接对接前端。

模块划分的好处是，当某个环节出问题时，我可以快速定位是文档解析的问题、向量化的问题，还是检索或生成的问题，而不需要在一大坨代码里翻来翻去。实际开发中，这让我省了很多排查的时间。

3. 文档处理与向量索引的实现细节

3.1 文件解析与清洗：比想象中麻烦的环节

文档解析是整个 RAG 系统里最容易被人忽视、但坑最多的一环。我一开始天真地以为 PDF 解析就是调用一下库直接读文本，直到遇到扫描版 PDF、排版混乱的表格、以及带着大量无效页眉页脚的文档，才发现这里需要做很多预处理工作。

我最终的处理流程是：

1. 文件上传后，先用文件扩展名判断类型，然后分流到不同的解析器。.md和.txt文件直接读文本，.pdf文件用pypdf按页提取文本，同时做 OCR 兜底（如果某一页提取出的字符数少于 20，判定可能是扫描件，再用 PaddleOCR 识别一遍）。
2. 文本清洗环节，去掉多余的换行符、空格、不可见字符；去掉页眉页脚中重复出现的公司名和页码；对 Markdown 文件，保留标题层级信息，用特殊标记包裹标题，方便后面切片时把这些结构信息注回 chunk。
3. 统一编码为 UTF-8，防止后面 Embedding 时出现乱码。

清洗这一步直接影响了检索质量。举个真实例子，我处理一份 30 页的 PDF 需求说明书时，原始解析出来的文本里，每一页顶部都有"XX 公司 内部资料"和页脚页码，如果不去掉，检索时用户问"部署需要什么环境"，很可能召回的是包含"内部资料"字样的噪声文本块。清洗后，同样的检索准确率提升了大概 5 个百分点。

3.2 分块策略的对比与最终参数选择

分块是 RAG 里影响效果最敏感的参数之一，我在实验中对比了固定长度分块、递归字符分块和基于标题结构分块三种方式。

• 固定长度分块：直接按 512 个字符切割，实现简单，但容易在句子中间截断，导致语义不完整。
• 递归字符分块：按换行符、句号、逗号、空格这种优先级顺序递归切割，能尽量保持语义边界。我用RecursiveCharacterTextSplitter实测下来，比固定长度分块的效果好很多。
• 基于标题结构分块：先按 Markdown 或文档的大标题切分出"章节"，章节内部再用递归字符分块细化。这个方案能保证每个 chunk 都带有明确的主题，检索时命中率最高。

最终我采用基于标题结构 + 递归字符分块的组合方案，默认区块大小设为 400 个字符、重叠区 80 个字符。重叠区的目的是减少切分边界导致的语义断裂，比如一个关键句子被从中间切开，如果前后两个 chunk 有重叠，检索时至少能命中其中一半。这个参数不是拍脑袋定的，我在测试集上分别试了 300/400/500/600 四种区块大小，400 的效果在回答准确率和上下文冗余度之间最平衡。区块大小太大会携带太多无关信息，干扰模型回答；太小则信息量不足，检索到也答不全。

分块之后，我给每个 chunk 注入了元数据，包括来源文档名、章节标题、文档类别（技术文档/需求/FAQ）、创建时间。这些元数据在后面的过滤检索和回答溯源时非常有用。

3.3 Embedding 模型选型与本地部署

Embedding 模型负责把文本变成向量，它的选择直接决定了检索的上限。我对比了几种方案：

• 直接调用大模型厂商的 Embedding API，效果好但需要网络调用，批量索引 1000 个文档时耗时很长且费用不低。
• 使用开源模型本地部署，私密性好、无费用、速度快，但需要推理资源。

我最终选用text2vec-large-chinese，一个中文效果不错且参数量适中的模型。部署方式也很简单，先用sentence-transformers加载，再把模型打包成一个独立的 Embedding 服务，提供 HTTP 接口。实际测试中，单个文本的向量化耗时为毫秒级，批量处理时用 GPU 加速的话速度很快，完全满足生产需要。

关于向量维度，text2vec-large-chinese输出 1024 维向量，存入 Milvus 时直接按FloatVector字段声明维度即可。有一点需要注意：线上和线下的 Embedding 模型版本必须保持完全一致，否则会出现检索阶段无法命中的情况。我最初在本地测试时换过一次模型版本，结果向量库里的向量分布完全不同了，逼得我把整个索引重建了一遍。

3.4 向量数据库的集合设计与写入优化

Milvus 的集合（Collection）设计上，我建了一个名为 knowledge_chunk 的集合，字段包括：

• chunk_id（主键，字符串类型）
• doc_id（文档 ID，用于按文档删除数据）
• text（原始文本内容）
• metadata（JSON 字段，存标题、文档名等信息）
• vector（1024 维浮点向量）

写入的时候，我遇到了一个性能问题：逐条 insert 1000 条向量需要几分钟，对批量索引来说太慢了。后来我改成按批次写入，每批 100 条，用insert接口一次性提交，整个索引时间从几分钟降到了十几秒。另外，Milvus 的索引类型我选了 HNSW，参数M = 16、efConstruction = 200，检索时ef = 64，在 10 万条向量的测试集上，查询延迟保持在 50ms 以内，召回质量也不错。

这里有个经验：向量数据库不是越复杂越好，如果你的数据量在几万到几十万这个量级，用一套合理配置的 HNSW 就够了，暂时不用考虑 IVF 或 ScaNN 这种更复杂的索引类型。

4. 检索与生成链路：让问答更准确的调试记录

4.1 从纯向量检索到混合检索

纯向量检索的问题在于：它只做语义匹配，对关键词一致性的把控不好。比如用户问"RAG 是什么"，如果知识库里有一句话"RAG 是一种检索增强生成技术"，向量检索能找到；但如果文档里用的是英文缩写"Retrieval-Augmented Generation"而用户输入"RAG"，向量检索就经常掉链子。反过来，纯关键词检索又没法理解同义词和语义相近的表达。

我最终采用了混合检索方案：向量检索与 BM25 关键词检索并行执行，各返回 top-20 结果，然后合并去重，取交集或综合打分排名靠前的 10 个作为候选。

合并策略上，我先为向量得分和 BM25 得分分别做 min-max 归一化，然后按final_score = 0.7 * 向量得分 + 0.3 * BM25 得分加权融合。这个权重经过实验调整，语义匹配为主、关键词匹配为辅，效果比单一检索方式有明显提升。在 50 条测试问题集上，混合检索的 top-5 召回率比纯向量检索提高了约 8 个百分点。

4.2 重排序环节：用小模型做粗排后的精排

混合检索召回 top-20 之后，直接全部塞给大模型会有一个问题：引入太多无关信息，让大模型回答变得啰嗦甚至答非所问。这里我加入了一个**重排序（Rerank）**环节。

Rerank 模型的思路是：把用户问题和候选文本块做 cross-encoder 匹配，输出一个相关性分数，然后按分数重新排序，只取 top-5 进入最终 Prompt。我选用的是一个中文 Rerank 模型，部署方式和 Embedding 模型类似，也是用 transformers 封装成服务。

加入 Rerank 之后的效果非常明显：回答的准确率从 68% 提升到了 79%，尤其是在一些长文档、多主题混杂的场景下，模型不再被无关信息误导。Rerank 也带来了一定的延迟开销，单次 rerank 大概耗时 200ms，但我可以通过只对 top-20 做精排来控制总耗时。

4.3 Prompt 模板设计与上下文压缩

当检索结果进入 Prompt 后，怎么组织语言直接影响回答质量。我设计的 Prompt 模板包含以下几个部分：

1. 系统提示：说明你是团队知识库助手，只能根据提供的资料回答，资料中没有的信息要明确说"知识库中没有相关内容"，不能编造。
2. 检索结果区：用[1]、[2]等编号列出检索到的文本块，每个文本块前标明来源文档名和章节。
3. 用户问题区：单独标识用户的具体问题。
4. 输出要求：要求回答时引用对应编号的资料来源，如果用户问题与知识库无关，也要礼貌提示。

这个 Prompt 设计很重要的一点是"限制模型自由发挥的空间"。在大模型测试阶段，我发现如果不加"资料中没有的信息要明确说不知道"这条约束，模型会一本正经地编造答案，这是 RAG 系统最忌讳的问题。加入约束后，虽然回答会变得保守一些，但准确率和可信度大幅提升。

此外，我还实现了检索结果的上下文压缩：如果重排序后 top-5 的文本块总长度超过 3000 字，我会通过再次提示对每个文本块做"只保留与问题最相关的一句话或一段话"的压缩处理，避免超出模型的上下文窗口。当然，大多数情况下不会触发这个逻辑，但作为兜底策略是必要的。

4.4 Agentic RAG 和 Graph RAG 的初步探索

在做基础 RAG 稳定之后，我花了一点时间调研了Agentic RAG和Graph RAG这两个方向。它们的思路是：

• Agentic RAG：不止做一次"检索-生成"，而是让模型有自主判断能力，比如判断是否需要多次检索、是否需要调用工具、是否需要追问用户澄清问题。我实验了用自定义 Agent 流程来处理"多轮对话中用户没说完整实体"的情况，效果不错，但工程复杂度明显上升。
• Graph RAG：把文档中的实体和关系构建成知识图谱，在处理"谁和谁有什么关系"这类问题时很有优势。但构建图谱的成本高、对结构化要求高，我暂时只在小规模测试集上试了，没有放到生产环境。

结论是：如果你的场景是"文档问答"，标准 RAG 加混合检索、Rerank 已经足够稳定。Agentic RAG 适合需要复杂推理和工具调用的场景，Graph RAG 适合强关系型知识的场景，但都要根据自己的数据特点来判断，不要盲目跟风。

5. 生产级部署：从本地脚本到可靠服务的改造

5.1 离线索引与在线问答的职责拆分

最初的代码是一个 Python 脚本，导入文档就直接跑完整链路，这在本地实验没问题，但要部署成服务就有很多问题：上传大文件会阻塞 API 请求、重复索引会导致数据混乱、没有失败重试机制等。生产级部署的第一步，我把离线索引和在线问答彻底拆开。

离线索引侧，我用 Celery + Redis 实现了异步任务队列。用户上传文档后，API 接口只负责接收文件并创建一条"待处理"任务，随后立即返回"文档处理中"的状态。后台 worker 任务依次执行文件解析、清洗、分块、向量化、写入 Milvus。这样即便有一个大文件处理很慢，也不会卡住其他用户的访问。任务队列还天然支持失败重试，例如网络抖动导致向量化失败时，Celery 可以自动重试三次。

在线问答侧，我仍然使用 FastAPI 提供同步接口，但内部做了并发控制。因为大模型 API 的并发有限，我加了信号量限制同时进行的模型调用数，防止调用超时或触发限流。

5.2 异步改造与超时控制

生产环境的另一个关键改造是超时控制。大模型 API 有时会因为网络问题迟迟不返回，如果不加超时限制，用户的请求会一直挂着，前端只能干等。我做了这样几层超时设计：

• 调用大模型 API 时设置 30 秒超时，超时后返回友好错误信息。
• 整个问答接口的总超时时间设置为 45 秒，包括检索时间和模型生成时间，超过了就返回"生成超时，请重试"。
• 前端请求设置为 50 秒超时，并加一个加载动画提示用户等待。

这种"逐层超时"的机制非常实用，避免了某个环节卡住拖垮整个服务的情况。

5.3 Docker Compose 一键部署

为了让系统可以在任何一台新服务器上快速跑起来，我把所有依赖服务都用 Docker Compose 编排起来，包括：

• api：FastAPI 后端服务
• frontend：Nginx 托管前端静态文件，同时做 API 反向代理
• milvus+etcd+minio：Milvus 向量数据库及其依赖组件
• redis：Celery 的 broker 和 result backend
• worker：Celery worker 进程
• embedding+rerank：独立部署的模型推理服务

Docker 化的过程中遇到的最大坑是 Milvus 依赖了 etcd 和 MinIO 两个组件，三个容器的启动顺序和网络配置很讲究。我的做法是使用 docker-compose 的depends_on配置启动顺序，同时在 API 服务里加了"等待 Milvus 可用"的启动健康检查，避免服务启动就报错。

5.4 数据库与文件存储的持久化方案

生产环境里容器是无状态的，如果容器重启，Milvus 中的数据、上传的文件、问答记录都会丢失。这里我在 Docker Compose 的配置中为 Milvus 挂载了本地数据卷，MinIO 的数据也做了持久化，Redis 开启了 AOF 持久化。上传的原始文件存储到了服务器的指定目录，并在结构化数据库中用字段记录文件路径。

问答记录和文档元数据我存到了 PostgreSQL 中，通过单独的schema.sql初始化表结构。这张表的设计包含：doc_id、doc_name、doc_type、upload_time、chunk_count 等，问答记录表包含 question、answer、sources、latency_ms、create_time 等字段。保存问答记录的目的不只是留痕，更是为了后续做效果评估和问题分析。

5.5 性能测试与容量规划

部署完成后，我做了一轮简单的性能压测。测试场景是 20 个并发用户同时提问，每个问题都走"检索 + Rerank + 大模型生成"全链路。从压测数据来看，单次问答的平均响应时间是 3.2 秒，p95 是 5.8 秒，符合周报里设定的 5 秒内基本达到的指标。

容量规划上的建议是：如果你的文档量在 10 万 chunk 以内，单机部署完全够用；如果超过这个量级，Milvus 就要考虑分片和扩容了。Embedding 服务的 GPU 使用率在批量索引时一定要监控，避免单任务把显存占满导致其他任务排队。

6. 效果评估与调优：指标怎么定、怎么测

6.1 离线评估指标的选择

很多初学者做完 RAG 系统，最大的困惑是"怎么知道它好不好用"。我这次搭建了一个简单的离线评估流程，用的指标是从 RAG 评估框架里提炼出来的几个核心指标：

我准备了一个包含 50 条问题的测试集，覆盖了"简单事实类""步骤流程类""对比类""超纲类"四类问题。测试时直接向评估脚本喂入问题，自动跑完检索和生成链路，输出各项指标。这个方法不需要复杂的框架，用很少的代码就能实现，但收益很大。

6.2 人工评测与用户反馈闭环

指标是冷冰冰的，最终好不好用还是要看真实用户的感受。我在团队内部找了 5 名同事试用，收集到的反馈中有几个典型问题：

• 有的问题问得太模糊，比如"怎么部署"，系统不知道用户是想问"部署环境"还是"部署步骤"，回答会比较泛。
• 有的问题包含两个子问题，系统只回答了一半。
• 有些文档内容本身相互矛盾，系统没有指出矛盾，而是直接选择了其中一个回答。

针对这些问题，我在应用层面做了几个改进：对模糊问题，增加一个"澄清追问"的交互，先让用户明确意图再回答；对多子问题，Prompt 里加了"将问题拆解为多个子问题并逐一回答"的指令；对文档矛盾，Prompt 加了"如果多个资料存在不一致，请指出并说明"。这些改进并不需要改动核心链路，但对体验的提升非常明显。

6.3 几轮调优后达到的效果

经过分块参数调整、混合检索加入、Rerank 引入、Prompt 迭代这几轮调优后，最终效果是：

• 简单事实类问题召回率和准确率已达到 85% 以上。
• 步骤流程类问题整体可用，但有时会漏掉流程中的前置条件。
• 对比类问题需要用户把对比对象说清楚，否则容易答偏。
• 超纲类问题（知识库中完全没有相关信息的）识别准确率大幅提升，系统基本能直接说"没有找到相关资料"，不再胡编。

整体上，系统从"能跑通"进化到了"在限定场景下具备生产可用性"的程度。但距离"什么都能答"还有明显差距，这也让我更清楚下一步优化的方向。

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

7.1 检索结果为空或相关性极差

现象：用户输入问题后，检索返回的文本块与问题完全不相关。

排查步骤：

1. 第一步检查向量库中是否有数据。用 SQL 查询 collection 的实体数，确认索引是否成功。
2. 检查用户问题的向量化结果是否正常。单独调用 Embedding 服务，看返回的向量是否有值、维度是否正确。
3. 检查 Embedding 模型版本是否一致。这一点在前面提到过，是我踩过最深的坑。
4. 检查查询语句的top_k参数是否设置过小，比如只有 1，就会导致召回很有限。

7.2 回答中出现了知识库之外的信息

现象：生成答案连模型自带的常识都混进来了，而不是完全基于知识库。

原因：大多是因为 Prompt 中约束不明确，或者模型本身幻觉严重。

解决办法：在 Prompt 中强制加"只能根据提供的资料回答，禁止使用自身知识补充"，并在系统层面做一次答案检测，如果模型回答中的关键实体在检索结果中找不到对应，就把答案标记为"低置信度"。

7.3 大文件上传后索引时间过长

现象：一份 50MB 的 PDF 上传后，索引任务跑了十几分钟，用户端一直在转圈。

原因：文件解析和向量化都是计算密集型操作，在单 worker 下排队处理会很慢。

解决办法：将任务并发数调大，同时把大文件切分后的每一个 chunk 的向量化任务也拆成子任务，一条文档的索引任务被拆成多个小任务并行处理。实测 50MB 的文档索引时间从十几分钟降到了三分钟左右。

7.4 服务重启后向量数据丢失

现象：Docker 容器重启后，问答接口报错找不到集合。

原因：Milvus 的数据没有持久化，容器删除后数据跟随消失。

解决办法：在 Docker Compose 中为 Milvus 挂载持久化数据卷，并统一设置数据存储目录。同时定期对向量库做备份，备份内容至少包含向量库数据、原始文件、结构化数据库数据三部分。

7.5 并发升高后响应变慢

现象：压测阶段，50 个并发请求时，平均响应时间从 3 秒飙升到了 12 秒。

原因：大模型 API 的并发限制和 Embedding 服务的推理瓶颈同时出现。

解决办法：加请求队列，控制同时调用大模型 API 的数量；Embedding 服务改用 GPU 推理并开启动态批处理；Milvus 查询改为连接池方式。

8. 写在最后的几点经验

做这个 Week 5 的项目，最大的体会是：RAG 系统的效果天花板不取决于模型，而取决于数据质量和中间环节的精细度。同样的一个大模型，配合清洗干净的数据、合理的分块、有效的重排序，回答质量会有质的差别；反之，数据一团糟，再强的模型也救不回来。

另外有一个小技巧分享给大家：日志一定要从第一天就开始打。我在项目初期偷懒，很多环节没有日志，结果出了问题只能靠猜。后来我在文档解析、向量化、检索、Rerank、模型调用每个环节都加了结构化日志，记录耗时、输入输出摘要、错误信息，调试效率提升了一倍不止。建议你也从项目开始就用好日志这一个基础设施。

这个系统后续我会继续迭代的方向包括：多模态文档的支持、基于反馈的自动重训机制、更强的关系型知识建模。不过这些都是后话了，先把当前这套跑稳、用熟，再一步步扩张。希望这篇实践总结能给你在搭建 RAG 知识库的路上提供一些实在的参考，少踩几个我踩过的坑。