LocalAI Reranker 重排序实践:cross-encoder 后端与 /v1/rerank API
LocalAI Reranker 重排序实践:cross-encoder 后端与 /v1/rerank API
在 RAG 与检索系统中,LocalAI 的 reranker(重排序)能力用于两段式检索的第二阶段:快速检索器先召回候选文档,cross-encoder 再对「查询 + 文档」联合打分并重排,从而提升最终答案的相关性。本文基于 LocalAI 官方文档 reranker.md 展开,完整覆盖 rerankers 后端的模型配置、/v1/rerank 请求/响应结构、top_n 语义,并深入仓库源码梳理从 HTTP 入口到 Python gRPC 服务的完整调用链。
什么是 Reranking:两段式检索的第二阶段
Reranking 模型通常被称为 cross-encoder(交叉编码器),是信息检索与自然语言处理任务中两段式检索系统的核心组件:
- 第一阶段(召回):由向量检索、关键词匹配等快速检索器从全库中捞出候选文档,速度优先、精度有限;
- 第二阶段(重排):把查询(query)与每篇候选文档拼接后送入 cross-encoder,输出一个相似度分数(relevance score)。
拿到分数后,就可以按相关性对文档重新排序,提升 RAG 系统的整体准确率,同时过滤掉不相关的结果——这正是 LocalAI reranker 功能要解决的问题。
与传统 bi-encoder 嵌入模型「query 和 document 各自独立编码、再用向量距离比对」不同,cross-encoder 在编码阶段就让 query 与 document 充分交互,因此判别更准,但代价是每篇文档都要跑一次模型推理,只能用在数量可控的候选集上。这也是两段式架构存在的原因。
可用的后端与镜像
LocalAI 支持 reranker 模型,官方文档推荐的方式是使用 rerankers 后端,该后端封装了 rerankers 这个 Python 包(支持 cross-encoder 等多种重排器)。
前提:必须使用 Python 版容器镜像
文档中特别强调:测试 rerankers 需要使用 带 python 的容器镜像,core 镜像不支持该后端。这是由后端的运行形态决定的——rerankers 后端是一个独立的 Python gRPC 服务进程,由 Go 核心通过 gRPC 调用,而不是编译进 core 二进制的本地扩展。
rerankers 后端在 backend/index.yaml 中登记了多套硬件变体镜像,可按 GPU 平台选择:
| 变体名 | 镜像 tag 示例 | 适用平台 |
|---|---|---|
cuda12-rerankers |
latest-gpu-nvidia-cuda-12-rerankers |
NVIDIA CUDA 12 |
cuda13-rerankers |
latest-gpu-nvidia-cuda-13-rerankers |
NVIDIA CUDA 13 |
intel-rerankers |
latest-gpu-intel-rerankers |
Intel GPU |
rocm-rerankers |
latest-gpu-rocm-hipblas-rerankers |
AMD ROCm |
metal-rerankers |
metal-rerankers |
Apple Metal |
rerankers(默认) |
通用 python 镜像 | CPU 等 |
此外还有对应的 -development 开发版镜像(master 分支构建)。这些后端镜像的 Python 依赖固定在 backend/python/rerankers/requirements-cpu.txt 中(各硬件平台另有 cublas12/cublas13/hipblas/mps/intel 变体):
transformers
accelerate
torch==2.7.1
rerankers[transformers]
也就是说,运行环境本质是 PyTorch + HuggingFace Transformers + rerankers 包,从源码结构看与 CUDA/MPS/ROCm 各变体只是 torch 的构建渠道不同。
模型配置
方式一:手写模型配置文件
文档给出的最简配置如下:
name: jina-reranker-v1-base-en
backend: rerankers
parameters:
model: cross-encoder
参数说明:
name:在 LocalAI 中注册的服务名,后续 API 请求的model字段填它;backend: rerankers:指定走 Pythonrerankers后端;parameters.model:传给后端的模型标识。填cross-encoder表示使用 rerankers 包内置的 cross-encoder 加载方式,也可以替换为 HuggingFace 上具体的 cross-encoder 仓库标识(如cross-encoder/ms-marco-MiniLM-L-6-v2)。从源码结构看,该值会经由 gRPC 请求的Type字段进入后端,成为Reranker构造器的model_type参数(见下文 LoadModel 一节)。
方式二:从模型库(Gallery)安装
更省事的途径是在 LocalAI 的 Web UI 模型库中直接安装 cross-encoder 模型。对应条目定义在 gallery/rerankers.yaml 中,配置内容正是:
backend: rerankers
并在 gallery/index.yaml 中登记了 cross-encoder 条目(tags: reranker、gpu、python,parameters.model: cross-encoder)。
自动导入:从 HuggingFace 仓库识别 reranker
如果你在 UI 中通过 HuggingFace URL 导入一个模型,core/gallery/importers/rerankers.go 中的 RerankersImporter 会自动判断它是否为 reranker,命中条件(满足其一即可):
- 导入偏好中显式指定
backend: "rerankers"; - HuggingFace 仓库属于
cross-encoder组织(sentence-transformers 官方的 cross-encoder 组织); - 仓库名中包含
reranker(不区分大小写)——可覆盖 BAAI 的bge-reranker-*、Alibaba-NLP 的gte-reranker-*等常见系列。
该 importer 必须注册在 SentenceTransformers / Transformers 等通用 importer 之前,原因是 reranker 仓库通常附带 tokenizer 文件,否则会被通用 importer 错误认领。命中后自动生成的配置会带上 backend: rerankers、Reranking: true 以及 usecase: rerank 标记,与手工写法等效。
API 调用:POST /v1/rerank
请求与响应结构
端点由 core/http/routes/jina.go 注册,路由为 POST /v1/rerank,并通过 FLAG_RERANK 用例过滤器匹配具备 rerank 能力的模型。请求/响应结构定义在 core/schema/jina.go:
type JINARerankRequest struct {
Query string `json:"query"`
Documents []string `json:"documents"`
TopN *int `json:"top_n,omitempty"`
// 另有继承自 BasicModelRequest 的 model 字段
}
type JINADocumentResult struct {
Index int `json:"index"`
Document JINAText `json:"document"`
RelevanceScore float64 `json:"relevance_score"`
}
type JINARerankResponse struct {
Model string `json:"model"`
Usage JINAUsageInfo `json:"usage"`
Results []JINADocumentResult `json:"results"`
}
top_n 是可选字段,其语义在 core/http/endpoints/jina/rerank.go 中实现:
- 省略
top_n:返回全部文档的得分; top_n < 1:返回 422("top_n - should be greater than or equal to 1");top_n > 文档数:自动收敛为文档总数,避免后端困惑。
完整示例(继承自官方文档)
启动服务后,可以用以下请求测试:
curl http://localhost:8080/v1/rerank \
-H "Content-Type: application/json" \
-d '{
"model": "jina-reranker-v1-base-en",
"query": "Organic skincare products for sensitive skin",
"documents": [
"Eco-friendly kitchenware for modern homes",
"Biodegradable cleaning supplies for eco-conscious consumers",
"Organic cotton baby clothes for sensitive skin",
"Natural organic skincare range for sensitive skin",
"Tech gadgets for smart homes: 2024 edition",
"Sustainable gardening tools and compost solutions",
"Sensitive skin-friendly facial cleansers and toners",
"Organic food wraps and storage solutions",
"All-natural pet food for dogs with allergies",
"Yoga mats made from recycled materials"
],
"top_n": 3
}'
响应为 JINA reranker 风格的结构,results 按得分降序、最多 top_n 条(本例为 3 条),每条携带原文档下标 index、原文 document.text 与 relevance_score;usage 字段给出 token 统计。结构示意如下:
{
"model": "jina-reranker-v1-base-en",
"usage": { "total_tokens": 0, "prompt_tokens": 0 },
"results": [
{ "index": 3, "document": { "text": "Natural organic skincare range for sensitive skin" }, "relevance_score": 0.0 },
{ "index": 6, "document": { "text": "Sensitive skin-friendly facial cleansers and toners" }, "relevance_score": 0.0 },
{ "index": 2, "document": { "text": "Organic cotton baby clothes for sensitive skin" }, "relevance_score": 0.0 }
]
}
示例中的
relevance_score与usage数值仅作结构示意,实际值取决于所用模型。
关于 usage 的统计口径,从 backend/python/rerankers/backend.py 的 Rerank 方法可以看到:当前 Python 后端以词数近似 token 数(len(doc.split()) 求和,prompt_tokens 为 query 的词数),源码中留有 TODO: Implement the usage calculation with reranker 注释,即尚未接入真实 tokenizer 计数。
源码级调用链:从 HTTP 到 Python 模型
一次 /v1/rerank 请求在 LocalAI 内部的完整路径是:
POST /v1/rerank
→ core/http/routes/jina.go 注册路由,按 FLAG_RERANK 选择模型
→ core/http/endpoints/jina/rerank.go 解析 top_n,构造 proto.RerankRequest
→ core/backend/rerank.go 加载模型、获取全局后端槽位、写入 trace
→ gRPC 调用 rerankers 后端容器
→ backend/python/rerankers/backend.py rerankers.Reranker.rank() 计算得分
关键源码细节:
- Go 侧编排(core/backend/rerank.go):
Rerank()先用ModelLoader按模型配置加载(或复用已加载的)rerank 模型,随后通过AcquireGlobalBackendSlot()获取全局后端并发槽位(准入控制,防止同时压垮多个后端),再发起 gRPC 调用。若开启EnableTracing,会以BackendTraceRerank类型记录一次后端 trace,包含 query(截断至 200 字符)、文档数与top_n,可在 UI 的 trace 视图中复盘每次重排。 - gRPC 服务端(Python)(backend/python/rerankers/backend.py):
LoadModel:调用Reranker(model_name, model_type=..., lang=...)实例化模型。其中model_type来自 gRPC 请求的Type字段(对应配置中的parameters.model),lang复用PipelineType字段传递语言信息;Rerank:调用 rerankers 包的model.rank(query=..., docs=..., doc_ids=...)得到带doc_id与score的排序结果;top_n > 0时用top_k(top_n)截断,否则返回全量。最终每个结果映射为DocumentResult(index, text, relevance_score)返回。
- 不截断的内部消费者:同一个
core/backend/rerank.go还导出了Reranker接口(NewReranker),供路由层以TopN=0方式获取全部文档的分数——源码注释解释,截断会「悄悄丢掉 reranker 认为不太可能的标签」,而路由分类器需要完整分布来做决策。也就是说,rerank 分数除了对外 API,还服务于 LocalAI 内部的路由/分类场景。
值得注意的旁支:除了 rerankers 后端,LocalAI 的 llama-cpp 后端也承接了 GGUF 格式的重排模型(见 llama-cpp score 补丁),端到端测试 tests/e2e-aio/models/rerank.yaml 就是一个例子:
name: jina-reranker-v1-base-en
reranking: true
f16: true
parameters:
model: jina-reranker-v1-tiny-en.f16.gguf
backend: llama-cpp
download_files:
- filename: jina-reranker-v1-tiny-en.f16.gguf
uri: huggingface://mradermacher/jina-reranker-v1-tiny-en-GGUF/jina-reranker-v1-tiny-en.f16.gguf
它通过 reranking: true 声明重排用途,直接加载量化 GGUF 权重,无需 Python 运行环境。此外 gallery/index.yaml 中还收录了 ColBERT 晚交互模式(bge-m3-colbert,经 rerankers 后端加载,配合 router 分类器无需 LLM 往返即可给策略描述打分)以及 GGUF 多模态重排模型(如 Qwen3-VL-Reranker 系列,走 llama-cpp 后端)等条目。可以推断:若你已有 llama-cpp 后端环境,优先尝试 GGUF 重排模型是更轻量的路径;需要 HuggingFace 原生 cross-encoder 时再上 rerankers 后端。
快速参考与排错
| 问题/参数 | 说明与依据 |
|---|---|
使用 core 镜像报后端不可用 |
rerankers 后端必须使用带 python 的后端镜像(官方文档明确说明),参见 backend/index.yaml 中 cuda12-rerankers 等平台变体 |
省略 top_n |
返回全部文档得分(jina/rerank.go 中 TopN == nil 分支) |
top_n < 1 |
返回 HTTP 422 与提示文本 |
top_n > len(documents) |
自动截断为文档数 |
parameters.model 含义 |
对应 gRPC LoadModel 的 Type 字段,最终成为 rerankers 包的 model_type(backend.py LoadModel) |
响应 usage 数值偏小 |
Python 后端目前按词数估算 token,非 tokenizer 精确计数 |
| 想看某次重排详情 | 开启 EnableTracing,Rerank 会记录 BackendTraceRerank trace(query、文档数、top_n、耗时) |
小结
LocalAI 的 reranker 功能围绕一条清晰的链路构建:rerankers(或 llama-cpp GGUF)后端提供 cross-encoder 打分能力,POST /v1/rerank 以 JINA 兼容的协议暴露「query + documents + top_n → 排序得分」的服务,Go 核心负责模型加载、并发准入与 trace 记录,Python 侧则直接复用 rerankers 生态完成推理。对于搭建本地 RAG 的团队,只需两步即可获得重排序能力:选用带 python 的后端镜像并注册一个 backend: rerankers 的模型配置(或在 UI 中安装 gallery 的 cross-encoder),即可让检索结果按真实相关性重排,过滤噪声、提升生成质量。
