一、概述本文档介绍如何在华为昇腾 NPUAtlas 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 缓存管理和 MTPHybrid 和 Mamba 对齐前缀缓存提升相关序列间的缓存命中率FULL_AND_PIECEWISE 图模式引入混合全图与分段策略的编译模式需要 HDK 25.5.1 / CANN 8.5.0Python 3.12 支持所有基础镜像已升级至 py3.12三、环境准备3.1 依赖版本要求v0.21.0rc1 版本所需的依赖包版本如下包名必需版本CANN9.0.0NNAL9.0.0torch2.10.0torch-npu2.10.0Triton Ascend3.2.13.2 Atlas 300I DUO 特别说明对于 Atlas 300I DUO310P设备需要注意以下事项图模式限制当前版本在 Atlas 300I DUO 上支持FULL_DECODE_ONLY图模式。当启用多个 Tensor ParallelTPrank 时可捕获的图数量有限TP1 时无此限制。不支持 TritonAtlas 300I DUO 不支持triton或triton-ascend。若从源码安装需要手动卸载相关依赖bashpip uninstall -y triton triton-ascend必须显式设置 max-model-len不可依赖自动检测否则可能因分配O(max_model_len^2)大小的掩码张量导致 OOM。建议设置保守值如--max-model-len 2048。四、部署步骤4.1 启动 Docker 容器使用以下命令启动容器已根据用户实际命令调整bashdocker run -itd \ --nethost \ --name qwen-embedding-vllm-0 \ --shm-size10g \ --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-len2048 \ --port11000 \ --runner pooling \ --dtypehalf \ --tensor-parallel-size1 \ --enforce-eager4.2 参数说明参数说明--nethost使用主机网络模式--shm-size10g共享内存大小设置为 10GB--device /dev/davinci0挂载 NPU 设备单卡-v /home/yyp/model/:/home/yyp/model挂载模型目录vllm serve启动 vLLM 推理服务--served-model-name服务暴露的模型名称--max-model-len2048最大序列长度必须显式设置--port11000服务端口--runner pooling使用 Pooling 模式Embedding 任务--dtypehalf使用半精度FP16推理--tensor-parallel-size1张量并行度单卡场景--enforce-eager强制使用 Eager 模式执行五、服务验证5.1 检查容器状态bashdocker ps | grep qwen-embedding-vllm-05.2 查看服务日志bashdocker logs qwen-embedding-vllm-05.3 测试 Embedding 接口服务启动后可通过 OpenAI 兼容的 Embeddings API 进行测试bashcurl http://localhost:11000/v1/embeddings \ -H Content-Type: application/json \ -d { model: qwen3-embedding, input: Hello, world! }六、常见问题6.1 环境变量设置问题若遇到libatb.so找不到或设备类型推断失败的问题需要加载环境变量bashsource /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 版本bashexport VLLM_VERSION0.21.06.3 内存不足OOM确认已显式设置--max-model-len为较小的保守值可设置PYTORCH_NPU_ALLOC_CONFmax_split_size_mb:256减少内存碎片七、参考资料vLLM Ascend 官方文档vLLM Ascend v0.21.0rc1 版本说明Qwen3-Embedding-8B 部署教程vLLM-Ascend GitHub 仓库