Qwen-VL-Dense(Qwen3-VL-8B/32B)¶

1 简介¶

阿里云的 Qwen-VL（视觉-语言）系列是一组强大的大型视觉-语言模型（LVLM），旨在实现全面的多模态理解。它们接受图像、文本和边界框作为输入，并输出文本和检测框，支持图像检测、多模态对话和多图像推理等高级功能。

本文档将展示模型的主要验证步骤，包括支持的功能、功能配置、环境准备、NPU 部署、精度和性能评估。

本教程使用 vLLM-Ascend v0.11.0rc3-a3 版本进行演示，以 Qwen3-VL-8B-Instruct 模型为例，展示单 NPU 和多 NPU 部署。

Note

对于 Atlas 推理产品，Qwen3-VL Dense 需要 vLLM-Ascend v0.18.0 或更高版本（对于 950DT 产品，该模型从 vllm-ascend:v0.23.0rc1 开始支持）。请勿在此硬件上使用上述演示版本。

2 支持的功能¶

请参考支持功能列表以获取模型的支持功能矩阵。

请参考功能指南以获取功能配置。

3 前提条件¶

3.1 模型权重¶

权重版本	硬件要求	下载链接
`Qwen3-VL-8B-Instruct`	Atlas 800I A2（64GB × 8）、Atlas 800 A3（64GB × 16）或 Atlas 300I DUO 上的 1 卡	ModelScope
`Qwen3-VL-8B-Instruct-w8a8`（量化版本）	950DT 产品（96GB × 8）节点上的 1 卡	ModelScope
`Qwen3-VL-32B-Instruct`	Atlas 800I A2（64GB × 8）、Atlas 800 A3（64GB × 16）或 Atlas 推理产品上的 2 卡	ModelScope
`Qwen3-VL-32B-Instruct-w8a8`（量化版本）	950DT 产品（96GB × 8）节点上的 1 卡	ModelScope

建议将模型权重下载到多节点共享目录，例如 /root/.cache/。

路径说明：将模型权重下载到您选择的目录并记录该路径。确保后续部署命令中的模型路径与该目录一致。

4 安装¶

4.1 Docker 镜像安装¶

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

950DT ProductsA2 / A3 seriesAtlas 300I DUO

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

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

docker run --rm \
--name $NAME \
--net=host \
--shm-size=1g \
--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/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/bin/urma_admin:/usr/bin/urma_admin \
-v /lib/route.conf:/lib/route.conf \
-v /usr/lib64:/usr/lib64 \
-itd $IMAGE bash

# Update the vllm-ascend image
# A2: quay.io/ascend/vllm-ascend:v0.23.0
# A3: quay.io/ascend/vllm-ascend:v0.23.0-a3
export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0

docker run --rm \
--name vllm-ascend \
--shm-size=1g \
--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/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 \
-p 8000:8000 \
-it $IMAGE bash

# Use the vllm-ascend image
export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-310p

docker run --rm \
--name vllm-ascend \
--shm-size=10g \
--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/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 \
-p 8000:8000 \
-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 .

Note

Atlas 300I DUO 不支持 triton 或 triton-ascend。源代码安装可能会自动引入它们；运行前请手动卸载：

pip uninstall -y triton-ascend triton

安装验证：

pip show vllm vllm-ascend

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

Note

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

更多详细信息，请参阅安装指南。

5 在线服务部署¶

5.1 单节点在线部署¶

运行 Docker 容器以在单 NPU 上启动 vLLM 服务器：

950DT 产品A2 / A3 系列Atlas 300I DUO

export HCCL_OP_EXPANSION_MODE="AIV"
export ASCEND_RT_VISIBLE_DEVICES=$1
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

# Ensure the model path matches the directory recorded during download
vllm serve Qwen/Qwen3-VL-8B-Instruct \
  --host 0.0.0.0 \
  --port $2 \
  --quantization ascend \
  --served-model-name qwen3vl \
  --no-enable-prefix-caching \
  --data-parallel-size $3 \
  --tensor-parallel-size $4 \
  --trust-remote-code \
  --max-num-seqs 128 \
  --max-model-len 32768 \
  --max-num-batched-tokens 16384 \
  --gpu-memory-utilization 0.91 \
  --async-scheduling \
  --compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY", "cudagraph_capture_sizes": [1,2,4,8,16,32]}' \
  --mm-processor-cache-gb 0

