公司管理层把两千多页产品资料丢过来要求做一个“内部AI助手”——员工问什么它就答什么还要标注回答来源。我一开始以为这只是接个大模型API的活儿但真正梳理下来才发现横在面前的是三个绕不过去的门槛数据不能出内网、问答必须溯源、文档还得持续更新。最终这个项目落地成了一套私有化部署的企业RAG知识库前后正好用了两周。把当初怎么设计架构、怎么一步步搭起来、以及最值得记录的坑在这里做一个完整的复盘。我会尽量把决策背后的理由也讲清楚而不是只列技术清单。毕竟私有化RAG这种东西网上教程一抓一大把真正拉开差距的往往是踩坑后的取舍。1. 需求拆解为什么企业知识库最终没有选择公有云方案1.1 数据边界与合规是最大的拦路虎这个项目最初的诱惑非常大直接把文档丢到某公有云平台的“知识库”功能里上传、解析、问答一气呵成甚至用不着自己写代码。但讨论到一半就卡住了——文档里包含未公开的产品参数、客户方案、报价逻辑还有一部分合作方的技术资料。企业一旦把这些内容传到外部服务上首先就过不了自己内部的合规评估。这不是信不信任某个厂商的问题而是企业文档的所有权和使用边界必须严格限定在内网。只要数据出过内网哪怕是“只用来做向量化”在审计和合同层面都很难交代。所以需求评审的第一条结论就是所有环节包括文档解析、向量化、检索、生成都必须跑在我们自己的服务器上。私有化不是一种技术偏好而是企业级知识库的硬性前提。1.2 权限控制与溯源要求看似简单做到却不容易第二个需求点是权限隔离。企业问答不是单纯“翻文档回答问题”不同角色能看的文档范围完全不同。比如销售团队可以问报价政策但新入职实习生不应该看到完整的成本结构。这意味着检索阶段就必须做权限过滤而不是在答案生成之后再删减。同时还要求回答必须可溯源。管理层明确说AI给出任何结论都要能定位到对应的文档和页码方便人去复核。这就决定了不能一步到位把问题丢给大模型直接作答而是先走“文档召回→重排→根据召回内容生成答案”的链路。也就是说这个项目本质上不是做个ChatGPT套壳而是要做一个带检索和引用机制的私有化知识库系统。1.3 两周工期内如何把需求切成阶段需求边界确认后我把工期切成两段第一周打通从“文档上传”到“问答返回”的完整链路第二周专门用来解决准确率、并发和更新问题。头两天只做一件事——确定架构和技术选型因为后面所有开发都依赖这套骨架。这里也想给一个经验接到类似任务时别一上来就陷入“用哪个框架”的纠结先把业务边界说清楚。知识库是给多少人用的、文档总量多大、更新频率多高、回答要不要分权限这四个问题直接决定了架构的复杂度。这个项目的实际情况是内部约300个员工使用文档总量初期在2000页左右按周更新需要按部门做权限过滤。这个体量决定了我的选型方向——轻量、可控、不过度设计。2. 总体架构设计模块划分与技术选型的真实考量2.1 五层架构大致长什么样整个系统我按职责拆成了五个层面每一层只关心一件事接入层对外提供文档上传和问答接口走FastAPI实现问答流用SSEServer-Sent Events做流式输出。文档处理层负责解析PDF、Word、扫描件清洗内容做分块和元数据抽取。索引与检索层包含向量库、关键词索引、重排序模块是RAG最核心的部分。模型层embedding模型负责文本向量化生成模型负责根据召回内容组织答案。管理层批量入库任务、日志、监控、权限映射保证系统能被人维护。之所以拆这么细是因为踩坑后的复盘点非常清晰数据解析出问题找文档处理层答非所问找检索层生成质量差找模型层和提示词谁都不用来回扯皮。2.2 技术栈对比与选型理由这里直接放一张当初对比后的选型表后面每项都会解释为什么这么选模块最终选择没选的方案理由embedding模型BGE-M3通用英文模型、text2vec中文长文档效果更好支持多语义粒度向量库Milvus 2.xChroma、pgvector支持批量写入、过滤检索、文档规模扩展余地大生成模型Qwen2.5-14B-Instruct更大参数模型单张A100可部署中文效果足够后端框架FastAPI自研编排LangChain全流程可控性高链路每一环都能单独调试重排序模型BGE-Reranker-v2-m3无rerank直接取topk显著提升“精确命中”概率OCRPaddleOCR商用OCR服务私有化要求模型可本地部署我这边的推理服务器是单张A100 80GB所以生成模型选了14B量级跑起来余量充足。如果是两张4090或者单张A100也可以考虑7B版本再小的话答案组织能力会明显下滑尤其是在多文档融合问答时小模型经常忘了引用来源。2.3 没有全盘使用LangChain或LlamaIndex的原因很多教程推荐直接用LangChain把RAG链路拼起来确实方便但我实际测试后发现LangChain的抽象层太厚出了问题很难定位。比如想看“某一步到底用了哪些文档片段”它内部的retriever逻辑包装了好几层打印出来的trace很长也很难读。而企业知识库最需要的恰恰是可观测、可单独调试的链路。所以最终方案是参考LangChain的思路但核心流程全用FastAPI和Python自己编排遇到需要工具类函数时才引用它的模块。这样做的代价是代码量多了一些但换来了对每个环节的绝对掌控——比如我可以在检索阶段随时打印向量召回和关键词召回的原始分数这在调优时帮了大忙。3. 核心链路从零搭建每一环的落地细节3.1 文档解析PDF、扫描件和表格各有各的处理方式第一周有整整两天耗在文档解析上因为RAG的上限由数据质量决定解析出来的文本如果是乱的后面检索再优化也白搭。我根据文档类型做了分流普通文本型PDF用PyMuPDF抽取速度快且能保留页码信息扫描件走PaddleOCR因为不少历史资料是图片格式Word文档用python-docx直接读但要注意把页眉页脚去掉最麻烦的是带复杂表格的PDF后面第4章会详细讲这个坑。统一的处理入口我定义成一套内部schema每个解析结果都包含doc_id、page、source_name、chunk_text、metadata这五个字段。这样做的好处是无论原始文件是什么格式后面分块、向量化、检索都只面对一种标准化结构不用反复适配。解析完的内容还会做一个简单清洗去掉多余空白符、合并被PDF换行切断的英文单词、按页记录页码。这些看起来不起眼但对后续召回准确率影响非常大。3.2 分块策略不是越大越好也不是越小越好分块是整个RAG里最容易被忽略但又最重要的参数。块太大向量化的语义容易被稀释召回精度下降块太小单个片段缺乏上下文生成模型无法组织出完整答案。我做了几组实验对比最终选择了“先按文档结构切分再按块大小回退”的策略。具体做法是先根据Markdown标题或PDF书签定位章节边界把每个章节作为天然的分块候选。如果某个章节内容超过设定上限再按段落合并控制在768个token左右同时保留96个token的overlap。overlap的作用是避免检索时刚好截断在关键边界上让相邻块之间有一点信息冗余召回率会好看很多。def split_document(text, max_chunk768, overlap96): sections split_by_headings(text) for section in sections: if len(section) max_chunk: yield {chunk_text: section} else: paragraphs split_by_paragraphs(section) chunk for para in paragraphs: if len(chunk) len(para) max_chunk: yield {chunk_text: chunk} chunk para else: chunk \n\n para实测下来这种“结构优先大小兜底”的策略比单纯按固定长度硬切Top5命中率大概提升了十个百分点左右。原因也很好理解按段落和章节切分出来的片段本身就是一个相对完整的语义单元而硬切出来的块经常是一段话讲到一半就断了。3.3 向量化与写入批量入库的工程细节embedding用的是BGE-M3支持稠密向量、稀疏向量和多向量三种表示。我在生产环境只启用了稠密向量加稀疏向量两种模式稠密向量负责语义相似度召回稀疏向量用来做关键词层面的匹配兜底。它的中文效果比早期那些以英文为主的模型好很多这个后面踩坑章节会重点说。批量入库时第一个教训是千万不要一条一条请求embedding模型慢到无法忍受。我改成每次打包32个chunk请求一次利用GPU批量推理的优势2000页文档全部向量化大约用了四十分钟。写入Milvus时开了批量insert每批500条向量整体吞吐量非常可观。写入的每条向量都带上metadata重点包括doc_id、chunk_index、department、update_time。这个设计直接支撑了后面的增量更新和权限过滤。没有这一步增量更新那部分几乎没法做。3.4 检索与生成混合检索、重排序与流式输出的组装检索设计成了三段式向量召回 关键词召回 交叉重排序。向量召回负责语义相近但表达不同的情况关键词召回保证专有名词和编号不被漏掉重排序则把两路结果合并后的候选重新打分排序。我的接口大致长这样def hybrid_search(query, top_k20, bm25_k10): dense_result vector_search(query, top_k) sparse_result bm25_search(query, bm25_k) merged merge_and_dedupe(dense_result, sparse_result) reranked reranker.rerank(query, merged) return reranked[:5]这里的重点是top_k不能太小。向量和关键词两路召回先各自取前十到二十个候选合并后再由reranker精排只取前五个喂给大模型。如果一开始就只取五个rerank阶段可选余地太小正确结果很容易被过滤掉。提示词模板是这套系统效果稳定的一半开场明确告诉模型只基于提供的资料片段回答找不到相关内容就直接说明没有找到不许编造。同时要求答案末尾标注引用来源的文档名和页码方便用户点击核查。流式输出用的是SSEFastAPI里通过StreamingResponse实现前端收一个事件流逐字渲染。这个体验和直接用API接口等完整结果完全不同企业内部第一次demo的时候流式输出带来的“AI感”明显更强决策层对项目的接受度也高了不少。4. 两周里最有必要记录的五个坑4.1 表格解析错乱导致回答准确率跌到三成这个坑排在我所有踩坑记录的第一位。项目里的产品资料有大量参数表比如“内存容量、CPU型号、最大功耗”这种三列结构。一开始我用PyMuPDF直接提取文字出来的结果是每个单元格的文本按阅读顺序被拆得乱七八糟有时一行内容横跨了表格的三列有时两行数据被并成一行。问题现象是那些涉及产品参数的问题系统要么答不出来要么把A型号的功耗说成B型号的功耗准确率一度只有三成左右。我当时排查的第一件事是把提取后的原始文本打印出来结果一眼就发现问题不在检索也不在模型而是解析阶段就把数据弄坏了。根因是普通PDF解析库对复杂表格的布局还原能力非常弱。解决方式分两层对于简单表格用pdfplumber的extract_tables直接取结构化数据把每一行转换成一个独立的知识块对于复杂合并单元格的表格用ppstructure做表格识别输出HTML格式的表格结构再按行提取内容。每行作为chunk落到知识库后产品参数类问题的准确率回升到了85%以上。这个坑给我的教训是凡是知识库里有表格一定要单独在解析层做表格识别不能指望通用解析一把梭。4.2 中文场景下embedding模型的选型教训项目第一版我图省事直接沿用了网上教程里常见的通用英文embedding模型。结果一测试中文问句还能召回一些内容但一旦文档里是中英混排、或者同义词比较多Top5命中率就跌得很难看。比如文档里写“故障恢复时间”用户问“宕机多久能恢复”向量检索完全匹配不上。那个阶段的我一度以为问题出在分块策略上反复调chunk大小和overlap收效甚微。直到我把一个同义改写测试用例单独拎出来对比不同模型的向量相似度分数才意识到是embedding模型本身的语言覆盖能力不够。换成BGE-M3之后这类同义改写场景的召回效果立刻好转。验证方法也留下了准备一组“同一意思不同说法”的测试问题集专门用来对比embedding模型的鲁棒性而不是只看总命中率。这套测试集后来也被复用到了模型升级的评估里。4.3 检索到了但还是胡编幻觉问题的根因不只在模型上线前一晚我用测试集跑了一遍突然发现一个非常诡异的现象文档里明明有正确答案检索Top5里也确实召回到了正确片段但模型给的答案还是错的。这就说明问题不在检索而在生成环节。排查链路是这样的先打印出每次问答实际召回的前五个chunk发现正确片段排在第一位但内容被截断了——因为分块时overlap设置太小这个片段缺少了回答问题所需的完整上下文。比如“保修期为一年”这句话在chunk里但“保修期自签收之日起计算”这个条件在另一个chunk里模型单独看第一个片段就给了错误理解。解决方式分两步一是把overlap从64调整到96尽量保证关键条件不落在块边缘二是修改提示词要求模型只能基于片段回答如果片段中的信息不足以完整作答必须输出“资料中未找到完整说明”。第二个改动立竿见影从产品名到参数之间的张冠李戴急剧减少。这让我认识到一个关键点RAG的幻觉不都是模型“编造”有很大一部分是召回片段不完整导致的“误读”。先查召回内容再调提示词顺序不能反。4.4 多人同时用的第一周就卡死内部测试第一天十几个同事同时提问系统直接假死。直观上以为是大模型推理扛不住并发但看了监控发现GPU利用率并不高反而是后端服务大量超时。排查看了一圈当时Gunicorn起了2个worker每个worker同时只能处理一个同步请求。embedding请求是同步调用模型服务的当一个worker在处理embedding时所有其他排队的问答请求都被堵住。再加上Milvus的连接池默认参数非常保守并发一上来连接就被占满。这个链路排查起来比较费劲因为表面现象是“整体变慢”实际瓶颈在两个不起眼的地方。修复方案是三层配合Gunicorn的worker数调到2*CPU核数1Milvus客户端连接池上限从10调到40embedding推理改成独立异步队列前端请求不再同步等待。改完之后20人同时提问也能稳定响应首token延迟大约在1.5秒左右。这个坑提醒我私有化RAG的性能瓶颈往往不在大模型推理而在外部依赖的并发配置上。第一周打压力测试非常有必要别等上线当天才暴露。4.5 文档更新后老版本内容还在“历劫”上线之后第一次更新文档我们只做了“新增”新文档的chunk向量化后插入向量库。结果立刻出现了一个尴尬问题——新的产品手册发布后用户提问时还是经常被召回老版本的参数新旧数据混在一起答案前后矛盾。排查时才发现Milvus里的删除操作不是立刻生效的旧chunk如果还带着原来的doc_id就会在下一次检索时继续被召回。解决方式是在写入阶段就给每条向量record里存了doc_id更新流程变成按doc_id先删除全部旧chunk再插入新chunk最后重建关键词索引。删除完成后还要等几秒做一致性检查确保旧向量不再被召回。这里踩下的最重要经验就是知识库的“更新”和“新增”要当成两个完全不同的操作来设计。如果没有在第一次入库时就规划好doc_id和metadata后面想清理旧数据会非常痛苦。5. 从能用走向好用检索效果调优的一线经验5.1 先给项目建立评估集不然调优全靠感觉第二周调优一开始几乎没法做因为“感觉变好了”和“实际变好了”完全是两回事。后来我花了半天从真实工单和同事提问里收集了100个问题逐条标注答案所在的文档和页码形成一个最小可用的评估集。有了评估集就定义了两个核心指标。第一个是Hit Rate即正确答案所在文档片段是否进入最终送给模型的前5个片Recall中。第二个是Answer Accuracy即人工判断模型给出的答案是否正确。Hit Rate解决“有没有找对资料”的问题Answer Accuracy解决“最终答得对不对”的问题。没有这套评估集我后面所有的调优手段都无从验证。5.2 调优顺序比调优手段更重要调优过程中我踩了一个效率大坑一开始先调提示词模型答案质量有所提升但很快到了一个平台期。后来回头检查才发现召回阶段就没把正确答案捞上来提示词再努力也没用。之后我把调优顺序固定成了文档清洗→分块策略→embedding模型→检索融合→重排序→提示词。顺序背后的逻辑很简单前一层决定后一层效果的上限。解析出来的文本是乱的分块再合理也白搭分块不合理embedding效果再好也召不回完整语义召回内容不完整提示词写得再好模型也巧妇难为无米之炊。这个顺序帮我大幅减少了无效工作。比如最后调提示词时我可以放心地在“召回内容已经正确”的前提下进行一旦效果不佳问题肯定出在生成环节不用再回头怀疑检索。5.3 三个立竿见影的检索增强手段评估集建立后的第一个手段是query扩展。对于问题比较绕的情况我先让生成模型把原问题改写成一个更完整的检索式再拿扩展后的query做召回。比如用户问“数据存在哪最安全”扩展成“数据库存储方案中哪种方式安全性最高”召回效果明显提升。第二个手段是元数据过滤。加上权限隔离后我同步把update_time也作为过滤条件问答时默认只检索最近一年内的文档。这个看似简单的改动让大量过期内容从候选集里消失Hit Rate稳步上升。第三个手段是关键词兜底。向量召回对同义词友好但对精确编号和缩写经常力不从心。BM25的关键词召回正好补齐这个短板两路结果合并后再交给reranker做最终排序。实测数据里关键词兜底对“型号、编号、人名”这类问题的贡献最大几乎占了正确答案来源的一半。5.4 调优前后的效果对比下面是这个项目调优前后的核心指标对比都是基于那100道评估题的实测数据指标初始版本调优后提升幅度Hit Rate召回命中58%91%33个百分点Answer Accuracy答案正确62%85%23个百分点平均首token延迟3.1秒1.6秒快了一倍20人并发成功率约70%98%明显改善Hit Rate从58%到91%这段靠的是表格解析、embedding模型替换和rerank引入Answer Accuracy从62%到85%主要是overlap调整和提示词约束的功劳。当然85%的准确率距离“完全可用”还有距离目前生产环境里我们把“找不到明确依据时明确说明”的情况也算作正确因为它避免了更严重的误导。我个人这次最大的感受是私有化RAG的难点从来不在大模型本身而在数据治理、检索细节和工程化的耐心。两周时间搭起来一个Demo并不难难的是把准确率从“能跑”推到“敢用”。如果你也在做类似项目建议在动手前就想清楚三个问题——文档有多乱、权限多复杂、发版后怎么更新这三件事决定了你后面要踩多少坑。