LocalAI Reranker 重排序实践:cross-encoder 后端与 /v1/rerank API

原创2026-09-07 17:55:272,227 阅读
文章标签:人工智能大模型模型推理服务本地部署AI AgentRAGLLM 网关多模态语音/音频媒体生成MCP 服务

LocalAI Reranker 重排序实践:cross-encoder 后端与 /v1/rerank API

在 RAG 与检索系统中,LocalAI 的 reranker(重排序)能力用于两段式检索的第二阶段:快速检索器先召回候选文档,cross-encoder 再对「查询 + 文档」联合打分并重排,从而提升最终答案的相关性。本文基于 LocalAI 官方文档 reranker.md 展开,完整覆盖 rerankers 后端的模型配置、/v1/rerank 请求/响应结构、top_n 语义,并深入仓库源码梳理从 HTTP 入口到 Python gRPC 服务的完整调用链。

两段式检索:快速检索器先召回候选文档,cross-encoder 再按相关性重排

什么是 Reranking:两段式检索的第二阶段

Reranking 模型通常被称为 cross-encoder(交叉编码器),是信息检索与自然语言处理任务中两段式检索系统的核心组件:

  1. 第一阶段(召回):由向量检索、关键词匹配等快速检索器从全库中捞出候选文档,速度优先、精度有限;
  2. 第二阶段(重排):把查询(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:指定走 Python rerankers 后端;
  • 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,命中条件(满足其一即可):

  1. 导入偏好中显式指定 backend: "rerankers";
  2. HuggingFace 仓库属于 cross-encoder 组织(sentence-transformers 官方的 cross-encoder 组织);
  3. 仓库名中包含 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() 计算得分

关键源码细节:

  1. Go 侧编排(core/backend/rerank.go):Rerank() 先用 ModelLoader 按模型配置加载(或复用已加载的)rerank 模型,随后通过 AcquireGlobalBackendSlot() 获取全局后端并发槽位(准入控制,防止同时压垮多个后端),再发起 gRPC 调用。若开启 EnableTracing,会以 BackendTraceRerank 类型记录一次后端 trace,包含 query(截断至 200 字符)、文档数与 top_n,可在 UI 的 trace 视图中复盘每次重排。
  2. 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) 返回。
  3. 不截断的内部消费者:同一个 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),即可让检索结果按真实相关性重排,过滤噪声、提升生成质量。

登录后查看全文
LocalAI