export HCCL_OP_EXPANSION_MODE="AIV"
export ASCEND_RT_VISIBLE_DEVICES=$1
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

# Ensure the model path matches the directory recorded during download
vllm serve Qwen/Qwen3-VL-8B-Instruct \
--host 0.0.0.0 \
--port $2 \
--dtype bfloat16 \
--served-model-name qwen3vl \
--no-enable-prefix-caching \
--data-parallel-size $3 \
--tensor-parallel-size $4 \
--trust-remote-code \
--max-num-seqs 128 \
--max-model-len 32768 \
--max-num-batched-tokens 16384 \
--gpu-memory-utilization 0.91 \
--async-scheduling \
--compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY", "cudagraph_capture_sizes": [1,2,4,8,16,32]}' \
--mm-processor-cache-gb 0

export HCCL_OP_EXPANSION_MODE="AIV"
export ASCEND_RT_VISIBLE_DEVICES=$1
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

# Ensure the model path matches the directory recorded during download
vllm serve Qwen/Qwen3-VL-8B-Instruct \
--dtype float16 \
--max_model_len 16384 \
--host 0.0.0.0 \
--port $2 \
--dtype bfloat16 \
--served-model-name qwen3vl \
--no-enable-prefix-caching \
--data-parallel-size $3 \
--tensor-parallel-size $4 \
--trust-remote-code \
--max-num-seqs 128 \
--max-model-len 32768 \
--max-num-batched-tokens 16384 \
--gpu-memory-utilization 0.91 \
--async-scheduling \
--compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY", "cudagraph_capture_sizes": [1,2,4,8,16,32]}' \
--additional-config '{"ascend_compilation_config": {"enable_npugraph_ex":false}}' \
--mm-processor-cache-gb 0

Note

在 Atlas 300I DUO 上：

仅支持 float16 数据类型。
图编译（--compilation-config）要求 CANN 版本 >= 9.0.0。如果您的 CANN 版本较低，请将 --compilation-config 替换为 --enforce-eager。
由于 Atlas 300I DUO 不支持 enable_npugraph_ex，因此需要使用带有 "ascend_compilation_config": {"enable_npugraph_ex": false} 的 --additional-config。

关键参数说明：

添加 --max_model_len 选项，以避免 Qwen3-VL-8B-Instruct 模型的最大序列长度（256000）超过 KV 缓存可存储的最大 token 数时发生 ValueError。该值会因不同 NPU 系列而异，具体取决于片上内存大小。请根据适合您的 NPU 系列的值进行修改。

如果服务成功启动，您将看到以下信息：

INFO:     Started server process [2736]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

6 功能验证¶

服务器启动后，您可以使用输入 prompt 查询模型：

curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
    "model": "Qwen/Qwen3-VL-8B-Instruct",
    "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?"}
    ]}
    ]
    }'

预期结果：

服务返回 HTTP 200 OK。

{"id":"chatcmpl-d3270d4a16cb4b98936f71ee3016451f","object":"chat.completion","created":1764924127,"model":"Qwen/Qwen3-VL-8B-Instruct","choices":[{"index":0,"message":{"role":"assistant","content":"The text in the illustration is: **TONGYI Qwen**","refusal":null,"annotations":null,"audio":null,"function_call":null,"tool_calls":[],"reasoning_content":null},"logprobs":null,"finish_reason":"stop","stop_reason":null,"token_ids":null}],"service_tier":null,"system_fingerprint":null,"usage":{"prompt_tokens":107,"total_tokens":123,"completion_tokens":16,"prompt_tokens_details":null},"prompt_logprobs":null,"prompt_token_ids":null,"kv_transfer_params":null}

7 精度评估¶

某些模型的精度已纳入我们的 CI 监控范围，包括：

Qwen3-VL-8B-Instruct

