一、引言Demo 三天上线生产环境却迟迟无法交付几乎所有团队做 RAG 都经历过同一个过程接上大模型、写个 PDF 解析、扔进向量库半天就能跑出一个能答问题的 Demo但真正进入业务、面对几万份内部文档和挑剔的用户时系统立刻变得不可用——答非所问、答案残缺、引用张冠李戴、明明文档里有答案却说“未找到”。很多人第一反应是换更大的模型。这是一个典型的误判。在 RAG 里生成模型决定的是“表达下限”而检索质量决定的是“事实上限”。如果召回的上下文里根本没有答案再强的模型也只能编。工程实践中一次 RAG 效果不达标80% 的归因落在三件事上文档解析质量差、分块破坏了语义、召回链路单一且缺乏评估。本文不谈概念只讲落地向量库怎么选、分块怎么做、召回率怎么调以及那些只有在生产环境才会暴露的问题。先把“不可用”这件事拆细一点因为不同症状对应的病因完全不同盲目调模型只会浪费预算用户看到的症状真实病因典型修复手段答非所问答的是另一个产品的参数分块把表格切碎 / 缺少标题路径结构感知分块 元数据注入答案残缺只答了一半chunk 太小跨块信息未合并父子分块 / 增大 overlap引用张冠李戴来源对不上元数据doc_id、页码未随 chunk 落库全链路透传 metadata文档里明明有却答“未找到”单路向量召回漏掉了精确词混合检索BM25 向量答案前后矛盾新旧版本文档同时被召回软删除 版本覆盖回答内容正确但语气发散噪声上下文过多Context Precision 低Rerank 上下文裁剪我见过一个很典型的内部知识库项目3200 份 PDF 产品文档第一版用“固定 500 字 100 字重叠”的粗暴分块评估集上 Recall10 只有 61%端到端人工抽检准确率 41%。后面三轮优化没有换模型、没有换向量库只做了四件事PDF 解析改为保留标题层级、分块改为结构感知并注入标题路径、加入 BM25 混合召回、加一层 rerank。Recall10 提到 89%端到端准确率 78%。这就是本文要讲的全部内容。另外一个必须先建立的工程习惯在写第一行检索代码之前先攒一个 50~200 条的评估集。每条样本包含query、gold_chunk_ids或至少gold_doc_id 段落定位、标准答案。没有它你后面所有的“优化”都是凭感觉改 A 坏 B永远收敛不了。二、核心原理RAG 本质是一个搜索问题RAG 的完整链路可以拆成离线与在线两条离线索引文档解析PDF/HTML/Word → 纯文本 结构 → 清洗 → 分块Chunking → 嵌入Embedding → 写入向量库并建立索引。在线检索Query 改写/扩展 → 多路召回向量 关键词 → 融合 → 重排Rerank → 上下文拼装 → 生成。衡量这条链路的两个核心指标RecallK召回率正确答案所在的片段是否出现在前 K 个候选里。这是硬性上限——没召回后面全是零。Context Precision上下文精度进入 Prompt 的片段里有多少是真正相关的。噪声过多会显著降低模型的忠实度也会推高 token 成本。一个必须建立起来的认知向量检索不是“语义搜索”的银弹它是近邻搜索。嵌入模型把文本压成定长向量必然丢失细节对于型号、编号、人名、错误码这类低频精确词向量相似度经常完全失效。所以生产级 RAG 几乎不会只用单路向量召回。把这件事说得再具体一点。嵌入模型比如 1024 维的 bge-m3做的事情是把一段几百字的文本压缩成 1024 个浮点数并且保证“语义相近的文本向量夹角小”。这个压缩过程是有损且平滑的——它会保留“这段在讲连接失败排查”这种粗粒度语义但会把ERR_CONN_REFUSED_1042和ERR_CONN_REFUSED_1043这种只差一位的字符串映射到几乎相同的位置。对模型来说它们是“同一类东西”对业务来说它们是两个完全不同的故障。这就解释了一个经典现象用户问“1043 报错怎么解决”向量检索返回了一堆 1042 的文档因为语义确实最接近而真正包含 1043 的那一段可能因为措辞不同“连接被拒绝错误码 1043”排在第 30 名开外。BM25 这类稀疏检索恰恰相反——它对词频和逆文档频率敏感精确匹配1043的片段会直接被顶到第一。两者的失效模式互补这就是混合检索存在的根本理由。融合两路结果最常用的是 RRFReciprocal Rank Fusion它只看排名不看分数天然规避了两路分数量纲不可比的问题defrrf_fuse(rank_lists,k:int60,top_n:int20): rank_lists: 多路召回的有序 id 列表例如 [向量召回ids, BM25召回ids] k: 平滑常数经验值 60k 越小头部排名的影响越被放大 scores{}foridsinrank_lists:forrank,doc_idinenumerate(ids,start1):scores[doc_id]scores.get(doc_id,0.0)1.0/(krank)returnsorted(scores.items(),keylambdax:-x[1])[:top_n]两个指标的量化方式也要提前定死否则团队内部会各说各话。RecallK 按“gold 片段被召回的比例”算Context Precision 可以先用人工标注的小样本估规模上来后用 LLM-as-judge 打分让模型判断“这段上下文对回答该问题是否有用”0/1 二分类即可比打 1~5 分稳定得多。三、向量库选型别被 Benchmark 带偏选型的核心不是“谁的 QPS 高”而是你的数据规模、过滤需求、运维能力和更新频率。以下是常见选项的定位对比产品部署形态典型规模过滤/混合能力适用场景FAISS嵌入式库单机内存级无元数据过滤需自建离线实验、批量打分Chroma库 / 轻服务十万级基础元数据过滤原型验证、内部工具pgvectorPostgreSQL 扩展百万 ~ 千万SQL 过滤极强0.7 支持稀疏向量已有 PG 团队默认首选Qdrant独立服务千万 ~ 亿payload 过滤 稀疏向量强需要精细过滤的生产系统Milvus分布式亿级以上强支持多索引类型大规模、多租户Weaviate独立服务千万级内置 BM25开箱混合检索想少写代码做混合召回我的明确观点千万级以下、团队已有 PostgreSQL 的直接用 pgvector不要引入新组件。RAG 的瓶颈在分块和召回策略不在向量库性能多一个中间件就多一套备份、监控、扩容和故障排查。只有当数据量突破千万、或需要多租户强隔离与极致低延迟时再考虑 Qdrant / Milvus。补充一句规模换算方便你对号入座一条 1024 维的 float32 向量约 4KB100 万条 chunk 的原始向量约 4GB加上 HNSW 图结构的额外开销通常 1.5~2 倍单机 16GB 内存完全扛得住。也就是说百万级数据量根本不是选型的决策点过滤能力和运维成本才是。选型时容易忽略的三个细节过滤与检索的顺序。向量库普遍采用 post-filter先取 top_k 再过滤一旦带上tenant_id xxx这类高选择性条件top_k 会被过滤到只剩几条召回直接崩。务必确认目标库支持pre-filter / filtered search或把ef_search、nprobe调大到 top_k 的 3~5 倍。HNSW 参数。M每层连接数16~32、ef_construction200 左右是常见起点ef_search必须 ≥ top_k 的 2 倍否则近邻图搜不充分召回率会莫名其妙掉 10 个点。更新与删除。文档是会改版的。索引必须支持按doc_id软删除与版本覆盖否则新旧内容会同时被召回模型给出自相矛盾的答案。把 pgvector 的最小可用建表和查询写出来很多坑在 SQL 层面就能规避CREATEEXTENSIONIFNOTEXISTSvector;CREATETABLEdoc_chunks(id bigserialPRIMARYKEY,doc_idtextNOTNULL,-- 原始文档唯一标识tenant_idtextNOTNULL,-- 多租户隔离字段versionintNOTNULLDEFAULT1,heading_pathtext,-- 标题路径用于展示引用contenttextNOTNULL,embedding vector(1024)NOTNULL,is_deletedbooleanNOTNULLDEFAULTfalse,updated_at timestamptzNOTNULLDEFAULTnow());-- 向量索引余弦距离CREATEINDEXONdoc_chunksUSINGhnsw(embedding vector_cosine_ops)WITH(m16,ef_construction200);-- 过滤字段一定要建索引否则 pre-filter 退化成全表扫描CREATEINDEXONdoc_chunks(tenant_id,doc_id,version)WHEREis_deletedfalse;SETLOCALhnsw.ef_search100;-- 必须 top_k * 2SELECTid,doc_id,heading_path,content,1-(embedding$1)ASscoreFROMdoc_chunksWHEREtenant_id$2ANDis_deletedfalseORDERBYembedding$1LIMIT20;关于 post-filter 那个坑值得讲一个真实故障。某 SaaS 团队把 30 个租户的数据放在同一张表查询时写的是“先ORDER BY 距离 LIMIT 5再在应用层过滤tenant_id”。结果大租户的数据多、距离近把小租户的候选全挤掉了小租户的召回率长期在 20% 上下排查了两周才发现是过滤顺序问题。修复方式有两种一是像上面 SQL 那样把过滤条件下推到WHEREpgvector 会走 pre-filter 路径二是升级到 pgvector 0.8开启迭代扫描SET hnsw.iterative_scan relaxed_order;让它在图里持续搜索直到凑够满足条件的行数。四、文本分块RAG 效果的第一性变量分块是整条链路里最“脏”也最关键的环节。它决定了检索的最小语义单元一旦切错后面所有优化都是在错误的地基上装修。4.1 策略谱系固定长度 重叠最省事的基线适合结构混乱的纯文本但极易在句子、表格中间切断。结构感知分块按 Markdown 标题、段落、列表、代码块切分保证每块语义自洽。这是绝大多数企业文档的最佳实践。语义分块计算相邻句子的嵌入相似度在相似度骤降处断开。效果略好但索引成本高、速度慢通常只在关键知识库上使用。父子分块Small-to-Big用小块200 字建索引保证检索精度命中后返回其所属的大块1500 字给模型保证上下文完整。这是解决“精度与完整性矛盾”的最有效手段之一。再补充两个策略谱系里常被漏掉的句子窗口检索Sentence Window索引单句命中后向前后各扩 N 句再送给模型。它是父子分块的一种轻量变体特别适合 FAQ、法规条款这类“一句话就是一条知识”的文档。表格/代码单独成块表格不要和正文混在一个 chunk 里代码块同理。它们各自需要不同的切分逻辑表格按行组切代码按函数/类切混切的结果是两边都不可用。不同策略的取舍可以对照这张表策略索引成本检索精度上下文完整性适用文档固定长度 重叠极低中中无结构纯文本、会议纪要结构感知低高高产品手册、规范、Markdown语义分块高高中长段落散文、研究报告父子分块中高极高技术文档、法务合同句子窗口中高中FAQ、条款、参数表4.2 代码示例结构感知分块 元数据注入下面的实现按标题层级切分跳过代码块内的#并把标题路径写进 chunk 正文——这一步极其重要因为一块脱离了标题的正文往往语义不完整比如“以上参数默认关闭”补上产品手册 配置说明 高级选项后它的可检索性会明显提升。importrefromdataclassesimportdataclass,field HEADING_REre.compile(r^(#{1,6})\s(.*)$)dataclassclassChunk:text:strmetadata:dictfield(default_factorydict)def_split_long(text:str,max_chars:int,overlap:int)-list[str]:对超长正文做兜底二次切分优先在段落/句号处断开避免硬切。iflen(text)max_chars:return[text]parts,start[],0whilestartlen(text):endmin(startmax_chars,len(text))ifendlen(text):# 在窗口后 20% 范围内找一个句号或换行作为断点windowtext[end-max_chars//5:end]cutmax(window.rfind(。),window.rfind(\n))ifcut!-1:endend-max_chars//5cut1parts.append(text[start:end])startmax(end-overlap,start1)# 保证前进防止死循环returnpartsdefsplit_by_heading(md:str,max_chars:int800,overlap:int100)-list[Chunk]:linesmd.splitlines()chunks:list[Chunk][]stack:list[tuple[int,str]][]# 维护标题栈(level, title)buf:list[str][]in_codeFalse# 代码块内的 # 不是标题defflush():ifnotbuf:returnbody\n.join(buf).strip()buf.clear()ifnotbody:returnpath .join(tfor_,tinstack)# 关键把标题路径拼进正文提升可检索性prefixf【{path}】\nifpathelseforpiecein_split_long(body,max_chars,overlap):chunks.append(Chunk(textprefixpiece,metadata{heading_path:path,level:stack[-1][0]ifstackelse0},))forlineinlines:ifline.strip().startswith():in_codenotin_code buf.append(line)continuemNoneifin_codeelseHEADING_RE.match(line)ifm:flush()# 遇到新标题先把上一节收尾level,titlelen(m.group(1)),m.group(2).strip()whilestackandstack[-1][0]level:stack.pop()# 同级或更高级标题弹栈stack.append((level,title))else:buf.append(line)flush()returnchunks这段代码有三处值得单独说flush()放在遇到标题时调用而不是在循环结束后统一处理。这样每个 chunk 天然以标题为边界不会出现“上一节的结尾 下一节的开头”这种拼接污染。标题栈的弹栈条件用。假设当前栈是[H1, H2]来了一个 H2说明新的 H2 和旧的 H2 是兄弟关系旧的必须弹出如果来了 H3则保留因为它属于当前 H2 的子节点。prefix拼在每一段前面而不是只拼在 chunk 的第一个。超长节被二次切分后每一段都要带上标题路径否则后半段又会变成“无主正文”。还有一个进阶玩法值得一试给每个 chunk 补一句“这段在讲什么”的自动摘要可以用便宜的小模型批量生成拼在正文前面再去做嵌入。业界把这叫 contextual retrieval实测能把 Recall20 提升 5~15 个点代价是索引阶段多一轮 LLM 调用。对知识库更新不频繁的场景这笔钱花得值。4.3 分块参数怎么定别拍脑袋跑网格chunk_size和overlap没有普适最优值但有可靠的起点中文技术文档300~600 字/块overlap 10%~15%。低于 200 字容易丢上下文高于 800 字会稀释向量语义。FAQ / 条款一条一问一块不做合并。代码文档按函数/类切单块不超过 100 行。overlap 不要超过 chunk_size 的 20%否则相邻块高度重复检索时会出现“同一个内容占满 top5”的假象反而挤掉了其他有用信息。定参数的正确姿势是拿评估集跑网格搜索而不是看哪篇博客说得对。一个最小化的跑批脚本长这样fromstatisticsimportmeandefrecall_at_k(retrieved_ids,gold_ids,k):topkset(retrieved_ids[:k])returnlen(topkset(gold_ids))/max(len(gold_ids),1)defevaluate(search_fn,dataset,k10):scores[recall_at_k([h[chunk_id]forhinsearch_fn(it[query],k)],it[gold_chunk_ids],k)foritindataset]return{recall%d%k:round(mean(scores),4),n:len(dataset)}把(chunk_size, overlap)组合成 4×3 的网格每组重建索引、跑一遍评估通常两小时内就能得到属于你自己数据的最优解。经验上这个网格搜索带来的收益比换一个更强的嵌入模型还大。五、召回率调优从 60% 到 90% 的工程路径这是最容易被跳过、也最决定成败的一节。调优要按“性价比”排序从上往下做做到指标达标就停手。5.1 第一层混合召回收益最大成本最低向量召回 BM25 关键词召回各取 top 20用前面写的rrf_fuse融合。BM25 不需要额外组件pgvector 场景可以直接用 PostgreSQL 的tsvector全文索引或者装pg_search/zhparser做中文分词。-- 中文需要先装分词扩展英文用内置 english 配置即可CREATEINDEXidx_chunks_ftsONdoc_chunksUSINGgin(to_tsvector(simple,content));这一步在含型号、编号、专有名词的知识库上Recall10 通常能提升 15~25 个点是所有优化里投入产出比最高的。5.2 第二层Query 改写解决“用户不会说人话”用户的提问往往很短、带指代、缺上下文。三种改写手段按需选用指代消解多轮对话里把“它的默认值是多少”补全成“XX 组件的超时默认值是多少”。不做这一步第二轮的召回率会断崖式下跌。多查询扩展Multi-Query让模型把一个问题改写成 3 个不同措辞的版本分别召回后融合。适合口语化提问多的 C 端场景。HyDE先让模型“编”一段假答案再用这段假答案去检索。因为假答案的用词更接近文档语料实测对短 query 有效但对事实性极强的问题有引入偏差的风险谨慎使用。5.3 第三层Rerank提升 Context Precision召回阶段追求“不漏”rerank 阶段追求“精准”。用 cross-encoder如 bge-reranker 系列对 query 和每个候选 chunk 做联合打分把 top 50 精排到 top 8 再送进 Prompt。cross-encoder 逐对计算慢但准所以只放在召回之后、条数有限的位置。这一步的收益往往体现在“答案质量”而不是 Recall 上噪声被清掉后模型的忠实度和引用准确率会明显改善同时 token 成本下降 40% 以上。5.4 调优效果对照某 3200 份文档知识库实测阶段Recall10Context Precision端到端准确率基线固定分块 单路向量61%0.3841% 结构感知分块与标题路径注入74%0.4556% BM25 混合召回 RRF86%0.5269% Rerank50 → 889%0.8178% Query 指代消解89%0.8381%注意最后一行Recall 没涨但端到端准确率涨了 3 个点。这说明多轮场景下问题本身没被正确理解时检索再好也白搭。5.5 调优时的三个反直觉结论top_k 不是越大越好。把 top_k 从 10 提到 50Recall 只涨 2 个点但 Context Precision 掉 20 个点端到端反而变差。正确做法是“大召回 强重排”而不是“大召回直接喂”。换嵌入模型之前先看分块。很多团队一上来就换更大的 embedding 模型结果提升微乎其微——因为瓶颈在分块把语义切碎了模型再好也救不回来。评估集要定期扩充。线上真实 query 分布和初期拍脑袋写的评估集差异很大建议每月从线上日志里采样 badcase 补充进评估集否则你会在一套过时的标尺上持续“优化”。六、生产环境踩坑清单FAQQ1PDF 解析出来全是乱序表格变成一列数字怎么办A优先换解析器而不是硬修。带版式的 PDF双栏、表格、页眉页脚用通用文本抽取必然出错。选型上简单 PDF 用pdfplumber复杂版式用unstructured的hi_res模式或商用文档解析 API扫描件走 OCR。解析阶段丢的结构后面任何环节都补不回来。Q2chunk 里到底要不要保留标题会不会污染向量A要保留而且要把标题路径拼进正文。标题是天然的语义浓缩去掉它正文里的“以上”“如下”就失去了指代对象。担心污染的话可以把标题放在正文前面而不是混在句子里嵌入模型对位置是有感知的。Q3文档更新了旧 chunk 怎么处理A按doc_id做版本覆盖写入新版本时把旧版本置is_deleted true查询永远带is_deleted false。不要物理删除留出回滚和排查的余地。定期跑一次离线任务清理 30 天前的软删除记录。**Q4为什么加了tenant_id过滤之后召回率突然暴跌更多硬核网安与AI工具包请扫码获取完整源码**Apost-filter 的典型症状见第三节。把过滤条件下推到WHERE或开启hnsw.iterative_scan或把ef_search调到 top_k 的 5