跳转至

Qwen3-Reranker

1 引言

Qwen3 Reranker 模型系列是 Qwen 家族最新的专有模型，专为文本嵌入和排序任务设计。基于 Qwen3 系列的密集基础模型，它提供了多种尺寸（0.6B、4B 和 8B）的全面文本嵌入和重排序模型。本指南介绍如何使用 vLLM Ascend 运行该模型。请注意，只有 vLLM Ascend 0.9.2rc1 及更高版本支持该模型。

2 支持的特性

请参考支持的特性获取模型的支持特性矩阵。

3 前提条件

3.1 模型权重

建议将模型权重下载到多个节点的共享目录，例如 /root/.cache/

4 安装

4.1 Docker 镜像安装

您可以使用我们的官方 Docker 镜像直接运行 Qwen3-Reranker 模型。

根据您的机器类型选择镜像并在节点上启动 Docker 镜像，请参考使用 Docker。

在每个节点上启动 Docker 镜像。

export IMAGE=quay.io/ascend/vllm-ascend:v0.22.1rc1-a3
docker run --rm \
    --name vllm-ascend \
    --shm-size=1g \
    --net=host \
    --privileged=true \
    --device /dev/davinci0 \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v /root/.cache:/root/.cache \
    -it $IMAGE bash

在每个节点上启动 Docker 镜像。

  export IMAGE=quay.io/ascend/vllm-ascend:v0.22.1rc1
docker run --rm \
    --name vllm-ascend \
    --shm-size=1g \
    --net=host \
    --privileged=true \
    --device /dev/davinci0 \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v /root/.cache:/root/.cache \
    -it $IMAGE bash

在每个节点上启动 Docker 镜像。

export IMAGE=quay.io/ascend/vllm-ascend:v0.22.1rc1-310p
docker run --rm \
    --name vllm-ascend \
    --shm-size=1g \
    --net=host \
    --privileged=true \
    --device /dev/davinci0 \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v /root/.cache:/root/.cache \
    -it $IMAGE bash

Docker 运行成功后，您可以通过执行 docker ps 命令来验证正在运行的容器服务。

4.2 源码安装

如果您不想使用上述 Docker 镜像，也可以从源码构建所有内容：

  • 从源码安装 vllm-ascend，请参考安装。

如果您想部署多节点环境，需要在每个节点上设置环境。

5 在线服务部署

#!/bin/sh
vllm serve Qwen/Qwen3-Reranker-0.6B \
    --served-model-name Qwen/Qwen3-Reranker-0.6B \
    --runner pooling \
    --hf_overrides '{"architectures": ["Qwen3ForSequenceClassification"],"classifier_from_token": ["no", "yes"],"is_original_qwen3_reranker": true}' \
    --port 8000 \
    --max-model-len 1024


#!/bin/sh
vllm serve Qwen/Qwen3-Reranker-0.6B \
    --served-model-name Qwen/Qwen3-Reranker-0.6B \
    --runner pooling \
    --hf_overrides '{"architectures": ["Qwen3ForSequenceClassification"],"classifier_from_token": ["no", "yes"],"is_original_qwen3_reranker": true}' \
    --compilation-config '{"cudagraph_capture_sizes": [1024,512]}' \
    --additional-config '{"ascend_compilation_config": {"fuse_norm_quant": false}}' \
    --dtype float16 \
    --port 8000 \
    --max-model-len 1024
必需参数说明：

--compilation-config 对于 Atlas 300I DUO，由于硬件流有限，cudagraph_capture_sizes 的大小受到限制。

关键参数说明：

  • --max-model-len 表示上下文长度，即单个请求的输入加输出的最大值。对于 Atlas 300I DUO，如果自动解析得到较大的上下文长度，分配此掩码（O(max_model_len^2)）可能会超出 NPU 内存并触发 OOM。请务必设置明确且保守的值，例如 --max-model-len 1024。

