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。

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

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 在线服务部署¶

A3/A2 系列Atlas 300I DUO

在每个节点上启动 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  \
  --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。

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

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，并返回包含 embedding 字段的 JSON 响应。示例输出：

{
  "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 基准测试¶

以 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 常见问题¶

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

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