Qwen3-VL-30B-A3B-Instruct#

1 引言#

Qwen3-VL-30B-A3B-Instruct 是 Qwen3-VL 系列中的稀疏 MoE 视觉语言模型,总参数量约 300 亿,每个 token 激活约 30 亿参数。该模型适用于在昇腾硬件上进行图像理解、视频理解、多模态对话以及长上下文在线服务。

本文档描述了该模型的主要验证步骤,包括支持特性、前提条件、安装、图像与视频在线部署、离线推理、功能验证、精度与性能评估、性能调优以及常见问题解答。

Qwen3-VL-30B-A3B-Instruct 教程是在 vllm-ascend v0.13.0 验证周期中引入的。请使用 v0.13.0 或更高版本来运行此模型。以下示例使用了文档构建系统配置的版本占位符。

2 支持特性#

请参阅支持特性列表以获取该模型的支持特性矩阵。

请参考特性指南获取特性的配置方法。

3 前提条件#

3.1 模型权重#

  • Qwen3-VL-30B-A3B-Instruct(BF16版本):需要1个Atlas 800 A3(64G x 16)节点或1个Atlas 800 A2(64G x 8)节点。模型权重。

  • Qwen3-VL-30B-A3B-Instruct-w8a8-mxfp8(量化版本):需要1个Ascend 950DT(96G x 8)节点。模型权重。

建议将模型权重下载到跨多个节点的共享目录中。

4 安装#

4.1 Docker 镜像安装#

根据您的机器类型选择镜像,并在节点上启动 docker 镜像,请参考使用 docker。

在每个节点上启动docker镜像。

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0.post1-#TODO
export NAME=vllm-ascend

docker run --rm \
  --name $NAME \
  --net=host \
  --shm-size=1g \
  --device /dev/davinci0 \
  --device /dev/davinci1 \
  --device /dev/davinci2 \
  --device /dev/davinci3 \
  --device /dev/davinci4 \
  --device /dev/davinci5 \
  --device /dev/davinci6 \
  --device /dev/davinci7 \
  --device /dev/davinci_manager \
  --device /dev/hisi_hdc \
  --device /dev/ummu \
  --device /dev/uburma \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v /etc/ascend_install.info:/etc/ascend_install.info \
  -v /etc/hccl_rootinfo.json:/etc/hccl_rootinfo.json \
  -v /etc/hixlep/:/etc/hixlep/ \
  -v /root/.cache:/root/.cache \
  -v /usr/local/sbin:/usr/local/sbin \
  -v /usr/local/dcmi:/usr/local/dcmi \
  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
  -v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi \
  -v /usr/lib64:/usr/lib64 \
  -itd $IMAGE bash

在每个节点上启动 docker 镜像。

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0.post1-a3
docker run --rm \
    --name vllm-ascend \
    --shm-size=512g \
    --net=host \
    --device /dev/davinci0 \
    --device /dev/davinci1 \
    --device /dev/davinci2 \
    --device /dev/davinci3 \
    --device /dev/davinci4 \
    --device /dev/davinci5 \
    --device /dev/davinci6 \
    --device /dev/davinci7 \
    --device /dev/davinci8 \
    --device /dev/davinci9 \
    --device /dev/davinci10 \
    --device /dev/davinci11 \
    --device /dev/davinci12 \
    --device /dev/davinci13 \
    --device /dev/davinci14 \
    --device /dev/davinci15 \
    --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 /etc/hccn.conf:/etc/hccn.conf \
    -it $IMAGE bash

在每个节点上启动 docker 镜像。

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0.post1
docker run --rm \
    --name vllm-ascend \
    --shm-size=512g \
    --net=host \
    --device /dev/davinci0 \
    --device /dev/davinci1 \
    --device /dev/davinci2 \
    --device /dev/davinci3 \
    --device /dev/davinci4 \
    --device /dev/davinci5 \
    --device /dev/davinci6 \
    --device /dev/davinci7 \
    --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 /etc/hccn.conf:/etc/hccn.conf \
    -it $IMAGE bash

docker 运行成功后,您可以执行 docker ps 命令来验证正在运行的容器服务。

4.2 源码安装#

如果您不想使用 Docker 镜像,可以从源码构建。首先从源码安装 vLLM:

  1. 克隆并安装 vLLM:

    git clone https://github.com/vllm-project/vllm.git
    cd vllm
    pip install -e .
    
  2. 克隆并安装 vLLM-Ascend 仓库:

    git clone https://github.com/vllm-project/vllm-ascend.git
    cd vllm-ascend
    pip install -e .
    

安装验证:

pip show vllm vllm-ascend

预期结果:显示两个包的版本信息,确认安装成功。

备注

如果部署多节点环境,请在每个节点上设置环境。

更多详情,请参考安装指南。

5 在线服务部署#

5.1 单节点在线部署#

单节点部署在同一节点上运行Prefill和Decode。以下示例适用于仅图像的在线服务。