常见问题提示：如果遇到问题，请参考公共 FAQ进行故障排除。

6 功能验证

服务器启动后，您可以通过以下命令进行验证：

服务验证：

import requests

url = "http://127.0.0.1:8000/v1/rerank"

# Please use the query_template and document_template to format the query and
# document for better reranker results.

prefix = '<|im_start|>system\nJudge whether the Document meets the requirements based on the Query and the Instruct provided. Note that the answer can only be "yes" or "no".<|im_end|>\n<|im_start|>user\n'
suffix = "<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n"

query_template = "{prefix}<Instruct>: {instruction}\n<Query>: {query}\n"
document_template = "<Document>: {doc}{suffix}"

instruction = (
    "Given a web search query, retrieve relevant passages that answer the query"
)

query = "What is the capital of China?"

documents = [
    "The capital of China is Beijing.",
    "Gravity is a force that attracts two bodies towards each other. It gives weight to physical objects and is responsible for the movement of planets around the sun.",
]

documents = [
    document_template.format(doc=doc, suffix=suffix) for doc in documents
]

response = requests.post(url,
                         json={
                             "query": query_template.format(prefix=prefix, instruction=instruction, query=query),
                             "documents": documents,
                         }).json()

print(response)

预期结果：

服务返回 HTTP 200 OK，JSON 响应中包含 relevance_score 字段。示例输出：

{
    "id": "score-xxx",
    "model": "Qwen/Qwen3-Reranker-0.6B",
    "usage": {
        "prompt_tokens": 193,
        "total_tokens": 193
    },
    "results": [
        {
            "index": 0,
            "document": {
                "text": "<Document>: The capital of China is Beijing.<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n",
                "multi_modal": null
            },
            "relevance_score": 0.9994981288909912
        },
        {
            "index": 1,
            "document": {
                "text": "<Document>: Gravity is a force that attracts two bodies towards each other. It gives weight to physical objects and is responsible for the movement of planets around the sun.<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n",
                "multi_modal": null
            },
            "relevance_score": 0.00000506485957885161
        }
    ]
}

更多使用示例，请参考示例

7 精度评估

这里提供两种精度评估方法。

使用 MTEB

  1. 有关详细信息，请参考 MTEB。

  2. 运行以下代码执行精度评估。

    import os

from mteb.models.vllm_wrapper import VllmCrossEncoderWrapper

if __name__ == "__main__":
    import mteb

    data_path = "/home/data/mteb_data"
    os.environ["HF_DATASETS_CACHE"] = data_path
    os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

    model = VllmCrossEncoderWrapper(f"/root/.cache/Qwen3-Reranker-0.6B",
                                revision="norm",
                                dtype="float16",
                                enforce_eager=True,
                                max_model_len=10240,
                                hf_overrides={"architectures": ["Qwen3ForSequenceClassification"],"classifier_from_token": ["no", "yes"],"is_original_qwen3_reranker": True})

    cache = mteb.ResultCache("/home/data/mteb_data")
    tasks = mteb.get_tasks(
        task_types=["Reranking"],
        languages=["zho"]
    )
    tasks = mteb.get_tasks(tasks=["MultiLongDocReranking"])
    results = mteb.evaluate(model, tasks=tasks, cache=cache, overwrite_strategy="always")
    print(results)

  3. 执行后，您可以获得结果。

8 性能评估

使用 vLLM Benchmark

以运行 Qwen3-Reranker-0.6B 的性能为例。 有关更多详细信息，请参考 vllm benchmark。

以 serve 为例。运行代码如下。

vllm bench serve --model Qwen/Qwen3-Reranker-0.6B --backend vllm-rerank  --port 8000 --dataset-name random-rerank --endpoint /v1/rerank --random-input 200  --save-result --result-dir ./

大约几分钟后，您可以获得性能评估结果。

9 常见问题

有关常见的环境、安装和一般参数问题，请参考公共 FAQ。