基于RAG的校园私域知识库问答系统：从数据清洗到部署的完整实践

这学期我们学校的2023级创新实训（三）终于结项了，我们小组做的是一个校园私域知识库问答系统。实训周期一共12周，从需求调研、技术选型，到数据清洗、模型接入，再到最后的部署演示和答辩，整个过程走下来比预想中曲折不少，但收获也确实很大。这篇就当是给下一届学弟学妹和正在带创新实训的老师们一份踩坑记录，把我们从零到一搭建这套系统的思路、参数、代码片段和真实遇到的问题全部交代清楚。

先说一句：网上到处是各种教程，但到了自己写代码、跑数据、调接口的时候，你会发现坑都不在教程里，而在文档没写的那几行注释里。这篇文章会把我们实操时的方案选择、参数调优、现场排错都展开讲，适合想用自然语言问答的方式做校园信息查询、企业内部知识库、甚至是个人文档助手的开发团队拿来参考。

1. 项目整体设计与思路拆解

1.1 为什么选这个方向

创新实训（三）的主题没有限死，但学校要求必须贴近实际场景，不能为了做项目而做项目。我们组前期调研了三个方向：校园二手交易小程序、食堂菜品推荐系统、私域知识库问答系统。前两个方向开发难度一般，但创新点不够，答辩时容易被问到"为什么不用现成产品"。知识库问答这个方向踩中了当时大模型应用的热点，而且校园里确实有这样的痛点：学生想查培养方案、选课规则、奖学金申请条件、社团活动场地借用流程，通常需要翻好几个网站、问好几个群，信息分散且更新不及时。

我们想做的是一个统一入口：学生输入一句自然语言，系统直接给出准确答案，并且附带信息来源，方便追溯。这个方向既有人工智能相关的算法内容，又有工程化的数据清洗和系统开发任务，小组分工时很容易拉开梯度，也让每个人都有明确的技术成长点。实训结束之后，这个系统还能继续被学校信息化部门拿去完善，不是那种结项就报废的项目。

1.2 技术方案选型：为什么是RAG而不是微调

选题确定后，第一个争论焦点就是：到底让模型直接回答问题，还是把文档喂给微调后的模型？我们最初请教了某位带过多届实训的老师，他的建议很直接：12周时间做一个垂直领域微调，数据量不够，效果不稳定，而且后续知识更新非常麻烦。校园政策每年都会调整，如果所有知识都融在模型参数里，改一个奖学金的申请条件就得重新训练。这不现实。

最后我们选的是RAG（Retrieval Augmented Generation，检索增强生成），整体思路分三步：

• 把校园里有参考价值的文档统一采集下来，清洗干净后切片，再做向量化，存进向量数据库。
• 用户提问时，先用检索模块把最相关的文档片段捞出来。
• 把问题加上检索到的上下文一起发给大模型接口，由模型基于这些上下文组织自然语言回答。

这种方案最大的优点是知识更新只需要重新处理新增文档，不用动模型本身。而且用户在系统里能看到"参考依据"来自哪一份文件，这对校园场景尤其重要，因为学生看到答案的时候会本能地质疑"你凭什么这么说"，有了引用来源说服力会强很多。

提示：如果你们的实训项目也是做问答类系统，应对"数据更新快"的场景优先考虑RAG；如果数据非常固定且你手里有几千条高质量问答对，再考虑微调也不迟。

1.3 系统总体架构与核心组件

整个系统我们拆成四个模块，各模块之间通过API通信：

• 前端：Vue 3 + Element Plus，部署在Nginx上，提供问答对话框、来源展示、历史记录查看。
• 后端：Python FastAPI，负责接收前端请求、调用检索模块、调用模型接口、返回结果并记录日志。
• 知识库处理：包括文档采集脚本、清洗脚本、切片工具、向量化任务，是一套离线Pipeline。
• 向量数据库：一开始用Milvus，后来因为Docker部署太占内存换成了开源的Qdrant，实测在16GB内存的服务器上跑200W条向量依然没有明显卡顿。

当时还对比了MongoDB加全文索引的方案，但向量召回效果差距太大，直接放弃。Milvus功能强，但配套组件太多，实训这种多人协作且服务器配置有限的场景，Qdrant安装简单、API文档友好，更适合我们。这个选型在后面部署阶段省了不少事。

