零GPU也能跑重排序服务:hs-rerank-1 ONNX int8量化与CPU部署完整教程

原创2026-11-11 20:22:192,205 阅读

零GPU也能跑重排序服务:hs-rerank-1 ONNX int8量化与CPU部署完整教程

📦 hs-rerank-1 是一个多语言 Cross-Encoder 重排序模型,内置 ONNX int8 量化导出文件,专门支持 CPU 部署——没有 GPU 也能跑起完整的高精度重排序服务。它同时提供 FP16 的 safetensors 权重,有显卡时可无缝升级。本文带你从零开始,理解它的量化方案并完成 CPU 端部署。

一、为什么重排序模型也能"零GPU"?

常见的 Cross-encoder(交叉编码器)会把 query + 文档拼接后一起送入模型,输出一个 0~1 的相关性分数。相比双塔向量检索,它精度更高,但推理开销也更大,过去通常"必须上GPU"。

hs-rerank-1 通过两个关键设计改变了这一点:

设计点 说明 带来的收益
int8 量化词表 ONNX 导出中词嵌入表(98M 参数)采用 int8 存储 模型体积大幅缩小,CPU 内存友好
极小的主干网络 114M 总参数中,每次前向只跑 15M 参数的 transformer CPU 单次推理速度快

💡 简单说:占参数大头的是 embedding 词表,量化它之后,实际参与计算的只有一台"轻量级 transformer",这就是 CPU 能扛住的原因。

核心参数一览(来自 config.json):

参数 值 位置
模型类型 Cross-encoder 重排序器 config.json
上下文长度 8,192 tokens(同类模型中罕见的长输入) config.json
支持语言 中、英、日、韩、西、法、德、葡 README.md
输出 每对 query-文档一个 0~1 相关度分数 README.md

二、仓库文件结构:CPU 与 GPU 双格式

仓库为 CPU 和 GPU 两种部署场景分别准备好了权重文件,这是理解 ONNX int8 量化方案的关键:

文件 用途 精度/格式
onnx/model.onnx CPU 推理(TEI 自动选用) ONNX,词表 int8 量化
model.safetensors GPU 推理 FP16(fp32 分支另有 FP32 副本)
tokenizer.json / tokenizer_config.json 多语言分词器,max length 8192 —
sentence_bert_config.json 声明 max_seq_length: 8192、do_lower_case: false —

也就是说:同一个模型,两种格式、两种精度,CPU 用 ONNX int8,GPU 用 FP16,精度差异可忽略,按需取用即可。

三、CPU 部署:Docker 一条命令拉起服务

最省事的 CPU 部署方式是官方推荐的 Text Embeddings Inference(TEI) 推理服务。它会自动识别并加载 onnx/model.onnx:

docker run -p 8080:80 \
  ghcr.io/huggingface/text-embeddings-inference:cpu-1.9.3 \
  --model-id hindsight-ai/hs-rerank-1 --auto-truncate \
  --max-client-batch-size 128

几个参数解释 🛠️:

  • cpu-1.9.3:CPU 专用镜像(无需 --gpus),走 ONNX 路径;
  • --auto-truncate:超长文本自动截断到 8,192 token;
  • --max-client-batch-size 128:提高批量吞吐,适合检索后批量重排。

启动后用 curl 验证 /rerank 接口:

curl 127.0.0.1:8080/rerank \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "¿Qué app de presupuesto estoy creando?",
    "texts": [
      "El usuario quiere tooltips en su app de presupuesto.",
      "El usuario corre los domingos por la mañana."
    ]
  }'

返回结果为每条文本一个 score(0~1),相关度越高分数越大。

四、没有 Docker?本地 Python 也能跑

如果只想在脚本里调用,sentence-transformers 一行加载(自动使用 model.safetensors,CPU 下同样可用,只是不如 ONNX int8 极致优化):

from sentence_transformers import CrossEncoder

model = CrossEncoder("hindsight-ai/hs-rerank-1")

query = "¿Qué app de presupuesto estoy creando?"
documents = [
    "El usuario quiere tooltips en su app de presupuesto.",
    "El usuario corre los domingos por la mañana.",
]

print(model.rank(query, documents))
# [{'corpus_id': 0, 'score': 0.9647}, {'corpus_id': 1, 'score': 0.0003}]

rank / predict 返回 0~1 分数;需要原始 logit 时传入 activation_fn=torch.nn.Identity() 即可。

五、接入 Hindsight:两种本地化配置

如果你的检索管线基于 Hindsight,只需改环境变量,CPU 服务即刻生效:

方案 A:本地直接加载模型

HINDSIGHT_API_RERANKER_PROVIDER=local
HINDSIGHT_API_RERANKER_LOCAL_MODEL=hindsight-ai/hs-rerank-1

方案 B:指向 TEI 重排序服务(推荐,配合第三节部署)

HINDSIGHT_API_RERANKER_PROVIDER=tei
HINDSIGHT_API_RERANKER_TEI_URL=http://localhost:8080

🎯 方案 B 让重排序服务独立扩缩容,多台 CPU 机器即可横向扩容,这是"零GPU集群"的典型玩法。

六、有GPU时如何平滑升级?

同一镜像体系提供 GPU 版本,切换镜像 tag 即可(89-1.9.3 对应 L4 等 Ada 架构,1.9.3 对应 A100/H100):

docker run --gpus all -p 8080:80 \
  ghcr.io/huggingface/text-embeddings-inference:89-1.9.3 \
  --model-id hindsight-ai/hs-rerank-1 --auto-truncate \
  --max-client-batch-size 128

接口、参数完全一致,业务代码零改动。

七、FAQ 快速答疑

Q1:int8 量化会明显掉精度吗? 词表从 FP 降为 int8 后,每次前向仅 15M 参数参与计算,量化收益(体积/内存/速度)远大于精度损失,官方基准见 README.md。

Q2:为什么强调 8,192 token? 绝大多数 reranker 上限 512~1024 token,长文档必须切块多次打分。hs-rerank-1 支持单对 8,192 token,长文档一次排完,CPU 上也能稳定跑。

Q3:支持中文吗? 支持。官方语言列表包含简体中文与繁体中文(zh),另有英、西、法、德、葡、日、韩共 8 种语言。

总结

🚀 hs-rerank-1 证明了一件事:重排序服务不必被 GPU 绑架。int8 量化的 ONNX 词表 + 轻量主干网络,让 114M 参数模型在纯 CPU 上通过 TEI 即可提供生产级 /rerank 服务;需要更高吞吐时再切换到 FP16 GPU 镜像,无缝迁移。如果你的检索系统正被"重排太慢、显存不够"困扰,这套零GPU方案值得一试。

登录后查看全文
hs-rerank-1