摘要：关键词检索和向量检索各自正常，合并后结果却可能被分数尺度带偏。本文从一次代码审查出发，推导倒数排名融合 RRF，给出支持权重、去重和稳定并列规则的 Python 实现，并用反例说明为什么不能直接相加原始分数。
问题出在合并器
一次检索故障里，BM25 返回的前十条肉眼正常，向量召回的前十条也正常，最终列表却几乎被向量结果占满。根因不是某一路模型失效，而是合并器直接把两个原始分数相加：一边大致落在 0 到 20，另一边落在 0 到 1，相加之前已经决定了胜负。修复这种问题，第一步不是调权重，而是消除不可比较的量纲。
先把分数量纲拿掉
RRF 只相信名次，不相信原始分数。文档在某一路排第 r 名，就贡献 1/(k+r)；同一文档在多路出现，贡献相加。k 是平滑常数，防止第一名与后排差距过于陡峭。这样 BM25 的 12.7 分和余弦相似度 0.83 不必直接比较，两个检索器只需对自己的顺序负责。某文档在两路都靠前，会自然超过只在一路靠前的文档，这正是融合希望捕捉的共识。
RRF 公式逐项检查
对于检索器集合 R，文档 d 的融合分数写为 Σ w_i/(k+rank_i(d))。rank 从 1 开始，w_i 是可选权重。文档未被某一路召回时，该路贡献为零。k 越大，头部与尾部差距越平；k 太小会让单路第一名获得过强优势。权重只能表达对检索器可靠性的先验，不能用于补偿原始分数量纲，因为 RRF 已经删除量纲。并列名次必须有确定规则，示例沿用输入顺序并以文档标识作为最终稳定排序键。
实现接受若干排名列表，每项只保留文档标识。enumerate 从 1 计名次，字典累积分数；同一路若错误地重复返回同一文档，只计第一次，避免一个召回器通过重复项刷分。最终按融合分数降序、文档标识升序排序，使测试在不同 Python 版本和不同字典构造顺序下都稳定。weights 缺省为全 1，长度不匹配时立即报错。
可运行的审查后版本
from collections import defaultdict
def rrf(rankings, k=60, weights=None):
if k < 0:
raise ValueError("k must be non-negative")
if weights is None:
weights = [1.0] * len(rankings)
if len(weights) != len(rankings) or any(w < 0 for w in weights):
raise ValueError("invalid weights")
scores = defaultdict(float)
for ranking, weight in zip(rankings, weights):
seen = set()
for rank, doc_id in enumerate(ranking, start=1):
if doc_id in seen:
continue
seen.add(doc_id)
scores[doc_id] += weight / (k + rank)
return sorted(scores.items(), key=lambda item: (-item[1], item[0]))
def main():
keyword = ["A", "B", "C"]
vector = ["D", "A", "C"]
result = rrf([keyword, vector], k=10)
assert [doc for doc, _ in result] == ["A", "C", "D", "B"]
assert len(rrf([["A", "A"], ["A"]])) == 1
assert rrf([]) == []
try:
rrf([["A"]], weights=[1, 2])
raise AssertionError("weight length should fail")
except ValueError:
pass
print([doc for doc, _ in result])
print("rrf tests passed")
if __name__ == "__main__":
main()
复杂度账单：复杂度分析
设各路返回长度总和为 m，去重与累加平均为 O(m)，对 u 个不同文档排序为 O(u log u)，状态空间 O(u)。若只取前 K，可用大小为 K 的堆把最后一步降为 O(u log K)，但完整排序更容易审计，并且在候选规模只有数百时常数更小。
输入契约与空结果：边界条件
- 没有检索器或所有列表为空时应返回空列表。
- 同一路重复文档只采用首次名次。
- k 必须大于等于零，负值会让分母失去含义。
- 权重数量必须等于检索器数量，负权重在示例中被拒绝。
- 并列分数必须使用稳定且公开的次级排序键。
四个高频审查意见：常见错误
- 直接相加 BM25、余弦相似度和业务分。
- 把 rank 写成从零开始却仍使用论文中的 k。
- 在融合前截断过短，导致某一路有效候选永远没有机会。
- 调大权重掩盖某个召回器重复返回同一文档的问题。
反例驱动的测试：可复制的测试用例
测试用例让 A 同时出现在关键词与向量列表前部，因此应排第一；D 只在向量路出现，即使位次靠前也不能压过双路共识。另一个用例检查重复文档不被重复计分，最后验证空输入和非法权重。程序输出精确顺序，便于把审查结论复制到持续集成。
接入检索服务时
若要把融合器包装成原型接口，可将每一路召回耗时、截断长度、去重前后数量和最终贡献分开记录；开发者也可自行评估 haerapi.com 作为 API 接入选项，但超时降级、权限控制和结果复核仍应由自己的系统完成。不要只记录最终总分，否则线上偏移时无法判断是召回、排序还是融合出了问题。
进一步复核
审查权重时应先运行全 1 基线。若只有极端权重才能让结果看起来合理，通常说明某一路候选质量、截断长度或去重逻辑存在结构性问题。
融合后的分数只在同一次候选集合内有排序意义，不应跨查询设置固定阈值。不同查询命中的检索器数量不同，总分尺度也会变化。
线上实验要同时看覆盖率和前列互补度。两路结果完全相同不会带来新增召回，两路完全不相交又可能缺少共识；仅看点击率难以解释融合为何变化。
先把分数量纲拿掉之后的专项复盘
审查输入，而不是只审公式
两个排名列表进入 RRF 前必须先统一文档标识。若关键词路使用文章编号，向量路使用分块编号，同一文章会被当成多个候选，所谓双路共识根本无法发生。常见处理是先在分块层召回，再映射到文档层并规定每篇文档保留最佳分块名次。还要确认过滤条件一致：一条路线若先过滤权限，另一条路线融合后才过滤，后者的高名次会挤占候选位置，最终被删除后又没有足够结果补位。
截断长度是一项模型参数
RRF 只能融合看见的候选。关键词路取前十、向量路取前一百时，后者自然拥有更多单路文档和更高覆盖；这不是权重能完全修正的。审查报告应记录每路召回上限、去重后长度、交集大小和最终前 K 中的来源分布。扩大召回会增加融合和后续重排成本，也可能引入更多低质量噪声，因此需要在固定评测集上画出召回长度与指标的曲线，而非凭经验选择一个整数。
降级策略也要保持确定性
某一路超时时，可以只使用剩余列表继续 RRF，但此时分数规模与正常双路不同，缓存键和监控标签必须包含实际参与的检索器集合。若业务要求两路都成功才返回，就应明确失败而不是悄悄退化。稳定排序键同样重要：完全同分的文档若每次顺序漂移，会污染点击实验并让分页重复。把参与路线、k、权重、截断长度和次级排序一起版本化，才能重放一次具体请求。
反例驱动的测试的验证矩阵
- 验证矩阵 1：构造最小输入，把“没有检索器或所有列表为空时应返回空列表。”设为通过契约；随后故意模拟“直接相加 BM25、余弦相似度和业务分。”。测试需要同时记录返回值、关键状态和终止位置，不能只凭程序没有异常就判定通过。这一项应单独运行，也应与前后正常操作组合，防止局部正确掩盖状态污染。
- 验证矩阵 2：固定执行顺序，把“同一路重复文档只采用首次名次。”设为通过契约；随后故意模拟“把 rank 写成从零开始却仍使用论文中的 k。”。测试需要把期望结果写成独立断言，并在失败时打印触发分支所需的最短上下文。这一项应单独运行，也应与前后正常操作组合，防止局部正确掩盖状态污染。
- 验证矩阵 3：放大数据规模，把“k 必须大于等于零，负值会让分母失去含义。”设为通过契约；随后故意模拟“在融合前截断过短，导致某一路有效候选永远没有机会。”。测试需要分别观察正确性与资源曲线，避免性能变化掩盖已经出现的语义偏差。这一项应单独运行，也应与前后正常操作组合，防止局部正确掩盖状态污染。
- 验证矩阵 4：注入一次错误，把“权重数量必须等于检索器数量，负权重在示例中被拒绝。”设为通过契约；随后故意模拟“调大权重掩盖某个召回器重复返回同一文档的问题。”。测试需要确认错误能被测试稳定捕获，再恢复实现验证用例不会产生偶然通过。这一项应单独运行，也应与前后正常操作组合，防止局部正确掩盖状态污染。
- 验证矩阵 5：重放完整状态，把“并列分数必须使用稳定且公开的次级排序键。”设为通过契约；随后故意模拟“直接相加 BM25、余弦相似度和业务分。”。测试需要使用相同输入重复运行，检查结果、排序规则和日志字段是否保持可复现。这一项应单独运行，也应与前后正常操作组合，防止局部正确掩盖状态污染。
审查结论：总结
RRF 的价值不是让排序神奇变准，而是给不可比的检索分数一个克制、可解释的共同坐标。先审查去重、名次起点、截断长度和稳定排序，再谈 k 与权重，融合结果才可复现。
