【VLM】Qwen3-VL模型架构和训练流程

note

• Qwen3-VL模型，提供稠密型（2B/4B/8B/32B）和混合专家型（30B-A3B/235B-A22B）两种变体。通过集成高质量的多元模态数据迭代和架构创新（如增强的交错MRoPE、DeepStack视觉-语言对齐和基于文本的时间对齐）
• 其原生支持256K token的交错序列，使其能够在长复杂文档、图像序列和视频上进行稳健的推理，特别适用于现实世界应用中高保真跨模态理解的需求。Qwen3-VL系列的密集和MoE变体确保了在不同延迟和质量要求下的灵活部署，后训练策略包括非思考模式和思考模式，进一步提升了模型的应用范围。
  • 数据过滤方面，去除噪声、低对齐样本，确保数据质量与多样性。
  • 模型架构方面，使用DeepStack 跨层融合，提取视觉编码器多中间层特征，通过轻量残差连接注入 LLM 对应层，强化视觉-语言对齐，保留从低级到高级的丰富视觉信息。
• RoPE旋转位置编码的高低频含义：
  • 低频：转得慢，擅长远距离位置区分（长序列、大图、长视频等）
  • 高频：转得快，位置稍微一变，角度就剧变，擅长近距离精细区分（小区域、局部细节），适合：局部纹理、短时序变化等
• Qwen3-VL创新：
  • 采用SigLIP-2架构并继续动态分辨率训练，小规模模型(2B/4B)使用SigLIP2-Large(300M)，默认使用SigLIP2-SO-400M变体
  • 支持动态输入分辨率，同时使用2D-RoPE（相对位置编码）和可学习的绝对位置嵌入（根据输入尺寸插值），以支持动态分辨率
  • 模态桥接部分从单层MLP，转变为多层独立Merger (DeepStack)
  • 位置编码从标准RoPE/MRoPE，转变为Interleaved MRoPE
• 未来工作将集中于扩展Qwen3-VL的能力，以实现交互式感知、工具增强推理和实时多模态控制

文章目录

• note
• 速读：Qwen3-VL
  • 1、快速介绍
  • 2、模型应用
• 一、研究背景
• 二、Qwen3-VL模型架构
  • 1、增强的交错MRoPE位置编码
  • 2、视觉编码器
  • 3、显式视频时间戳
  • 4、视觉-语言融合：DeepStack集成
  • 5、其他
• 三、模型训练
• 四、模型评测分析
• 五、相关代码解读
  • 1、数据流
  • 2、多模态处理
  • 3、模型变体与扩展
• Reference

速读：Qwen3-VL

链接：https://arxiv.org/pdf/2511.21631

模型家族包含密集型（2B/4B/8B/32B）与混合专家（Mixture-of-Experts, MoE）两种架构（30B-A3B/235B-A22B），以适应不同延迟-质量权衡需求。

1、快速介绍

【多模态大模型进展】Qwen3-VL-4B/8B发布，Qwen3-VL系列小参数模型，共提供4B与8B两种参数规模，每种规模均发布Instruct与Thinking两个版本。https://huggingface.co/collections/Qwen/qwen3-vl-68d2a7c1b8a8afce4ebd2dbe

主要特点为模型原生上下文256K，可扩展至1M，支持小时级视频逐秒索引；新增Interleaved-MRoPE、DeepStack与Text–Timestamp Alignment三项结构改进，分别用于长视频时序建模、多尺度ViT特征融合和事件定位。OCR语种从19种增至32种，低光、模糊、倾斜场景下的鲁棒性提升，可解析古籍与专业术语。视觉Agent可直接操作PC与移动GUI，完成元素识别、工具调用与任务闭环；视觉编码增强功能可根据图像或视频生成Draw.io、HTML、CSS、JS代码；空间感知支持2D Grounding与3D Grounding，可判断物体位置、视角与遮挡关系。此外，NexaAI适配本地推理方案，通过NexaSDK提供GGUF、MLX、NexaML三种格式，支持在Apple Silicon、NVIDIA、Intel、AMD、Qualcomm NPU等，https://nexa.ai/blogs/qwen3vl

2、模型应用

这些 Cookbook 围绕真实场景设计，覆盖高精度文档解析、多语言自然场景 OCR、长视频理解、3D 物体定位、空间关系推理，以及面向移动端和计算机操作的智能体控制等核心能力，全面展现 Qwen3-VL 在复杂视觉语言任务中的强大表现。

