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`	ModelScope
`Qwen3-Embedding-4B`	ModelScope
`Qwen3-Embedding-0.6B`	ModelScope

建议将模型权重下载到多节点共享目录，例如 /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.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 后，您可以通过执行 docker ps 命令验证正在运行的容器服务。

4.2 源代码安装¶

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

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

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

5 在线服务部署¶

A3/A2 系列Atlas 300I DUO

#!/bin/sh
# Ensure the model path matches the directory recorded during download
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
# Ensure the model path matches the directory recorded during download
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。

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

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 准确性评估¶

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

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-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 性能评估¶

8.1 使用 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 常见问题¶

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

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