Qwen3-VL 使用指南¶

Qwen3-VL 是阿里巴巴达摩院推出的 Qwen 系列中最强大的视觉语言模型。

这一代模型在各个方面都进行了全面升级：更强的文本理解与生成能力，更深入的视觉感知与推理能力，更长的上下文长度，增强的空间和视频动态理解能力，以及更强大的智能体交互能力。

提供密集（Dense）和混合专家（MoE）两种架构，可从边缘设备扩展到云端，并提供指令增强（Instruct）和推理增强（Thinking）版本，实现灵活的按需部署。

安装 vLLM¶

uv venv
source .venv/bin/activate

# Install vLLM >=0.11.0
uv pip install -U vllm

# Install Qwen-VL utility library (recommended for offline inference)
uv pip install qwen-vl-utils==0.0.14

运行 Qwen3-VL¶

Qwen3-VL-235B-A22B-Instruct¶

这是 Qwen3-VL 的旗舰 MoE 模型，最少需要 8 块 GPU，每块 GPU 至少需要 80 GB 显存（例如 A100、H100 或 H200）。在某些硬件上，模型可能无法以默认设置成功启动。推荐的按硬件类型进行的部署方法如下：

H100 配备 fp8：使用 FP8 检查点以实现最佳显存效率。
A100 & H100 配备 bfloat16：可以降低 --max-model-len 或将推理限制为仅处理图像。
H200 & B200：开箱即用，支持完整的上下文长度以及并发的图像和视频处理。

有关每种配置的详细启动参数，请参阅下文。我们正在积极进行优化，推荐的启动模型的方式将相应更新。

H100（图像 + 视频推理，FP8）

vllm serve Qwen/Qwen3-VL-235B-A22B-Instruct-FP8 \
  --tensor-parallel-size 8 \
  --mm-encoder-tp-mode data \
  --enable-expert-parallel \
  --async-scheduling

H100（仅图像推理，FP8，TP4）

vllm serve Qwen/Qwen3-VL-235B-A22B-Instruct-FP8 \
  --tensor-parallel-size 4 \
  --limit-mm-per-prompt.video 0 \
  --async-scheduling \
  --gpu-memory-utilization 0.95 \
  --max-num-seqs 128

A100 & H100（仅图像推理，BF16）

vllm serve Qwen/Qwen3-VL-235B-A22B-Instruct \
  --tensor-parallel-size 8 \
  --limit-mm-per-prompt.video 0 \
  --async-scheduling

A100 & H100（图像 + 视频推理，BF16）

vllm serve Qwen/Qwen3-VL-235B-A22B-Instruct \
  --tensor-parallel-size 8 \
  --max-model-len 128000 \
  --async-scheduling

H200 & B200

vllm serve Qwen/Qwen3-VL-235B-A22B-Instruct \
  --tensor-parallel-size 8 \
  --mm-encoder-tp-mode data \
  --async-scheduling

ℹ️ 注意
Qwen3-VL-235B-A22B-Instruct 在纯文本任务上也表现出色，在本指南撰写之时，它在 lmarena.ai 上的文本处理能力方面排名 #1 的开源模型。
您可以通过传递 --limit-mm-per-prompt.video 0 --limit-mm-per-prompt.image 0 来启用纯文本模式，这将跳过视觉编码器和多模态配置文件，从而释放显存以容纳额外的 KV 缓存。

配置技巧¶

如果您的推理服务器仅处理图像输入，强烈建议设置 --limit-mm-per-prompt.video 0，因为启用视频输入会占用更多用于长视频嵌入的显存。或者，您可以跳过多模态输入的显存配置文件，使用 --skip-mm-profiling 并相应地降低 --gpu-memory-utilization（风险自负）。
为避免不必要的 CPU 争用，建议通过设置环境变量 OMP_NUM_THREADS=1 来限制分配给预处理的线程数。这在同一台主机上部署多个 vLLM 实例时特别有用，并且可以显著提高吞吐量。
您可以设置 --max-model-len 来节省显存。默认情况下，模型的上下文长度为 262K，但对于大多数场景，--max-model-len 128000 效果良好。
指定 --async-scheduling 可以通过将调度开销与解码过程重叠来提高整体系统性能。注意：对于 vLLM >= 0.11.1，已改进了与结构化输出和带惩罚的采样兼容性，但仍可能与投机解码（已合并但尚未发布的特性）不兼容。 请查看最新版本以了解持续改进。
指定 --mm-encoder-tp-mode data 以数据并行的方式部署视觉编码器，以获得更好的性能。这是因为视觉编码器非常小，张量并行带来的增益很小，但会产生显著的通信开销。启用此功能会占用额外的显存，可能需要调整 --gpu-memory-utilization。
如果您的工作负载主要涉及**独特**的多模态输入，建议传递 --mm-processor-cache-gb 0 以避免缓存开销。否则，指定 --mm-processor-cache-type shm 可以启用此实验性功能，它利用主机共享内存来缓存预处理的输入图像和/或视频，在较高的 TP 设置下可以获得更好的性能。
vLLM 支持通过 --enable-expert-parallel 实现专家并行（EP），这允许 MoE 模型中的专家部署在不同的 GPU 上，以提高吞吐量。有关更多详细信息，请参阅专家并行部署。
您可以使用 benchmark_moe 为您的硬件执行 MoE Triton 内核调优。
您可以进一步扩展模型的上下文窗口，使用 YaRN，方法是传递 --rope-scaling '{"rope_type":"yarn","factor":3.0,"original_max_position_embeddings": 262144,"mrope_section":[24,20,20],"mrope_interleaved": true}' --max-model-len 1000000

在 VisionArena-Chat 数据集上进行基准测试¶

当 Qwen3-VL-235B-A22B-Instruct 模型的服务器运行起来后，打开另一个终端并运行基准测试客户端。

vllm bench serve \
  --backend openai-chat \
  --endpoint /v1/chat/completions \
  --model Qwen/Qwen3-VL-235B-A22B-Instruct \
  --dataset-name hf \
  --dataset-path lmarena-ai/VisionArena-Chat \
  --num-prompts 1000 \
  --request-rate 20

使用兼容 OpenAI API 的服务器¶

import time
from openai import OpenAI

client = OpenAI(
    api_key="EMPTY",
    base_url="https://:8000/v1",
    timeout=3600
)

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://ofasys-multimodal-wlcb-3-toshanghai.oss-accelerate.aliyuncs.com/wpf272043/keepme/image/receipt.png"
                }
            },
            {
                "type": "text",
                "text": "Read all the text in the image."
            }
        ]
    }
]

start = time.time()
response = client.chat.completions.create(
    model="Qwen/Qwen3-VL-235B-A22B-Instruct",
    messages=messages,
    max_tokens=2048
)
print(f"Response costs: {time.time() - start:.2f}s")
print(f"Generated text: {response.choices[0].message.content}")

有关更多使用示例，请参阅 vLLM 多模态模型用户指南和官方 Qwen3-VL GitHub 仓库！