从 0 到 1：华为昇腾部署 Qwen3-30B-A3B 大模型推理服务

一、环境说明

项目	要求
硬件	Atlas 800I A2 / 910B4（单卡 64GB NPU 内存）
操作系统	Ubuntu 22.04 / openEuler（ARM64 架构）
宿主机	已安装 Ascend Driver（版本需与容器内 CANN 兼容）
容器	Docker + vLLM-Ascend 官方预构建镜像
模型	Qwen3-30B-A3B（BF16）

前置检查命令：

bash 复制代码

# 确认 NPU 驱动正常，能看到 davinci0~7
npu-smi info

# 确认 Docker 已安装
docker --version

# 确认当前用户有权限访问 NPU 设备
ls -la /dev/davinci*

⚠️ 官方文档明确：Atlas A2（64GB 单卡）运行 Qwen3-30B-A3B，tensor-parallel-size 至少为 2 ；如果是 32GB 显存版本则至少 4。910B4 为 64GB，推荐 TP=2 或 TP=4，配合专家并行效果最佳。

二、获取 vLLM-Ascend 推理镜像

千万不要用 NVIDIA 的 vllm/vllm-openai 镜像 ，那是给 CUDA 用的。昇腾要用社区官方维护的 vllm-ascend 插件镜像。

镜像仓库地址：https://quay.io/repository/ascend/vllm-ascend

标签命名规则：

v0.23.0rc1 → A2（910B）Ubuntu
v0.23.0rc1-openeuler → A2（910B）openEuler
v0.23.0rc1-a3 → A3（Atlas 800I A3）Ubuntu

bash 复制代码

# 以 910B + Ubuntu 为例，请替换为最新稳定 tag
export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0rc1
docker pull $IMAGE

# 查看已拉取的镜像
docker images | grep vllm-ascend

💡 内网机器可先在外网 docker pull 然后 docker save 导出 tar 包迁移。

三、下载 Qwen3-30B-A3B 模型权重

方式 1：ModelScope（国内推荐，速度快）

bash 复制代码

pip install modelscope
modelscope download \
  --model Qwen/Qwen3-30B-A3B \
  --local_dir /data/models/Qwen3-30B-A3B

方式 2：HuggingFace

bash 复制代码

huggingface-cli download Qwen/Qwen3-30B-A3B \
  --local-dir /data/models/Qwen3-30B-A3B

下载完成后确认目录结构：

bash 复制代码

ls /data/models/Qwen3-30B-A3B
# 应包含：config.json、tokenizer*、*.safetensors、model.safetensors.index.json

📌 官方文档注明：Qwen3-30B-A3B 从 vLLM-Ascend v0.8.4rc2 开始支持，本文基于 v0.23.0rc1 验证。

四、启动 Docker 容器

关键说明

Atlas A2 单机有 8 张 NPU （/dev/davinci0 ~ /dev/davinci7）
下面示例用 4 张卡（davinci0~3） 跑 Qwen3-30B-A3B，你可以按实际调整
必须挂载驱动库和 npu-smi 等文件，否则容器内无法识别 NPU

启动容器

bash 复制代码

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0rc1

docker run -itd \
  --name qwen3-30b-a3b \
  --net=host \
  --shm-size=50g \
  --device /dev/davinci0 \
  --device /dev/davinci1 \
  --device /dev/davinci2 \
  --device /dev/davinci3 \
  --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 /data/models:/data/models \
  -p 8000:8000 \
  $IMAGE bash

进入容器：

bash 复制代码

docker exec -it qwen3-30b-a3b bash

🔍 进容器后验证 NPU 可见：
bash 复制代码
ls /dev/davinci*
# 应能看到 davinci0 davinci1 davinci2 davinci3 davinci_manager 等

五、容器内启动 vLLM 服务

1. 设置环境变量

bash 复制代码

# 指定可见的 NPU 卡（与 docker run 挂载的一致）
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3

# 减少内存碎片，避免 OOM（官方推荐）
export PYTORCH_NPU_ALLOC_CONF=max_split_size_mb:256

