Carrel 是一个面向 AI Agent 的自托管知识库，核心能力是混合检索与本体增强生成（Ontology-Augmented Generation）。它的图文双路重排（Dual Reranking）机制，让文本片段和图片证据先由两个独立的重排模型分别打分、各自判断相关性，最后再按名次而非分数融合成一份结果。本文将拆解这条检索链路的原理、关键参数和实测收益，帮你理解为什么开启双路重排后，图片类问题的命中率能从 50% 提升到 87.5%。

🔍 为什么需要「双路」：单路重排搞不定图文混合检索

传统 RAG 的重排环节通常只有一个文本交叉编码器（Cross-Encoder），但知识库里的证据并不都是文字：

• 图片证据（截图、图表、界面照片）在索引时只有一小段视觉模型生成的描述文字。文本重排器只能读这段"旁白"，看不见图本身，相关性判断经常失准；
• 用一张图提问（以图搜证据）时，文本重排器更是完全无能为力；
• 文本分数和图片分数来自不同模型，数值尺度不可比，直接相加或取最大值都会互相干扰。

Carrel 的解法是：两路各打各的分、各判各的相关性，最后只用"名次"这一把通用的尺子来融合。

🧩 整体流程：召回 → 通道融合 → 双路并行重排 → 名次融合

一次检索请求在重排前后的链路如下：

第 ② 步的 RRF 只决定候选进入重排的先后（预算默认 64 个名额，KB_SEARCH_RERANK_N），真正的相关性判断发生在 ③④ 两步。

✍️ 文本路：交叉编码器如何给长文本打分

文本重排器（如 qwen3-reranker-0.6b）接收的是"清洗后的正文"，规则很讲究：

• 长切块不截断，而是开窗打分：约 480 token 一个窗口、32 token 重叠（KB_SEARCH_RERANK_WINDOW_TOKENS/KB_SEARCH_RERANK_OVERLAP_TOKENS），每个候选的最终分数取所有窗口的最高分，避免答案被切在窗口缝隙里而丢失，实现见 rerank.py；
• 输入带"文件名 › 章节路径"的头部行，帮助模型理解出处；
• 通过相关性地板（默认 0.1，KB_SEARCH_RERANK_THRESHOLD）的候选才被标记为accepted，全部低于地板时整包降级为diagnostic，提示 Agent"证据偏弱"；
• 文本路超时默认 20 秒，失败时退回第 ② 步的融合顺序并在degraded字段中报告，而不是让整个请求失败。

🖼️ 图像路：多模态模型"真的看图"打分

图像重排是双路机制的核心增量。rerank_images 的工作方式：

• 看缓存像素：只允许读取校验过的本地缓存图片，转成 data URL 喂给模型；模型绝不会去抓取文档里引用的任何网络地址；
• 图 + 文一起进：每个候选是"多模态 content"——图片像素 + 截断到 384 token 的来源文字，模型综合判断"这张图"和问题的相关度；
• 以图搜图：如果请求本身带查询图片（image_b64），问题一侧也变成"文字 + 图片"，实现跨模态匹配；
• 小批量 + 硬预算：每批最多 4 张图，图像阶段默认 15 秒预算（KB_SEARCH_VISUAL_RERANK_TIMEOUT），且受整次请求总预算约束；
• 独立的相关性门槛 0.5（KB_SEARCH_VISUAL_RERANK_THRESHOLD）：低分是"拒绝"，不是"模型故障"。一张低相关图片不能靠它的向量相似度高分被救回（见 test_dual_rerank.py 中的同名断言）。

⚖️ 名次融合：为什么按排名而不是按分数

不同模型输出的分数分布差异很大：0.9 的文本分和 0.9 的视觉分含义完全不同。Carrel 的融合策略因此只用名次：

1. 拿到视觉分数的候选只进入图像分路，从文本分路中移除——同一证据只投一票，避免"图注文字 + 图片"双重计票；
2. 两条分路内部各自按相关性精排后，分别计算 RRF 名次分1 / (60 + 名次)，得到统一的score_fusion（service.py）；
3. 存在被接受候选时，未通过各自门槛的候选被整体过滤——"拒绝"在融合后依然生效；
4. 名次相同时不跨模型比大小，保留原始召回顺序；仅当请求带图片时，图像分路在同名次下获得优先；
5. 表格偏好、样板内容降权、低置信视觉降权等微调都在各分路内部、融合之前完成，融合分数本身是排名分而非可信度概率。

这套设计还有一个工程收益：两条分支并行执行、独立降级。图像端点挂了，文本路照常返回，响应里只多一条visual_rerank:unavailable的降级记录。

📊 实测效果：图片证据命中率接近翻倍

官方 0.3.0 检索评测 在 176 份文档、99 道问题上用本地 Qwen3 / Qwen3-VL 模型测得：

结论很清晰：双路重排最确定的收益在图片证据（新增的 3 个 top-5 命中全部排到第 1 名），而文本与表格题略有让位——这是能力取舍，不是回归。完整报告含耗时与跨文档覆盖分析：retrieval-evaluations-0.3.0.zh-CN.md。

⚙️ 如何开启与调整双路重排

双路重排默认开启，只需提供端点即可自动生效（配置说明见 configuration.zh-CN.md）：

本地部署可用--with-local-models一键拉起包含文本/视觉重排器在内的模型服务，模板文件在 qwen3_reranker.jinja 与 qwen3_vl_reranker.jinja。排障时看两处：/health会分别报告文本重排、视觉召回、图像重排是否在线；响应里的retrieval_summary.ranking给出两路状态，sources中每条证据的ranking字段标明它来自哪条分路、排名第几。

📚 关键源码与文档导航

• 双路重排主逻辑：app/kb_search/service.py（_rank_dual并行打分与名次融合）
• 重排客户端与窗口打分：app/kb_search/rerank.py
• 召回通道 RRF 融合：app/kb_search/fusion.py
• 全部检索参数与默认值：app/kb_search/config.py
• 分路行为测试（融合、超时、回退）：app/tests/test_dual_rerank.py
• 图文分路重排官方说明：docs/retrieval.zh-CN.md

小结

Carrel 的图文双路重排可以浓缩成三句话：图像证据交给看得见图的多模态模型，文本证据交给文本交叉编码器；两路独立打分、独立设门槛，拒绝不可被高分翻案；最后只用名次做 RRF 融合，让不可比的分数量纲退场。这正是它在图片类问题上命中率接近翻倍的来源。