Pipeline local de sumarização de vídeos com SmolVLM2-2.2B: processando frames sem depender da nuvem

Pipeline local de sumarização de vídeos com SmolVLM2-2.2B: processando frames sem depender da nuvem

Até recentemente, entender o que acontece dentro de um vídeo — uma reunião de duas horas, uma aula gravada, uma sequência de câmeras de segurança — exigia escolher entre dois caminhos insatisfatórios. O primeiro: enviar o arquivo para uma API na nuvem, pagar por minuto processado e torcer pela privacidade dos dados. O segundo: rodar localmente, mas só com GPUs empresariais de US$ 10 mil que consomem mais energia que um ar-condicionado. Em julho de 2026, esse cálculo mudou.

O SmolVLM2-2.2B, lançado pelo Hugging Face, roda em 5.2 GB de VRAM — o equivalente a uma RTX 3060, um MacBook Pro M2 ou até o tier gratuito do Google Colab (T4). No benchmark Video-MME, referência para compreensão de vídeos longos, ele supera todos os modelos existentes na escala de 2 bilhões de parâmetros. Não é mágica: é uma decisão inteligente de design sobre como tokenizar imagens.

Este tutorial expande o guia original de Shittu Olumide (KDnuggets) e mostra como construir um pipeline completo que recebe qualquer arquivo de vídeo, extrai frames, roda inferência local com SmolVLM2 e gera um resumo estruturado em JSON — com descrições por cena, momentos-chave com timestamps, itens de ação e narrativa final. Tudo offline, tudo sob seu controle.

✅ O que você ganha

• Privacidade total: nenhum frame sai do seu computador. Reuniões confidenciais, vídeos de segurança, aulas protegidas por direitos autorais — tudo processado localmente.
• Custo zero por minuto: sem cobrança por API. O modelo roda na GPU que você já tem. A única despesa é energia elétrica (cerca de R$ 0,15 por hora de processamento em uma RTX 3060 no Brasil, considerando tarifa residencial média de R$ 0,90/kWh).
• Pipeline completo em Python puro: três arquivos (frame_extractor.py, smolvlm2_loader.py, video_summarizer.py) que somam menos de 400 linhas.
• Saída estruturada em JSON: resumo narrativo, lista de ações, momentos-chave com timestamps — pronto para integrar com sistemas downstream.
• Dois modos de amostragem: uniforme para reuniões/aulas (cobertura completa) e por keyframes para vigilância/detecção de eventos (foco em mudanças visuais).
• Checkpoint automático: suporte a JSONL com retomada de processamento — se cair no frame 35 de 50, recomeça do 36.

⚠️ O que você NÃO ganha

• Velocidade de datacenter: uma RTX 3060 processa ~50 frames em 5-8 minutos. Um cluster A100 faria em segundos. O trade-off é deliberado: autonomia vs. velocidade.
• Compreensão de áudio: o SmolVLM2 analisa apenas imagens. Para transcrição de fala, você precisará de Whisper ou similar em paralelo.
• Resolução cinematográfica: o modelo comprime cada patch de 384×384 pixels em 81 tokens visuais. Texto muito pequeno em slides pode não ser capturado com precisão.

Requisitos de hardware e software

Por que o SmolVLM2 é diferente

O segredo está na tokenização. Modelos como Qwen2-VL gastam até 16.000 tokens para representar uma única imagem. Cinquenta frames nessa densidade consumiriam 800.000 tokens — impossível em uma GPU de consumo. O SmolVLM2 usa uma estratégia de pixel shuffle que comprime cada patch de 384×384 em apenas 81 tokens. Cinquenta frames viram ~4.050 tokens de imagem, perfeitamente gerenciáveis em uma única chamada de inferência.

Isso se traduz em números concretos: o throughput de prefill do SmolVLM2 é 3,3 a 4,5 vezes mais rápido que o Qwen2-VL-2B; a geração é 7,5 a 16 vezes mais rápida. Não é marketing — é consequência direta do orçamento de tokens.

O modelo vem em três tamanhos: 256M (roda em celular), 500M (edge devices) e 2.2B (o que usamos aqui). Só o 2.2B tem benchmarks de vídeo fortes o suficiente para resumos confiáveis multi-cena: Video-MME 52.1, MLVU 55.2, MVBench 46.27.

Passo 1: Configurando o ambiente

Comece criando um ambiente virtual e instalando as dependências. O transformers precisa vir do branch específico SmolVLM-2 — a versão estável do PyPI ainda não inclui suporte ao modelo:

# Python 3.10+ obrigatório
python --version

python -m venv smolvlm2-env
source smolvlm2-env/bin/activate       # Linux / macOS
# smolvlm2-env\Scripts\activate        # Windows

# Transformers do branch SmolVLM-2
pip install git+https://github.com/huggingface/[email protected]

