1. 为什么“让模型自己判断”这件事迟早要翻车做过 RAG 项目的人大概都经历过这个阶段检索回来一堆文档片段直接塞进 prompt让大模型自己看着办。早期 demo 阶段这么干确实爽几行代码就能跑通效果看着也还行。但只要往生产环境推一步问题就全冒出来了——同一个问题问两遍答案可能一次引用对了文档、一次引用错了模型偶尔会把检索到的无关内容当成事实编进回答里更头疼的是你根本没法跟业务方解释“为什么这次答错了”因为整个判断过程都藏在模型的隐层里是个黑盒。这就是TypeSafe这个概念真正要解决的问题。它不是一个具体的库或者框架的名字而是一种设计思路把原本交给 LLM 自由发挥的那些判断抽出来变成有类型约束、可校验、可测试的编程能力。重排序Rerank是其中一环RAG 护栏Guardrail是另一环两者串起来才构成一条从“检索结果”到“可信输出”的完整链路。我先把这篇要讲的东西摊开说清楚免得你读到一半发现不是自己要的重排序到底在 RAG 里承担什么角色为什么向量检索之后几乎必须补这一步BM25 这类稀疏检索和稠密向量怎么配合TypeSafe 的思路怎么落到重排序上——把“相关性判断”从模型打分变成带 schema 的结构化输出RAG 护栏具体拦什么怎么设计才能既不误杀又不漏放Agentic RAG 场景下护栏和重排序怎么协同以及 skill 和 RAG 结合时容易踩的坑最后给一套可以照着搭的本地知识库方案包括 BM25 向量混合检索 重排序 护栏的完整参数配置。适合谁看已经跑通过基础 RAG、现在被“答案不稳定”折磨的开发者正在做企业知识库、医疗/金融这类对准确性要求高的场景的工程师以及想理解 Agentic RAG 里“判断层”该怎么设计的架构同学。纯小白也能看我会把每个概念用生活化的方式讲一遍再上代码。提示本文讲的 TypeSafe 是一种工程范式不是某个特定开源项目的 API。你用的可能是 LangChain、LangChain4j、Spring AI 或者自己手写的框架思路是通用的代码示例以 Python 为主Java 生态的同学看逻辑即可。2. 重排序在 RAG 链路里的真实位置它不是可选项2.1 向量检索的“召回率陷阱”先纠正一个特别常见的误解很多人以为向量检索embedding 余弦相似度返回的 top-k 就是“最相关的 k 个片段”。不是的。向量检索优化的是召回它保证的是“相关内容大概率出现在候选集里”但它对排序精度的保证很弱。原因在于稠密向量的相似度是一个被压缩过的语义距离。一段文本被编码成 768 维或 1024 维的向量之后很多细粒度的差异被抹平了。比如你问“布洛芬和对乙酰氨基酚能不能一起吃”检索可能同时召回“布洛芬的用法用量”“对乙酰氨基酚的肝毒性”“解热镇痛药联合用药原则”三个片段它们的向量相似度可能都在 0.8 上下但真正能回答问题的只有第三个。向量检索分不出这个差别因为前两个在语义上也“很像”。这就是所谓的召回率陷阱你以为 top-5 就是最相关的 5 个实际上里面可能混了两三个“语义相近但答非所问”的片段。在 demo 里模型还能靠自己的常识兜住在生产环境里这就是错误答案的来源。2.2 BM25 和稠密向量为什么必须一起用BM25 是经典的稀疏检索算法它基于词频和逆文档频率打分。它的强项和向量检索正好互补维度BM25稀疏稠密向量强项精确关键词、专有名词、编号、代码语义改写、同义表达、跨语言弱项换个说法就检索不到细粒度区分能力弱典型失效场景用户用口语描述专业概念查询里有精确的型号、药名、错误码打分可解释性高能追溯到具体词低是个黑盒距离举个实际例子。用户查“错误码 E5023 怎么解决”BM25 能精准命中包含 “E5023” 的文档向量检索可能给你召回一堆“系统错误处理”的泛泛内容。反过来用户问“登录一直转圈进不去”BM25 可能一个词都对不上向量检索却能找到“认证超时排查”的文档。所以成熟方案基本都是混合检索BM25 和向量各召回一批合并去重再交给重排序。这一步的关键是不要在这一层做取舍宁可多召回一些把精排的活留给重排序模型。2.3 重排序模型到底在算什么重排序Rerank用的是 Cross-Encoder 结构和向量检索的 Bi-Encoder 有本质区别。Bi-Encoder 是 query 和 document 分别编码再算距离快但粗Cross-Encoder 是把 query 和 document 拼在一起送进模型让模型在注意力层里直接建模两者的交互慢但准。用生活类比Bi-Encoder 像是把两个人的简历分别打分再比对Cross-Encoder 像是让两个人当面聊一次再判断合不合适。后者当然更准但成本高所以只能用在候选集已经缩小到几十条的时候。重排序的输入是(query, candidate_doc)对输出是一个相关性分数。常见模型有 bge-reranker、Cohere Rerank、以及各家自己微调的版本。实测下来在混合检索召回 50 条、重排序取 top-5 的配置下答案准确率比纯向量 top-5 能高出 20 到 30 个百分点这个提升幅度在 RAG 里是相当可观的。注意重排序不是免费的。Cross-Encoder 的推理成本是 Bi-Encoder 的几十倍50 条候选的重排序延迟在几百毫秒到一秒之间。如果你的场景对延迟极敏感要么减少候选数要么上更小的重排序模型要么做异步预计算。3. 把“相关性判断”变成 TypeSafe 的结构化输出3.1 让 LLM 打分为什么不可靠很多团队图省事直接让 LLM 给候选片段打分“请给下面这段内容和问题的相关性打 0 到 10 分”。这个做法在 demo 里能用生产里问题一堆分数不稳定同一个输入温度稍微变一下分数就从 7 跳到 9没有校准模型给的 8 分和另一个模型给的 8 分不是一个意思跨批次没法比较无法校验模型返回 “8.5 分因为……” 这种自由文本你得写正则去抠数字抠错了还没法发现不可测试你没法为“打分逻辑”写单元测试因为输出是自然语言。这就是 TypeSafe 要解决的痛点。核心思路是不要让模型输出自由文本而是让它输出符合预定义 schema 的结构化数据。3.2 用 schema 约束模型输出假设我们要做重排序定义一个这样的输出结构from pydantic import BaseModel, Field from typing import Literal class RerankResult(BaseModel): doc_id: str Field(description候选文档的唯一标识) relevance: Literal[high, medium, low, irrelevant] Field( description相关性等级只能是这四个值之一 ) reason: str Field(max_length100, description判断理由不超过100字) key_evidence: str Field(description支撑判断的原文片段必须逐字引用)注意几个设计细节用枚举而不是连续分数。high/medium/low/irrelevant四档比 0-10 分稳定得多模型不容易在相邻档位之间反复横跳。如果你确实需要更细的粒度用 5 档别用 10 档。强制引用原文。key_evidence字段要求模型逐字引用候选文档里的片段这能极大降低幻觉——模型没法凭空编造证据因为它必须从给定文本里抄。限制理由长度。max_length100既省 token又逼模型说重点避免它写一大段废话稀释信号。然后调用模型时开启结构化输出OpenAI 的response_format、Anthropic 的 tool use、或者本地模型用 outlines/guidance 做约束解码response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: RERANK_SYSTEM_PROMPT}, {role: user, content: build_rerank_input(query, candidates)} ], response_format{type: json_schema, json_schema: RerankResult.model_json_schema()} )这样拿到的结果可以直接RerankResult.model_validate_json(response)解析解析失败就是明确的错误而不是“抠不出数字”的模糊状态。3.3 TypeSafe 带来的三个实际好处第一可校验。解析出来的对象字段类型是确定的relevance一定是四个枚举值之一key_evidence一定是字符串。你可以在入库前加一道校验如果key_evidence不在原文里出现直接判定这次判断无效降级处理。第二可测试。你可以写单元测试构造一批(query, doc)对和期望的relevance标签跑回归测试。模型换版本、prompt 改一版跑一遍测试就知道有没有退化。这在纯自由文本打分方案里是做不到的。第三可组合。结构化输出可以直接喂给下游逻辑。比如relevance irrelevant的片段直接丢弃high的片段加权medium的进护栏二次检查。整个链路是确定性的代码不是“看模型心情”。实操心得枚举档位的命名别用good/bad这种模糊词用high/medium/low/irrelevant这种有明确排序含义的词模型对有序枚举的判断一致性更高。另外irrelevant这一档一定要有否则模型会把所有片段都往low里塞你就失去了“明确排除”的能力。4. RAG 护栏拦的不是模型是整条链路4.1 护栏到底该拦什么很多人一提 RAG 护栏就想到“内容安全过滤”这理解太窄了。生产级 RAG 的护栏至少要覆盖四类问题护栏类型拦截目标典型触发场景输入护栏恶意/越界 queryprompt 注入、越权查询、无关闲聊检索护栏低质量召回召回为空、召回内容与 query 明显无关生成护栏幻觉与越界答案引用了不存在的文档、超出知识库范围输出护栏合规与格式敏感信息泄露、格式不符合下游要求重排序和护栏的关系是重排序负责“排序”护栏负责“裁决”。重排序给出相关性等级护栏根据等级和业务规则决定“这条能不能用、怎么用”。4.2 检索护栏召回为空时不要硬答最常见的翻车场景是知识库里根本没有相关内容但模型还是编了一个答案。护栏要在检索阶段就拦住这种情况。一个可落地的判断逻辑def retrieval_guardrail(candidates, rerank_results, threshold0.0): # 规则1召回为空 if not candidates: return GuardrailDecision(actionrefuse, reasonno_candidates) # 规则2重排序后没有任何 high/medium usable [r for r in rerank_results if r.relevance in (high, medium)] if not usable: return GuardrailDecision(actionrefuse, reasonall_irrelevant) # 规则3最高相关性等级低于业务阈值 top max(rerank_results, keylambda x: RELEVANCE_ORDER[x.relevance]) if RELEVANCE_ORDER[top.relevance] threshold: return GuardrailDecision(actionrefuse, reasonbelow_threshold) return GuardrailDecision(actionproceed, docsusable)这里的RELEVANCE_ORDER把枚举映射成可比较的整数{high: 3, medium: 2, low: 1, irrelevant: 0}。阈值设多少取决于业务——医疗、法律这类场景建议设到high才放行通用问答设到medium就够。4.3 生成护栏验证答案有没有“引用幻觉”模型生成答案后护栏要做的是核对答案里的每个事实性陈述是否能在检索到的文档里找到依据。这一步可以用另一个 LLM 调用完成同样用 TypeSafe 的结构化输出class ClaimCheck(BaseModel): claim: str Field(description从答案中抽取的事实性陈述) supported: bool Field(description该陈述是否被给定文档支持) supporting_doc_id: str | None Field(description支持的文档ID无则为None) class AnswerAudit(BaseModel): claims: list[ClaimCheck] overall_supported: bool把答案拆成若干 claim逐条核对。只要有一条supportedFalse就触发降级要么重新生成要么在答案里标注“此部分未经知识库验证”要么直接拒答。这个做法比“让模型自己检查一遍”可靠得多因为它是结构化的、可追溯的——每条 claim 都能定位到具体文档出了问题能复盘。4.4 护栏的误杀问题怎么破护栏最大的风险不是漏放是误杀。用户问了个正常问题护栏因为阈值设太严给拒了体验直接崩。我的经验是分级响应不要一刀切。低于阈值不一定拒答可以降级成“我找到的相关信息有限以下内容仅供参考”把判断权交回用户。记录所有护栏触发事件。每次refuse或降级都打日志定期 review看哪些是误杀据此调阈值。给护栏加白名单。某些高频、已验证的 query 模式可以直接放行绕过部分检查降低延迟和误杀率。注意护栏的 LLM 调用本身也会失败、也会幻觉。所以护栏逻辑里对 LLM 的依赖要尽量少能用规则判断的比如召回为空、引用文档 ID 不存在就用规则LLM 只用在真正需要语义判断的地方。5. Agentic RAG 里重排序和护栏怎么协同5.1 Agentic RAG 和普通 RAG 的区别普通 RAG 是单轮直线query → 检索 → 重排序 → 生成 → 输出。Agentic RAG 是多轮循环Agent 会自己决定“要不要检索”“检索什么”“检索结果够不够”“要不要换个 query 再检一次”。这个变化对重排序和护栏提出了新要求重排序要能被多次调用每次的候选集可能不同结果要能合并护栏要能拦截 Agent 的中间决策不只是最终输出整个循环要有终止条件否则 Agent 可能陷入“检索-不满意-再检索”的死循环。5.2 把重排序封装成 Agent 的 skill在 Agentic 架构里重排序应该被封装成一个独立的 skill工具Agent 可以显式调用它。这样做的价值是重排序从“隐式流程”变成“显式动作”Agent 的决策过程可观测、可干预。一个 skill 的定义大概长这样class RerankSkill: name rerank_documents description 对候选文档按与查询的相关性重新排序返回带相关性等级的文档列表 parameters { query: {type: string, description: 原始查询}, doc_ids: {type: array, items: {type: string}, description: 待重排序的文档ID列表}, top_k: {type: integer, default: 5} } def execute(self, query, doc_ids, top_k5): candidates fetch_docs(doc_ids) results rerank_with_schema(query, candidates) return sorted(results, keylambda r: RELEVANCE_ORDER[r.relevance], reverseTrue)[:top_k]Agent 调用这个 skill 之后拿到的是结构化的RerankResult列表可以直接根据relevance决定下一步全是irrelevant就换 query 重检有high就进入生成。5.3 护栏在 Agent 循环里的三个卡点Agentic RAG 的护栏要卡在三个位置卡点一检索前。检查 Agent 生成的 query 是否越界。比如用户问的是 A 领域Agent 却生成了一个查询 B 领域的 query这可能是 prompt 注入的信号直接拦截。卡点二重排序后。这是最关键的一环。如果重排序结果显示所有候选都是irrelevant护栏要阻止 Agent 继续“硬答”强制它要么换 query要么承认无法回答。卡点三生成后。和普通 RAG 一样核对答案的事实依据。但在 Agentic 场景下还要额外检查“Agent 是否用了它声称用过的文档”——有时候 Agent 会说“根据文档 X”但实际生成时根本没把 X 放进上下文。5.4 循环终止条件的设计Agentic RAG 最容易失控的地方是循环。我的做法是设三重终止条件任一满足就退出轮次上限最多循环 3 轮超过就返回当前最优结果并标注“未完全解决”质量达标某一轮重排序后出现了high相关性的文档且生成护栏通过直接返回边际收益递减连续两轮检索结果的最高相关性等级没有提升说明再检也没用退出。这三个条件里第 3 个最容易被忽略但恰恰最重要。很多 Agent 卡死就是因为它在反复检索同一批文档每轮结果都一样但因为没有“收益递减”判断它就一直转。6. 搭一套本地知识库BM25 向量 重排序 护栏的完整配置6.1 组件选型和理由先给一套我实测下来比较稳的本地方案全部可以离线跑环节选型理由稀疏检索BM25rank_bm25 或 Elasticsearch轻量中文需要先分词稠密检索bge-m3 或 bge-large-zh中文效果好支持多语言向量库FAISS 或 QdrantFAISS 纯本地Qdrant 支持过滤重排序bge-reranker-v2-m3和 bge-m3 配套中文重排序强生成Qwen2.5 或本地部署的开源模型可离线可控护栏规则 小模型结构化输出规则优先LLM 兜底选 bge 系列的原因是它在中文场景下的表现稳定而且 reranker 和 embedding 是同一家出的配合起来分数分布比较一致阈值好调。6.2 混合检索的合并策略BM25 和向量检索各自返回 top-N建议 N30合并时用RRFReciprocal Rank Fusion而不是简单加权分数。原因是 BM25 的分数和向量相似度的量纲完全不同直接加权需要归一化而归一化又会引入新的偏差。RRF 只看排名不看分数鲁棒得多def rrf_merge(bm25_results, vector_results, k60): scores {} for rank, doc_id in enumerate(bm25_results): scores[doc_id] scores.get(doc_id, 0) 1 / (k rank 1) for rank, doc_id in enumerate(vector_results): scores[doc_id] scores.get(doc_id, 0) 1 / (k rank 1) return sorted(scores.items(), keylambda x: x[1], reverseTrue)k60是 RRF 论文里的经验值实测下来 60 到 100 之间差别不大。合并后取 top-50 送进重排序。6.3 重排序的批处理和超时控制Cross-Encoder 重排序是逐对计算的50 条候选如果串行跑延迟会很难看。两个优化批处理把 50 个(query, doc)对打包成一个 batch 送进模型GPU 利用率能拉满延迟能降一个数量级超时降级给重排序设一个超时比如 800ms超时就用 RRF 的排序结果兜底不要让整个请求卡死。import concurrent.futures def rerank_with_timeout(query, candidates, timeout0.8): with concurrent.futures.ThreadPoolExecutor() as executor: future executor.submit(rerank_batch, query, candidates) try: return future.result(timeouttimeout) except concurrent.futures.TimeoutError: return fallback_by_rrf(candidates)6.4 阈值调参的实操方法护栏阈值不能拍脑袋定要有数据支撑。我的做法是构造一个标注集200 到 500 条(query, doc, 真实相关性)三元组覆盖典型场景和边界情况跑一遍重排序统计不同relevance等级下的准确率和召回率画一条阈值-准确率曲线找到业务能接受的准确率对应的阈值上线后持续收集护栏触发日志每月 review 一次动态调整。这个过程听起来麻烦但比“上线后天天被业务方投诉答错”要省事得多。而且标注集一旦建起来后续换模型、改 prompt 都能用它做回归测试是一次投入长期受益的事。6.5 一个容易忽略的坑文档切分粒度最后说一个和重排序、护栏都相关但经常被忽略的点文档切分粒度。切得太碎单个片段信息不完整重排序再准也没用切得太粗一个片段里混了多个主题重排序模型分不清主次。我的经验值是中文文档按 300 到 500 字切段落边界优先不要硬切句子。如果文档有明确的章节结构按章节切再在章节内细分。切完之后给每个片段加上上下文前缀比如“本文档来自《XX 手册》第 3 章主题是 XX”这个前缀在重排序时能提供额外的判断依据实测能提升几个点的准确率。实操心得切分粒度这件事没有万能参数一定要用你的真实数据试。我见过同一个团队在 A 项目用 300 字切分效果很好搬到 B 项目就一塌糊涂因为 B 项目的文档本身句子就长、信息密度低。先跑标注集再定参数。7. 我在实际项目里踩过的几个坑第一个坑是过度依赖 LLM 做护栏。早期我把护栏全交给 LLM 判断结果护栏本身成了延迟瓶颈而且护栏自己也会幻觉——它会把明明有依据的答案判成“无依据”。后来改成规则优先LLM 只处理规则覆盖不到的边界情况延迟降了一半准确率反而升了。第二个坑是重排序模型和 embedding 模型不配套。有次为了省事embedding 用了一个模型reranker 用了另一个结果两者的分数分布对不上阈值怎么调都不对。后来统一用同一家的模型问题自然消失。这个教训是重排序和检索的模型最好同源它们的训练数据和打分习惯是一致的。第三个坑是忽略了 query 改写对重排序的影响。Agentic RAG 里 Agent 会改写 query改写后的 query 和原始 query 的语义可能有偏差。如果重排序用的是改写后的 query可能把用户真正想要的内容排到后面。我的做法是重排序始终用原始 query改写后的 query 只用于检索召回。这样召回广度和排序精度都能兼顾。第四个坑是护栏日志没打全。上线初期只记了“触发了护栏”没记“为什么触发”“触发了哪条规则”“当时的候选是什么”。结果出了问题根本没法复盘。后来补全了日志字段才发现大部分误杀都集中在某几类 query 上针对性优化之后误杀率降了 70%。这套东西搭下来从零到能用的本地知识库大概需要两到三周其中一半时间花在标注集构建和阈值调参上。但这一步省不得因为 RAG 的准确性提升从来不是靠换个更强的模型而是靠把每个环节的判断都变成可校验、可测试的工程能力。TypeSafe 的价值就在这里——它让“AI 判断”从玄学变成工程。
TypeSafe RAG实战：重排序与护栏如何让检索结果可信
1. 为什么“让模型自己判断”这件事迟早要翻车做过 RAG 项目的人大概都经历过这个阶段检索回来一堆文档片段直接塞进 prompt让大模型自己看着办。早期 demo 阶段这么干确实爽几行代码就能跑通效果看着也还行。但只要往生产环境推一步问题就全冒出来了——同一个问题问两遍答案可能一次引用对了文档、一次引用错了模型偶尔会把检索到的无关内容当成事实编进回答里更头疼的是你根本没法跟业务方解释“为什么这次答错了”因为整个判断过程都藏在模型的隐层里是个黑盒。这就是TypeSafe这个概念真正要解决的问题。它不是一个具体的库或者框架的名字而是一种设计思路把原本交给 LLM 自由发挥的那些判断抽出来变成有类型约束、可校验、可测试的编程能力。重排序Rerank是其中一环RAG 护栏Guardrail是另一环两者串起来才构成一条从“检索结果”到“可信输出”的完整链路。我先把这篇要讲的东西摊开说清楚免得你读到一半发现不是自己要的重排序到底在 RAG 里承担什么角色为什么向量检索之后几乎必须补这一步BM25 这类稀疏检索和稠密向量怎么配合TypeSafe 的思路怎么落到重排序上——把“相关性判断”从模型打分变成带 schema 的结构化输出RAG 护栏具体拦什么怎么设计才能既不误杀又不漏放Agentic RAG 场景下护栏和重排序怎么协同以及 skill 和 RAG 结合时容易踩的坑最后给一套可以照着搭的本地知识库方案包括 BM25 向量混合检索 重排序 护栏的完整参数配置。适合谁看已经跑通过基础 RAG、现在被“答案不稳定”折磨的开发者正在做企业知识库、医疗/金融这类对准确性要求高的场景的工程师以及想理解 Agentic RAG 里“判断层”该怎么设计的架构同学。纯小白也能看我会把每个概念用生活化的方式讲一遍再上代码。提示本文讲的 TypeSafe 是一种工程范式不是某个特定开源项目的 API。你用的可能是 LangChain、LangChain4j、Spring AI 或者自己手写的框架思路是通用的代码示例以 Python 为主Java 生态的同学看逻辑即可。2. 重排序在 RAG 链路里的真实位置它不是可选项2.1 向量检索的“召回率陷阱”先纠正一个特别常见的误解很多人以为向量检索embedding 余弦相似度返回的 top-k 就是“最相关的 k 个片段”。不是的。向量检索优化的是召回它保证的是“相关内容大概率出现在候选集里”但它对排序精度的保证很弱。原因在于稠密向量的相似度是一个被压缩过的语义距离。一段文本被编码成 768 维或 1024 维的向量之后很多细粒度的差异被抹平了。比如你问“布洛芬和对乙酰氨基酚能不能一起吃”检索可能同时召回“布洛芬的用法用量”“对乙酰氨基酚的肝毒性”“解热镇痛药联合用药原则”三个片段它们的向量相似度可能都在 0.8 上下但真正能回答问题的只有第三个。向量检索分不出这个差别因为前两个在语义上也“很像”。这就是所谓的召回率陷阱你以为 top-5 就是最相关的 5 个实际上里面可能混了两三个“语义相近但答非所问”的片段。在 demo 里模型还能靠自己的常识兜住在生产环境里这就是错误答案的来源。2.2 BM25 和稠密向量为什么必须一起用BM25 是经典的稀疏检索算法它基于词频和逆文档频率打分。它的强项和向量检索正好互补维度BM25稀疏稠密向量强项精确关键词、专有名词、编号、代码语义改写、同义表达、跨语言弱项换个说法就检索不到细粒度区分能力弱典型失效场景用户用口语描述专业概念查询里有精确的型号、药名、错误码打分可解释性高能追溯到具体词低是个黑盒距离举个实际例子。用户查“错误码 E5023 怎么解决”BM25 能精准命中包含 “E5023” 的文档向量检索可能给你召回一堆“系统错误处理”的泛泛内容。反过来用户问“登录一直转圈进不去”BM25 可能一个词都对不上向量检索却能找到“认证超时排查”的文档。所以成熟方案基本都是混合检索BM25 和向量各召回一批合并去重再交给重排序。这一步的关键是不要在这一层做取舍宁可多召回一些把精排的活留给重排序模型。2.3 重排序模型到底在算什么重排序Rerank用的是 Cross-Encoder 结构和向量检索的 Bi-Encoder 有本质区别。Bi-Encoder 是 query 和 document 分别编码再算距离快但粗Cross-Encoder 是把 query 和 document 拼在一起送进模型让模型在注意力层里直接建模两者的交互慢但准。用生活类比Bi-Encoder 像是把两个人的简历分别打分再比对Cross-Encoder 像是让两个人当面聊一次再判断合不合适。后者当然更准但成本高所以只能用在候选集已经缩小到几十条的时候。重排序的输入是(query, candidate_doc)对输出是一个相关性分数。常见模型有 bge-reranker、Cohere Rerank、以及各家自己微调的版本。实测下来在混合检索召回 50 条、重排序取 top-5 的配置下答案准确率比纯向量 top-5 能高出 20 到 30 个百分点这个提升幅度在 RAG 里是相当可观的。注意重排序不是免费的。Cross-Encoder 的推理成本是 Bi-Encoder 的几十倍50 条候选的重排序延迟在几百毫秒到一秒之间。如果你的场景对延迟极敏感要么减少候选数要么上更小的重排序模型要么做异步预计算。3. 把“相关性判断”变成 TypeSafe 的结构化输出3.1 让 LLM 打分为什么不可靠很多团队图省事直接让 LLM 给候选片段打分“请给下面这段内容和问题的相关性打 0 到 10 分”。这个做法在 demo 里能用生产里问题一堆分数不稳定同一个输入温度稍微变一下分数就从 7 跳到 9没有校准模型给的 8 分和另一个模型给的 8 分不是一个意思跨批次没法比较无法校验模型返回 “8.5 分因为……” 这种自由文本你得写正则去抠数字抠错了还没法发现不可测试你没法为“打分逻辑”写单元测试因为输出是自然语言。这就是 TypeSafe 要解决的痛点。核心思路是不要让模型输出自由文本而是让它输出符合预定义 schema 的结构化数据。3.2 用 schema 约束模型输出假设我们要做重排序定义一个这样的输出结构from pydantic import BaseModel, Field from typing import Literal class RerankResult(BaseModel): doc_id: str Field(description候选文档的唯一标识) relevance: Literal[high, medium, low, irrelevant] Field( description相关性等级只能是这四个值之一 ) reason: str Field(max_length100, description判断理由不超过100字) key_evidence: str Field(description支撑判断的原文片段必须逐字引用)注意几个设计细节用枚举而不是连续分数。high/medium/low/irrelevant四档比 0-10 分稳定得多模型不容易在相邻档位之间反复横跳。如果你确实需要更细的粒度用 5 档别用 10 档。强制引用原文。key_evidence字段要求模型逐字引用候选文档里的片段这能极大降低幻觉——模型没法凭空编造证据因为它必须从给定文本里抄。限制理由长度。max_length100既省 token又逼模型说重点避免它写一大段废话稀释信号。然后调用模型时开启结构化输出OpenAI 的response_format、Anthropic 的 tool use、或者本地模型用 outlines/guidance 做约束解码response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: RERANK_SYSTEM_PROMPT}, {role: user, content: build_rerank_input(query, candidates)} ], response_format{type: json_schema, json_schema: RerankResult.model_json_schema()} )这样拿到的结果可以直接RerankResult.model_validate_json(response)解析解析失败就是明确的错误而不是“抠不出数字”的模糊状态。3.3 TypeSafe 带来的三个实际好处第一可校验。解析出来的对象字段类型是确定的relevance一定是四个枚举值之一key_evidence一定是字符串。你可以在入库前加一道校验如果key_evidence不在原文里出现直接判定这次判断无效降级处理。第二可测试。你可以写单元测试构造一批(query, doc)对和期望的relevance标签跑回归测试。模型换版本、prompt 改一版跑一遍测试就知道有没有退化。这在纯自由文本打分方案里是做不到的。第三可组合。结构化输出可以直接喂给下游逻辑。比如relevance irrelevant的片段直接丢弃high的片段加权medium的进护栏二次检查。整个链路是确定性的代码不是“看模型心情”。实操心得枚举档位的命名别用good/bad这种模糊词用high/medium/low/irrelevant这种有明确排序含义的词模型对有序枚举的判断一致性更高。另外irrelevant这一档一定要有否则模型会把所有片段都往low里塞你就失去了“明确排除”的能力。4. RAG 护栏拦的不是模型是整条链路4.1 护栏到底该拦什么很多人一提 RAG 护栏就想到“内容安全过滤”这理解太窄了。生产级 RAG 的护栏至少要覆盖四类问题护栏类型拦截目标典型触发场景输入护栏恶意/越界 queryprompt 注入、越权查询、无关闲聊检索护栏低质量召回召回为空、召回内容与 query 明显无关生成护栏幻觉与越界答案引用了不存在的文档、超出知识库范围输出护栏合规与格式敏感信息泄露、格式不符合下游要求重排序和护栏的关系是重排序负责“排序”护栏负责“裁决”。重排序给出相关性等级护栏根据等级和业务规则决定“这条能不能用、怎么用”。4.2 检索护栏召回为空时不要硬答最常见的翻车场景是知识库里根本没有相关内容但模型还是编了一个答案。护栏要在检索阶段就拦住这种情况。一个可落地的判断逻辑def retrieval_guardrail(candidates, rerank_results, threshold0.0): # 规则1召回为空 if not candidates: return GuardrailDecision(actionrefuse, reasonno_candidates) # 规则2重排序后没有任何 high/medium usable [r for r in rerank_results if r.relevance in (high, medium)] if not usable: return GuardrailDecision(actionrefuse, reasonall_irrelevant) # 规则3最高相关性等级低于业务阈值 top max(rerank_results, keylambda x: RELEVANCE_ORDER[x.relevance]) if RELEVANCE_ORDER[top.relevance] threshold: return GuardrailDecision(actionrefuse, reasonbelow_threshold) return GuardrailDecision(actionproceed, docsusable)这里的RELEVANCE_ORDER把枚举映射成可比较的整数{high: 3, medium: 2, low: 1, irrelevant: 0}。阈值设多少取决于业务——医疗、法律这类场景建议设到high才放行通用问答设到medium就够。4.3 生成护栏验证答案有没有“引用幻觉”模型生成答案后护栏要做的是核对答案里的每个事实性陈述是否能在检索到的文档里找到依据。这一步可以用另一个 LLM 调用完成同样用 TypeSafe 的结构化输出class ClaimCheck(BaseModel): claim: str Field(description从答案中抽取的事实性陈述) supported: bool Field(description该陈述是否被给定文档支持) supporting_doc_id: str | None Field(description支持的文档ID无则为None) class AnswerAudit(BaseModel): claims: list[ClaimCheck] overall_supported: bool把答案拆成若干 claim逐条核对。只要有一条supportedFalse就触发降级要么重新生成要么在答案里标注“此部分未经知识库验证”要么直接拒答。这个做法比“让模型自己检查一遍”可靠得多因为它是结构化的、可追溯的——每条 claim 都能定位到具体文档出了问题能复盘。4.4 护栏的误杀问题怎么破护栏最大的风险不是漏放是误杀。用户问了个正常问题护栏因为阈值设太严给拒了体验直接崩。我的经验是分级响应不要一刀切。低于阈值不一定拒答可以降级成“我找到的相关信息有限以下内容仅供参考”把判断权交回用户。记录所有护栏触发事件。每次refuse或降级都打日志定期 review看哪些是误杀据此调阈值。给护栏加白名单。某些高频、已验证的 query 模式可以直接放行绕过部分检查降低延迟和误杀率。注意护栏的 LLM 调用本身也会失败、也会幻觉。所以护栏逻辑里对 LLM 的依赖要尽量少能用规则判断的比如召回为空、引用文档 ID 不存在就用规则LLM 只用在真正需要语义判断的地方。5. Agentic RAG 里重排序和护栏怎么协同5.1 Agentic RAG 和普通 RAG 的区别普通 RAG 是单轮直线query → 检索 → 重排序 → 生成 → 输出。Agentic RAG 是多轮循环Agent 会自己决定“要不要检索”“检索什么”“检索结果够不够”“要不要换个 query 再检一次”。这个变化对重排序和护栏提出了新要求重排序要能被多次调用每次的候选集可能不同结果要能合并护栏要能拦截 Agent 的中间决策不只是最终输出整个循环要有终止条件否则 Agent 可能陷入“检索-不满意-再检索”的死循环。5.2 把重排序封装成 Agent 的 skill在 Agentic 架构里重排序应该被封装成一个独立的 skill工具Agent 可以显式调用它。这样做的价值是重排序从“隐式流程”变成“显式动作”Agent 的决策过程可观测、可干预。一个 skill 的定义大概长这样class RerankSkill: name rerank_documents description 对候选文档按与查询的相关性重新排序返回带相关性等级的文档列表 parameters { query: {type: string, description: 原始查询}, doc_ids: {type: array, items: {type: string}, description: 待重排序的文档ID列表}, top_k: {type: integer, default: 5} } def execute(self, query, doc_ids, top_k5): candidates fetch_docs(doc_ids) results rerank_with_schema(query, candidates) return sorted(results, keylambda r: RELEVANCE_ORDER[r.relevance], reverseTrue)[:top_k]Agent 调用这个 skill 之后拿到的是结构化的RerankResult列表可以直接根据relevance决定下一步全是irrelevant就换 query 重检有high就进入生成。5.3 护栏在 Agent 循环里的三个卡点Agentic RAG 的护栏要卡在三个位置卡点一检索前。检查 Agent 生成的 query 是否越界。比如用户问的是 A 领域Agent 却生成了一个查询 B 领域的 query这可能是 prompt 注入的信号直接拦截。卡点二重排序后。这是最关键的一环。如果重排序结果显示所有候选都是irrelevant护栏要阻止 Agent 继续“硬答”强制它要么换 query要么承认无法回答。卡点三生成后。和普通 RAG 一样核对答案的事实依据。但在 Agentic 场景下还要额外检查“Agent 是否用了它声称用过的文档”——有时候 Agent 会说“根据文档 X”但实际生成时根本没把 X 放进上下文。5.4 循环终止条件的设计Agentic RAG 最容易失控的地方是循环。我的做法是设三重终止条件任一满足就退出轮次上限最多循环 3 轮超过就返回当前最优结果并标注“未完全解决”质量达标某一轮重排序后出现了high相关性的文档且生成护栏通过直接返回边际收益递减连续两轮检索结果的最高相关性等级没有提升说明再检也没用退出。这三个条件里第 3 个最容易被忽略但恰恰最重要。很多 Agent 卡死就是因为它在反复检索同一批文档每轮结果都一样但因为没有“收益递减”判断它就一直转。6. 搭一套本地知识库BM25 向量 重排序 护栏的完整配置6.1 组件选型和理由先给一套我实测下来比较稳的本地方案全部可以离线跑环节选型理由稀疏检索BM25rank_bm25 或 Elasticsearch轻量中文需要先分词稠密检索bge-m3 或 bge-large-zh中文效果好支持多语言向量库FAISS 或 QdrantFAISS 纯本地Qdrant 支持过滤重排序bge-reranker-v2-m3和 bge-m3 配套中文重排序强生成Qwen2.5 或本地部署的开源模型可离线可控护栏规则 小模型结构化输出规则优先LLM 兜底选 bge 系列的原因是它在中文场景下的表现稳定而且 reranker 和 embedding 是同一家出的配合起来分数分布比较一致阈值好调。6.2 混合检索的合并策略BM25 和向量检索各自返回 top-N建议 N30合并时用RRFReciprocal Rank Fusion而不是简单加权分数。原因是 BM25 的分数和向量相似度的量纲完全不同直接加权需要归一化而归一化又会引入新的偏差。RRF 只看排名不看分数鲁棒得多def rrf_merge(bm25_results, vector_results, k60): scores {} for rank, doc_id in enumerate(bm25_results): scores[doc_id] scores.get(doc_id, 0) 1 / (k rank 1) for rank, doc_id in enumerate(vector_results): scores[doc_id] scores.get(doc_id, 0) 1 / (k rank 1) return sorted(scores.items(), keylambda x: x[1], reverseTrue)k60是 RRF 论文里的经验值实测下来 60 到 100 之间差别不大。合并后取 top-50 送进重排序。6.3 重排序的批处理和超时控制Cross-Encoder 重排序是逐对计算的50 条候选如果串行跑延迟会很难看。两个优化批处理把 50 个(query, doc)对打包成一个 batch 送进模型GPU 利用率能拉满延迟能降一个数量级超时降级给重排序设一个超时比如 800ms超时就用 RRF 的排序结果兜底不要让整个请求卡死。import concurrent.futures def rerank_with_timeout(query, candidates, timeout0.8): with concurrent.futures.ThreadPoolExecutor() as executor: future executor.submit(rerank_batch, query, candidates) try: return future.result(timeouttimeout) except concurrent.futures.TimeoutError: return fallback_by_rrf(candidates)6.4 阈值调参的实操方法护栏阈值不能拍脑袋定要有数据支撑。我的做法是构造一个标注集200 到 500 条(query, doc, 真实相关性)三元组覆盖典型场景和边界情况跑一遍重排序统计不同relevance等级下的准确率和召回率画一条阈值-准确率曲线找到业务能接受的准确率对应的阈值上线后持续收集护栏触发日志每月 review 一次动态调整。这个过程听起来麻烦但比“上线后天天被业务方投诉答错”要省事得多。而且标注集一旦建起来后续换模型、改 prompt 都能用它做回归测试是一次投入长期受益的事。6.5 一个容易忽略的坑文档切分粒度最后说一个和重排序、护栏都相关但经常被忽略的点文档切分粒度。切得太碎单个片段信息不完整重排序再准也没用切得太粗一个片段里混了多个主题重排序模型分不清主次。我的经验值是中文文档按 300 到 500 字切段落边界优先不要硬切句子。如果文档有明确的章节结构按章节切再在章节内细分。切完之后给每个片段加上上下文前缀比如“本文档来自《XX 手册》第 3 章主题是 XX”这个前缀在重排序时能提供额外的判断依据实测能提升几个点的准确率。实操心得切分粒度这件事没有万能参数一定要用你的真实数据试。我见过同一个团队在 A 项目用 300 字切分效果很好搬到 B 项目就一塌糊涂因为 B 项目的文档本身句子就长、信息密度低。先跑标注集再定参数。7. 我在实际项目里踩过的几个坑第一个坑是过度依赖 LLM 做护栏。早期我把护栏全交给 LLM 判断结果护栏本身成了延迟瓶颈而且护栏自己也会幻觉——它会把明明有依据的答案判成“无依据”。后来改成规则优先LLM 只处理规则覆盖不到的边界情况延迟降了一半准确率反而升了。第二个坑是重排序模型和 embedding 模型不配套。有次为了省事embedding 用了一个模型reranker 用了另一个结果两者的分数分布对不上阈值怎么调都不对。后来统一用同一家的模型问题自然消失。这个教训是重排序和检索的模型最好同源它们的训练数据和打分习惯是一致的。第三个坑是忽略了 query 改写对重排序的影响。Agentic RAG 里 Agent 会改写 query改写后的 query 和原始 query 的语义可能有偏差。如果重排序用的是改写后的 query可能把用户真正想要的内容排到后面。我的做法是重排序始终用原始 query改写后的 query 只用于检索召回。这样召回广度和排序精度都能兼顾。第四个坑是护栏日志没打全。上线初期只记了“触发了护栏”没记“为什么触发”“触发了哪条规则”“当时的候选是什么”。结果出了问题根本没法复盘。后来补全了日志字段才发现大部分误杀都集中在某几类 query 上针对性优化之后误杀率降了 70%。这套东西搭下来从零到能用的本地知识库大概需要两到三周其中一半时间花在标注集构建和阈值调参上。但这一步省不得因为 RAG 的准确性提升从来不是靠换个更强的模型而是靠把每个环节的判断都变成可校验、可测试的工程能力。TypeSafe 的价值就在这里——它让“AI 判断”从玄学变成工程。
![[ macOS] Zsh 原生增强 Tab 自动补全](http://pic.xiahunao.cn/yaotu/[ macOS] Zsh 原生增强 Tab 自动补全)
