一、概述

本文档介绍如何在华为昇腾 NPU（Atlas 300I DUO / 310I Duo）上，使用 vllm-ascend 框架部署 Qwen3-Embedding-8B 文本嵌入模型。

Qwen3 Embedding 模型系列是 Qwen 家族最新的专有模型，专为文本嵌入和排序任务设计，提供 0.6B、4B 和 8B 多种尺寸。vLLM Ascend 从 0.9.2rc1 版本开始支持该模型。

二、版本信息

本指南基于 vLLM Ascend v0.21.0rc1 版本，该版本于 2026 年 6 月 16 日发布，是 v0.21.0 发布系列的第一个候选版本。

v0.21.0rc1 主要亮点

• Ascend 950 端到端支持：提供对 DeepSeek-V4 的完整端到端支持，包括分段图模式、DSA 注意力、KV 缓存管理和 MTP

• Hybrid 和 Mamba 对齐前缀缓存：提升相关序列间的缓存命中率

• FULL_AND_PIECEWISE 图模式：引入混合全图与分段策略的编译模式，需要 HDK 25.5.1+ / CANN 8.5.0+

• Python 3.12 支持：所有基础镜像已升级至 py3.12

三、环境准备

3.1 依赖版本要求

v0.21.0rc1 版本所需的依赖包版本如下：

包名	必需版本
CANN	9.0.0
NNAL	9.0.0
torch	2.10.0
torch-npu	2.10.0
Triton Ascend	3.2.1

3.2 Atlas 300I DUO 特别说明

对于 Atlas 300I DUO（310P）设备，需要注意以下事项：

1. 图模式限制：当前版本在 Atlas 300I DUO 上支持 FULL_DECODE_ONLY 图模式。当启用多个 Tensor Parallel（TP）rank 时，可捕获的图数量有限；TP=1 时无此限制。

2. 不支持 Triton：Atlas 300I DUO 不支持 triton 或 triton-ascend。若从源码安装，需要手动卸载相关依赖：

   bash

   pip uninstall -y triton triton-ascend

3. 必须显式设置 max-model-len：不可依赖自动检测，否则可能因分配 O(max_model_len^2) 大小的掩码张量导致 OOM。建议设置保守值，如 --max-model-len 2048。

四、部署步骤

4.1 启动 Docker 容器

使用以下命令启动容器（已根据用户实际命令调整）：

bash

docker run -itd \
  --net=host \
  --name qwen-embedding-vllm-0 \
  --shm-size=10g \
  --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/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 /home/yyp/model/:/home/yyp/model \
  quay.io/ascend/vllm-ascend:v0.21.0rc1-310p-openeuler \
  bash -c "vllm serve /home/yyp/model/Qwen3-Embedding-8B \
    --served-model-name qwen3-embedding \
    --max-model-len=2048 \
    --port=11000 \
    --runner pooling \
    --dtype=half \
    --tensor-parallel-size=1 \
    --enforce-eager"

4.2 参数说明

参数	说明
--net=host	使用主机网络模式
--shm-size=10g	共享内存大小设置为 10GB
--device /dev/davinci0	挂载 NPU 设备（单卡）
-v /home/yyp/model/:/home/yyp/model	挂载模型目录
vllm serve	启动 vLLM 推理服务
--served-model-name	服务暴露的模型名称
--max-model-len=2048	最大序列长度（必须显式设置）
--port=11000	服务端口
--runner pooling	使用 Pooling 模式（Embedding 任务）
--dtype=half	使用半精度（FP16）推理
--tensor-parallel-size=1	张量并行度（单卡场景）
--enforce-eager	强制使用 Eager 模式执行

五、服务验证

5.1 检查容器状态

bash

docker ps | grep qwen-embedding-vllm-0

5.2 查看服务日志

bash

docker logs qwen-embedding-vllm-0

5.3 测试 Embedding 接口

服务启动后，可通过 OpenAI 兼容的 Embeddings API 进行测试：

bash

curl http://localhost:11000/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-embedding",
    "input": "Hello, world!"
  }'

六、常见问题

6.1 环境变量设置问题

若遇到 libatb.so 找不到或设备类型推断失败的问题，需要加载环境变量：

bash

source /usr/local/Ascend/nnal/atb/set_env.sh
source /usr/local/Ascend/ascend-toolkit/set_env.sh
npu-smi info  # 验证 NPU 可见性

6.2 版本兼容性问题

若遇到 InvalidVersion 错误，可设置环境变量指定 vLLM 版本：

bash

export VLLM_VERSION=0.21.0

6.3 内存不足（OOM）

• 确认已显式设置 --max-model-len 为较小的保守值

• 可设置 PYTORCH_NPU_ALLOC_CONF=max_split_size_mb:256 减少内存碎片

七、参考资料

• vLLM Ascend 官方文档

• vLLM Ascend v0.21.0rc1 版本说明

• Qwen3-Embedding-8B 部署教程

• vLLM-Ascend GitHub 仓库