一个容易被忽略的细节是：系统必须支持"不知道就坦白说不知道"。我们的对话策略里专门加了一个低置信度判定，如果检索出的最大相关分数低于某个阈值，就直接回复"知识库中暂无相关信息"，而不是强行生成一段胡编的内容。这个细节在答辩时很加分，评委一看就知道团队处理过模型幻觉问题。

2. 核心细节解析与实操要点

2.1 知识库构建：数据清洗是第一生产力

我们第一周收集文档，来源包括学校官网的通知公告、教务系统里的培养方案、学生工作部的资助政策、后勤处的办事指南，以及各学院公众号里的常见问答汇总。最终攒了大概2.3GB的原始材料，包含PDF、Word、Excel、HTML和纯文本五种格式。如果直接用这些原始文件去做检索，效果一定惨不忍睹，因为很多PDF是从OA系统打的，里面有大量页眉页脚、重复水印和表格错位。

清洗Pipeline我们做了这么几步：

1. 格式识别与解析：PDF用PyMuPDF提取文本，Word用docx库，HTML用BeautifulSoup去除标签和脚本。
2. 去噪：去掉连续空格、全角半角混乱、页眉页脚中的重复文字、日期和页码。
3. 规则去重：很多文件在官网里存在多个版本，比如某个奖学金的评选通知去年一份、今年一份。我们按文件标题和发布时间做了MD5比对，相同正文只保留最新一版。
4. 表格还原：一些政策类文件里嵌了Excel表格，单用文本提取会把表格内容拆得七零八落。这里我们写了一个小工具，把表格区域单独截出来，按行转成自然语言描述，例如"国家奖学金申请条件：成绩排名前10%"这样。

清洗前后的文本长度差距很大：有的PDF看起来有50页，清洗后有效内容只有8页，其他全是教务系统导出的水印和空行。数据质量决定了后面一切环节的上限，这点是我们整个项目最深刻的教训之一。

注意：一定不要在清洗阶段动手删掉包含敏感信息的字段。学生名单、身份证号、联系电话这些内容要单独脱敏后再入库。我们当时专门写了一个正则加关键词的双层脱敏脚本，防止隐私数据被检索出来后进入模型上下文。

2.2 文档切片与向量化：参数不是拍脑袋定的

RAG系统里，切片策略直接影响召回效果。切片太大，模型接收的上下文容易超长，检索返回的片段会混入无关信息；切片太小，语义不完整，一句提问对应的上下文经常被截断。我们试过三种配置：

最终我们用的是第三种：先识别文档里的标题结构，按章节切分，同时在章节内部，如果内容超过800字，再按段落边界继续切，保证每个切片至少包含一个完整的语义单元。这样做的本质是"先逻辑分段，再自动切细"，比单纯按字符切要可靠得多。

向量化模型我们用的是国产开源的中文向量模型，维度1024。批量向量化的速度很快，2.3GB的数据切完大约有18万个切片，两台机器跑一个晚上全部向量化完成。需要提醒的是，向量化之后一定要保存一份"切片ID与原文路径的映射表"，否则检索召回后你都不知道该把用户往那个页面上引导。

2.3 检索模块：召回加排序，两层逻辑不能省

检索我们实现了两层架构：第一层用Qdrant做向量召回，取Top100候选切片，第二层用重排模型（Reranker）对候选集合做精排，取Top5作为最终上下文。很多简化版的RAG系统只做第一层，直接把Top5给模型当上下文，实践下来的问题是：向量召回的第二三名经常是一字不差但语义完全不一样的内容，比如"校级奖学金申请"和"国家奖学金申请"边界容易被模糊。

重排层的选型：先用一个8GB显存的GPU跑开源的中文Reranker模型，单条Query重排100个片段耗时约200毫秒，完全在可接受范围。如果你们没有GPU，也可以直接用向量召回时的距离分数排序，效果会掉一些，但在数据量小（比如几万切片）的情况下差距不算特别大。

检索时的Query改写也很关键。校园场景里很多问题带着口语化的表达，比如"我想问一下奖学金什么时候评"和"奖学金评选时间"其实检索意图差不多，但直接拿原句去向量化，效果往往不如先改写一遍。我们接了一个大模型接口专门做Query改写，把口语自动归一成标准检索问句，实测召回准确率提升了大概8个百分点。

