Qwen3-VL-Reranker¶

1 简介¶

Qwen3-VL-Embedding 和 Qwen3-VL-Reranker 模型系列是 Qwen 家族的最新成员，基于近期开源且功能强大的 Qwen3-VL 基础模型构建。该系列专为多模态信息检索和跨模态理解而设计，支持文本、图像、截图、视频以及包含这些模态混合形式的多种输入。本指南介绍如何使用 vLLM Ascend 运行该模型。

2 支持特性¶

请参阅支持特性列表获取该模型的支持特性矩阵。

3 前提条件¶

3.1 模型权重¶

权重版本	下载链接
`Qwen3-VL-Reranker-8B`	ModelScope
`Qwen3-VL-Reranker-2B`	ModelScope

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

路径说明：将模型权重下载到您选择的目录并记录下来。确保后续部署命令中的模型路径与此目录一致。

4 安装¶

4.1 Docker 镜像安装¶

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

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

A3 系列A2 系列Atlas 300I DUO

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

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-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.23.0
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.23.0-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 run 后，您可以通过执行 docker ps 命令来验证容器服务是否正常运行。

4.2 源码安装¶

如果您不想像上面那样使用 Docker 镜像，也可以全部从源码构建：

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

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

5 在线服务部署¶

5.1 聊天模板¶

Qwen3-VL-Reranker 模型需要特定的聊天模板（chat template）才能正确格式化。请创建一个名为 qwen3_vl_reranker.jinja 的文件，内容如下：

{% raw %}
<|im_start|>system
Judge 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|>
<|im_start|>user
<Instruct>: {{
    messages
    | selectattr("role", "eq", "system")
    | map(attribute="content")
    | first
    | default("Given a search query, retrieve relevant candidates that answer the query.")
}}<Query>:{{
    messages
    | selectattr("role", "eq", "query")
    | map(attribute="content")
    | first
}}
<Document>:{{
    messages
    | selectattr("role", "eq", "document")
    | map(attribute="content")
    | first
}}<|im_end|>
<|im_start|>assistant
{% endraw %}

将此文件保存到您选择的位置（例如 ./qwen3_vl_reranker.jinja）。

A3/A2 系列Atlas 300I DUO

#!/bin/sh
# Ensure the model path matches the directory recorded during download
vllm serve Qwen/Qwen3-VL-Reranker-2B \
    --served-model-name Qwen/Qwen3-VL-Reranker-2B \
    --runner pooling \
    --hf_overrides '{"architectures": ["Qwen3VLForSequenceClassification"],"classifier_from_token": ["no", "yes"],"is_original_qwen3_reranker": true}' \
    --chat-template ./qwen3_vl_reranker.jinja \
    --port 8000 \
    --max-model-len 1024

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

#!/bin/sh
# Ensure the model path matches the directory recorded during download
vllm serve Qwen/Qwen3-VL-Reranker-2B \
    --served-model-name Qwen/Qwen3-VL-Reranker-2B \
    --runner pooling \
    --hf_overrides '{"architectures": ["Qwen3VLForSequenceClassification"],"classifier_from_token": ["no", "yes"],"is_original_qwen3_reranker": true}' \
    --chat-template ./qwen3_vl_reranker.jinja \
    --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。

常见问题提示：如果遇到任何问题，请参考公共常见问题进行排查。

6 功能验证¶

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

服务验证：

curl  http://localhost:8000/v1/rerank \
    -X POST \
    -d '{"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."]}' \
    -H 'Content-Type: application/json'

预期结果：

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

{
    "id": "score-xxxxx",
    "model": "Qwen/Qwen3-VL-Reranker-2B",
    "usage": {
        "prompt_tokens": 179,
        "total_tokens": 179
    },
    "results": [
        {
            "index": 0,
            "document": {
                "text": "The capital of China is Beijing.",
                "multi_modal": null
            },
            "relevance_score": 0.7209711670875549
        },
        {
            "index": 1,
            "document": {
                "text": "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.",
                "multi_modal": null
            },
            "relevance_score": 0.18871910870075226
        }
    ]
}

更多使用示例请参考 examples

7 准确性评估¶

以下是两种准确性评估方法。

7.1 使用 MTEB¶

详细信息请参考 MTEB。

运行以下代码以执行准确性评估。

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-VL-Reranker-2B",
                                revision="norm",
                                dtype="float16",
                                enforce_eager=True,
                                max_model_len=10240,
                                hf_overrides={"architectures": ["Qwen3VLForSequenceClassification"],"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)

执行完成后，您可以获取结果。

8 性能评估¶

8.1 使用 vLLM 基准测试¶

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

以 serve 为例。按如下方式运行代码。

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

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

9 常见问题¶

对于常见的环境、安装和通用参数问题，请参考公共常见问题。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 vl/vllm-ascend