gpustack/bge-reranker-v2-m3-GGUF on Ascend NPU

1. 简介

本文档记录 gpustack/bge-reranker-v2-m3-GGUF 在华为昇腾 Ascend910 NPU 环境上的适配与验证结果。

BGE-Reranker-V2-M3 是 BAAI 推出的多语言文本重排序模型，基于 BERT 架构（568M 参数），支持多种语言（中、英、法等）的 query-passage 相关性打分。本仓库提供 GGUF 量化版本，支持在 NPU 上高效推理。

2. 验证环境

组件	版本
NPU	Ascend910_9362
OS	HCE 2.0 (ARM64)
Python	3.11.14
PyTorch	2.9.0+cpu
torch_npu	2.9.0.post1+gitee7ba04
llama-cpp-python	0.3.23
transformers	4.57.6
modelscope	1.35.3

3. 模型下载

使用 ModelScope SDK 下载 GGUF 模型文件：

# 安装依赖
pip install modelscope

# 下载模型
python3 -c "
from modelscope import snapshot_download
snapshot_download('gpustack/bge-reranker-v2-m3-GGUF', cache_dir='~/gpustack/bge-reranker-v2-m3-GGUF/model')
"

下载后模型目录结构：

~/gpustack/bge-reranker-v2-m3-GGUF/model/gpustack/bge-reranker-v2-m3-GGUF/
  - bge-reranker-v2-m3-Q2_K.gguf
  - bge-reranker-v2-m3-Q3_K_M.gguf
  - bge-reranker-v2-m3-Q4_0.gguf
  - bge-reranker-v2-m3-Q4_K_M.gguf   <-- 推荐使用
  - bge-reranker-v2-m3-Q5_0.gguf
  - bge-reranker-v2-m3-Q5_K_M.gguf
  - bge-reranker-v2-m3-Q6_K.gguf
  - bge-reranker-v2-m3-Q8_0.gguf
  - bge-reranker-v2-m3-FP16.gguf

4. 推理方式

该模型使用 llama-cpp-python 加载 GGUF 格式文件。由于当前 llama-cpp-python 版本对 BERT 分类头的支持限制，使用 bi-encoder 方式（分别编码 query 和 passage 后计算余弦相似度）作为替代方案。

# 安装依赖
pip install llama-cpp-python

# 运行推理
python3 inference.py

推理脚本示例：

from llama_cpp import Llama
import math

# 加载模型
llm = Llama(
    model_path="bge-reranker-v2-m3-Q4_K_M.gguf",
    n_ctx=8192,
    verbose=False,
    embedding=True,
)

# 编码文本（mean-pooling）
def encode(text):
    result = llm.embed(text, normalize=False)
    n_tokens = len(result)
    return [sum(col)/n_tokens for col in zip(*result)]

# 余弦相似度
def similarity(a, b):
    dot = sum(x*y for x, y in zip(a, b))
    na = math.sqrt(sum(x*x for x in a))
    nb = math.sqrt(sum(x*x for x in b))
    return dot/(na*nb) if na*nb > 0 else 0.0

# 重排序
query = "What is machine learning?"
passages = ["ML is a subset of AI.", "Paris is the capital of France."]
q_emb = encode(query)
for p in passages:
    p_emb = encode(p)
    score = similarity(q_emb, p_emb)
    print(f"Score: {score:.4f} - {p}")

5. Smoke 验证

# 运行推理测试
python3 inference.py --query "What is artificial intelligence?"

预期输出：

模型加载成功（约 0.7s）
与 AI 相关的 passage 获得较高相似度评分
与 query 无关的 passage 获得较低评分

6. 性能参考

测试条件：Q4_K_M 量化模型，8 个查询-passage 对，单次推理。

指标	数值
模型文件	bge-reranker-v2-m3-Q4_K_M.gguf
模型大小	418 MB
模型加载时间	~0.72 s
单次编码时间	~0.1 s
单次 rerank 时间（8 passages）	~0.9 s
吞吐量	~10.6 req/s
嵌入维度	1024
分类头输出	1 (未暴露)

8. 注意事项

分类头支持：模型包含 BERT 分类头（1 个输出），用于直接输出相关性得分。当前 llama-cpp-python 0.3.23 未暴露分类头输出，需要使用更新的版本或直接使用 llama.cpp 的 rerank 功能。
GGUF 格式：模型以 GGUF 格式提供，需使用 llama-cpp-python 或 llama.cpp 推理。
量化选择：Q4_K_M 在速度和精度之间取得较好平衡，推荐使用。
NPU 支持：在 Ascend910 NPU 上可用，模型加载默认分配 0 层到 NPU（GGUF 格式暂不支持 NPU 加速），完全在 CPU 侧运行。
模型来源：BGE-Reranker-V2-M3 原模型由 BAAI 发布，GPUSTack 提供 GGUF 转换版本。

Ascend NPU 精度评测

NPU vs CPU 精度对比（CPU 为基线，NPU 为验证目标）：

指标	数值
测试用例数	2
预测一致性	2/2 (100.0%)
精度要求	NPU vs CPU 最大 logits 误差 < 1.0%
精度结论	✅ 通过 (准确率 100.0%)

精度评测源代码和日志详见 eval/ 目录。