# Dependências principais
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
pip install opencv-python Pillow numpy num2words accelerate

# Flash Attention 2 (apenas CUDA — pule no Mac/CPU)
pip install flash-attn --no-build-isolation

# Decord para entrada nativa de vídeo do SmolVLM2
pip install decord

Atenção: o pacote num2words parece supérfluo, mas é uma dependência oculta. O processador do SmolVLM2 o usa para converter dígitos em palavras (ex: 3 → “three”) por consistência com os padrões de treinamento. Omiti-lo causa erro silencioso na importação.

Verifique seu dispositivo antes de carregar o modelo:

# device_check.py
import torch

def detect_device():
    if torch.cuda.is_available():
        name = torch.cuda.get_device_name(0)
        vram = torch.cuda.get_device_properties(0).total_memory / 1e9
        print(f"CUDA: {name} ({vram:.1f} GB VRAM)")
        return "cuda", torch.bfloat16, "flash_attention_2"
    elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
        print("Apple Silicon MPS detectado")
        return "mps", torch.float16, "eager"
    else:
        print("CPU fallback (lento — considere Colab T4)")
        return "cpu", torch.float32, "eager"

if __name__ == "__main__":
    device, dtype, attn = detect_device()
    print(f"Device: {device} | dtype: {dtype} | attn: {attn}")

Passo 2: Extraindo frames do vídeo

O extrator de frames converte um arquivo de vídeo em uma lista de imagens PIL com timestamps. Dois modos para cenários diferentes:

• Amostragem uniforme: distribui frames igualmente por toda a duração. Ideal para reuniões gravadas, aulas e tutoriais — você não pode perder nenhuma seção.
• Amostragem por keyframes: extrai frames apenas onde o conteúdo visual muda significativamente (corte de cena, novo slide, novo interlocutor). Ideal para vigilância e detecção de eventos — reduz a contagem de frames e foca nos momentos distintos.

O código completo do frame_extractor.py está no artigo original. A classe FrameExtractor oferece dois métodos principais: uniform_sample(video_path) e keyframe_sample(video_path, diff_threshold=30.0). O limite de 50 frames é o teto prático antes que a pressão de VRAM afete a qualidade da geração.

Passo 3: Carregando o modelo e fazendo a primeira inferência

A classe correta para carregar o SmolVLM2 é AutoModelForImageTextToText — não a genérica AutoModelForCausalLM. Em CUDA, habilite Flash Attention 2 para ganhos significativos de latência em entradas com múltiplas imagens:

from transformers import AutoProcessor, AutoModelForImageTextToText

MODEL_ID = "HuggingFaceTB/SmolVLM2-2.2B-Instruct"

processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForImageTextToText.from_pretrained(
    MODEL_ID,
    torch_dtype=torch.bfloat16,
    _attn_implementation="flash_attention_2",
).to("cuda")
model.eval()

O template de chat do SmolVLM2 espera a imagem antes do texto na mensagem — isso espelha o formato dos dados de treinamento e é essencial para saídas confiáveis. A função describe_frame() encapsula esse padrão.

Passo 4: O pipeline completo de sumarização

A classe VideoSummarizer implementa uma estratégia de duas passagens que é o coração do tutorial:

1. Primeira passagem: descreve cada frame individualmente. É uma tarefa focada e realizável — o modelo produz descrições precisas e concretas do que vê.
2. Segunda passagem: sintetiza todas as descrições em um relatório estruturado com resumo narrativo, itens de ação e momentos-chave com timestamps em [MM:SS].

Separar as duas etapas é deliberado: pedir ao modelo para descrever um frame por vez é uma tarefa que ele executa bem. Pedir para sintetizar 30 descrições em uma narrativa coerente é outra tarefa, que ele trata melhor como chamada separada com as descrições concatenadas como entrada.

# Uso:
python video_summarizer.py reuniao_2026_07_10.mp4 --output resumo.json

# Para vigilância/eventos:
python video_summarizer.py cameras.mp4 --mode keyframe --output eventos.json

# Ajuste de batch size conforme VRAM:
python video_summarizer.py aula_longa.mp4 --batch-size 4 --output aula.json

Passo 5: Gerenciando VRAM com lotes

O batch size é o principal controle para se manter dentro do orçamento de VRAM. O cálculo: pesos do SmolVLM2-2.2B ocupam ~4,5 GB em bfloat16. Cada frame contribui com ~81 tokens de imagem. Com 20% de headroom:

Casos de uso reais