# 启用 V1 引擎（vLLM Ascend 最新版默认生效）
export VLLM_USE_V1=1

# 可选：使用 ModelScope 加速下载（如果模型路径指向模型 ID 而非本地路径）
# export VLLM_USE_MODELSCOPE=True

2. 启动 Qwen3-30B-A3B 服务

bash 复制代码

vllm serve /data/models/Qwen3-30B-A3B \
  --served-model-name qwen3-30b-a3b \
  --host 0.0.0.0 \
  --port 8000 \
  --tensor-parallel-size 4 \
  --enable-expert-parallel \
  --trust-remote-code \
  --max-model-len 32768 \
  --max-num-seqs 32 \
  --gpu-memory-utilization 0.90

参数解读：

参数	说明
`--tensor-parallel-size 4`	4 卡张量并行，需与 `ASCEND_RT_VISIBLE_DEVICES` 数量一致
`--enable-expert-parallel`	MoE 专家并行，对 Qwen3-30B-A3B 至关重要
`--max-model-len 32768`	最大上下文长度；显存紧张可调小到 8192 或 16384
`--gpu-memory-utilization 0.90`	NPU 显存利用率上限，建议 0.85~0.92 之间
`--trust-remote-code`	Qwen 系列需要加载自定义代码

看到以下日志说明启动成功：

text 复制代码

INFO: Started server process [PID]
INFO: Uvicorn running on http://0.0.0.0:8000
INFO: Application startup complete.

六、验证推理服务

1. 健康检查

bash 复制代码

curl http://localhost:8000/health

2. 查看模型列表

bash 复制代码

curl http://localhost:8000/v1/models

3. 聊天接口测试

bash 复制代码

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-30b-a3b",
    "messages": [
      {"role": "system", "content": "你是一个有帮助的助手"},
      {"role": "user", "content": "用一句话解释 MoE 混合专家模型"}
    ],
    "temperature": 0.6,
    "top_p": 0.95,
    "max_tokens": 512
  }'

4. Python SDK 调用

python 复制代码

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY"  # vLLM 默认不需要 API Key
)

resp = client.chat.completions.create(
    model="qwen3-30b-a3b",
    messages=[
        {"role": "user", "content": "你好，介绍一下你自己"}
    ],
    temperature=0.6,
    max_tokens=512
)
print(resp.choices[0].message.content)

七、显存与卡数规划参考

基于官方文档推荐配置：

模型精度	硬件	推荐卡数
Qwen3-30B-A3B (BF16)	Atlas 800I A2（64GB）	2~4 张
Qwen3-30B-A3B (BF16)	Atlas 800I A3（64GB）	1~2 张
Qwen3-30B-A3B-W8A8	Atlas 800I A2（64GB）	2~4 张

💡 如果显存紧张，可以考虑使用 W8A8 量化版本 （如 Qwen3-30B-A3B-W8A8），或用 msmodelslim 工具对 BF16 模型自行量化。

八、常见坑与排错

❌ 坑 1：用了 NVIDIA 的 vLLM 镜像

text 复制代码

RuntimeError: CUDA not found / No such device

✅ 必须用 quay.io/ascend/vllm-ascend，普通 x86 平台的 vLLM 镜像无法在 ARM 架构的昇腾服务器上运行。

❌ 坑 2：容器里看不到 `/dev/davinci*`

text 复制代码

RuntimeError: NPU device not found

✅ 检查 docker run 时是否挂载了全部必要的 device 和 volume，尤其是：

--device /dev/davinci0~N
--device /dev/davinci_manager
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/

❌ 坑 3：MoE 模型没开专家并行

显存占用异常高
专家负载不均
吞吐量上不去

✅ 务必加上 --enable-expert-parallel。

❌ 坑 4：`max-model-len` 开太大直接 OOM

新手别一上来就开 128K。910B4 建议：

bash 复制代码

# 先跑通
--max-model-len 8192

# 稳定后再逐步提升到 32768
--max-model-len 32768

