1. 为什么 Demo 跑得通生产却崩了我前后经手过三个企业级 RAG 落地项目行业分别是制造业售后知识库、金融合规问答、以及一个内部研发文档检索系统。这三个项目有一个共同点立项时都拿某个开源 Demo 或者大厂 POC 方案做参照演示环节效果惊艳老板点头预算批下来然后真正开始往生产环境推的时候问题一个接一个冒出来。最典型的一个场景Demo 阶段用几百份 PDF 做测试问什么答什么准确率看着能有百分之八九十。上线之后文档量涨到几十万份用户量从几个人变成几百人突然发现响应时间从两秒变成二十秒检索结果开始飘有些明明存在的文档就是搜不出来还有些不该被看到的文档被普通员工搜到了。这时候你回头看那个 Demo 方案会发现它压根没考虑过这些问题因为它本来就不是为生产环境设计的。这篇文章我想把这三个项目里踩过的坑、总结出来的方案、以及那些 Demo 里永远不会告诉你的细节完整地讲一遍。核心关键词会围绕RAG、Embedding、BM25、Rerank、ACL这几个展开因为这几个词基本覆盖了生产级 RAG 系统最核心的几个模块。如果你正在做或者准备做 RAG 项目不管是用 LangChain4j、AgentScope 还是自己手搓这篇文章里的经验应该都能帮你少走一些弯路。先说清楚一件事我不是说 Demo 方案没用。Demo 的价值在于快速验证可行性让你知道这条路走得通。但 Demo 到生产之间的距离比大多数人想象的要大得多。这个距离不是靠调几个参数就能填平的它涉及到架构设计、性能优化、权限控制、运维监控等一整套工程化的问题。2. 生产级 RAG 和 Demo 的本质区别2.1 数据规模带来的连锁反应Demo 阶段通常用几百到几千份文档这个量级下很多问题不会暴露。比如最简单的全量向量检索几千个向量在内存里做余弦相似度计算毫秒级就出结果。但当你把文档量推到几十万甚至上百万级别事情就完全不一样了。首先是内存问题。假设你用的是一个 768 维的 Embedding 模型每个向量用 float32 存储那就是 768 乘以 4 等于 3072 字节约 3KB。一百万份文档每份切成 10 个 chunk那就是一千万个向量光向量数据就是 30GB。这还没算索引结构的开销。你不可能把所有向量都加载到内存里做暴力检索必须上专门的向量数据库比如 Milvus、Qdrant、Weaviate 这些。其次是检索延迟。暴力检索的时间复杂度是 O(n)一千万个向量做一次全量比对就算用上 SIMD 指令集优化单次查询也要几百毫秒甚至更久。而生产环境用户对响应时间的容忍度通常在 3 到 5 秒以内这还包括了后续的 Rerank 和大模型生成时间。所以你必须用近似最近邻ANN索引比如 HNSW、IVF-PQ 这些把检索复杂度降到 O(log n) 级别。但 ANN 索引带来一个新问题召回率下降。近似检索为了速度牺牲了精度有些本该被检索到的文档可能就被漏掉了。这就引出了下一个话题也是我在项目里花时间最多的部分混合检索。2.2 单一向量检索的致命缺陷很多 Demo 方案只用了向量检索这一路。用户问一个问题把问题用 Embedding 模型编码成向量然后在向量库里找最相似的 Top-K 个 chunk丢给大模型生成答案。这套流程在演示的时候看起来很美好但实际用起来会发现几个硬伤。第一个硬伤是对精确匹配场景的无能为力。比如用户问ERR-4032 这个错误码是什么意思向量检索可能会返回一堆语义相近但错误码不同的文档因为 Embedding 模型关注的是语义相似度不是精确的字符串匹配。它可能觉得ERR-4032和ERR-4033在语义上非常接近但实际上这是两个完全不同的错误。第二个硬伤是对专有名词和缩写的处理。制造业项目里有一堆内部缩写比如某个型号叫XG-2000AEmbedding 模型在预训练时根本没见过这个词编码出来的向量没有区分度。用户搜XG-2000A 的维护周期可能返回的是XG-2000B甚至完全不相关的文档。第三个硬伤是短查询效果差。用户有时候就输入两三个词比如年假规定这种短查询的 Embedding 向量信息量很少检索出来的结果往往很发散。这三个问题叠加在一起导致纯向量检索在生产环境下的准确率远低于 Demo 阶段的表现。而解决这些问题的方法就是引入 BM25。2.3 BM25 为什么在生产环境不可或缺BM25 是一个经典的稀疏检索算法基于词频和逆文档频率来计算相关性。它的核心思想很简单一个词在文档中出现次数越多这个词越罕见那么这篇文档和这个查询的相关性就越高。虽然听起来很朴素但它在精确匹配和关键词检索场景下的表现往往比向量检索更靠谱。我拿制造业项目里的一个真实案例来说明。用户查询液压泵密封圈更换步骤BM25 会精确匹配到包含液压泵密封圈更换这些词的文档而且因为密封圈这个词在整个文档库里出现频率不高它的 IDF 权重会很高所以包含这个词的文档会被排到前面。向量检索呢它可能返回一堆讲液压系统维护的文档语义上确实相关但未必包含具体的更换步骤。所以生产级 RAG 的标准做法是混合检索一路用向量检索负责语义召回一路用 BM25 负责关键词召回然后把两路结果融合。融合的算法常见的有 RRFReciprocal Rank Fusion和加权求和。RRF 的好处是不需要调权重它对两路结果的排名做倒数求和公式是 score Σ 1/(k rank)其中 k 通常取 60。这个算法我在三个项目里都用过效果稳定推荐优先考虑。2.4 Rerank 是精度提升的关键一环混合检索解决了召回的问题但召回的结果里仍然会有不少噪声。比如 Top-20 里可能只有 5 个是真正相关的剩下 15 个是搭便车进来的。如果直接把这 20 个 chunk 都丢给大模型一方面浪费 token另一方面噪声会干扰大模型的判断导致生成的答案质量下降。Rerank 的作用就是对召回结果做精排。它用一个 Cross-Encoder 模型把查询和每个候选文档拼在一起输入直接输出相关性分数。和 Embedding 的 Bi-Encoder 不同Cross-Encoder 能让查询和文档在模型内部做充分的交叉注意力计算所以精度高很多。代价是速度慢没法预先计算只能对少量候选做在线打分。生产环境的典型做法是混合检索召回 Top-50 到 Top-100Rerank 精排后取 Top-5 到 Top-10 送给大模型。这样既保证了召回率又控制了送入大模型的噪声。Rerank 模型的选择上开源的有 BGE-Reranker 系列、Cohere RerankAPI 调用中文场景下 BGE-Reranker-v2-m3 是我用得比较多的效果和速度平衡得不错。2.5 ACL 权限控制是 Demo 永远不会碰的雷区这是我在金融合规项目里踩得最狠的一个坑。Demo 阶段所有人用同一个账号所有文档对所有人生效检索逻辑里压根没有权限这一层。但生产环境里不同部门、不同职级的员工能看到的文档是完全不同的。合规部门的文档普通业务员不能看管理层的会议纪要基层员工不能搜到客户的敏感信息更是要严格隔离。如果你在检索阶段不做权限过滤而是在生成答案之后再做那就晚了。因为大模型可能已经把敏感信息写进答案里了你再去过滤答案要么过滤不干净要么把整个答案都删掉用户体验极差。正确做法是在检索阶段就把无权访问的文档排除掉让它们根本不进入候选集。具体实现上有两种主流方案。一种是在向量库和 BM25 索引里给每个 chunk 打上 ACL 标签检索时带上用户权限做过滤。Milvus 支持标量字段过滤Qdrant 支持 payload filterBM25 那边可以在倒排索引的基础上加一层文档 ID 过滤。另一种是维护一个独立的权限映射表检索后先拿到候选文档 ID再去权限表里查这个用户有没有权限把没权限的剔除。前者的性能更好后者实现更简单具体选哪个看你的文档更新频率和权限复杂度。3. 核心模块的选型与实操细节3.1 Embedding 模型怎么选才不踩坑Embedding 模型是 RAG 的地基选错了后面怎么调都费劲。我选型的标准主要看四个维度中文效果、向量维度、推理速度、部署成本。中文效果这块BGE 系列是目前开源里比较稳的。BGE-large-zh-v1.5 维度是 1024效果不错但模型大推理慢。BGE-base-zh-v1.5 维度 768速度和效果平衡得比较好是我在制造业项目里的主力。BGE-small-zh-v1.5 维度 512适合对延迟极度敏感的场景但效果会打折扣。另外 M3E 系列也值得一试M3E-base 在某些中文语义任务上表现和 BGE-base 接近。向量维度直接影响存储和检索成本。维度越高表达能力越强但存储和计算开销也越大。1024 维比 768 维多占 33% 的存储检索时距离计算的耗时也相应增加。所以不是维度越高越好要结合你的数据规模和延迟要求来定。我一般建议从 768 维起步如果效果不达标再往上加。推理速度方面如果你用 GPU 部署batch size 开到 32 或 64BGE-base 在单张消费级显卡上每秒能编码几百个 chunk基本够用。如果用 CPU 部署那就要慎重了BGE-base 在 CPU 上单条编码可能要几十毫秒文档量大时索引构建会非常慢。这种情况可以考虑用 ONNX Runtime 加速或者干脆用 API 调用外部 Embedding 服务。还有一个容易被忽略的点查询和文档要用同一个模型编码。有些 Demo 为了省事查询用一个模型文档索引用另一个模型这是绝对不行的。两个模型的向量空间不兼容算出来的相似度没有意义。另外有些模型区分 query 和 passage 的编码方式比如 BGE 系列在编码查询时需要加指令前缀为这个句子生成表示以用于检索相关文章编码文档时不需要。这个细节如果搞错了效果会明显下降。3.2 BM25 索引的构建与调优BM25 的实现有很多选择。Python 生态里 rank_bm25 是最简单的但它不支持增量更新每次加文档都要重建整个索引生产环境不实用。Elasticsearch 和 OpenSearch 内置了 BM25功能完善支持增量索引和分布式部署是我在企业项目里的首选。如果不想引入 ES 这么重的组件可以考虑 TantivyRust 实现或者它的 Python 绑定轻量且性能好。BM25 有两个核心参数k1 和 b。k1 控制词频饱和的速度默认 1.2 到 2.0 之间。b 控制文档长度归一化的程度默认 0.75。这两个参数对检索效果有影响但说实话在大多数场景下默认值就够用了除非你有明确的评估集可以调优否则不建议瞎调。中文场景下 BM25 有一个特殊问题分词。英文天然用空格分词中文必须用分词器。分词器的选择直接影响 BM25 的效果。jieba 是最常用的但它对专有名词和新词的识别一般。如果你的领域有很多专业术语建议自定义词典把领域词汇加进去。比如制造业项目里我把所有产品型号、零部件名称、工艺术语都加进了 jieba 的自定义词典BM25 的召回效果明显提升。另一个技巧是保留原始查询和分词后查询两路。有些用户查询里包含型号、编号这类不该被分词的字符串如果你强行分词反而会破坏匹配。我的做法是一路用原始查询做精确匹配一路用分词后的查询做 BM25 检索两路结果合并。这样既照顾了精确匹配又覆盖了语义匹配。3.3 Rerank 模型的部署与性能权衡Rerank 模型通常是 Cross-Encoder 结构参数量比 Embedding 模型大推理也慢。BGE-Reranker-v2-m3 的参数量是 568M在 GPU 上对 50 个候选文档打分大概需要 100 到 200 毫秒可以接受。但如果候选数增加到 200耗时就线性增长到 400 到 800 毫秒这就有点危险了。所以 Rerank 的候选数量要控制。我的经验是混合检索召回 Top-50 比较合适Rerank 后取 Top-5。如果召回质量差可以放宽到 Top-100但再往上就得不偿失了。另外Rerank 可以做成异步的先返回混合检索的结果给用户看Rerank 完成后再更新。不过这样用户体验会有点割裂一般不建议。部署方式上如果 QPS 不高比如每秒几个查询单张 GPU 跑一个 Rerank 服务就够了。如果 QPS 高可以考虑模型量化INT8 量化能提速 2 到 3 倍精度损失很小或者用多实例加负载均衡。CPU 部署 Rerank 基本不可行延迟太高。还有一个省事的方案是用 Cohere Rerank 的 API效果很好按调用量付费。但金融和制造业项目通常有数据不出内网的要求所以只能自己部署开源模型。这个要提前和合规部门确认清楚。3.4 ACL 权限模型的设计ACL 这块我在金融项目里设计了三种粒度的权限文档级、部门级、角色级。文档级是最细的每份文档可以指定哪些用户能看。部门级是按组织架构划分比如风控部的文档只有风控部的人能看。角色级是按职能划分比如合规专员角色能看所有合规相关文档不管在哪个部门。实现上我在每个 chunk 的元数据里存了三个字段allowed_users用户 ID 列表、allowed_depts部门 ID 列表、allowed_roles角色 ID 列表。检索时根据当前用户的 ID、部门、角色构造过滤条件只有三个字段中任意一个匹配的 chunk 才会被召回。这个逻辑在 Milvus 里用 expr 表达式实现在 Qdrant 里用 filter 实现在 ES 里用 bool query 实现。这里有个性能陷阱如果 allowed_users 列表很长比如一份文档对几千个用户开放过滤条件的构造和匹配会很慢。优化方法是把用户列表换成用户组 ID检索时先查用户属于哪些组再用组 ID 过滤。这样过滤条件的大小就从用户数量降到了组数量通常能减少一到两个数量级。还有一个坑是权限的实时性。如果管理员刚撤销了某个用户的权限但检索服务里还缓存着旧的权限数据那这个用户仍然能搜到不该看的文档。所以权限数据要么不缓存要么设置很短的缓存过期时间比如 30 秒要么在权限变更时主动推送失效通知。金融项目里我选的是第三种权限变更时通过消息队列通知检索服务刷新缓存实时性最好。4. 完整实操流程与关键配置4.1 文档预处理流水线生产级 RAG 的文档预处理远比 Demo 复杂。Demo 通常就是读 PDF、切 chunk、编码入库三步。生产环境要考虑格式多样性PDF、Word、Excel、PPT、HTML、Markdown、编码问题、表格和图片的处理、文档版本管理等等。我的预处理流水线是这样的第一步做格式解析PDF 用 PyMuPDF 或 pdfplumberWord 用 python-docxExcel 用 openpyxlHTML 用 BeautifulSoup。解析出来的文本要保留结构信息比如标题层级、表格、列表这些结构对后续的 chunk 切分和检索都有帮助。第二步做清洗。去掉页眉页脚、页码、水印文字合并断行修正 OCR 错误。这一步看起来简单但实际很费功夫。制造业项目里的 PDF 有很多是扫描件OCR 出来的文字错误率不低我专门写了一套规则加词典的纠错逻辑把常见的 OCR 错误比如0和O混淆、1和l混淆批量修正。第三步做 chunk 切分。这是影响检索效果的关键环节。Demo 里常用的固定长度切分比如每 512 个 token 切一刀在生产环境效果很差因为它会把一个完整的语义单元切断。我的做法是递归切分先按标题切标题下的内容如果超过阈值再按段落切段落还超再按句子切。chunk 大小控制在 256 到 512 个 token 之间相邻 chunk 之间保留 50 到 100 token 的重叠避免边界信息丢失。第四步做元数据抽取。每个 chunk 除了文本内容还要带上来源文档 ID、文档标题、章节路径、页码、创建时间、权限标签这些元数据。这些元数据在检索过滤和结果展示时都会用到。4.2 混合检索的融合策略混合检索的融合我试过三种方案最后稳定用的是 RRF。先说另外两种为什么放弃。第一种是加权求和把向量相似度和 BM25 分数归一化后加权相加。问题是这两个分数的量纲不一样向量相似度通常在 0 到 1 之间BM25 分数可能是 0 到几十甚至上百归一化方法的选择对结果影响很大调参很痛苦。而且不同查询的分数分布不一样固定权重很难适应所有情况。第二种是级联先用 BM25 召回一批再用向量检索在这批里精排。问题是 BM25 的召回可能漏掉语义相关但关键词不匹配的文档级联会把这个缺陷放大。RRF 的好处是只依赖排名不依赖分数所以不用归一化也不用调权重。公式是 score(d) Σ 1/(k rank_i(d))其中 rank_i(d) 是文档 d 在第 i 路检索结果中的排名k 是平滑参数通常取 60。这个公式的直觉是一个文档在多路检索中都排得靠前那它大概率是真正相关的。实际配置上向量检索和 BM25 各召回 Top-50RRF 融合后取 Top-50 送给 Rerank。k 值我试过 30、60、100差异不大60 是个稳妥的选择。4.3 Rerank 与上下文组装Rerank 之后拿到 Top-5 到 Top-10 的 chunk接下来要组装成送给大模型的上下文。这里有几个细节要注意。第一是去重。同一个文档的不同 chunk 可能都被召回了如果不去重上下文里会有大量重复内容浪费 token。我的做法是按文档 ID 分组同一文档最多保留 2 到 3 个最相关的 chunk。第二是排序。Rerank 后的顺序是按相关性排的但送给大模型时我习惯把最相关的放在最前面和最后面中间放次相关的。这是借鉴了迷失在中间的研究结论大模型对上下文首尾的信息关注度更高。第三是长度控制。大模型的上下文窗口有限虽然现在动辄 128K但塞太多内容反而会降低答案质量。我的经验是控制在 3000 到 5000 token 之间具体看模型能力和问题复杂度。第四是引用标注。每个 chunk 前面加上来源标记比如[文档1]然后在 prompt 里要求大模型在答案中标注引用来源。这样用户能追溯答案的依据也方便排查问题。4.4 大模型生成与幻觉抑制大模型生成环节prompt 的设计很关键。我的 prompt 模板大致是这样的先给系统指令说明角色和任务然后给上下文每个 chunk 带来源标记然后给用户问题最后给输出要求包括只根据提供的上下文回答如果上下文没有相关信息明确说不知道在答案中标注引用来源。幻觉抑制是生产环境的重点。Demo 阶段大模型胡说八道可能没人管但生产环境里一个错误的答案可能导致严重的业务后果。除了 prompt 约束我还会做一层后置校验把大模型生成的答案里的关键实体型号、数字、日期抽出来和上下文做比对如果答案里出现了上下文没有的实体就标记为可疑要么重新生成要么降级为未找到相关信息。另一个技巧是让大模型输出结构化结果比如 JSON 格式包含 answer、confidence、sources 三个字段。confidence 让模型自评置信度低于阈值的答案可以走人工审核流程。sources 列出引用的 chunk ID方便追溯。5. 常见问题与排查技巧实录5.1 检索召回率低的排查思路召回率低是最常见的问题表现是用户明明知道库里有相关文档但就是搜不出来。排查要分路进行。先单独测向量检索。拿一个已知答案的查询看向量检索的 Top-50 里有没有正确的文档。如果没有说明 Embedding 模型不适合这个场景或者 chunk 切分有问题。可以试试换模型或者调整 chunk 大小和重叠。再单独测 BM25。同样拿已知答案的查询看 BM25 的 Top-50 里有没有。如果没有大概率是分词问题。检查查询里的关键词有没有被正确切分领域术语有没有加进自定义词典。如果两路单独测都有但融合后没了那是融合策略的问题。检查 RRF 的 k 值或者试试调整两路的召回数量。如果两路单独测都没有那可能是文档压根没入库或者入库时编码/分词出了问题。检查文档预处理流水线的日志确认文档被正确解析和索引。5.2 响应时间过长的优化路径响应时间长要分段测量定位瓶颈在哪一段。我的做法是在检索链路的每个环节打点计时查询编码耗时、向量检索耗时、BM25 检索耗时、RRF 融合耗时、Rerank 耗时、大模型生成耗时。常见瓶颈和对策瓶颈环节典型耗时优化手段查询编码10-50ms用更小的模型或 ONNX 加速向量检索50-500ms调 ANN 索引参数或加副本BM25 检索20-200ms优化分词或加缓存Rerank100-800ms减少候选数或模型量化大模型生成1-10s用更快的模型或流式输出大模型生成通常是大头如果这块超过 5 秒考虑换更小的模型或者用流式输出让用户先看到部分结果。Rerank 如果超过 500 毫秒把候选数从 100 降到 50。向量检索如果超过 500 毫秒检查 ANN 索引的 ef 参数是不是设太大了。5.3 权限泄露的排查与防范权限泄露是最危险的问题一旦发生可能造成严重的合规事故。排查方法是构造一个低权限用户的账号用各种查询去试探看能不能搜到高权限文档。测试要覆盖各种查询方式精确关键词、模糊语义、文档标题、文档内容片段。防范上除了前面说的检索阶段过滤还要做几层兜底。第一层是索引构建时就按权限分区不同权限级别的文档存在不同的 collection 或 index 里物理隔离。第二层是检索时强制带权限过滤条件这个条件由服务端根据用户身份生成不接受客户端传入。第三层是结果返回前再做一次权限校验防止过滤逻辑有 bug。第四层是日志审计记录每次检索的用户、查询、返回的文档 ID定期审计异常访问。5.4 文档更新与索引一致性生产环境的文档是不断更新的新增、修改、删除都要同步到索引里。Demo 阶段通常是一次性建索引没有这个问题。我的做法是用消息队列做异步同步。文档系统发生变更时发一条消息索引服务消费消息后更新对应的 chunk。新增和修改是重新编码入库删除是按文档 ID 删除所有相关 chunk。这里要注意向量库和 BM25 索引要同时更新否则两路检索的结果会不一致。还有一个坑是文档版本。同一份文档可能有多个版本用户应该搜到最新版本。我的做法是在元数据里存版本号和生效时间检索时只返回最新生效的版本。旧版本不删除保留用于追溯但检索时过滤掉。6. 三个项目的经验教训制造业项目最大的教训是领域词典的重要性。项目初期没做自定义词典BM25 对产品型号和工艺术语的召回很差后来花了两周时间整理词典效果立竿见影。这件事让我意识到通用方案在垂直领域必须做适配不能指望开箱即用。金融项目的教训是权限设计要前置。项目中期才发现权限需求回头改架构把检索链路整个重构了一遍浪费了大量时间。如果一开始就把 ACL 作为核心需求设计进去能省很多事。研发文档检索项目的教训是评估体系要早建。项目初期靠感觉调参今天觉得这个配置好明天觉得那个配置好没有客观标准。后来建了一套评估集包含 200 个查询和对应的标准答案每次改动都跑一遍评估用召回率、准确率、MRR 这些指标量化对比调参效率高了很多。这三个项目做下来我最大的体会是RAG 的难点不在模型在工程。Embedding 模型、Rerank 模型、大模型都有现成的开源方案拿来就能用。真正花时间的是数据预处理、检索融合、权限控制、性能优化、评估体系这些工程化的工作。Demo 方案之所以扛不住生产环境就是因为它们跳过了这些工程化的环节。如果你正在做 RAG 项目我的建议是先用 Demo 验证可行性然后立刻开始补工程化的课。数据预处理流水线、混合检索、Rerank、ACL、评估体系这五块一个都不能少。每块都做到生产级你的 RAG 系统才能真正扛住真实用户的考验。