• Resumo de reuniões: grave 2h de reunião, rode o pipeline e receba um JSON com ata automática — tópicos discutidos, decisões tomadas, tarefas atribuídas com timestamps. Ideal para times remotos que precisam de documentação sem assistir à gravação inteira.
• Monitoramento de segurança: processe 24h de footage de câmeras no modo keyframe. O pipeline extrai apenas momentos com mudança visual significativa, gerando um log de eventos com timestamps para revisão humana.
• Catalogação de acervo audiovisual: universidades, museus e emissoras podem processar milhares de horas de vídeo histórico, gerando metadados pesquisáveis sem enviar conteúdo para serviços de terceiros.
• Análise de aulas e treinamentos: professores podem rodar o pipeline sobre aulas gravadas para gerar resumos que os alunos usam como guia de estudo, com timestamps que linkam direto para os momentos-chave.
• Due diligence audiovisual: escritórios de advocacia podem processar depoimentos gravados, gerando índices timestampados de menções a termos específicos, pessoas ou eventos — tudo offline, preservando privilégio advogado-cliente.

Comparação de custo: local vs. nuvem

Troubleshooting: erros comuns e soluções

1. ❌ ModuleNotFoundError: No module named 'num2words'
   Causa: dependência oculta do processador SmolVLM2. Solução: pip install num2words.
2. ❌ CUDA out of memory ao processar muitos frames
   Causa: batch_size alto demais para sua VRAM. Solução: reduza --batch-size pela metade e tente novamente. Comece com 4 e suba até encontrar o limite estável.
3. ❌ Respostas muito curtas ou obviamente erradas na primeira inferência
   Causa: transformers instalado da versão estável do PyPI, não do branch SmolVLM-2. Solução: reinstale com pip install git+https://github.com/huggingface/[email protected].
4. ❌ Erro ao abrir vídeo: Cannot open video
   Causa: codec não suportado pelo OpenCV ou arquivo corrompido. Solução: converta o vídeo com ffmpeg -i input.mkv -c:v libx264 output.mp4 e tente novamente.
5. ❌ ImportError silencioso ao carregar o processador
   Causa: num2words ausente. O erro não aparece como exceção explícita — o processador simplesmente falha ao carregar. Solução: instale num2words antes de importar o transformers.
6. ❌ Muitos frames redundantes (5 slides quase idênticos seguidos)
   Causa: amostragem uniforme em vídeos com longos trechos estáticos. Solução: mude para keyframe_sample e ajuste diff_threshold de 30 para 20.

FAQ

Preciso de GPU NVIDIA ou funciona em Mac?

Funciona em Mac com Apple Silicon (M1/M2/M3) via MPS. O desempenho é menor que em CUDA, mas suficiente para processamento offline. CPUs x86 sem GPU funcionam, mas cada frame pode levar minutos — use Google Colab T4 (gratuito) como alternativa.

O modelo entende áudio ou só imagem?

Apenas imagem. O SmolVLM2 analisa frames visuais. Para transcrição de fala, combine com Whisper (OpenAI) rodando em paralelo. Os timestamps do extrator de frames facilitam alinhar transcrições de áudio com descrições visuais.

Posso processar vídeos de qualquer duração?

Sim, mas o limite padrão é 50 frames extraídos. Para um vídeo de 2h, isso significa ~1 frame a cada 2,4 minutos — suficiente para capturar a estrutura. Para vídeos mais longos com muitos detalhes, aumente max_frames (até 75-100 com 16 GB+ VRAM). Use o JSONL writer com checkpoint para não perder progresso em vídeos muito longos.

O que acontece com meus dados? Eles sobem para algum servidor?

Nada sai do seu computador. O modelo é baixado uma vez (~4,5 GB) e toda inferência roda localmente. Não há chamada de API, não há telemetria, não há log remoto. A privacidade é total.

Quanto custa rodar isso no Brasil?

Com uma RTX 3060 (170W TDP) e tarifa residencial média de R$ 0,90/kWh, processar 1 hora de vídeo custa cerca de R$ 0,01 em energia. O download inicial do modelo (~4,5 GB) é o único custo único de banda. Compare com ~R$ 1,50-3,00 por hora nas APIs cloud.

O futuro do processamento local de vídeo

O SmolVLM2-2.2B representa um ponto de inflexão: qualidade de compreensão de vídeo que até 2024 exigia GPUs de datacenter agora roda em hardware de consumo. A tendência para 2027 aponta para modelos ainda menores (sub-1B) com qualidade equivalente, viabilizando processamento em tempo real em dispositivos móveis e câmeras embarcadas.

Enquanto isso, o pipeline deste tutorial é o template. Troque FRAME_PROMPT por um prompt ajustado ao seu domínio, modifique build_synthesis_prompt() para extrair os campos estruturados que importam para seu caso de uso, e o mesmo pipeline funciona para aulas, segurança, demonstrações de produtos ou highlights esportivos. O padrão de duas passagens — descrição por frame primeiro, síntese depois — se mantém porque o modelo descreve frames individuais com precisão e sintetiza através de descrições de forma confiável.