运行以下脚本在1个Ascend 950DT(96G x 8)上执行在线推理。量化版本(Qwen3-VL-30B-A3B-Instruct-w8a8-mxfp8)可以部署在单个Ascend 950DT节点上。W8A8版本需要--quantization ascend。

#!/bin/sh

# Load model from ModelScope to speed up download.
export VLLM_USE_MODELSCOPE=True

# Reduce memory fragmentation and avoid out-of-memory errors.
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_BUFFSIZE=400
export OMP_PROC_BIND=false
export OMP_NUM_THREADS=100
export TASK_QUEUE_ENABLE=1
export VLLM_ASCEND_ENABLE_FLASHCOMM1=1

vllm serve Eco-Tech/Qwen3-VL-30B-A3B-Instruct-w8a8-mxfp8 \
  --host 0.0.0.0 \
  --port 8000 \
  --distributed-executor-backend mp \
  --data-parallel-size 1 \
  --tensor-parallel-size 8 \
  --enable-expert-parallel \
  --seed 1024 \
  --quantization ascend \
  --served-model-name qwen3-vl-30b \
  --max-num-seqs 32 \
  --max-model-len 32768 \
  --max-num-batched-tokens 8192 \
  --trust-remote-code \
  --no-enable-prefix-caching \
  --mm-processor-cache-gb 0 \
  --limit-mm-per-prompt.image 1 \
  --limit-mm-per-prompt.video 0 \
  --gpu-memory-utilization 0.9 \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}'

运行以下脚本在1个Atlas 800 A3(64G x 16)节点上启动仅图像服务。

#!/bin/sh

# Load model from ModelScope to speed up download.
export VLLM_USE_MODELSCOPE=True

# Reduce memory fragmentation and avoid out-of-memory errors.
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_BUFFSIZE=1024
export OMP_NUM_THREADS=1
export OMP_PROC_BIND=false
export TASK_QUEUE_ENABLE=1
export VLLM_ASCEND_ENABLE_FLASHCOMM1=1
export VLLM_ASCEND_ENABLE_FUSED_MC2=1

vllm serve Qwen/Qwen3-VL-30B-A3B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --served-model-name qwen3-vl-30b \
  --data-parallel-size 1 \
  --tensor-parallel-size 2 \
  --enable-expert-parallel \
  --seed 1024 \
  --max-num-seqs 32 \
  --max-model-len 32768 \
  --max-num-batched-tokens 16384 \
  --gpu-memory-utilization 0.9 \
  --no-enable-prefix-caching \
  --mm-processor-cache-gb 0 \
  --limit-mm-per-prompt.image 1 \
  --limit-mm-per-prompt.video 0 \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY","cudagraph_capture_sizes":[1,2,4,8,16,24,32]}'

上述A3系列脚本同样适用于1个Atlas 800 A2(64G x 8)节点。

关键参数说明:

  • --tensor-parallel-size 2 将模型映射到两个 NPU。仅在验证了硬件上的内存、通信和吞吐量之后,再增加 TP。

  • --enable-expert-parallel 为 MoE 层启用专家并行。不要在同一个 MoE 层中混合使用 MoE 张量并行和专家并行。

  • --max-model-len 是单个请求的最大输入加输出长度。默认情况下,模型可以支持长上下文,但 128000 是许多图像/视频工作负载的实用验证值。

  • --max-num-seqs 是每个 DP 组调度的最大活跃请求数。视频请求消耗更多内存,因此视频示例使用了较小的值。

  • --max-num-batched-tokens 是单个调度步骤中处理的最大 token 数。较大的值可以提高 prefill 效率,但会消耗更多的激活内存。

  • --gpu-memory-utilization 控制 vLLM 可用于计算 KV 缓存容量的 HBM 量。仅在确认服务稳定后增加此值。

  • --limit-mm-per-prompt.video 0 禁用视频输入,为纯图像服务节省内存。

  • --allowed-local-media-path /media 允许请求使用本地文件,例如 file:///media/test.mp4。

  • --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' 启用完整的 decode ACLGraph 重放以减少调度开销。

常见问题提示:如果遇到问题,请参考公共 FAQ 进行故障排除。

服务验证:

curl http://<server_ip>:<port>/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "qwen3-vl-30b",
        "messages": [
            {
                "role": "user",
                "content": "Who are you?"
            }
        ],
        "max_tokens": 256,
        "temperature": 0
    }'

预期结果:

服务返回 HTTP 200 OK,JSON 响应中包含 choices 字段。

6 功能验证#

服务器启动后,发送请求以验证基本的多模态功能。

curl http://<server_ip>:<port>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-vl-30b",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": [
        {"type": "image_url", "image_url": {"url": "https://modelscope.oss-cn-beijing.aliyuncs.com/resource/qwen.png"}},
        {"type": "text", "text": "What is the text in the illustration?"}
      ]}
    ],
    "max_completion_tokens": 100,
    "temperature": 0
  }'

预期结果:HTTP 状态码为 200,JSON 响应中包含带有生成文本的 choices 字段,例如类似于 TONGYI Qwen 的文本。