A2 / A3 seriesAtlas 300I DUO

使用 Language Model Evaluation Harness

例如，以 mmmu_val 数据集作为测试数据集，在离线模式下对 Qwen3-VL-8B-Instruct 运行精度评估。

有关 lm_eval 安装的更多详情，请参阅使用 lm_eval。
```
pip install lm_eval
```

运行 lm_eval 执行精度评估。

lm_eval \
    --model vllm-vlm \
    --model_args pretrained=Qwen/Qwen3-VL-8B-Instruct,max_model_len=8192,gpu_memory_utilization=0.7 \
    --tasks mmmu_val \
    --batch_size 32 \
    --apply_chat_template \
    --trust_remote_code \
    --output_path ./results

执行完成后，即可获取结果。以下为 Qwen3-VL-8B-Instruct 在 vllm-ascend:0.11.0rc3 上的结果，仅供参考。

任务	值	标准误
mmmu_val	0.5389	0.0159

使用 AISBench

以 text_vqa 数据集为例，对 Qwen3-VL-8B-Instruct 运行精度评估。

安装、数据集下载及配置详情，请参阅使用 AISBench。

运行 ais_bench 执行精度评估。

ais_bench --models vllm_api_general_chat --datasets textvqa_gen_base64 --mode all --debug

执行完成后，即可获取结果。以下为 Qwen3-VL-8B-Instruct 在 vllm-ascend:0.23.0rc1 上的结果，仅供参考。

数据集	指标	模式	vllm-api-general-chat
text_vqa	accuracy	gen	80.57

8 性能评估¶

8.1 使用 vLLM Benchmark¶

更多详情请参阅 vLLM Benchmark。

共有三个 vllm bench 子命令：

latency：对单个请求批次的延迟进行基准测试。
serve：对在线服务吞吐量进行基准测试。
throughput：对离线推理吞吐量进行基准测试。

性能评估必须在在线模式下进行。以 serve 为例，运行以下代码。

vllm bench serve --model Qwen/Qwen3-VL-8B-Instruct  --dataset-name random --random-input 200 --num-prompts 200 --request-rate 1 --save-result --result-dir ./

几分钟后，即可获取性能评估结果。

9 性能调优¶

9.1 推荐配置¶

注意：以下配置已在特定测试环境中验证，仅供参考。最佳配置取决于最大输入/输出长度、前缀缓存命中率、精度要求及部署机器配比等因素。建议根据实际条件参考 9.2 节进行调优。

表 1：场景概览¶

场景	部署模式	*NPU 总数	权重版本	关键考量
高吞吐（16k 上下文）	单节点混合	1（A3）	Qwen3-VL-8B-Instruct	高分辨率文本输入时使用 tp2
长上下文（128k，无前缀缓存）	单节点混合	1（A3）	Qwen3-VL-8B-Instruct	高分辨率文本输入时使用 tp2
长上下文（128k，有前缀缓存）	单节点混合	1（A3）	Qwen3-VL-8B-Instruct	高分辨率文本输入时使用 tp2
多模态（1080p）	单节点混合	1（A3）	Qwen3-VL-8B-Instruct	高分辨率视觉输入时使用 tp2

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

表 2：详细节点配置¶

场景	配置	NPU	TP	DP	最大模型长度	MTP 推测数量	权重版本
高吞吐/低延迟（16k）	服务器/单机	1	1	1	~16k	3	Qwen3-VL-8B-Instruct
长上下文（128k，无缓存）	服务器/单机	1	1	1	128k	3	Qwen3-VL-8B-Instruct
长上下文（128k，有缓存）	服务器/单机	1	1	1	128k	3	Qwen3-VL-8B-Instruct
多模态（1080p）	服务器/单机	1	1	1	~16k	3	Qwen3-VL-8B-Instruct

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

注意： max-model-len 和 max-num-seqs 需要根据实际使用场景进行设置。其他设置请参阅部署章节。

9.2 调优指南¶

9.2.1 通用调优参考¶

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

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

10 常见问题¶

有关常见环境、安装及通用参数问题，请参阅公共 FAQ。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 vl/vllm-ascend