Qwen3-Embedding¶

1 引言¶

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

2 支持的特性¶

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

3 前提条件¶

3.1 模型权重¶

Qwen3-Embedding-8B 下载模型权重
Qwen3-Embedding-4B 下载模型权重
Qwen3-Embedding-0.6B 下载模型权重

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

4 安装¶

4.1 Docker 镜像安装¶

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

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

A3 系列A2 系列Atlas 300I DUO

在每个节点上启动 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 在线服务部署¶

A3/A2 系列Atlas 300I DUO

#!/bin/sh
vllm serve Qwen/Qwen3-Embedding-0.6B  \
  --served-model-name Qwen/Qwen3-Embedding-0.6B  \
  --runner pooling \
  --port 8000 \
  --max-model-len 1024

#!/bin/sh
vllm serve Qwen/Qwen3-Embedding-0.6B  \
  --served-model-name Qwen/Qwen3-Embedding-0.6B  \
  --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-Embedding-0.6B",
  "data": [
    {
      "index": 0,
      "object": "embedding",
      "embedding": [
      -0.04725276678800583,-0.021066857501864433
      ]
    },
    {
      "index": 1,
      "object": "embedding",
      "embedding": [
        -0.053165290504693985,-0.01480848714709282
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 39,
    "total_tokens": 39,
    "completion_tokens": 0,
    "prompt_tokens_details": null
  }
}

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

7 精度评估¶

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

使用 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-Embedding-0.6B",
                                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 性能评估¶

使用 vLLM Benchmark¶

以 Qwen3-Embedding-0.6B 的性能测试为例。有关更多详细信息，请参阅 vllm benchmark。

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

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

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

9 常见问题¶

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