Qwen3-VL 模型架构与训练流程

具体为：

传统 MRoPE (Qwen2-VL): 维度:[t,t,t,t, h,h,h,h, w,w,w,w](分组排列) └─低频─┘ └─中频─┘ └─高频─┘ 问题：t 只在低频，w 只在高频 → 谱不平衡
Qwen3-VL Interleaved MRoPE: 维度:[t,h,w,t, h,w,t,h, w,t,h,w](交错排列) └── 每个轴均匀分布所有频段 ──┘

2、视觉编码器

作者采用 SigLIP-2 架构作为视觉编码器，并基于官方预训练权重进行初始化，继续以动态输入分辨率进行训练。为有效适应动态分辨率，作者采用 2D-RoPE（Rotary Position Embedding），并根据输入尺寸对绝对位置嵌入进行插值，遵循 CoMP 的方法。具体而言，作者默认使用 SigLIP2-SO-400M 变体，并在小规模 LLM（2B 和 4B）中采用 SigLIP2-Large（300M）。

![视觉编码器架构图]

3、显式视频时间戳

• 在 Qwen2.5-VL 中，采用了一种时间同步的 MRoPE 变体，以赋予模型时间感知能力。然而，作者发现该方法存在两个关键局限性：
  • 通过将时间位置 ID 直接绑定到绝对时间，该方法在处理长视频时会产生过大且 Sparse 的时间位置 ID，从而削弱模型对长时序上下文的理解能力。
  • 在该方案下实现有效学习需要在多种帧率（fps）下进行广泛且均匀的采样，显著增加了训练数据构建的成本。
• 显式视频时间戳：
  • 为了更有效地表示时间信息，Qwen3-VL 采用了基于文本的时间戳，而不是绝对时间对齐。
  • 每个视频时间片段都带有格式化的文本字符串（例如，<3.0 秒>），并在训练中使用秒和 HMS 格式生成时间戳，以确保模型能够有效学习和解释多样的时间码表示。

4、视觉 - 语言融合：DeepStack 集成

• DeepStack 集成：为了加强视觉 - 语言对齐，Qwen3-VL 引入了 DeepStack 机制。该机制通过将视觉编码器的不同层的视觉标记通过轻量级残差连接路由到相应的 LLM 层，增强了多级融合，而不会引入额外的上下文长度。
• 作者受到 DeepStack 的启发，将视觉 Token（visual tokens）注入到大语言模型（LLM）的多个层级中。与原始的 DeepStack 方法不同，后者将多尺度视觉输入的 Token 进行堆叠，作者将其扩展为从视觉 Transformer（Vision Transformer, ViT）的中间层提取视觉 Token。这种设计能够保留从 Low-Level 到 High-Level 的丰富视觉信息。
• 具体而言，如图 1 所示，作者从视觉编码器的三个不同层级中选取特征。随后，专用的视觉 - 语言融合模块将这些多层级特征投影为视觉 Token（visual tokens），并直接添加到前三个大语言模型（LLM）层的对应隐藏状态中。

动作：

视觉编码器层 1 ──→ Merger ──┐
视觉编码器层 2 ──→ Merger ──┼→ 分别注入 LLM 的对应层
视觉编码器层 3 ──→ Merger ──┘

优势:

• 保留从低级到高级的多层次视觉信息
• 通过残差连接，不增加序列长度
• 增强细粒度视觉理解 (InfoVQA +2.3, DocVQA +1.6)

相关对比：

具体代码做法参考如下：

def _deepstack_process(self, hidden_states: torch.Tensor, visual_pos_masks: torch.Tensor, visual_embeds: torch.Tensor):
    if visual_pos_masks is None:
        return hidden_states + visual_embeds.mean() * 0
    visual_pos_masks = visual_pos_masks.to(hidden_states.device)
    visual_embeds = visual_embeds.to(hidden_states.device, hidden_states.dtype)
    local_this = hidden_states[visual_pos_masks, :].clone() + visual_embeds
    hidden_states[visual_pos_masks, :] = local_this
    return hidden_states

5、其他

作者从每样本损失（per-sample loss）转向平方根归一化的每 token 损失（square-root-normalized per-token loss），该方法在训练过程中能更好地平衡文本与多模态数据的贡献。

三、模型训练

