零GPU也能跑重排序服务:hs-rerank-1 ONNX int8量化与CPU部署完整教程
零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方案值得一试。