🔗 链接: https://github.com/QwenLM/Qwen3-VL/tree/main/cookbooks
💬 体验地址:chat.qwen.ai (在模型列表选择Qwen3-VL系列模型)
🤖 模型链接：https://modelscope.cn/collections/Qwen3-VL-5c7a94c8cb144b
⚙️ 百炼 API :https://help.aliyun.com/zh/model-studio/developer-reference/qwen-vl-api

一、研究背景

• 研究问题：这篇文章要解决的问题是如何构建一个能力更强的视觉语言模型（VL模型），以在多模态基准测试中取得卓越的表现。具体来说，该模型需要支持高达256K token的交错上下文，无缝集成文本、图像和视频。
• 研究难点：该问题的研究难点包括：如何在保持文本理解能力的同时，增强长上下文理解能力；如何有效地进行跨模态推理；如何在多模态学习目标之间平衡文本和模态数据的贡献。
• 相关工作：该问题的研究相关工作包括早期的视觉语言模型（如CLIP和ALIGN）以及最近的多模态模型（如Llama系列和Gemini系列）。这些模型在视觉感知、长上下文理解和多模态推理方面取得了一定的进展，但在处理长视频和复杂任务时仍存在不足。

二、Qwen3-VL模型架构

相关模型列表：
Qwen3-VL 以三种密集型变体（Qwen3-VL-2B/4B/8B/32B）和两种 MoE（Mixture of Experts）变体（Qwen3-VL-30B-A3B、Qwen3-VL-235B-A22B）实现，均基于 Qwen3 Backbone 构建。旗舰模型 Qwen3-VL-235B-A22B 拥有总计 2350 亿参数，每 token 激活 220 亿参数。该模型在广泛的多模态任务中表现优于大多数视觉语言模型（Visual Language Model, VLM），并在多数语言基准测试中超越其纯文本对应模型。

1、增强的交错MRoPE位置编码

1、前置知识回顾：
（1）复数 e i θ e^{i \theta} eiθ 的模长为1，是一个只旋转、不变长短的算子：

z = e i θ = cos ⁡ θ + i sin ⁡ θ z=e^{i \theta}=\cos \theta+i \sin \theta z=eiθ=cosθ+isinθ

模长（长度）公式：

∣ z ∣ = cos ⁡ 2 θ + sin ⁡ 2 θ |z|=\sqrt{\cos ^2 \theta+\sin ^2 \theta} ∣z∣=cos2θ+sin2θ​
因为三角恒等式：

cos ⁡ 2 θ + sin ⁡ 2 θ = 1 \cos ^2 \theta+\sin ^2 \theta=1 cos2θ+sin2θ=1

所以：

∣ e i θ ∣ = 1 = 1 \left|e^{i \theta}\right|=\sqrt{1}=1 ​eiθ​=1​=1

（2）ROPE的本质：RoPE 做的事只有一件事，对每个 token／像素，给一个旋转角度： θ m = m ⋅ θ i \theta_m=m \cdot \theta_i θm​=m⋅θi​

• m = m= m= 位置（第几个像素／第几帧）
• θ i = \theta_i= θi​= 基底频率（决定转得快还是慢）

然后用这个角度做旋转：

( q , m ) → q ⋅ e i m θ i (q, m) \rightarrow q \cdot e^{i m \theta_i} (q,m)→q⋅eimθi​

（3）这里的旋转是在复数平面上的旋转。每两个维度作为一组，当做一个平面向量，然后按位置角度旋转。比如在 (x, y) 点，绕原点转 θ 角，二维平面上的旋转公式：在 ( x , y ) (x, y) (x,y) 点，绕原点转 θ \theta θ 角，新坐标 ( x ′ , y ′ ) \left(x^{\prime}, y^{\prime}\right) (x′,y′) 是：

