Qwen3-VL-30B-A3B-Instruct¶

1 引言¶

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

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

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）节点。模型权重。

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

4 安装¶

4.1 Docker 镜像安装¶

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

A3 系列A2 系列

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

export IMAGE=quay.io/ascend/vllm-ascend:v0.22.1rc1-a3
docker run --rm \
    --name vllm-ascend \
    --shm-size=512g \
    --net=host \
    --privileged=true \
    --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 \
    -v /root/.cache:/root/.cache \
    -it $IMAGE bash

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

export IMAGE=quay.io/ascend/vllm-ascend:v0.22.1rc1
docker run --rm \
    --name vllm-ascend \
    --shm-size=512g \
    --net=host \
    --privileged=true \
    --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 \
    -v /root/.cache:/root/.cache \
    -it $IMAGE bash

启动容器后，运行以下命令验证安装：

docker ps | grep vllm-ascend

预期结果：容器状态显示为 Up。您还可以在容器内验证 vllm-ascend 版本：

pip show vllm-ascend

预期结果：显示版本信息，与拉取的镜像版本一致。

4.2 源码安装¶

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

克隆并安装 vLLM：

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

克隆并安装 vLLM-Ascend 仓库：

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

安装验证：

pip show vllm vllm-ascend

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

Note

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

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

5 在线服务部署¶

5.1 单节点在线部署¶

单节点部署将 Prefill 和 Decode 运行在同一个节点上。以下示例适用于在 1 个 Atlas 800 A2（64G x 8）节点或 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]}'

关键参数说明：

--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"}' 启用完整解码 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¶

详情请参考使用 AISBench。
执行后，即可获取结果。

dataset	version	metric	mode	result
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.1 推荐配置¶

注意：以下配置在特定测试环境中验证，仅供参考。最佳配置取决于硬件类型、图像分辨率、视频长度、最大输入/输出长度、请求并发度、前缀缓存命中率以及预填充/解码比例。请根据实际工作负载调整第9.2节中的参数。

表1：场景概览¶

场景	部署模式	*NPU总数	权重版本	关键考量
纯图像服务	单节点在线服务	2个或更多NPU	BF16	禁用视频，调整上下文长度，并为视觉令牌保留足够的KV缓存。
视频服务	单节点在线服务	2个或更多NPU	BF16	使用本地媒体路径，降低并发度，若发生OOM则减少视频长度或帧采样。
功能图验证	单节点PP	2个NPU	BF16	使用较短的上下文和显式捕获大小，以验证完整解码ACLGraph行为。

*NPU总数表示所有节点使用的NPU总数。1个节点 = 1台Atlas 800 A3服务器（64G × 16 NPU）。

表2：详细节点配置¶

场景	节点角色	NPU数	TP	PP	最大序列数	最大模型长度	最大批处理令牌数	前缀缓存	主要优化
Image-only serving	Single node	2 or more	2	1	16	128000	4096	Workload dependent	FullGraph, EP, video disabled
Video serving	Single node	2 or more	2	1	8	128000	4096	Workload dependent	FullGraph, EP, local media path
Graph validation	Single node	2	1	2	Tune by test	4096	1024	Off	FullGraph capture sizes

完整的启动命令和参数说明，请参考第5章中的部署示例。

9.2 调优指南¶

9.2.1 通用调优参考¶

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

详细功能描述请参考功能指南。

9.2.2 推荐调优顺序¶

从纯图像服务开始。仅在图像路径稳定后，再添加视频。
使用--max-model-len选择最大上下文长度。多模态请求会同时消耗文本令牌和视觉令牌的KV缓存，因此如果发生OOM，请降低图像分辨率、视频长度、请求并发度或上下文长度。
调整多模态限制。使用--limit-mm-per-prompt.image和--limit-mm-per-prompt.video来匹配您的请求形状。
调整--max-num-batched-tokens。较大的值通常能提高预填充吞吐量，但会增加激活内存。视频密集型工作负载通常需要保守的值。
根据服务并发度调整--max-num-seqs。视频请求比图像请求更消耗内存，因此请从较小的值开始。
调整--gpu-memory-utilization。增加该值以提供更多KV缓存，但需为运行时内存波动和媒体预处理预留空间。
调整ACLGraph捕获。解码推荐使用FULL_DECODE_ONLY。如果手动设置cudagraph_capture_sizes，请包含常见的解码批次大小。

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 常见问题¶

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

Q1：为什么服务在启动时报告OOM？¶

现象： 服务在性能分析运行期间失败，或在接受请求之前退出。

原因： 长上下文、高图像分辨率、视频输入、较大的 --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。