❌ 坑 5：V1 引擎未启用

vLLM Ascend 新版默认使用 V1 引擎，但老版本升级时需要显式开启：

bash 复制代码

export VLLM_USE_V1=1

九、生产化建议

text 复制代码

✅ 镜像 tag 不要写 latest，锁定具体版本（如 v0.23.0rc1）
✅ 生产环境用 --net=host 减少网络开销，或用 nginx 做反向代理 + API Key 鉴权
✅ 高并发场景开启 --enable-prefix-caching 提升重复请求命中率
✅ 量化版本（W8A8）可显著提升吞吐，适合生产高并发
✅ 日志接入 Prometheus / Grafana 做可观测性
✅ 多节点部署可参考 vLLM-Ascend 官方多节点 Ray 文档

十、docker-compose 一键版（附赠）

把下面内容保存为 docker-compose.yml，读者可以直接 docker compose up -d：

yaml 复制代码

services:
  qwen3-30b-a3b:
    image: quay.io/ascend/vllm-ascend:v0.23.0rc1
    container_name: qwen3-30b-a3b
    network_mode: host
    shm_size: 50g
    devices:
      - /dev/davinci0
      - /dev/davinci1
      - /dev/davinci2
      - /dev/davinci3
      - /dev/davinci_manager
      - /dev/devmm_svm
      - /dev/hisi_hdc
    volumes:
      - /usr/local/dcmi:/usr/local/dcmi
      - /usr/local/bin/npu-smi:/usr/local/bin/npu-smi
      - /usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64
      - /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info
      - /etc/ascend_install.info:/etc/ascend_install.info
      - /data/models:/data/models
    environment:
      - ASCEND_RT_VISIBLE_DEVICES=0,1,2,3
      - PYTORCH_NPU_ALLOC_CONF=max_split_size_mb:256
      - VLLM_USE_V1=1
    command: >
      vllm serve /data/models/Qwen3-30B-A3B
      --served-model-name qwen3-30b-a3b
      --host 0.0.0.0
      --port 8000
      --tensor-parallel-size 4
      --enable-expert-parallel
      --trust-remote-code
      --max-model-len 32768
      --max-num-seqs 32
      --gpu-memory-utilization 0.90

参考文档

vLLM Ascend 官方文档 --- Qwen3-30B-A3B：https://docs.vllm.com.cn/projects/ascend/en/latest/tutorials/models/Qwen3-30B-A3B.html
vLLM Ascend 官方文档 --- Multi-NPU 部署：https://vllm-ascend.readthedocs.io/en/v0.9.1/tutorials/multi_npu_qwen3_moe.html
vLLM Ascend 镜像仓库：https://quay.io/repository/ascend/vllm-ascend
vLLM Ascend 中文文档：https://docs.vllm.ai/projects/ascend/zh-cn/latest/

从 0 到 1：华为昇腾部署 Qwen3-30B-A3B 大模型推理服务

一、环境说明

二、获取 vLLM-Ascend 推理镜像

三、下载 Qwen3-30B-A3B 模型权重

方式 1：ModelScope（国内推荐，速度快）

方式 2：HuggingFace

四、启动 Docker 容器

关键说明

启动容器

五、容器内启动 vLLM 服务

1. 设置环境变量

2. 启动 Qwen3-30B-A3B 服务

六、验证推理服务

1. 健康检查

2. 查看模型列表

3. 聊天接口测试

4. Python SDK 调用

七、显存与卡数规划参考

八、常见坑与排错

❌ 坑 1：用了 NVIDIA 的 vLLM 镜像

❌ 坑 2：容器里看不到 /dev/davinci*

❌ 坑 3：MoE 模型没开专家并行

❌ 坑 4：max-model-len 开太大直接 OOM

❌ 坑 5：V1 引擎未启用

九、生产化建议

十、docker-compose 一键版（附赠）

参考文档

❌ 坑 2：容器里看不到 `/dev/davinci*`

❌ 坑 4：`max-model-len` 开太大直接 OOM