Phase 12 - Lesson 09

Família Qwen-VL e Vídeo com FPS Dinâmico

A família Qwen-VL — Qwen-VL (2023), Qwen2-VL (2024), Qwen2.5-VL (2025), Qwen3-VL (2025) — é a linhagem de modelos de linguagem e visão abertos mais influente em 2026. Cada geração fez uma única aposta arquitetural decisiva que o restante do ecossistema aberto copiou em doze meses: resolução dinâmica nativa via M-RoPE, amostragem de FPS dinâmico com alinhamento temporal absoluto, atenção em janela no ViT e formatos estruturados de saída de agentes. Com o Qwen3-VL, a receita se estabilizou: um codificador ViT com RoPE 2D com entradas de proporção de aspecto nativa, um projetor MLP em uma grande base de linguagem Qwen3 e etapas de treinamento que enfatizaram OCR, grounding e comportamento de agente como alvos de primeira classe. Esta lição lê a família cronologicamente para que você entenda por que cada ajuste está onde está.

Tipo: Learn Linguagens: Python (stdlib, codificador M-RoPE + amostrador de FPS dinâmico) Pré-requisitos: Fase 12 · 06 (patch-n'-pack) Tempo: ~120 minutos

Objetivos de Aprendizado

• Calcular as rotações de três eixos do M-RoPE (temporal, altura, largura) e explicar por que todas as três são necessárias.
• Escolher uma estratégia de amostragem de FPS dinâmico para um vídeo e ponderar sobre tokens por segundo versus precisão de detecção de eventos.
• Nomear as quatro atualizações geracionais do Qwen-VL em ordem e o que cada uma viabilizou.
• Estruturar um formato de saída de agente JSON no estilo Qwen2.5-VL e analisar chamadas de ferramentas estruturadas a partir de uma resposta de VLM.

O Problema

O Qwen-VL foi lançado em agosto de 2023 como uma resposta direta ao LLaVA-1.5 e ao BLIP-2. A lacuna que a equipe do Qwen mirava era tripla: resolução, vídeo e saída estruturada.

Resolução: O LLaVA-1.5 rodava em 336x336. Bom para fotos, inútil para uma fatura em chinês ou uma captura de tela densa de planilha. A primeira inovação do Qwen-VL foi 448x448 e saída de caixa delimitadora (bounding-box) com grounding, permitindo que o modelo apontasse para as coisas.

Vídeo: O Video-LLaMA empilhava codificadores por frame e os alimentava no LLM. Funcionava para clipes curtos, mas não para vídeos de vários minutos onde o eixo temporal é o sinal. A equipe do Qwen queria um único codificador que entendesse o tempo.

Saída estruturada: O LLaVA emitia texto livre. Um agente precisa de JSON. O Qwen-VL treinou em formatos de saída JSON explícitos, incluindo coordenadas de caixas delimitadoras como texto.

Cada geração do Qwen-VL estende um desses três eixos.

O Conceito

Qwen-VL (Agosto de 2023)

A primeira geração: OpenCLIP ViT-bigG/14 como codificador (2.5B parâmetros), Q-Former compatível com LLaMA (1 etapa com 256 consultas), base Qwen-7B. Contribuições:

• Resolução de 448x448 (então SOTA para um VLM aberto).
• Grounding: treinado em pares de imagem-texto com saída explícita de tokens de coordenadas. "The cat is at (112, 204), (280, 344)".
• Treinamento multilíngue em chinês + inglês desde o início.

Benchmarks na época: competitivo com o GPT-4V em inglês, dominante em chinês. A supervisão de grounding foi o verdadeiro destaque.

Qwen2-VL (Setembro de 2024) — M-RoPE e resolução nativa

O Qwen2-VL substituiu a pilha de resolução fixa + Q-Former por um codificador ViT com resolução nativamente dinâmica. Principais mudanças:

• Resolução dinâmica nativa. O ViT aceita qualquer HxW divisível por 28 (patch 14 com fusão espacial de 2x). Uma imagem de 1120x672 (40x24 patches fundidos) produz 960 tokens visuais. Sem redimensionamento, sem divisão em blocos (tiling), sem miniatura (thumbnail).
• M-RoPE (RoPE Multimodal). Cada token carrega uma posição 3D (t, h, w) em vez de 1D. Para imagens, t=0; para vídeo, t = frame_index. O RoPE rotaciona os vetores de consulta/chave por uma frequência por eixo. Sem tabela de embeddings posicionais.
• Projetor MLP. Remoção do Q-Former; uso de um MLP de 2 camadas nos tokens de patches fundidos.
• Vídeo com FPS dinâmico. Vídeo amostrado a 1-2 FPS por padrão, mas o modelo aceita contagens de frames arbitrárias.

Resultado: O Qwen2-VL-7B igualou o GPT-4o em vários benchmarks multimodais e o venceu no DocVQA (94.5 vs 88.4). A mudança na arquitetura foi o movimento decisivo.

Qwen2.5-VL (Fevereiro de 2025) — FPS dinâmico + tempo absoluto

A grande mudança do Qwen2.5-VL foi o vídeo. O FPS dinâmico não é apenas "amostrar mais frames quando necessário". O artigo formalizou:

• Tokens de tempo absoluto. Em vez de índices posicionais (frame 0, 1, 2...), use carimbos de data/hora (timestamps) reais. "At 0:04, the cat jumps." O modelo vê tokens <time>0.04</time> intercalados com tokens de frame.
• FPS dinâmico. Amostragem a 1 FPS para filmagens lentas, 4+ FPS para ação. O usuário ou instrutor escolhe; o M-RoPE se adapta.
• Atenção em janela no ViT. A atenção espacial é em janela (local dentro dos blocos) para maior taxa de transferência (throughput); atenção global a cada poucas camadas.
• Formato de saída JSON explícito. Treinado em dados de chamada de ferramentas: "{"tool": "click", "coords": [380, 220]}". Pronto para agentes nativamente.
• Escalonamento do MRoPE-v2. As posições escalam com o tamanho máximo de entrada para que um vídeo de 10 minutos não fique fora da faixa de frequência.

Benchmarks: O Qwen2.5-VL-72B supera o GPT-4o na maioria dos benchmarks de vídeo, iguala o Gemini 2.0 em documentos e define o SOTA de modelo aberto para grounding de GUI (ScreenSpot: 84% de acurácia vs 38% para o GPT-4o).

Qwen3-VL (Novembro de 2025)

O Qwen3-VL é uma atualização incremental que consolida em vez de reinventar: base de LLM maior (Qwen3-72B), dados de treinamento expandidos, OCR aprimorado, raciocínio mais forte através do "thinking mode" do Qwen3. O ViT e o M-RoPE permanecem. O artigo foca em melhorias de dados e treinamento em vez de arquitetura.

A lição da linhagem: em 2025, a arquitetura do Qwen-VL havia se estabilizado. Gerações adicionais escalam computação e dados, não as primitivas.

M-RoPE matematicamente

O RoPE clássico rotaciona uma consulta q de dimensão d pela posição m usando coordenadas pareadas:

q_rot[2i]   = q[2i]   * cos(m * theta_i) - q[2i+1] * sin(m * theta_i)
q_rot[2i+1] = q[2i]   * sin(m * theta_i) + q[2i+1] * cos(m * theta_i)
theta_i     = 10000^(-2i/d)

O M-RoPE divide a dimensão oculta em três bandas. Digamos d = 96. Atribua 32 dimensões para temporal, 32 para altura, 32 para largura. Cada banda rotaciona por sua própria posição de eixo. Um patch em (t=5, h=10, w=20) recebe as rotações R_t(5), R_h(10), R_w(20) aplicadas às suas três bandas.

Tokens de texto usam t = text_index, h = 0, w = 0 (or uma escolha normalizada), mantendo a compatibilidade. Frames de vídeo usam t = frame_time, h = row, w = col. Imagens avulsas usam t = 0.

O benefício: uma única codificação de posição lida com texto, imagem e vídeo sem ramificação de código ou tabelas de posições diferentes.

Lógica de amostragem de FPS dinâmico

Dado um vídeo de duração de T segundos e um orçamento de tokens alvo B:

1. Calcule o FPS máximo que você pode pagar: fps_max = B / (T * tokens_per_frame).
2. Escolha um FPS alvo de {1, 2, 4, 8} que satisfaça fps <= fps_max.
3. Se o movimento for alto (heurística de fluxo óptico ou solicitação explícita do usuário), escolha um FPS mais alto. Se o movimento for baixo, escolha um mais baixo.
4. Faça a amostragem uniformemente no FPS escolhido; insira tokens <time>t</time> entre os frames.

O Qwen2.5-VL treina essa lógica implicitamente; na inferência, o usuário controla por meio do parâmetro fps. Uma sequência de ação de 60 segundos a 4 FPS com 81 tokens por frame = 19440 tokens, gerenciável em um contexto de 32k.

Saída estruturada de agentes

O treinamento de agentes do Qwen2.5-VL visa explicitamente chamadas de ferramentas estruturadas:

{
  "tool": "mouse_click",
  "coords": [1024, 512],
  "button": "left",
  "modifier": null
}

A análise (parsing) é determinística: JSON.parse sobre a saída do modelo. Compare com a forma livre "click at (1024, 512)", que exigia regex e tratamento de ambiguidades. Essa mudança é o motivo pelo qual as pontuações do ScreenSpot do Qwen2.5-VL saltaram de 55% no Qwen2-VL para 84%.

Use-o

O arquivo code/main.py implementa:

• Cálculo de posição M-RoPE para uma sequência empacotada misturando texto, patches de imagem e frames de vídeo.
• Amostrador de FPS dinâmico: dados (duração, orçamento, nível de movimento), escolhe o FPS e emite os carimbos de data/hora (timestamps) dos frames.
• Um analisador (parser) de saída JSON de brinquedo do Qwen2.5-VL que lida com respostas de chamadas de ferramentas com campos de coordenadas.

Execute-o e sinta a diferença ao trocar o FPS fixo pelo FPS dinâmico em um vídeo de 5 minutos.

Envie-o

Esta lição produz outputs/skill-qwen-vl-pipeline-designer.md. Dada uma tarefa de vídeo (monitoramento, agente, reconhecimento de ação, acessibilidade), ela emite a configuração do Qwen2.5-VL (orçamento de frames, estratégia de FPS, flag de atenção em janela, modo de saída do agente) e uma estimativa de latência. Use isso sempre que implantar um modelo da família Qwen-VL para um produto de vídeo.

Exercícios

1. Calcule as rotações de M-RoPE para um patch em (t=3, h=5, w=7) com dimensão oculta de 48 (16 por banda, theta base de 10000). Mostre os ângulos de rotação para os primeiros três pares em cada banda.

2. Uma gravação de câmera de segurança de 10 minutos a 1 FPS produz quantos frames? A uma resolução de 384 com pool de 3x, quantos tokens no total? O contexto padrão de 32k do Qwen2.5-VL consegue lidar com isso?

3. Escolha o FPS para um rali de tênis de 30 segundos versus uma demonstração de receita de 30 segundos versus uma gravação de agente de UI de 30 segundos. Justifique cada um com a lógica de FPS dinâmico.

4. O Qwen2.5-VL remove o Q-Former inteiramente. Por que um MLP simples funciona em 2025, mas não em 2023? (Dica: escala de dados e qualidade do codificador.)

5. Analise três saídas de chamadas de ferramentas JSON do Qwen2.5-VL em dicionários Python. O que falha no caso de um JSON malformado e qual estratégia de recuperação o cookbook do Qwen recomenda?

Termos-Chave

Leituras Adicionais

• Bai et al. — Qwen-VL (arXiv:2308.12966)
• Wang et al. — Qwen2-VL (arXiv:2409.12191)
• Qwen Team — Qwen2.5-VL Technical Report (arXiv:2502.13923)
• Qwen Team — Qwen3-VL (arXiv:2511.21631)
• Zhu et al. — InternVL3 (arXiv:2504.10479)