2.4 大模型接口接入与对话流程

模型接口我们初期对比了好几家，最终选定的是国内某开放平台发布的对话模型API。接入逻辑非常简单，就是POST一个包含system、user、assistant三段消息的JSON过去，但真正的细节在于Prompt设计：

• system消息明确告知模型："你是校园信息助手，只根据提供的知识片段回答用户问题，若片段中没有相关内容，请明确告知用户不知道，不要编造建议。"
• user消息不直接把检索结果倒进去，而是用模板包一层，把来源文件名标注出来，让模型知道每条内容的出处。
• 为了防止模型输出过于教条，我们允许它在回答开头先给出结论，再补充细节，比如"可以申请，申请条件是……。

温度参数我们从默认的0.7调到了0.2，因为校园政策类问答讲究准确，不需要太发散。如果你们做的是聊天机器人场景，温度可以调大；但做知识库问答，温度越低越稳定。

另一个很坑的地方是上下文长度。我们的向量切片平均是400字，Top5就是2000字，加上问题和对话历史，很容易撑爆模型的上下文窗口。我们在后端加了一个历史消息压缩逻辑：当前轮对话保留完整历史，超过5轮之后，把更早的历史用一个大模型一次性压缩成摘要再拼接。这个模块写起来不复杂，但测试时发现很多线上的"上下文超限"报错都是因为它没生效而导致的。

3. 实操过程与核心环节实现

3.1 两周一迭代：从Demo到可演示版本

这个实训是跨学期的，实际编码时间并不连续，我们按两周一迭代来推进：

• 第1到2周：完成数据调研和采集，做出一个包含500条问题的问答需求清单。
• 第3到4周：搭好后端API骨架，实现最基本的"向量召回+模型调用"，回显效果还是个黑框框。
• 第5到6周：完成后端调优和前端基础界面，对话框支持流式输出和来源展示。
• 第7到8周：清洗第二批高优先级文档，扩充知识库，加入Query改写和Reranker。
• 第9到10周：部署到服务器，配置HTTPS，做并发压测。
• 第11到12周：准备演示环境、整理代码文档、模拟答辩问答。

这个节奏看起来很常规，但有一个关键经验：第一轮Demo一定要"窄而深"。也就是哪怕只支持20个问题，也要把完整的检索链路跑通，而不是先把界面做好、再慢慢加知识库。我们组有个中途差点把前端做成了重头戏，还好及时发现并纠正了方向。搞实训项目最忌讳的就是把时间全花在页面上，结果核心链路数据质量不行，答辩一演示就露馅。

3.2 后端核心代码与参数细节

后端我们用了FastAPI，原因是异步支持好、写起来快、Swagger文档自动生成，团队内部分工也方便。下面这段是检索加生成主链路的简化版代码，参数已经改成我们最终调试好的配置：

from fastapi import FastAPI, HTTPException from qdrant_client import QdrantClient from sentence_transformers import SentenceTransformer import openai app = FastAPI() client = QdrantClient(host="localhost", port=6333) encoder = SentenceTransformer("/models/embedding_model") openai.api_key = "your_api_key" TOP_K_CANDIDATE = 100 TOP_K_FINAL = 5 CONFIDENCE_THRESHOLD = 0.35 @app.post("/chat") async def chat(payload: dict): query = payload["query"] rewritten = rewrite_query(query) # 调用大模型接口做Query改写 query_vector = encoder.encode(rewritten).tolist() hits = client.search( collection_name="campus_kb", query_vector=query_vector, limit=TOP_K_CANDIDATE ) if not hits or hits[0].score < CONFIDENCE_THRESHOLD: return {"answer": "知识库中暂无相关信息，请换个问法或联系辅导员。", "citations": []} top_hits = rerank(rewritten, hits[:TOP_K_CANDIDATE])[:TOP_K_FINAL] context = build_context(top_hits) answer = call_llm(query, context) return {"answer": answer, "citations": [h.payload["source"] for h in top_hits]}

这里重点解释几个我们踩过坑的参数：