{ x ′ = x ⋅ cos ⁡ θ − y ⋅ sin ⁡ θ y ′ = x ⋅ sin ⁡ θ + y ⋅ cos ⁡ θ \left\{\begin{array}{l} x^{\prime}=x \cdot \cos \theta-y \cdot \sin \theta \\ y^{\prime}=x \cdot \sin \theta+y \cdot \cos \theta \end{array}\right. {x′=x⋅cosθ−y⋅sinθy′=x⋅sinθ+y⋅cosθ​

（4）RoPE 中第 i i i 维的角度： θ i = 1 10000 2 i d \theta_i=\frac{1}{10000^{\frac{2i}{d}}} θi​=10000d2i​1​，其中 i i i表示维度序号， d d d表示总维度。

（5）RoPE旋转位置编码的高低频含义：

• 低频：θᵢ 很小 → 转得很慢，转得慢，擅长远距离位置区分（长序列、大图、长视频等）
• 高频（维度越低的时候）：θᵢ 很大 → 转得极快，转得快，位置稍微一变，角度就剧变，擅长近距离精细区分（小区域、局部细节）

2、传统的MRoPE和当前交错MRoPE的对比：

• 传统的MRoPE（在qwen2.5 VL中）：
  • 将嵌入维度划分为时间（t）、水平（h）和垂直（w）子空间，导致频谱不平衡。
  • 交错MRoPE通过在低频和高频带中均匀分布t、h和w分量，解决了这一问题，
  • 时间t只有高频，如果距离一长，模型就认不出长时间序列；空间h/w只有低频，局部精细位置区分变差
• 为了增强图像和视频的空间-时间建模能力，Qwen3-VL采用了交错MRoPE，作者采取如下优化方法：
  • 将t、h、w分量在嵌入维度上交错分布
  • 每个时空轴在低高频带均匀表示
  • 显著改善长距离视频位置建模

具体为：

传统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 isNone: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：

Your role is that of a research assistant specializing in visual information. Answer questions about images by looking at them closely and then using research tools. Please follow this structured thinking process and show your work. Start an iterative loop for each question:-**First, look closely:** Begin with a detailed description of the image, paying attention to the user’s question. List what you can tell just by looking,and what you’ll need to look up.-**Next, find information:** Use a tool to research the things you need to find out.-**Then, review the findings:** Carefully analyze what the tool tells you and decide on your next action. Continue this loop until your research is complete. To finish, bring everything together in a clear, synthesized answer that fully responds to the user’s question.#Tools You may call one or more functions to assist with the user query. You are provided with function signatures within <tools></tools> XML tags:<tools>{"type":"function","function":{"name":"image_zoom_in_tool","description":"Zoom in on a specific region of an image by cropping it based on a bounding box (bbox) and an optional object label","arguments":{"type":"object","properties":{"bbox_2d":{"type":"array","items":{"type":"number"},"minItems":4,"maxItems":4,"description":"The bounding box of the region to zoom in, as [x1, y1, x2, y2], where (x1, y1) is the top-left corner and (x2, y2) is the bottom-right corner"},"label":{"type":"string","description":"The name or label of the object in the specified bounding box"},"img_idx":{"type":"number","description":"The index of the zoomed-in image (starting from 0)"}},"required":["bbox_2d","label","img_idx"]}}}</tools> For each function call,return a JSON objectwith function name and arguments within <tool_call></tool_call> XML tags:<tool_call>{"name":<function-name>,"arguments":<args-json-object>}</tool_call><image>{question}

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

Your role is that of a research assistant specializing in visual information. Answer questions about images by looking at them closely and then using research tools. Please follow this structured thinking process and show your work. Start an iterative loop for each question:-**First, look closely:** Begin with a detailed description of the image, paying attention to the user’s question. List what you can tell just by looking,and what you’ll need to look up.-**Next, find information:** Use a tool to research the things you need to find out.-**Then, review the findings:** Carefully analyze what the tool tells you and decide on your next action. Continue this loop until your research is complete. To finish, bring everything together in a clear, synthesized answer that fully responds to the user’s question.#Tools You may call one or more functions to assist with the user query. You are provided with function signatures within <tools></tools> XML tags:<tools>{"type":"function","function":{"name":"image_zoom_in_tool","description":"Zoom in on a specific region of an image by cropping it based on a bounding box (bbox) and an optional object label","arguments":{"type":"object","properties":{"bbox_2d":{"type":"array","items":{"type":"number"},"minItems":4,"maxItems":4,"description":"The bounding box of the region to zoom in, as [x1, y1, x2, y2], where (x1, y1) is the top-left corner and (x2, y2) is the bottom-right corner"},"label":{"type":"string","description":"The name or label of the object in the specified bounding box"},"img_idx":{"type":"number","description":"The index of the zoomed-in image (starting from 0)"}},"required":["bbox_2d","label","img_idx"]}}}</tools> For each function call,return a JSON objectwith function name and arguments within <tool_call></tool_call> XML tags:<tool_call>{"name":<function-name>,"arguments":<args-json-object>}</tool_call><image>{question}{options}

五、相关代码解读

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_omni( 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)

Reference

[1] https://nexa.ai/blogs/qwen3vl
[2] 同时斩获两个开源第一，超火的Qwen3-VL CookBook来了
[3] 万字解析 | 终于等到了Qwen3-VL报告.集智书童
[4] https://arxiv.org/pdf/2511.21631