Qwen3-VL-Embedding¶

1 引言¶

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

2 支持的特性¶

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

3 前提条件¶

3.1 模型权重¶

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

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

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

4 安装¶

4.1 Docker镜像安装¶

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

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

Ascend 950DT&950PR ProductsA3系列A2系列Atlas 300I DUO

以下命令使用适用于 Ascend 950DT&950PR Products 的 Ubuntu 镜像启动容器。

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-a5
docker run --rm \
    --name vllm-ascend \
    --net=host \
    --shm-size=1g \
    --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-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

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运行成功后，您可以通过执行docker ps命令来验证正在运行的容器服务。

4.2 源码安装¶

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

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

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

5 在线服务部署¶

Ascend 950DT&950PR Products/A3/A2Atlas 300I DUO

vllm serve Qwen/Qwen3-VL-Embedding-2B \
  --served-model-name Qwen/Qwen3-VL-Embedding-2B \
  --runner pooling \
  --port 8000 \
  --max-model-len 1024

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

#!/bin/sh
# Ensure the model path matches the directory recorded during download
vllm serve Qwen/Qwen3-VL-Embedding-2B  \
  --served-model-name Qwen/Qwen3-VL-Embedding-2B  \
  --compilation-config '{"cudagraph_capture_sizes": [1024,512]}' \
  --additional-config '{"ascend_compilation_config": {"fuse_norm_quant": false}}' \
  --runner pooling \
  --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 功能验证¶

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

服务验证：

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

预期结果：

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

{
  "id": "embd-8136155c01e8411d",
  "object": "list",
  "created": 1784538286,
  "model": "Qwen/Qwen3-VL-Embedding-2B",
  "data": [
    {
      "index": 0,
      "object": "embedding",
      "embedding": [
        -0.028474265709519386,
        -0.02678542211651802
      ]
    },
    {
      "index": 1,
      "object": "embedding",
      "embedding": [
        -0.016785264015197754,
        -0.003787524998188019
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 39,
    "total_tokens": 39,
    "completion_tokens": 0,
    "prompt_tokens_details": null
  }
}

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

7 精度评估¶

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

7.1 使用 MTEB¶

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

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

import os
import mteb

from mteb.models.vllm_wrapper import VllmEncoderWrapper

if __name__ == "__main__":

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

    model = VllmEncoderWrapper(f"/root/.cache/Qwen3-VL-Embedding-2B",
                                revision="norm",
                                dtype="float16",
                                max_model_len=10240,
                               )

    cache = mteb.ResultCache("/home/data/mteb_data")
    tasks = mteb.get_tasks(tasks=["LeCaRDv2"])
    results = mteb.evaluate(model, tasks=tasks, cache=cache, encode_kwargs={"batch_size": 2}, overwrite_strategy="always")
    df = results.to_dataframe()
    print(df)

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

8 性能评估¶

8.1 使用 vLLM Benchmark¶

以运行Qwen3-VL-Embedding-2B的性能为例。有关更多详细信息，请参考vllm基准测试。

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

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

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

9 常见问题解答¶

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