7 精度评估#

使用 AISBench#

  1. 详情请参考使用 AISBench。

  2. 执行后,您可以获取结果。

数据集

版本

指标

模式

结果

mmmu_val

-

acc,none

gen

0.58

8 性能评估#

8.1 使用AISBench#

详情请参考使用AISBench进行性能评估。对于图像或视频性能,请使用包含真实多模态负载的数据集,而非随机的纯文本提示。

8.2 使用vLLM基准测试#

以Qwen3-VL-30B-A3B-Instruct为例进行性能评估。更多详情请参考vLLM基准测试。

vllm bench包含三个子命令:

  • latency:对单批请求的延迟进行基准测试。

  • serve:对在线服务吞吐量进行基准测试。

  • throughput:对离线推理吞吐量进行基准测试。

以serve为例:

export VLLM_USE_MODELSCOPE=True

vllm bench serve \
  --model Qwen/Qwen3-VL-30B-A3B-Instruct \
  --served-model-name qwen3-vl-30b \
  --dataset-name random \
  --random-input 200 \
  --num-prompts 200 \
  --request-rate 1 \
  --save-result \
  --result-dir ./

几分钟后,即可获得性能评估结果。此随机基准测试适用于服务流水线验证;如需评估图像/视频令牌性能,请使用AISBench或自定义多模态数据集。

9 性能调优#

9.2 调优指南#

9.2.1 通用调优参考#

调优方法请参考公共性能调优文档。

详细功能描述请参考功能矩阵。

9.3 模型特定优化#

优化项

启用方式

收益

备注

多模态提示限制

--limit-mm-per-prompt.image, --limit-mm-per-prompt.video

避免为未使用的媒体类型预留内存。

纯图像服务时禁用视频。

本地媒体访问

--allowed-local-media-path /media

避免在服务过程中进行缓慢的网络视频下载。

在请求中使用 file:///media/...。

全解码ACLGraph

--compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}'

减少算子调度开销,稳定解码性能。

推荐用于解码密集型服务。

专家并行

--enable-expert-parallel

提升MoE服务吞吐量。

不要在同一个MoE层中混合使用MoE张量并行和专家并行。

前缀缓存

--enable-prefix-caching

改善重复前缀的工作负载。

随机提示或唯一媒体可能无法受益。

异步调度

--async-scheduling

可以提升高并发吞吐量。

对于延迟敏感的工作负载,请禁用并进行比较。

流水线并行验证

--pipeline-parallel-size 2

提供另一种双卡验证布局。

对于功能测试,使用较短的上下文和较低的批次令牌数。

10 常见问题#

关于常见环境、安装和通用参数问题,请参考公共常见问题。本节仅涵盖Qwen3-VL-30B-A3B-Instruct的模型特定问题。

Q1:为什么服务在启动时报告OOM?#

现象: 服务在profile运行期间失败,或在接受请求之前退出。

原因: 长上下文、高图像分辨率、视频输入、较大的--max-num-seqs、较大的--max-num-batched-tokens或较高的--gpu-memory-utilization可能导致HBM余量不足。

解决方案: 从纯图像服务开始,设置--limit-mm-per-prompt.video 0,减小--max-model-len,降低--max-num-seqs,降低--max-num-batched-tokens,或降低--gpu-memory-utilization。保持PYTORCH_NPU_ALLOC_CONF=expandable_segments:True。

Q2:为什么在纯图像命令中禁用了视频?#

现象: 即使请求仅包含图像,服务也会保留超出预期的内存。

原因: 允许视频输入可能会为长视觉嵌入和预处理路径保留内存。

解决方案: 对于纯图像服务,使用--limit-mm-per-prompt.video 0。仅在工作负载需要时才启用视频。

Q3:为什么使用本地文件路径的视频请求会失败?#

现象: 请求报告文件不被允许或无法找到。

原因: 服务器只能访问已挂载到容器中且由--allowed-local-media-path允许的本地媒体路径。

解决方案: 将主机媒体目录挂载到/media,使用--allowed-local-media-path /media启动服务器,并使用类似file:///media/test.mp4的请求URL。

Q4:为什么启用前缀缓存没有提升性能?#

现象: 已启用前缀缓存,但吞吐量或延迟没有改善。

原因: 前缀缓存仅在请求共享可重用前缀时才有帮助。唯一的图像、唯一的视频或随机提示可能会增加内存压力,但没有可见的收益。

解决方案: 为重复前缀的工作负载启用前缀缓存。对于随机基准测试或内存受限的视频工作负载,请与禁用前缀缓存的情况进行比较。

Q5:为什么多模态精度评估无法插入图像令牌?#

现象: 评估失败,因为在提示中找不到图像占位符。

原因: Qwen3-VL多模态任务依赖模型聊天模板在多模态处理之前插入图像占位符令牌。

解决方案: 在评估配置中启用聊天模板应用。对于基于lm_eval的多模态任务,将apply_chat_template设置为true。