人工智能大模型模型推理服务AscendCANN【免费下载链接】vllm-ascendCommunity maintained hardware plugin for vLLM on Huawei Ascend项目地址https://gitcode.com/gh_mirrors/vl/vllm-ascend点击查看免费下载Qwen3-Embedding 是 Qwen 家族面向文本嵌入embedding与重排序reranking任务推出的专用模型系列本文以 vllm-ascend 为运行环境完整讲解从权重获取、Docker/源码安装、在线服务部署、功能验证到 MTEB 精度评估与 vLLM Benchmark 性能测试的全流程。读完本文你将能在 Atlas A2/A3、Ascend 950DT950PR 以及 Atlas 300I DUO 等昇腾设备上稳定地以pooling模式对外提供/v1/embeddings兼容服务并掌握关键参数如--runner pooling、--compilation-config、fuse_norm_quant、--max-model-len在昇腾硬件上的约束与调优要点。1 模型与支持情况概述Qwen3 Embedding 模型系列是 Qwen 家族最新的专有模型专为文本嵌入和排序ranking任务设计。它建立在 Qwen3 系列密集基础模型之上提供多种尺寸的文本嵌入与重排序模型0.6B、4B 和 8B。在 vllm-ascend 中该模型属于Pooling Models池化模型类别通过runnerpooling运行模式对外提供嵌入向量输出。需要特别注意的是只有 vLLM Ascend 0.9.2rc1 及更高版本才支持该模型。从仓库的支持模型矩阵Pooling Models 一节可以看到当前各硬件平台的支持状态硬件平台支持状态说明A2/A3 系列实验性支持W8A8 未测试Ascend 950DT950PR Products实验性支持—Atlas 300I DUO实验性支持FP16W8A8 未测试其中 表示“实验性支持” 表示“未测试或未验证”使用前请结合自身硬件与精度要求评估。此外在版本发布说明中可以看到项目已修复过 310P 上 Qwen3-Embedding 与 Qwen3-VL-Embedding 的运行失败问题说明该模型在昇腾侧的兼容性处于持续演进中。2 前提条件模型权重获取2.1 权重下载推荐从 ModelScope 下载以下任一版本的模型权重权重版本下载链接Qwen3-Embedding-8BModelScopeQwen3-Embedding-4BModelScopeQwen3-Embedding-0.6BModelScope路径说明将模型权重下载到任意指定目录并记录该路径确保后续部署命令中的模型路径与此目录完全一致。对于多节点部署场景建议将权重下载到多个节点的共享目录例如/root/.cache/这样每个节点都可以直接访问同一份权重避免重复下载和磁盘浪费。3 安装环境3.1 Docker 镜像安装推荐可以直接使用 vllm-ascend 官方 Docker 镜像运行Qwen3-Embedding模型。根据你的机器类型选择对应镜像并在节点上启动容器详见安装文档。Ascend 950DT950PR Products以下命令使用适用于 Ascend 950DT950PR Products 的 Ubuntu 镜像启动容器export IMAGEquay.io/ascend/vllm-ascend:{{ vllm_ascend_version }}-a5 docker run --rm \ --name vllm-ascend \ --nethost \ --shm-size1g \ --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 bashA3 系列在每个节点上启动 Docker 镜像export IMAGEquay.io/ascend/vllm-ascend:{{ vllm_ascend_version }}-a3 docker run --rm \ --name vllm-ascend \ --shm-size1g \ --nethost \ --privilegedtrue \ --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 bashA2 系列export IMAGEquay.io/ascend/vllm-ascend:{{ vllm_ascend_version }} docker run --rm \ --name vllm-ascend \ --shm-size1g \ --nethost \ --privilegedtrue \ --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 bashAtlas 300I DUOexport IMAGEquay.io/ascend/vllm-ascend:{{ vllm_ascend_version }}-310p docker run --rm \ --name vllm-ascend \ --shm-size1g \ --nethost \ --privilegedtrue \ --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上述命令中的{{ vllm_ascend_version }}是文档模板变量实际使用时请替换为你所需的具体版本号注意需为0.9.2rc1 及以上版本。容器挂载了昇腾驱动、dcmi、npu-smi 等必要设备与目录其中-v /root/.cache:/root/.cache用于把共享权重目录映射进容器。docker run成功后可通过执行docker ps命令验证容器服务已正常运行。3.2 源码安装如果不想使用上述 Docker 镜像也可以从源码构建全部组件从源码安装vllm-ascend参考安装文档。若需部署多节点环境需要在每个节点上分别完成环境配置。4 在线服务部署4.1 Ascend 950DT950PR Products / A3 / A2在以上三类硬件上直接使用 vllm-ascend 的标准serve命令启动 Qwen3-Embedding 服务vllm serve Qwen/Qwen3-Embedding-0.6B \ --served-model-name Qwen/Qwen3-Embedding-0.6B \ --runner pooling \ --port 8000 \ --max-model-len 10244.2 Atlas 300I DUOAtlas 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 \ --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由于硬件流stream数量有限cudagraph_capture_sizes的大小受到严格限制必须显式指定如[1024, 512]否则可能因捕获形状过大导致编译失败或资源不足。关键参数说明--max-model-len表示上下文长度即单个请求的输入加输出的最大值。对于 Atlas 300I DUO如果自动解析得到较大的上下文长度分配该注意力掩码复杂度为O(max_model_len²)可能会超出 NPU 内存并触发OOM。务必设置一个明确且保守的值例如--max-model-len 1024。--runner pooling指定以 pooling 模式运行这是嵌入类模型在 vLLM 中的标准运行方式用于输出句子级嵌入向量而非逐 token 生成。--additional-config中的ascend_compilation_config.fuse_norm_quant控制在昇腾图编译阶段是否启用 norm 与量化quant的算子融合 pass。该配置项在 ascend_config.py 中默认值为True在 Atlas 300I DUO 上需要显式设为false以选择已验证的 norm 与量化执行路径保证正确性与稳定性参见additional_config 配置文档。--dtype float16Atlas 300I DUO 平台按支持矩阵要求以 FP16 精度运行该模型。常见问题提示若遇到部署问题请参考公共 FAQ 进行故障排查。4.3 仓库中的可复用示例与验证用例仓库提供了两个可以直接参考的实现与测试证据离线嵌入示例演示了不经过 HTTP 服务、直接在 Python 中以LLM(modelQwen/Qwen3-Embedding-0.6B, runnerpooling)加载模型并调用model.embed(input_texts)获取嵌入向量的方式还展示了 Qwen3-Embedding 官方的任务指令模板用法——查询query需附上一句任务描述Instruct: {task_description}\nQuery:{query}而检索文档documents无需加指令最后通过向量点积计算查询与文档间的相似度分数。单卡功能验证用例以VllmRunner(model_name, runnerpooling, max_model_lenNone, cudagraph_capture_sizes[4])运行模型并用check_embeddings_close与 HF 参考实现对比嵌入输出容差tol1e-2可用于功能与精度冒烟验证。MRV2 pooling 验证用例在 A2 上通过VLLM_USE_V2_MODEL_RUNNER1开启 V2 model runner并使用compilation_config{cudagraph_capture_sizes: [1024, 512]}、max_model_len1024、dtypefloat16等参数验证 MRV2 pooling 执行路径。5 功能验证服务启动后可以通过以下命令验证嵌入服务是否正常工作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 OKJSON 响应中包含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 } }响应中每个输入文本对应一个embedding数组为节省篇幅示例截取了向量前两维usage字段记录了本次请求的 token 统计如prompt_tokens: 39。更多使用示例可以参考仓库中的离线嵌入示例其中包含批量文本嵌入与相似度计算逻辑。6 精度评估这里提供一种基于 MTEB 的精度评估方法。6.1 使用 MTEB 进行精度评估有关 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, revisionnorm, dtypefloat16, max_model_len10240, ) cache mteb.ResultCache(/home/data/mteb_data) tasks mteb.get_tasks(tasks[LeCaRDv2]) results mteb.evaluate(model, taskstasks, cachecache, encode_kwargs{batch_size: 2}, overwrite_strategyalways) df results.to_dataframe() print(df)执行完成后即可得到精度评估结果df数据框会打印出所选任务上的指标分数。脚本要点说明通过VllmEncoderWrapper将本地权重包装为 MTEB 可用的编码器权重路径需与第 2 节记录的下载目录一致revisionnorm表示使用归一化后的权重版本这是 Qwen3-Embedding 在检索评测场景下的推荐用法os.environ[HF_ENDPOINT] https://hf-mirror.com用于在国内网络环境下加速 HuggingFace 数据集下载数据缓存目录由HF_DATASETS_CACHE指定。7 性能评估7.1 使用 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 ./参数含义--backend openai-embeddings指定使用 OpenAI 兼容的 embeddings 后端--endpoint /v1/embeddings指定压测请求的 API 端点--random-input 200生成 200 条随机输入文本作为压测负载--save-result --result-dir ./将压测结果保存到当前目录。大约几分钟后即可获得性能评估结果吞吐、时延等指标会输出到控制台并写入结果文件。8 常见问题FAQ对于常见的环境问题、安装问题和通用参数问题请参考公共 FAQ其中包含当前支持设备清单Atlas A2/A3 训练与推理系列、实验性的 Atlas 300I 系列等以及暂不支持的设备如 Atlas 200I A2、Ascend 910/910 Pro BDocker 镜像获取方式Quay.io 官方源及国内镜像加速方式如m.daocloud.io、quay.nju.edu.cn离线环境下镜像的导出与导入方法。针对 Qwen3-Embedding 部署FAQ 之外还需重点自查以下几点版本是否满足vLLM Ascend ≥ 0.9.2rc1Atlas 300I DUO 上是否设置了保守的--max-model-len如 1024以避免 O(max_model_len²) 掩码导致 OOMAtlas 300I DUO 上是否已按文档设置--compilation-config {cudagraph_capture_sizes: [1024,512]}与--additional-config {ascend_compilation_config: {fuse_norm_quant: false}}模型路径是否与权重下载目录一致多节点部署时确认共享目录挂载正确。9 总结本文围绕 vllm-ascend 上运行 Qwen3-Embedding 模型给出了端到端指引从模型选择与权重下载、按硬件平台选择 Docker 镜像或源码安装、在线服务部署与关键参数约束到/v1/embeddings接口功能验证、MTEB 精度评估以及 vLLM Benchmark 性能测试。核心要点可归纳为Qwen3-Embedding0.6B/4B/8B以pooling runner模式运行仅支持 vLLM Ascend 0.9.2rc1各硬件平台支持状态均为实验性其中 Atlas 300I DUO 需使用 FP16 并附加编译参数限制昇腾场景下务必关注--max-model-len的显式设置与fuse_norm_quant等编译融合选项对内存与稳定性的影响仓库中的离线示例与端到端测试用例可直接复用用于快速验证功能与精度。赞分享人工智能大模型模型推理服务AscendCANN【免费下载链接】vllm-ascendCommunity maintained hardware plugin for vLLM on Huawei Ascend项目地址https://gitcode.com/gh_mirrors/vl/vllm-ascend点击查看免费下载相关推荐Qwen3-8B 昇腾 NPU 部署实战基于 vLLM-ascend 插件的高效推理服务搭建指南Qwen3 8B 昇腾 NPU 部署实战基于 vLLM ascend 插件的高效推理服务搭建指南 本指南以《开源大模型食用指南》self llm仓库中 m教程大模型本地部署微调Qwen3-30B-A3B 昇腾 NPU 部署实战基于 vLLM-Ascend 的安装、推理与精度/性能调优指南Qwen3 30B A3B 昇腾 NPU 部署实战基于 vLLM Ascend 的安装、推理与精度/性能调优指南 Qwen3 30B A3B 是 Qwen3人工智能大模型模型推理服务AscendCANN昇腾 Ascend NPU 上基于 vllm-ascend 部署 Qwen3.6-35B-A3B 推理服务全指南昇腾 Ascend NPU 上基于 vllm ascend 部署 Qwen3.6 35B A3B 推理服务全指南 Qwen3.6 35B A3B 是通义实验室发大模型人工智能教程本地部署微调上一篇3分钟学会在Windows电脑安装安卓应用APK Installer完全指南下一篇WorkTool企业微信自动化机器人技术架构解析基于Android无障碍服务的非侵入式RPA实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考