Qwen3-Embedding

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 系列

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

A2 系列

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

Atlas 300I DUO

    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 系列

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

Atlas 300I DUO

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

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

以 Qwen3-Embedding-0.6B 的性能运行为例。更多详情请参考 vllm 基准测试。

以 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。