• CONFIDENCE_THRESHOLD = 0.35：Qdrant返回的score不是0到1的概率，在不同距离函数下数值范围不一样。我们最终用余弦距离，实测这个阈值区分度最好。你们接入时不要直接照抄，要拿一批真实问题去跑一遍，看看答不上来时score普遍落在什么范围，再反向订阈值。
• TOP_K_CANDIDATE = 100：候选数量不是越多越好。100个候选配合Reranker，在18万切片上性能还可以；如果候选太少，Reranker优势体现不出来；如果候选太多，重排耗时过高。
• build_context内部会把每个片段的来源文件名包在引用标记里，比如"来源：2024年本科生奖学金评审办法.docx"。这样模型回答时能自动带上出处。

3.3 前端联调与流式输出

前端我们找的是Vue 3生态里现成组件库，没做特别复杂的界面。整个页面分成三大块：中间是对话列表，右侧是当前回答的引用来源卡片，顶部是知识库覆盖范围的说明文字。实际做下来，最花时间的不是界面布局，而是流式输出和后端日志的配合。

大模型API本身支持流式返回，我们后端用SSE（Server-Sent Events）把增量推给前端。这个过程中遇到过一个经典问题：页面流式输出时如果网络抖动，消息会奇怪地中断，但后端日志显示任务其实还挂着。排查了很久才发现是前端在SSE连接断开后没有重试机制，最后加了一个简单的指数退避重连才稳定。

另一个前后端联调的经验是：接口返回结构一定要在设计阶段定死。我们早期接口里的citations字段一会儿是列表、一会儿是字符串数组，前端对应解析逻辑反复改，浪费了不少时间。后来直接把JSON Schema固定下来，前端Mock数据先跑通，后端再按契约实现，联调效率立刻提升。

3.4 部署与压测

服务器配置是4核CPU、16GB内存、一块Tesla T4显卡。整个部署用Docker Compose编排了四个容器：前端Nginx、后端API、Qdrant、一个向量化微服务。最开始我们尝试过把Python环境和模型加载全都打包进一个镜像，结果镜像体积超过8GB，每次启动要5分钟，改起来痛不欲生。后来拆成两个镜像，一个负责接口服务载入重排模型，另一个负责文本向量化，中间用HTTP通信，虽然是多了一步网络请求，但开发迭代速度明显提升了。

压测我们用的Locust，模拟了50个并发用户，每个用户平均间隔3秒发一轮问答。主要测了两个指标：

• 请求成功率：要求99%以上。
• 回答总耗时：P95需要控制在5秒以内。

实测下来瓶颈不在Qdrant，也不在大模型API，而是Reranker的GPU推理。50并发时，单条请求的P95耗时能达到3.4秒，其中Reranker占了约1.6秒。我们临时加了一个简单的缓存：如果Query改写后的文本和最近10分钟内某条请求完全相同，直接复用上一次的检索结果。这个缓存命中率大约25%，P95降到了2.8秒，能接受了。

注意：部署阶段一定要把API密钥和数据库密码写进环境变量文件，不要直接硬编码在源码里。答辩结束时有个小组做代码展示，不小心把第三方API密钥打到了大屏幕上，当场被提醒，这种教训比较尴尬。

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

整个开发过程中我们记录了一本问题台账，这里挑几个最有代表性的分享出来，基本都符合"网上搜不到、只能现场分析"的特点。

4.1 向量召回效果差的问题排查

现象：用户问"体测成绩在哪查"，召回结果前几名全是关于"体质健康测试免测申请"的文件，相关但答非所问。

排查思路：

1. 先看Query改写结果，发现改写后的句子太长，模型把"在哪查"这种字眼扩充成了一大段描述，反而稀释了关键词。
2. 用改写后的Query做高维向量可视化，发现它和目标的距离分布非常扁平，说明向量化特征不够集中。
3. 我们尝试去掉Query改写步骤，直接拿原始问题召回，效果反而好一些，虽然也会漏召回，但至少不明显偏。

结论：Query改写不是万能药。如果你们的问题本来就是规范化表达，直接召回比改写后再召回更稳。后来我在系统里加了一个规则：只有当原问句包含明显口语词（比如"咋""啥""我想问"）时才走改写，其他情况直接跳过。

4.2 模型输出格式不稳定

现象：系统偶尔会把知识片段里的表格描述原封不动地倒出来，一段回答里混杂着大量换行和编号，用户看得很累。