• 数据收集：Qwen3-VL 的训练数据集包括高质量的图像 - 字幕对、交错文本 - 图像序列、知识世界数据、OCR 数据、文档解析数据和长文档理解数据。具体来说，图像 - 字幕对来自网络资源，交错文本 - 图像序列来自中国和其他英语网站，知识世界数据涵盖了超过 12 个语义类别，OCR 数据包括 3000 万个内部收集的样本，文档解析数据包括 300 万个 PDF 文件，长文档理解数据包括合成和实际的长文档数据。
• 预训练阶段：预训练分为四个阶段：初始对齐阶段、多模态预训练阶段、长上下文预训练阶段和超长短上下文适应阶段。每个阶段的训练目标和数据混合比例有所不同，以确保模型逐步建立从基本对齐到长上下文理解的能力。
  • S0 阶段：仅训练 MLP 融合层，实现视觉 - 语言基础对齐
  • S1 阶段：全参数多模态预训练，序列长度 8K
  • S2 阶段：长上下文预训练，序列长度扩展至 32K
  • S3 阶段：超长上下文适应，支持 256K 令牌上下文窗口
• 后训练阶段包括三个阶段：
  • 长链式思维数据的有监督微调、
  • 从更强教师模型的知识蒸馏
  • 强化学习
• 每个阶段的数据和方法都有所不同，以提高模型的指令遵循能力、推理能力和与人类偏好的对齐。

预训练阶段的具体信息：

Stage 0: 视觉 - 语言对齐 (Vision-Language Alignment)
├── 仅训练 MLP merger
├── 视觉编码器和 LLM 冻结
├── 67B tokens, 8K 序列长度
└── 数据：高质量图像 - 标题对、OCR 数据

Stage 1: 多模态预训练 (Multimodal Pre-Training)
├── 全参数训练
├── ~1T tokens, 8K 序列长度
├── 混合 VL 数据 + 纯文本数据
└── 新增：交错图文、视觉定位、STEM、视频

Stage 2: 长上下文预训练 (Long-Context)
├── ~1T tokens, 32K 序列长度
├── 增加纯文本比例 (长文本理解)
└── 大量视频和 agent 数据

Stage 3: 超长上下文适应 (Ultra-Long-Context)
├── 100B tokens, 262K 序列长度
└── 专注：长视频、长文档理解

对应的数据构成：

四、模型评测分析

qwen3-VL-235B-A22B 模型和主流多模态图生文模型的效果对比：

![评测对比图]

对于几个小参数的 qwen3 vl 模型，效果比 a22b 模型差，也是能理解的，毕竟参数量摆在这里：

![小参数模型对比图]

一般视觉问答：在 MMBench-V1.1、RealWorldQA、MMStar 和 SimpleVQA 等基准测试中，Qwen3-VL 系列模型展示了强大的性能。特别是在大模型（如 Qwen3-VL-235B-A22B）中，Qwen3-VL-235B-A22B-Thinking 在 MMStar 上取得了 78.7 分的高分，接近 Gemini-2.5-Pro 的 79.5 分。

多模态推理：在 MMMU、MathVision、MathVision-Wildphoto、MathVista 等 STEM 相关任务和视觉谜题任务中，Qwen3-VL 系列模型表现出色。特别是 Qwen3-VL-235B-A22B-Instruct 在多个基准测试中取得了最佳或次优成绩。

对齐和主观任务：在 MM-MT-Bench、HallusionBench 和 MIA-Bench 等基准测试中，Qwen3-VL 系列模型显著优于其他闭源模型。特别是在 HallusionBench 上，Qwen3-VL-235B-A22B-Thinking 比 Gemini-2.5-Pro 高出 6.3 分。

文本识别和文档理解：在 OCR 解析、文档问答和文档推理等基准测试中，Qwen3-VL 系列模型也表现出色。特别是在 OCR 相关的 VQA 基准测试中，Qwen3-VL-235B-A22B-Instruct 和 Qwen3-VL-235B-A22B-Thinking 在所有任务中都取得了强有力的一致性结果。

2D 和 3D 定位：在 RefCOCO、CountBench 和 ODinW-13 等 2D 和 3D 定位基准测试中，Qwen3-VL 系列模型展示了卓越的性能。特别是 Qwen3-VL-235B-A22B 在 ODinW-13 上取得了 48.6 mAP 的高分，表明其在多目标开放词汇对象定位中的强大能力。

