Video Processor

Um Video Processor é uma utilitário responsável por preparar os recursos de entrada para modelos de vídeo, bem como por tratar o pós-processamento de suas saídas. Ele fornece transformações como redimensionamento, normalização e conversão para PyTorch.

O processador de vídeo estende a funcionalidade dos processadores de imagem, permitindo que os modelos tratem vídeos com um conjunto distinto de argumentos em comparação com imagens. Ele atua como a ponte entre os dados brutos de vídeo e o modelo, garantindo que os recursos de entrada sejam otimizados para o VLM.

Use from_pretrained() para carregar a configuração de um processador de vídeo (tamanho da imagem, se normalizar e reescalar, etc.) a partir de um modelo de vídeo no Hub do Hugging Face ou em um diretório local. A configuração de cada modelo pré-treinado deve ser salva em um arquivo [video_preprocessor_config.json], mas modelos mais antigos podem ter a configuração salva em um arquivo preprocessor_config.json. Observe que este último é menos recomendado e será removido no futuro.

Quando um processador de vídeo faz parte de um processador multimodal, sua configuração fica aninhada em processor_config.json. Consulte Salvar e carregar um processador para mais detalhes.

Exemplo de uso

Aqui está um exemplo de como carregar um processador de vídeo com o modelo llava-hf/llava-onevision-qwen2-0.5b-ov-hf:

from transformers import AutoVideoProcessor

processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf")

Atualmente, ao usar o processador de imagem base para vídeos, os dados de vídeo são processados tratando cada quadro como uma imagem individual e aplicando transformações quadro a quadro. Embora funcional, essa abordagem não é muito eficiente. O uso de AutoVideoProcessor permite aproveitar os processadores de vídeo rápidos, utilizando a biblioteca torchvision. Os processadores rápidos lidam com o lote inteiro de vídeos de uma vez, sem iterar sobre cada vídeo ou quadro. Essas atualizações introduzem aceleração por GPU e aumentam significativamente a velocidade de processamento, especialmente para tarefas que exigem alto throughput.

Processadores de vídeo rápidos estão disponíveis para todos os modelos e são carregados por padrão quando um AutoVideoProcessor é inicializado. Ao usar um processador de vídeo rápido, você também pode definir o argumento device para especificar o dispositivo no qual o processamento deve ser realizado. Por padrão, o processamento é feito no mesmo dispositivo dos inputs, caso os inputs sejam tensors, ou na CPU, caso contrário. Para uma melhoria ainda maior de velocidade, podemos compilar o processador ao usar um acelerador como dispositivo.

import torch
from transformers.video_utils import load_video
from transformers import AutoVideoProcessor

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

video = load_video("video.mp4")
processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf", device=device)
processor = torch.compile(processor)
processed_video = processor(video, return_tensors="pt")

Amostragem de quadros

Um video processor decodifica um vídeo e seleciona os frames que o modelo realmente vê. Defina do_sample_frames=True para ativar a amostragem e, em seguida, escolha os frames de uma das duas formas.

• num_frames solicita uma contagem fixa distribuída uniformemente ao longo do vídeo.
• fps solicita uma taxa em quadros por segundo.

Passe um caminho ou URL e o processador decodifica o vídeo para você com torchcodec, o decodificador padrão. Se o torchcodec não estiver disponível e você estiver usando uma versão mais antiga do torchvision, a decodificação usa o torchvision como alternativa.

Adicione return_metadata=True para obter de volta os índices dos quadros amostrados, as dimensões originais, a duração e o fps.

from transformers import AutoVideoProcessor

processor = AutoVideoProcessor.from_pretrained("Qwen/Qwen3-VL-4B-Instruct")
inputs = processor(videos=["video.mp4"], do_sample_frames=True, fps=1, return_metadata=True, return_tensors="pt")

print(inputs.pixel_values_videos.shape, inputs.video_grid_thw)
print(inputs["video_metadata"][0].total_num_frames)

Os padrões de amostragem são específicos de cada modelo, e uma solicitação de num_frames ou fps é um ponto de partida, não uma garantia. O Qwen3-VL amostra em fps=2 e limita o resultado entre min_frames=4 e max_frames=768, de modo que um clipe de um segundo ainda gera 4 frames e uma gravação longa é limitada a um valor muito inferior ao seu número real de frames.

Modelos com temporal_patch_size adicionam uma segunda restrição, na qual os quadros são agrupados em patches com esse número de quadros ao longo do eixo do tempo, e o quadro final é repetido até que a contagem seja divisível.

Se você passar um array de vídeo já decodificado e ainda quiser amostragem específica do modelo, forneça também video_metadata. Sem ele, o amostrador não conhece a duração original nem o fps, e a amostragem por fps emite um aviso e assume que o vídeo foi gravado a 24 fps.

import torch
from transformers import AutoVideoProcessor
from transformers.video_utils import VideoMetadata

processor = AutoVideoProcessor.from_pretrained("Qwen/Qwen3-VL-4B-Instruct")
video = torch.randint(0, 255, size=(100, 3, 1280, 1280))  # short video of 100 frames
video_metadata = VideoMetadata(total_num_frames=100, fps=24, duration=4.1)

inputs = processor(
    videos=[video], video_metadata=[video_metadata], do_sample_frames=True, num_frames=16, return_tensors="pt"
)