原因分析：知识库切片里保留了一些结构化文本，比如"一、二、三"这种序号，模型不知道该把它们压缩成自然语言段落。

处理方式：我们在后续迭代里对切片内容做了轻量级预处理，把"一、""1."这些编号枚举改成"（1）"这样的行文格式，同时在Prompt里加了一句："回答时请用通顺的段落重新组织知识片段中的内容，不要直接复制。"加了这两件事之后，输出质量肉眼可见提升。

4.3 数据库挂了，容器重启就失联

现象：有一天拷贝服务器文件时误删了Qdrant的持久化目录，整个容器重启之后索引全部丢失，18万条向量需要重新向量化。

排查经历：这是一个比较低级的失误，但也暴露了我们的流程问题：没有给Qdrant数据目录做定期备份。最后我们写了一个定时任务，每天凌晨把/qdrant/storage目录打包到另一块磁盘上，保留最近7天版本。这个工作在实训中很快，但万一不备份，重新向量化的成本是几个小时，后面大家就都养成习惯了。

4.4 常见问题速查表

这些坑都不深，但如果不记录，几乎一定会改一次代码又重新踩一遍。强烈建议每个实训小组从一开始就维护一本共享的问题台账。

5. 项目管理与实训成果落地

5.1 团队协作与角色分配

我们小组5个人，按能力分成三条线：

• 后端兼算法2人：负责知识库Pipeline、检索链路、大模型接入。
• 前端兼交互1人：负责Vue界面、流式展示、移动端适配。
• 数据兼测试1人：负责文档采集清洗、脱敏、标注测试集。
• 组长兼部署1人：负责服务器、Docker编排、进度协调和答辩材料。

这个分工最合理的地方在于：数据和算法边界清晰但互相依赖，避免了两头都做导致沟通混乱。每周五下午固定开一次组会，会上只讨论三件事：这周目标达成了没有、下周优先级是什么、有没有需要其他成员提前准备的东西。这套机制看起来很简单，但对比隔壁组"平时各干各的，最后三周极限整合"的状态，我们的压力分布均匀太多了。

5.2 文档沉淀比写代码更重要

实训答辩的时候，评委老师最常问的问题并不是"系统演示效果怎么样"，而是"你们这个项目解决的核心问题是什么""技术上有什么难点""数据怎么来"。这就需要文档能讲清楚完整的故事。我们准备了四份材料：

• 需求文档：列出100条真实用户问题，标注优先级和覆盖范围。
• 技术方案：包括架构图、选型对比、Prompt模板、参数说明。
• 测试报告：包含验证集上的召回率、回答准确率、人工评测样本。
• 操作手册：从拉取代码到启动服务，覆盖所有环境依赖。

这些材料不仅仅是为了应对答辩，实际操作中也会发现，写完技术方案之后，你自己对项目结构的理解会提升一大截，很多之前模糊的设计决策会变得相当笃定。

5.3 给下一届学弟学妹的几点建议

最后说几条基于我们实际经历的经验：

• 选项目时先问自己一句："假设半年后回来看这个项目，我还会觉得它有意思吗？"如果觉得没意思，大概率做到中途会失去动力。
• 数据先准备好再做算法。我们第一版Demo效果不佳，90%的原因都是原始文档脏数据太多，不是在算法上缺东西。
• 尽早部署到一台真实服务器上。很多问题只有在公网能访问的环境里才会浮现，比如证书记载的HTTPS配置、接口并发限制、Nginx超时设置。
• 记录一切调试过程。这个实训项目不能光靠代码仓库里的commit记录，更要把参数调整的前因后果写成Markdown笔记，后面写结题报告时会感谢当时的自己。
• 答辩前至少完整演示五遍，每次都用同一个账号、同一个浏览器环境，防止现场暴露接口密钥或者缓存失效导致的问题。

我在这个项目里最大的体会是，创新实训的价值不在于做出一个多厉害的系统，而在于逼着你在一个有限周期里走完"发现问题—设计方案—动手实现—验证效果—总结复盘"的完整闭环。这个闭环在以后写代码或者带团队时都能受用。建议下一届实践时，把每一天的思考和调整都沉淀成文档，这样实训结束时你手里就不只是一个系统，还有一份属于自己的成长记录。