细粒度感知：在 V*、HRBench-4K 和 HRBench-8K 等细粒度感知基准测试中，Qwen3-VL 系列模型相比其前身 Qwen2.5-VL-72B 有显著提升，特别是在集成外部工具后，性能提升显著。

多图像理解：在 BLINK 和 MuirBench 等多图像理解基准测试中，Qwen3-VL 系列模型展示了整体优越性，特别是在 MuirBench 上，Qwen3-VL-235B-A22B-Thinking 取得了 80.1 分的高分，超过了所有其他模型。

具身和空间理解：在 ERQA、VSIBench 和 EmbSpatial 等具身和空间理解基准测试中，Qwen3-VL 系列模型展示了与顶级模型相媲美的能力，特别是在 EmbSpatial 上，Qwen3-VL-235B-A22B 取得了 84.3 分的高分。

视频理解：在 VideoMME、MVBench、VideoMMMU 等视频理解基准测试中，Qwen3-VL 系列模型展示了显著的改进，特别是在集成交错 MRoPE、文本时间戳和大规模时间密集视频字幕后，Qwen3-VL-8B 的性能与显著更大的 Qwen2.5-VL-72B 模型相当。

参考： 1、评测 ToolCall 任务 benchmark 的 prompt：

{
  "role": "system",
  "content": "Your role is that of a research assistant specializing in visual information..."
}

2、评测 HRBench4K benchmark（Visual Grounding 任务，需要选出图中对应的 Bounding Box，即 bbox）的 prompt：

{
  "role": "system",
  "content": "Your role is that of a research assistant specializing in visual information..."
}

五、相关代码解读

1、数据流

问题：Qwen3-VL 处理一张图片时，数据的完整流转路径是怎样的？从原始图像输入到最终 LLM 输出，请描述中间经过哪些主要模块（如 image_processor、visual encoder、merger/projector、language model）及其作用

代码参考：ms-swift/swift/model/models/qwen.py

Qwen3-VL 处理一张图片时，数据经过以下完整流程：

第一步：图像预处理

• 原始图片经过 image_processor 处理，转换为 pixel_values（像素张量）
• 同时生成 image_grid_thw，记录图片被分成多少个 patch（T×H×W）

第二步：视觉编码

• pixel_values 输入到 self.visual（ViT 视觉编码器）
• 输出两部分：
  • pooler_output：最终的视觉 embedding
  • deepstack_features：ViT 各中间层的特征（用于后续多层融合）

第三步：Embedding 替换

• 在 input_ids 中找到 <image> token 的位置
• 用视觉 embedding 替换这些位置，生成混合的 inputs_embeds

第四步：位置编码

• 调用 get_rope_index 计算 3D 旋转位置编码
• 图像/视频 token 使用特殊的 M-RoPE（多模态旋转位置编码）

第五步：语言模型处理

• inputs_embeds 输入 LLM（language_model）
• 同时传入 visual_pos_masks 和 deepstack_visual_embeds
• LLM 在前 N 层通过残差方式持续注入视觉特征（Deepstack 机制）

第六步：输出

• LLM 输出 last_hidden_state，可用于生成文本或其他下游任务

# 1. 图像输入处理：pixel_values → visual encoder → embeds
inputs_embeds, visual_pos_masks, deepstack_visual_embeds = _forward_qwen3_vl_or_qwen3_omni(
    self, processor, input_ids, inputs_embeds, pixel_values, pixel_values_videos,
    image_grid_thw, video_grid_thw
)
# 2. 位置编码：考虑图像/视频的 rope index
position_ids, rope_deltas = self.get_rope_index(
    input_ids, image_grid_thw, video_grid_thw, attention_mask=attention_mask
)
# 3. 语言模型处理：inputs_embeds + deepstack 注入
outputs = self.language_model(
    input_ids=None, position_ids=position_ids, inputs_embeds=inputs_embeds,
    visual_pos_masks=visual_pos_masks,  # 传入视觉位置掩码
    deepstack_visual_embeds=deepstack_visual_embeds,  # 传入多层视觉特征
    **kwargs,
)

2、多模态处理

在 ms-swift 代码中，pixel_values、image_grid_thw、pixel_values_videos、video_grid_thw 这几个变量分别是什么含义？为什么 Qwen3-VL 需要 grid_thw 这样的信息？这与 Qwen3-VL 处理动态分辨率图像/视频的机制有什么关系？

grid_thw 的作用：用于动态分辨率处理，表示图像/视频被分成 T×H×W 个 patch 块。

