昇腾 Ascend 910C 部署 Qwen3-VL-32B-Instruct 实战教程本文记录在昇腾 Ascend 910C 双 NPU 环境中使用 vLLM vLLM-Ascend 部署 Qwen3-VL-32B-Instruct 的完整过程包括环境检查、离线安装、常见报错及解决方法最后通过 OpenAI 兼容接口提供公网服务。一、硬件与系统环境本次环境信息系统Ubuntu 20.04.5 LTS 架构aarch64 Python3.11.4 NPUAscend 910C2 张 单卡显存约 64GB torch2.7.1cpu torch_npu2.7.1.post4检查 NPUnpu-smi info检查 Pythonpython3--versionpython3-mpip--versionuname-m检查 NPU 是否可用python3 -PY import torch import torch_npu print(torch:, torch.__version__) print(torch_npu:, torch_npu.__version__) print(NPU可用:, torch.npu.is_available()) print(NPU数量:, torch.npu.device_count()) PY如果显示NPU可用: True NPU数量: 2说明基础驱动和torch_npu正常。二、网络受限环境的处理思路容器内部可能无法访问公网但宿主机或外部电脑可以访问网络。这种情况下建议在外部机器下载 Git 仓库和 Python 安装包通过 CANNLab 文件上传、挂载目录或共享盘传入容器模型提前下载到/mnt/workspace/models容器内部使用本地源码安装不依赖外网。模型目录/mnt/workspace/models/Qwen3-VL-32B-Instruct确认模型文件find/mnt/workspace/models/Qwen3-VL-32B-Instruct-maxdepth2-typef|head三、vLLM 与 vLLM-Ascend 版本匹配最初尝试安装pip3install\vllm0.11.0\vllm-ascend0.11.0出现依赖冲突vllm 0.11.0 depends on torch2.8.0 vllm-ascend 0.11.0 depends on torch2.7.1原因是官方 vLLM 0.11.0 与 vLLM-Ascend 0.11.0 的默认依赖不一致而当前环境已经固定为torch2.7.1 torch_npu2.7.1.post4因此采用源码方式安装 vLLM并跳过依赖解析。四、安装 vLLM 源码假设源码位于/mnt/workspace/vllm-src安装前设置昇腾目标为空设备避免编译 CUDAcd/mnt/workspace/vllm-srcVLLM_TARGET_DEVICEempty\python3-mpipinstall-e.\--no-build-isolation\--no-deps第一次可能报错ModuleNotFoundError: No module named setuptools_scm如果容器可以访问镜像源可以安装python3-mpipinstall--usersetuptools_scm如果网络不可用则需要在外部机器下载对应 wheel再上传到容器离线安装。安装成功后应看到Successfully built vllm Successfully installed vllm-0.11.0empty五、安装 vLLM-Ascend假设源码位于/mnt/workspace/vllm-ascend-src由于容器缺少部分自定义编译依赖使用以下方式安装cd/mnt/workspace/vllm-ascend-srcCOMPILE_CUSTOM_KERNELS0\python3-mpipinstall-e.\--no-build-isolation\--no-deps\--config-settingseditable_modecompat曾经遇到的错误static library kineto_LIBRARY-NOTFOUND not found ninja: build stopped原因是环境中缺少 Kineto 相关库且没有安装 Ninja。对于当前推理部署可以先关闭自定义 Kernel 编译COMPILE_CUSTOM_KERNELS0成功后应看到Successfully built vllm_ascend Successfully installed vllm_ascend-0.11.0六、补齐 Python 依赖由于使用了--no-deps部分 Python 依赖需要手动安装。常见缺失模块和解决方法python3-mpipinstall--userprometheus-client python3-mpipinstall--useruvloop python3-mpipinstall--userstarlette python3-mpipinstall--useryarl python3-mpipinstall--userpkg_resourcespkg_resources通常由 setuptools 提供python3-mpipinstall--user-Usetuptools推荐一次性安装python3-mpipinstall--user\modelscope\qwen-vl-utils\pillow\prometheus-client\uvloop\starlette\watchfiles\xgrammar\aiohttp\yarl七、解决 Transformers 版本冲突曾遇到transformers requires tokenizers0.22.0,0.23.0 but found tokenizers0.23.1调整为python3-mpipinstall--user--no-deps --force-reinstall\transformers4.57.1\tokenizers0.22.2\huggingface-hub0.36.0注意华为镜像可能没有tokenizers0.23.0但有0.22.2因此使用 0.22.2 即可。检查版本python3 -PY import transformers import tokenizers import huggingface_hub print(transformers:, transformers.__version__) print(tokenizers:, tokenizers.__version__) print(huggingface-hub:, huggingface_hub.__version__) PY八、解决 libatb.so 缺失问题启动时曾遇到OSError: libatb.so: cannot open shared object file以及Please check that the nnal package is installed. Please run source set_env.sh in the NNAL installation path.最初执行find/usr/local/Ascend-namelibatb.so-typef没有找到文件以为容器没有 NNAL。后来全盘查找发现 NNAL 实际安装在/opt/home/developer/Ascend/nnal/atb/set_env.sh /opt/home/developer/Ascend/nnal/atb/9.0.0/atb/cxx_abi_1/lib/libatb.so /opt/home/developer/Ascend/nnal/atb/9.0.0/atb/cxx_abi_0/lib/libatb.so查找命令find/-namelibatb.so-typef2/dev/nullfind/-path*nnal*-nameset_env.sh2/dev/null启动前必须加载 NNALsource/opt/home/developer/Ascend/nnal/atb/set_env.shsource/opt/home/developer/Ascend/ascend-toolkit/set_env.sh2/dev/null||true测试动态库python3 -PY import ctypes ctypes.CDLL(libatb.so) print(libatb.so 加载成功) PY如果仍然找不到exportLD_LIBRARY_PATH/opt/home/developer/Ascend/nnal/atb/9.0.0/atb/cxx_abi_0/lib:$LD_LIBRARY_PATH检查依赖ldd /opt/home/developer/Ascend/nnal/atb/9.0.0/atb/cxx_abi_0/lib/libatb.so\|grepnot found||echolibatb依赖正常九、创建 Qwen3-VL 启动脚本创建vim/mnt/workspace/start_qwen3vl.sh内容如下#!/usr/bin/env bashset-esource/opt/home/developer/Ascend/nnal/atb/set_env.shsource/opt/home/developer/Ascend/ascend-toolkit/set_env.sh2/dev/null||trueexportASCEND_RT_VISIBLE_DEVICES0,1exportHCCL_OP_EXPANSION_MODEAIVexportPYTORCH_NPU_ALLOC_CONFexpandable_segments:TrueexportVLLM_ASCEND_ENABLE_NZ0exportCOMPILE_CUSTOM_KERNELS0exportOMP_PROC_BINDfalseexportOMP_NUM_THREADS1exportTASK_QUEUE_ENABLE1exportPATH/home/developer/.local/bin:$PATHcd/mnt/workspace/vllm-src python3-mvllm.entrypoints.openai.api_server\--model/mnt/workspace/models/Qwen3-VL-32B-Instruct\--host0.0.0.0\--port8000\--served-model-name qwen3-vl-32b\--tensor-parallel-size2\--dtypebfloat16\--trust-remote-code\--max-model-len4096\--max-num-seqs1\--max-num-batched-tokens2048\--gpu-memory-utilization0.90\--no-enable-prefix-caching\--mm-processor-cache-gb0\--api-keysujiapikey赋予执行权限chmodx /mnt/workspace/start_qwen3vl.sh启动/mnt/workspace/start_qwen3vl.sh看到以下日志表示服务启动成功Application startup complete.十、启动日志中的警告以下警告不一定影响推理Model architecture Qwen3NextForCausalLM is already registered这是模型架构重复注册提示。Failed to import vllm_ascend_C Sleep mode will be disabled这是因为之前关闭了自定义 Kernel 编译COMPILE_CUSTOM_KERNELS0会导致 Sleep mode 不可用但通常不影响基础推理。十一、测试 OpenAI 接口1. 查看模型列表curlhttp://127.0.0.1:8000/v1/models\-HAuthorization: Bearer sujiapikey2. 测试文本对话curlhttp://127.0.0.1:8000/v1/chat/completions\-HContent-Type: application/json\-HAuthorization: Bearer sujiapikey\-d{ model: qwen3-vl-32b, messages: [ { role: user, content: 你好请用一句话介绍你自己。 } ], max_tokens: 100 }成功时会返回{object:chat.completion,model:qwen3-vl-32b,choices:[{message:{role:assistant,content:你好我是一个多模态大语言模型。},finish_reason:stop}]}之前出现的JSON decode error是由于命令粘贴或 JSON 格式错误并非模型故障。十二、查看 NPU 使用情况另开终端watch-n1npu-smi info推理时重点观察HBM-Usage AICore(%) Process memory如果两张 NPU 都有显存占用并且推理时 AICore 利用率变化说明张量并行正常运行。十三、通过 FRP 暴露公网接口网络拓扑互联网客户端 ↓ 公网虚拟机 frps ↓ NPU容器 frpc ↓ 127.0.0.1:8000公网虚拟机 frps 配置/etc/frp/frps.tomlbindPort 7000 auth.method token auth.token 请修改为复杂随机字符串启动frps-c/etc/frp/frps.toml开放端口ufw allow7000/tcp ufw allow18000/tcpNPU 容器 frpc 配置/mnt/workspace/frpc.tomlserverAddr 公网虚拟机IP serverPort 7000 auth.method token auth.token 请使用与frps相同的随机字符串 [[proxies]] name qwen3-vl-api type tcp localIP 127.0.0.1 localPort 8000 remotePort 18000启动frpc-c/mnt/workspace/frpc.toml公网测试curlhttp://公网虚拟机IP:18000/v1/models\-HAuthorization: Bearer sujiapikey十四、安全建议不要直接使用sujiapikey建议生成随机 Keyopenssl rand-hex32然后修改启动脚本--api-key生成的随机字符串另外建议FRP 使用 token 认证只开放必要端口不要暴露 FRP 的管理端口公网 API 最好通过 HTTPS对接口增加访问频率限制不要把模型服务直接裸奔在公网长时间运行建议使用 systemd、tmux 或 supervisor。十五、问题总结问题原因解决方法vLLM 与 vLLM-Ascend 依赖冲突两者要求不同 torch 版本源码安装并使用--no-deps缺少setuptools_scm构建依赖未安装安装 setuptools_scm 或离线上传kineto_LIBRARY-NOTFOUND缺少 Kineto 库使用COMPILE_CUSTOM_KERNELS0缺少prometheus_clientvLLM API 服务依赖手动安装 prometheus-client缺少uvloopAPI Server 依赖安装 uvloop缺少starletteFastAPI 依赖未完整安装安装 starlettetransformers 与 tokenizers 冲突版本不匹配使用 transformers 4.57.1、tokenizers 0.22.2huggingface-hub 版本冲突版本过新降级到 0.36.0libatb.so找不到没有加载 NNAL 环境source NNAL 的 set_env.shWorker 初始化失败ATB 动态库无法加载检查LD_LIBRARY_PATH和lddJSON decode errorcurl JSON 格式错误检查引号、逗号和字段格式API 启动后退出引擎 Worker 初始化失败优先查看最早出现的 Worker 根因十六、最终验证标准以下条件全部满足说明部署成功NPU可用: True NPU数量: 2 vllm: 0.11.0 vllm_ascend: 0.11.0 libatb.so 加载成功 Application startup complete. / v1/models 可以返回模型 / v1/chat/completions 可以正常回答 npu-smi 可以看到两张 NPU 使用情况至此Qwen3-VL-32B-Instruct 已经在昇腾双 NPU 环境中成功部署并通过兼容 OpenAI 的 API 对外提供服务。