RAG 召回差别先换 Embedding从维度错误到重建索引的完整排错法RAG 系统回答不准时最容易出现的误判是把所有问题都归到大模型上模型不够强、提示词不够长、上下文不够多于是不断换模型、堆提示词、扩大 Top-K。实际工程中生成结果只是链路末端的表现。文档抽取丢字、切分破坏语义、索引没有更新、查询和文档使用了不同的 Embedding、元数据过滤条件过严、候选集太窄、重排输入被截断都会让一个原本正常的生成模型“看起来不会回答”。真正有效的排错方式不是先改提示词而是沿着数据流逐段验证原始文档是否可读切块是否能独立回答问题向量是否来自同一套编码规则正确证据是否进入候选集重排是否把它保留在前列最终上下文是否真的发送给生成接口。本文给出一套可复用的检查顺序、数据结构和最小测试代码目标是把“回答不对”转换成可定位、可复现、可比较的检索问题。一、先区分“没有证据”和“不会使用证据”收到一个错误答案后先不要观察文风而要保存这次请求的完整检索轨迹。至少回答四个问题知识库里是否存在能够支持正确答案的原文正确原文是否被切成了可检索的块这个块是否出现在召回候选中它进入上下文后模型是否仍然给出错误结论。四个问题把故障分成两大类。检索故障的特征是正确证据没有进入最终上下文。根因通常位于抽取、切分、索引、向量、过滤、查询改写、Top-K 或重排。生成故障的特征是上下文已经包含清晰证据但答案忽略、误读或越过证据边界。此时才应该检查上下文排序、提示约束、引用格式和生成参数。如果没有完成这个分流修改提示词可能只是掩盖召回缺陷。观察到的现象优先检查的阶段不应立刻下的结论候选结果完全无关索引版本、Embedding 一致性、查询改写模型不理解业务能搜到相近主题但缺少关键句切分边界、Top-K、过滤条件文档没有答案正确块排在候选末尾混合检索、重排、分数融合只能扩大上下文正确块进入提示但回答仍错上下文装配、提示约束、生成阶段检索系统无效同一个问题偶尔正确、偶尔错误索引更新、并发版本、非确定改写、缓存单纯是模型随机性还要区分三种容易混在一起的“没找到”。无结果是候选数组为空常见于索引、权限过滤或请求结构低相关结果是有候选但目标证据不在前列重点看切分、向量空间、关键词通道和候选宽度正确结果未被使用则要继续追踪重排、去重、上下文预算与生成。把三种状态都记录成“召回失败”会让统计数据失去诊断价值。复现问题时应固定语料快照和查询。若一边重新导入文档、一边修改过滤和模型前后结果没有可比性。建议先选一个能人工确认目标证据的查询为它记录源文档、目标块、索引版本和各阶段候选。单个样本用于理解链路随后再用成组评测验证结论是否具有普遍性。建议给每次请求分配trace_id并保存各阶段输入输出的摘要。不要只记录最终答案也不要在日志里保存完整敏感文档。工程上更有价值的是稳定标识、版本、长度、排名、分数、过滤条件和内容哈希。下面的轨迹对象可以作为起点{trace_id:rag_trace_demo_001,query:如何排查检索不到最新文档,index_version:kb_2026_06_30,embedding_version:embed_v3,filters:{tenant:demo,language:zh-CN,status:published},retrieved_chunk_ids:[doc-17#p4,doc-8#p2],reranked_chunk_ids:[doc-8#p2,doc-17#p4],context_chunk_ids:[doc-8#p2],answer_has_citation:true}二、从数据入口开始确认抽取结果真的可用RAG 的索引对象不是 PDF、网页或数据库记录本身而是抽取后的文本与元数据。如果解析器把双栏 PDF 的左右内容交错、忽略扫描页、丢失表格表头后续向量再准确也无法恢复原始关系。排错时应该抽样查看“进入切分器之前”的纯文本而不是只打开源文件确认肉眼可见。对每类来源准备固定样本普通段落、标题层级、表格、代码块、列表、图片说明、页眉页脚和跨页段落。为抽取结果保存字符数、段落数、表格数、空白比例与内容哈希。若同一文件重新入库后哈希发生变化要能说明是源内容变化、解析器升级还是清洗规则变化。无法解释的变化不应直接覆盖线上索引。还要检查去重逻辑。完全相同的文件可以按内容哈希去重但内容相近不等于重复。不同版本的制度、接口说明和产品手册可能只有少量差异却恰好影响用户问题。合理做法是保留document_id、version、effective_at、source_url与status在查询时根据业务规则过滤而不是在入库时粗暴删掉相似内容。表格与代码需要单独抽样。表格若只保留单元格文字而丢掉行列标题“30 天”之类的数值就失去适用对象代码若丢失缩进、围栏或文件路径检索器可能召回一个语法上不完整的片段。扫描件还要确认 OCR 是否识别页码、脚注和图中标签。对这些结构字符数正常并不能证明内容可用必须回到原文位置进行语义核对。数据入口还应保存可重放信息解析器名称与版本、清洗规则版本、源文件哈希、导入时间、解析状态和失败原因。增量任务不能只记录“完成”还应记录新增、更新、跳过与失败的文档数量。用户报告“最新文档搜不到”时这些字段可以先回答文档是否真的进入索引流程避免过早把问题归到 Embedding。三、切分不是按长度剪文本而是构造可回答的证据单元切块的目标并非让每段字符数相等而是让一个块在脱离全文后仍然保留必要主语、条件、单位和来源。固定长度切分容易实现适合建立基线结构感知切分可以尊重标题、段落、列表和表格语义切分尝试在主题变化处断开。哪一种更好不能靠直觉决定需要用真实问题集比较。常见坏块有四类。其一块开头只有“上述方案”或“该限制”失去了指代对象其二标题与正文被分开正文缺少主题其三表格行脱离表头数值失去含义其四多个不相关章节被塞进一个大块向量表达被不同主题稀释。人工抽样时不要只看块是否通顺要用问题反推这个块单独出现时是否足以支持一个可验证的答案。重叠可以保留跨边界语义但重叠越大重复候选越多索引体积与上下文浪费也越明显。与其设定一个放之四海而皆准的字符数不如记录一组可实验参数切分器版本、目标长度、重叠长度、是否附加父标题、是否保留表头。每次只改变一个变量用相同评测集比较召回率和重复率。评估切分时不要只统计平均长度。更有诊断价值的指标包括目标证据是否被完整包含、一个块跨越多少标题、表格行是否保留表头、指代词是否能在块内解析、同一原文产生多少近重复候选以及重排后有多少块来自同一父文档。切分方案改变后块标识也可能改变评测集需要通过原文位置或稳定语义锚点重新映射不能把旧 ID 失效误判为召回下降。一个可追踪的块至少应包含稳定块标识、父文档标识、正文、标题路径、来源、版本和权限元数据{chunk_id:guide-42#section-3#chunk-2,document_id:guide-42,text:查询向量应与文档向量使用相同的嵌入模型和预处理规则。,heading_path:[检索排错,向量一致性],source_url:https://example.invalid/guide-42,document_version:2026-06-30,language:zh-CN,tenant:demo,status:published}这里的示例域名只表达数据结构不是可访问来源。实际系统应保存能够追溯到原文的位置例如页面、段落、数据库主键或对象存储版本。只有来源可追溯离线评测失败时才能快速回看原始证据。四、Embedding 一致性检查要覆盖模型之外的所有输入规则向量相似度有意义的前提是查询和文档处于同一个表示空间。工程中常见的破坏方式不只是“模型名不同”还包括维度参数不同、前后缀模板不同、大小写或空白清洗规则不同、语言路由不同、向量归一化方式不同以及索引中混入旧版本向量。只核对 API 地址而不核对版本与预处理并不足以证明一致。建立索引时把embedding_provider、embedding_model、embedding_dimensions、preprocess_version和created_at写入索引元数据。查询时读取索引声明而不是依赖应用里的另一个默认值。若要升级模型应创建新索引完成全量重建和回归评测再切换别名不要把两种不可比较的向量追加到同一个字段中。维度一致只证明数组长度能参与运算不能证明坐标含义一致。两个不同模型即使都输出相同长度也可能把同一文本映射到不同空间文档使用旧模型、查询使用新模型时数据库可能不会报错却会出现更难发现的相关性退化。模型别名、可选维度参数、查询与文档任务类型、前缀模板、Unicode 规范化和空白处理都应进入版本清单。迁移不应直接覆盖旧索引。通用蓝绿流程是创建新版本索引对新增内容进行新旧双写后台读取原文并用新模型全量重新向量化完成数量与失败校验后运行离线评测再把少量查询流量切到新索引。指标和样本检查通过后切换别名旧索引保留到回滚窗口结束。若向量库支持 named vectors也可以在同一文档载荷上并存新旧向量但查询必须明确选择向量名不能让默认值漂移。重建的输入必须是可追溯原文而不是从旧向量推导新向量。向量不是可逆文本表示也不能通过补零、截断或线性缩放把一个模型的空间可靠转换成另一个模型的空间。若原始文本已经缺失真正的问题是数据治理而不是寻找一个数学捷径。还可以用几组“语义哨兵”做启动检查同义问题之间的相似度应高于无关问题同一文本重复编码的维度和数值范围应稳定空字符串、超长输入和异常字符应有明确处理。下面的函数只检查结构与有限值不替代业务评测但能尽早发现维度错配和非法数字functionvalidateEmbedding(vector,expectedDimensions){if(!Array.isArray(vector)){thrownewTypeError(embedding must be an array);}if(vector.length!expectedDimensions){thrownewError(dimension mismatch:${vector.length});}if(!vector.every(Number.isFinite)){thrownewError(embedding contains a non-finite value);}constnormMath.sqrt(vector.reduce((sum,value)sumvalue*value,0));if(norm0){thrownewError(embedding norm must be greater than zero);}return{dimensions:vector.length,norm};}如果线上出现“旧问题能搜到新问题搜不到”还要核对索引写入是否成功、增量任务是否跳过、别名是否仍指向旧索引以及查询服务是否命中陈旧缓存。Embedding 服务响应成功只说明向量生成完成不代表它已经写入正确集合。五、元数据过滤要先保证权限正确再讨论相关性向量检索通常与租户、语言、文档状态、产品线、时间范围和访问权限共同工作。过滤条件缺失可能造成越权过滤过严则会让正确证据在相似度计算前就被排除。因此过滤问题既是召回问题也是安全边界问题不能通过“临时去掉权限条件”来提升效果。排查过滤时记录用户原始条件、系统补充条件和最终下发条件分别统计每个条件过滤前后的候选数量。若候选从有到无可以准确定位是哪一个字段造成断流。重点检查枚举拼写、大小写、时区、空值语义、数组包含关系和发布状态。日期过滤尤其容易因本地时间与 UTC 转换出现边界误差。权限测试必须包含正向与反向用例有权限的用户能够召回目标块无权限的用户无论如何改写查询都不能召回同一文档权限变更后旧索引与缓存不会继续返回父文档与子块继承一致的权限。相关性评测可以接受排名波动权限评测则应视为硬约束。可以为同一查询建立三组对照只保留租户硬约束、加入业务状态过滤、加入全部个性化条件。若目标块在第二组消失就检查发布状态和生效时间若只在第三组消失就检查语言、产品线或用户偏好。对照测试只能在隔离环境使用有权限的样本不能为了诊断在线上绕开访问控制。六、查询改写要扩大表达不应偷偷改变问题用户问题往往带有指代、省略、口语和上下文。例如“这个为什么还是不行”对检索器几乎没有意义但对话历史可能说明“这个”指的是向量索引切换。查询改写可以补全对象、生成同义表达或拆分复合问题却不能添加用户没有提出的产品、时间或结论。建议同时保存原始查询和改写查询并让它们都参与评测。对复合问题可以拆成若干子查询再合并候选对包含代码、错误码、接口名和专有名词的问题要保留原始词面不要只留下抽象语义。改写器输出为空、输出过多或与原问题实体不一致时应回退到原始查询。查询改写的质量可以通过三类失败样本观察原查询能命中而改写后丢失说明改写破坏了关键词改写带来大量相似但无关内容说明范围过宽改写把旧对话实体带进新问题说明会话边界处理错误。不要仅凭“改写后的句子更完整”判断有效最终标准仍是目标证据能否进入候选集。七、关键词与向量检索是互补关系向量检索擅长语义相近的表达关键词检索擅长精确匹配错误码、接口路径、版本号、类名和缩写。技术知识库同时包含自然语言与大量精确标识只使用一种检索方式会形成明显盲区。混合检索可以分别获得词法候选和向量候选再使用排名融合生成一个列表。RRF 的实用之处在于它基于名次融合不要求词法分数与向量相似度处在同一数值尺度。下面是一个最小实现。rankConstant是融合参数不应凭单个问题调到满意后直接上线仍需通过固定评测集比较functionreciprocalRankFusion(resultLists,rankConstant60){constscoresnewMap();for(constlistofresultLists){list.forEach((item,index){constpreviousscores.get(item.id)??{...item,rrfScore:0};previous.rrfScore1/(rankConstantindex1);scores.set(item.id,previous);});}return[...scores.values()].sort((a,b)b.rrfScore-a.rrfScore);}融合前要统一去重键。若词法索引以段落为单位、向量索引以滑动窗口为单位同一原文可能对应多个标识简单按 ID 合并会留下重复证据。可以使用父文档、页面与字符区间构造规范键并在最终上下文装配阶段再次做相邻块合并。RRF 适合原始分数尺度不可直接比较的场景但它仍依赖各通道先提供有意义的排名。若词法通道因为分析器配置错误完全漏掉错误码或向量通道使用错配模型融合不会自动修复上游。评测时应同时保存每个通道的独立结果和融合结果确认改进来自互补召回而不是某一路噪声被另一条路线偶然遮住。八、Top-K 应分阶段设置不要把候选数等同于上下文数Top-K 太小会漏掉正确证据太大则会引入噪声、增加重排成本并挤占生成上下文。关键是区分“初始召回数量”“重排候选数量”和“最终上下文数量”。初始阶段以覆盖为目标可以相对宽重排阶段以顺序为目标最终上下文阶段以证据充分、非重复和预算可控为目标。调参时画出RecallK曲线而不是只看某一个 K 的答案是否正确。如果 K 从较小值增加后召回明显提升说明初始候选不足如果召回早已稳定但最终答案仍差继续扩大 K 通常没有帮助应转向重排和上下文装配。如果正确证据总在很后面则要检查切分、Embedding 或混合检索而不是无限增加候选。还要按问题类型分层统计。错误码查询可能依赖关键词概念问答更依赖语义时间敏感问题更依赖元数据跨文档比较则需要多个来源。一个全局 K 值可以作为默认基线但不应掩盖不同类型的真实分布。九、重排解决“找到了但顺序不好”不能弥补完全漏召回重排器只处理初始候选因此目标块没有被召回时重排无能为力。正确流程是先确保候选集具有足够覆盖再比较无重排、规则重排和模型重排。重排输入必须包含查询与完整候选文本如果为节省长度只传了块开头关键句位于后半段时会被错误降权。重排输出应保留原始召回分数、原始排名、重排分数和重排后排名。这样才能判断它是在修正顺序还是系统性压低某类内容。标题、正文、表格和代码的分布不同评测集也应覆盖这些内容形态。不要只用几个看起来合理的问题人工观察。对于同一父文档的相邻块可以在重排后合并但要防止一个文档占满全部上下文。可设置每个父文档的块数上限或在候选选择时增加多样性约束。这里的目标不是让来源越多越好而是在不牺牲关键证据的前提下减少重复。十、建立离线评测集避免靠印象调参没有固定问题集任何改动都很难证明是提升还是偶然。最小评测样本至少包含用户问题、允许的改写、目标文档或目标块、不能出现的文档、问题类型和备注。对于答案可能来自多个块的问题可以记录可接受证据集合而不是强制唯一块。检索阶段可以关注RecallK、首个相关结果排名、平均倒数排名、无结果率、重复块比例和过滤后候选数。生成阶段再关注答案是否被证据支持、引用是否指向正确来源、缺少证据时是否明确拒答。两组指标不要混成一个分数否则无法知道改动影响了哪一段。标注集不需要一开始就很大但要覆盖真实差异。可以从高频问题、失败工单、专有名词查询、跨文档问题、时间敏感问题、权限边界和“知识库没有答案”的反例中抽样。每个查询至少标出可接受的目标文档或块若相关性有强弱之分可以使用分级标签。合成问题适合扩展覆盖但它往往沿用源文档措辞可能让离线分数虚高因此应与真实查询分开报告。RecallK回答“前 K 个结果是否覆盖应有证据”MRR 更关注首个相关结果的位置NDCG 适合有分级相关性且重视顺序的场景。指标中的 K 要对应真实产品行为最终只给模型五个块却只报告 Recall100会把无效的宽候选包装成好结果。除总体指标外还应按问题类型、语言、文档结构和权限场景切片避免平均值掩盖关键失败群体。离线提升不等于线上答案必然提升。检索评测通过后还应验证上下文装配与生成反过来生成答案偶然正确也不能证明检索健康因为模型可能依赖参数知识作答。稳定的验收需要同时保存检索目标、实际上下文和引用证据。下面的示例计算目标块是否进入前 K并返回首个目标排名。它刻意只处理检索结果不评价生成文风functionevaluateRetrieval(retrievedIds,relevantIds,k){constrelevantnewSet(relevantIds);consttopretrievedIds.slice(0,k);constfirstIndextop.findIndex((id)relevant.has(id));return{hit:firstIndex0,firstRelevantRank:firstIndex0?firstIndex1:null,reciprocalRank:firstIndex0?1/(firstIndex1):0};}评测集要版本化并保存每次实验的代码版本、索引版本、切分器版本、Embedding 版本、查询改写版本、过滤规则和重排配置。只记录“新方案更好”没有复现价值。线上反馈可以补充评测集但在纳入前要人工确认目标证据避免把错误反馈直接固化成标签。十一、按最早失效阶段排查能减少无效改动故障定位应遵循从左到右、从确定性到概率性的顺序。先检查源文档与抽取再检查块、索引、向量和过滤然后检查召回、融合与重排最后检查上下文和生成。上游不正确时下游指标没有解释力。可以把一次问题复现整理成以下证据链在原始来源中圈出能够回答问题的最小证据并记录来源位置。用document_id找到抽取文本确认关键句没有丢失或错序。用chunk_id找到索引块确认标题、表头和条件仍完整。核对该块的索引版本、向量版本、维度和元数据。使用原始查询执行无过滤基线再逐项加回业务过滤。分别查看关键词列表、向量列表和融合列表。查看重排前后名次以及传给重排器的实际文本。查看最终上下文是否因长度预算、去重或文档上限被删除。在固定上下文下重复生成确认剩余问题是否属于生成阶段。这套顺序能区分多个外观相同的问题。例如“找不到新文档”可能是增量索引未完成也可能是时间过滤使用了错误时区“答案引用旧版本”可能是状态过滤缺失也可能是父文档去重优先保留旧块。只有保留阶段性数据才能从结果反推具体原因。十二、上下文装配要保留来源、边界和冲突进入生成模型的内容不应只是拼接后的长字符串。每个证据块应携带块标识、来源标题、来源地址、版本或时间、正文和排序信息。装配时先去掉近重复块再按问题覆盖度选择证据相邻块需要合并时保留原始边界避免引用位置失真。当多个来源冲突时不要静默选择一个。可以按生效时间、来源等级或业务规则排序并在提示中要求模型说明冲突。若上下文没有足够证据提示应允许返回“现有资料无法确认”而不是强迫模型补全。引用必须来自实际进入上下文的块不能在生成后根据关键词猜一个链接。上下文预算也要可观测。记录每个块的字符或 Token 数、被保留或丢弃的原因、最终顺序和总长度。若正确块已经召回却经常被预算裁掉应优化去重与选择策略而不是简单增大模型上下文。更多背景并不自动等于更多有效证据。十三、生成接口与检索接口要分开核验能力边界本地或第三方 OpenAI 兼容服务常被用于生成阶段但“兼容 Chat Completions”不代表一定提供 Embeddings、向量数据库或重排能力。工程文档必须分别核验每个端点不应从一个可用接口推断整套 RAG 能力。以本文项目的事实白名单为例已确认的固定信息只有 Base URLhttps://api.vectorengine.cn、OpenAI 兼容接口前缀https://api.vectorengine.cn/v1以及 Chat Completions 地址https://api.vectorengine.cn/v1/chat/completions。这三项可以用于生成阶段配置说明但不能据此声称该服务提供 Embedding、支持某个模型、具有特定并发、价格、日志保留或安全认证。Embedding 与向量检索应使用已经单独验证的组件并在系统配置里明确记录提供方与版本。如果团队需要查看相关配置入口可以把延伸阅读放在技术资料末尾https://178.nz/dn 。这个链接只作为一次自然延伸不替代本文引用的官方检索资料。十四、上线前的可执行检查清单数据与索引抽样核对解析文本确认表格与代码没有错序块可以独立表达条件块标识稳定父文档、版本、来源和权限齐全增量任务成功查询别名指向预期索引旧索引有可控回滚方案。向量与查询查询和文档使用相同的 Embedding 与预处理版本维度一致空输入和超长输入有明确错误查询改写保留错误码与专有名词会话指代补全不会污染新问题改写失败时能够回退原始查询。召回与过滤分别观察关键词、向量和融合结果过滤条件可解释权限反向用例通过时间与语言边界正确初始候选数与最终上下文数分离相邻块和重复块有规范化去重。重排与上下文正确证据先进入候选重排器收到完整文本保留重排前后名次避免单一父文档占满上下文记录每个块的保留或丢弃原因冲突来源不被静默覆盖引用只指向实际上下文。评测与观测评测集包含真实问题与目标证据指标区分检索和生成实验绑定全部版本线上每次请求都有轨迹标识日志不保存不必要的敏感正文索引、切分器或模型升级前执行回归比较。十五、缓存与索引版本也会制造“幽灵故障”检索链路经常同时存在文档缓存、查询向量缓存、搜索结果缓存和最终回答缓存。它们能降低延迟却也会让已经修复的问题继续出现。典型现象是管理后台能看到新文档直接查询新索引也能命中但业务接口仍返回旧结果或者同一个请求在不同实例上得到不同候选。此时根因可能不是检索算法而是缓存键没有包含索引版本、租户、权限或语言。缓存键应覆盖所有会改变检索结果的输入包括规范化查询、改写版本、索引版本、过滤条件、权限摘要、召回配置和重排版本。只用原始问题文本作为键会让不同用户共享不应共享的结果也会在索引切换后继续命中旧候选。对于最终答案缓存还要考虑生成提示版本和上下文来源版本避免旧答案与新证据错配。切换索引时建议使用不可变版本加别名新文档写入新版本完成索引统计、抽样查询和离线回归后再把查询别名切到新版本。查询轨迹必须记录实际命中的物理索引而不是只记录别名。若出现回归可以快速切回旧版本若只在原索引上原地覆盖就很难判断一个错误请求究竟读到了哪批数据。分布式部署还要检查实例配置是否同步。有的实例可能仍加载旧的 Embedding 配置有的实例可能尚未刷新别名有的后台任务可能向旧集合写入。可以在健康检查中返回不敏感的版本摘要并在请求轨迹里记录服务实例、配置版本和索引版本。这样同一问题的差异就能与具体实例关联而不是被误判为模型随机性。十六、多语言、表格和代码需要单独设计评测中文知识库中经常夹杂英文接口名、错误码、文件路径和代码。统一清洗时如果删除标点、改变大小写或把路径分隔符当成分句符语义段落可能仍然通顺但精确检索能力已经受损。对技术资料清洗规则应保留错误码、版本号、类名、函数名、接口路径和配置键并把这些字段同时提供给词法检索。多语言内容还会遇到查询语言与文档语言不同的问题。用户用中文询问英文文档时向量检索可能命中但精确术语和缩写仍可能丢失。可以保留原始查询同时生成受控翻译或双语查询再通过融合合并结果。评测集要包含中文问英文文档、英文问中文文档和中英混合问题不能只用单一语言样本推断整体表现。表格需要保留表头、行名、单位和适用条件。把每一行独立切块却不附带表头会让“限制为多少”这类问题召回一个数字却无法判断数字对应哪个版本或场景。可将父标题与表头复制到每个表格块或者把适度规模的整张表保存为结构化对象并额外生成便于搜索的文本表示。无论哪种方案都应在引用中回到原表位置。代码块则要避免被自然语言分句器切碎。函数签名、异常信息和配置示例往往依赖相邻行过短切分会让关键上下文分散。可以按代码块整体保存并额外提取语言、文件名、符号名和错误码元数据。检索时让词法路径负责精确符号让向量路径负责自然语言意图再由重排判断哪段代码真正回答问题。十七、线上观测要看分布变化而不只是平均值离线评测能比较可复现样本但线上还会出现新术语、文档更新、权限变化和用户表达漂移。应持续观察无结果率、候选数量分布、过滤后归零率、相似度分布、首个引用来源、上下文利用率和用户纠错信号。平均值可能掩盖少数租户、语言或问题类型的严重退化因此指标要能按业务维度分层同时避免在监控标签中写入敏感正文。报警条件应对应可行动的故障。例如某索引版本的文档数突然下降优先检查摄取任务过滤后归零率上升优先检查元数据和权限同步候选存在但引用率下降优先检查上下文装配与生成约束延迟只在重排阶段上升则检查候选规模和重排服务。一个无法指向阶段的总质量分数通常不利于值班定位。线上采样需要脱敏。可以保存查询类别、长度、语言、实体类型、哈希和阶段指标而不是默认保存完整问题与文档正文。确需保留失败样本时应遵守访问控制、保留期限和审计要求。调试便利不能成为扩大数据暴露面的理由尤其是知识库包含客户资料、内部制度或未公开代码时。每次发布检索改动都应设置回滚判据。新版本可以先处理一小部分可控流量与基线比较目标证据命中、无结果率、延迟和错误率。若出现权限回归、索引不完整或明显漏召回应停止扩大流量并回到已验证版本。只有离线指标、线上分层指标和失败样本方向一致才能说明改动具有稳定价值。十八、几个高频误区误区一相似度高就一定相关。相似度只在给定向量空间和候选集合中表达接近程度。模型错配、块过大或数据域偏移时高分也可能无关。判断依据应包含标注证据与排名而不是一个孤立阈值。误区二把整篇文档塞进上下文最保险。长文档会挤占预算增加冲突和重复也让引用难以定位。更稳妥的方式是保留可追溯块通过召回与重排选择必要证据。误区三扩大 Top-K 能解决所有漏召回。如果目标块未入索引、被过滤或向量错配扩大候选只会返回更多错误内容。应先判断目标块在哪个阶段消失。误区四重写 Git、重建索引或更换模型后立即覆盖线上。这些操作都会改变大量标识和结果。应建立新版本完成离线回归和小范围验证后再切换并保留回滚入口。误区五只看最终答案做 A/B。最终答案同时受检索、上下文和生成影响。没有阶段指标时即使答案变好也无法确认是系统性提升还是偶然命中。十九、把一次排错沉淀成可复用报告故障修复后不要只写“已调大 Top-K”或“已重建索引”。一份可复用报告应包含用户现象、可公开的最小复现问题、目标证据位置、故障首次出现时间、受影响索引与服务版本、证据在哪个阶段消失、根因、修复动作、回归样本和回滚条件。涉及权限或敏感内容时只保留必要摘要与受控链接。报告还应区分直接原因与系统缺口。例如直接原因是查询服务仍读取旧索引系统缺口可能是轨迹未记录物理索引版本、切换后没有自动回归、缓存键也没有版本字段。只修复直接原因会让类似问题再次发生补齐观测、测试和发布保护才算真正关闭故障。最后把本次失败样本加入离线评测并确认它不会与原有样本重复。若修复改变了切分或向量空间需要对完整评测集回归而不是只验证当前问题。这样每一次线上故障都会增加系统的防回归能力而不是留下一条难以搜索的聊天记录。结语RAG 排错的核心不是寻找一个神奇参数而是建立可观测的证据链。先证明原文存在再证明抽取和切分保留了语义再证明查询与文档处于同一向量空间权限过滤没有误伤正确证据进入候选并通过重排最后检查上下文装配和生成是否忠实使用证据。每一段都有输入、输出、版本和最小测试问题就会从“模型偶尔不聪明”变成一个能够复现和修复的工程缺陷。当系统准备升级切分策略、Embedding、混合检索或重排器时也沿用同一套评测集与轨迹结构。只要能回答“正确证据在哪个阶段消失、为什么消失、改动后是否稳定恢复”RAG 的质量改进就不再依赖印象。