1、pixel_values 和 pixel_values_videos

• pixel_values：图像的像素张量，形状为 [N, C, H, W]（N 张图，C 通道，H 高，W 宽）
• pixel_values_videos：视频的像素张量，视频被拆成多帧后的像素数据

2、image_grid_thw 和 video_grid_thw

• 这是 Qwen3-VL 动态分辨率机制的核心
• 格式为 [N, 3]，每一行是 (T, H, W)：
  • T：时间维度（图像 T=1，视频 T=帧数）
  • H：高度方向的 patch 数量
  • W：宽度方向的 patch 数量

3、为什么需要 grid_thw？ 传统 ViT 将所有图片 resize 到固定尺寸（如 224×224），会丢失细节或浪费计算。 Qwen3-VL 采用动态分辨率：

1. 根据原图大小，动态决定分成多少个 patch
2. 小图少分，大图多分，保留原始分辨率信息
3. grid_thw 告诉模型每张图/视频有多少个 token，用于：
   • 正确计算视觉 token 数量
   • 生成正确的位置编码
   • 在混合输入时正确分割图像和视频的 embedding

代码中的关键计算：

merge_length = processor.image_processor.merge_size**2  # 如 2²=4
image_tokens = (image_grid_thw.prod(dim=-1)// merge_length).sum()
# 例：grid_thw = [1, 14, 14] → 1×14×14 / 4 = 49 个 token

def _forward_qwen3_vl_or_qwen3_omini(self, processor, input_ids, inputs_embeds, pixel_values,  # 图像像素值 [N, C, H, W]
                                     pixel_values_videos,  # 视频像素值
                                     image_grid_thw,  # 图像网格信息 [N, 3] (T, H, W 分块数)
                                     video_grid_thw):  # 视频网格信息
    # 1. 混合图像和视频
    pixel_values_mixed = torch.concat([pixel_values, pixel_values_videos], dim=0)
    grid_thw = torch.concat([image_grid_thw, video_grid_thw], dim=0)
    # 2. 通过视觉编码器
    visual_res = self.visual(pixel_values_mixed, grid_thw=grid_thw)
    mixed_embeds = visual_res.pooler_output
    deepstack_visual_embeds = visual_res.deepstack_features
    # 3. 根据 token 数量分割图像和视频 embedding
    merge_length = processor.image_processor.merge_size**2
    image_tokens = (image_grid_thw.prod(dim=-1)// merge_length).sum()
    image_embeds = mixed_embeds[:image_tokens]
    video_embeds = mixed_embeds[image_tokens:]
    # 4. 用 masked_scatter 替换到 inputs_embeds
    image_mask = (input_ids == self.config.image_token_id)
    video_mask = (input_ids == self.config.video_token_id)
    inputs_embeds = inputs_embeds.masked_scatter(image_mask, image_embeds)
    inputs_embeds = inputs_embeds.masked_scatter(video_mask, video_embeds)

3、模型变体与扩展

qwen3_vl（基础版）

• 使用标准 Dense Transformer 架构
• 每层所有参数都参与计算
• 适合中小规模模型（2B、8B、32B）

qwen3_vl_moe（MoE 版）

• MoE = Mixture of Experts（专家混合）
• FFN 层被替换为多个'专家'网络
• 每个 token 只激活部分专家（如 8 选 2），节省计算
• 适合超大规模模型（如 72B-A14B、235B-A22B）
• 'A14B' 表示总参数 72B，但每次激活参数约 14B

qwen3_vl_emb（Embedding 版）

• 用于文本/图像检索任务
• 输入一段文本或图片，输出一个向量（embedding）
• 可用于相似度计算、语义搜索
• Template 强制添加空的 assistant 回复，取最后的 hidden state 作为 embedding

qwen3_vl_reranker（Reranker 版）

• 用于检索重排序任务
• 输入：query + document（候选文档）
• 输出：相关性分数
• 在检索系统中用于精排阶段，提升召回结果的排序质量
• Template 将 query 和 document 拼接成特定格式

变体关系图：

Qwen3VLLoader (基类)
│
├── qwen3_vl (Dense)
├── Qwen3VLMoeLoader ──→ qwen3_vl_moe (MoE)
├── Qwen3VLEmbLoader ──→ qwen3_vl_emb (Embedding)
└── Qwen3VLRerankerLoader ──→ qwen3_vl_reranker (Reranker)