Processador de vídeo

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. Além das transformações, a classe VideoProcessor gerencia a decodificação de vídeos a partir de caminhos locais ou URLs (requer torchcodec) e a amostragem de quadros de acordo com estratégias específicas de cada modelo.

O processador de vídeo estende a funcionalidade dos processadores de imagem, permitindo que Modelos de Linguagem Visuais (VLMs) processem 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.

As configurações do processador de vídeo são salvas em video_preprocessor_config.json. Checkpoints mais antigos podem armazená-las em preprocessor_config.json. Consulte Salvar e recarregar para o registro de backends personalizados ao recarregar.

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")

O pré-processamento é executado no dispositivo do tensor de entrada, ou na CPU para outras entradas. Defina device para mover os vídeos para outro dispositivo antes do pré-processamento; isso não altera o backend. Você também pode compilar o pré-processamento do torchvision com torch.compile ao usar um acelerador.

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")

Backends do processador de vídeo

Os processadores de vídeo integrados usam torchvision para redimensionamento, reescala e normalização em lote. Instale PyTorch e torchvision para usá-los. Diferentemente dos processadores de imagem, os processadores de vídeo integrados não fornecem um backend PIL.

AutoVideoProcessor seleciona o backend torchvision por padrão. Você também pode solicitá-lo explicitamente e inspecionar o atributo backend do processador carregado.

from transformers import AutoVideoProcessor

model_id = "llava-hf/llava-onevision-qwen2-0.5b-ov-hf"
video_processor = AutoVideoProcessor.from_pretrained(model_id, backend="torchvision")
print(video_processor.backend)
# torchvision

O argumento backend seleciona a implementação de pré-processamento, não o decodificador de vídeo. Consulte Comportamento de amostragem para decodificação e amostragem de quadros.

Backends personalizados

BaseVideoProcessor fornece pré-processamento baseado em torchvision. Para uma implementação que não utilize torchvision, você pode criar uma subclasse de VideoProcessorMixin e sobrescrever preprocess para retornar um BatchFeature contendo as entradas esperadas pelo modelo.

Registre classes personalizadas com AutoVideoProcessor.register() e use video_processor_classes para mapear os nomes dos backends para as classes. O exemplo abaixo pressupõe que NewCustomVideoProcessor esteja definida com o pré-processamento exigido pelo checkpoint LLaVA-OneVision.

from transformers import LlavaOnevisionConfig

AutoVideoProcessor.register(
    LlavaOnevisionConfig,
    video_processor_classes={"custom": NewCustomVideoProcessor},
    exist_ok=True,
)
custom_processor = AutoVideoProcessor.from_pretrained(model_id, backend="custom")

Use exist_ok=True porque LlavaOnevisionConfig já está registrado. As entradas fornecidas são mescladas em seu mapeamento de backend, onde os nomes correspondentes são substituídos, e as entradas não fornecidas, como torchvision, são preservadas.

Salvar e recarregar

save_pretrained() salva a configuração de pré-processamento, não os mapeamentos de backend adicionados com AutoVideoProcessor.register(). No mesmo processo Python, recarregue o processador salvo com backend="custom":

custom_processor.save_pretrained("./saved-video-processor")
custom_processor = AutoVideoProcessor.from_pretrained("./saved-video-processor", backend="custom")

Registrações personalizadas se aplicam ao processo Python atual. Em um novo processo, defina ou importe a classe personalizada e registre-a novamente antes de carregar.

Comportamento de amostragem

O processador de vídeo também pode amostrar quadros de vídeo usando a técnica mais adequada para o modelo em questão. O comportamento da amostragem é controlado pelo argumento do_sample_frames e pode ser configurado por meio de parâmetros específicos do modelo, como num_frames ou fps (a taxa na qual o vídeo será amostrado). Se o vídeo de entrada for fornecido como um caminho local ou URL (str), o processador o decodificará automaticamente. Para obter metadados sobre o vídeo decodificado, como os índices dos quadros amostrados, dimensões originais, duração e fps, passe return_metadata=True para o processador.

Especificar num_frames não garante que a saída contenha exatamente esse número de quadros. Dependendo do modelo, o sampler pode impor limites mínimos ou máximos de quadros.

O decodificador padrão é torchcodec, que deve ser instalado.

import torch
from transformers import AutoVideoProcessor

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

processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf", device=device)
processed_video_inputs = processor(videos=["video_path.mp4"], return_metadata=True, do_sample_frames=True, return_tensors="pt")
video_metadata = processed_video_inputs["video_metadata"]

# See how many frames the original video had and what was the original FPS
print(video_metadata.total_num_frames, video_metadata.fps)

If you pass an already decoded video array but still want to enable model-specific frame sampling, it is strongly recommended to provide video_metadata. This allows the sampler to know the original video’s duration and FPS. You can pass metadata as a VideoMetadata object or as a plain dict.

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

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

processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf", device=device)
decoded_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, # in seconds
)
processed_video_inputs = processor(videos=[decoded_video], video_metadata=video_metadata, do_sample_frames=True, num_frames=10, return_tensors="pt")
print(processed_video_inputs.pixel_values_videos.shape)
[10, 3, 384, 384]

VideoProcessorMixin

classe transformers.VideoProcessorMixin

< source >

( **kwargs: *<class 'transformers.processing_utils.VideosKwargs'> )

fetch_videos

< source >

( video_url_or_urls: str | list[str] | list[list[str]]sample_indices_fn = None )

Converte uma única URL ou uma lista de URLs nos objetos np.array correspondentes.

Se uma única url for passada, o valor retornado será um único objeto. Se uma lista for passada, uma lista de objetos é retornada.

from_dict

< source >

( video_processor_dict: dict**kwargs ) → ~video_processing_utils.VideoProcessorBase

Parâmetros

video_processor_dict (dict[str, Any]) — Dicionário que será usado para instanciar o objeto de processador de vídeo. Esse dicionário pode ser obtido de um checkpoint pré-treinado utilizando o método ~video_processing_utils.VideoProcessorBase.to_dict.
kwargs (dict[str, Any]) — Parâmetros adicionais a partir dos quais inicializar o objeto de processador de vídeo.

Retorna

~video_processing_utils.VideoProcessorBase

O objeto de processador de vídeo instanciado a partir desses parâmetros.

Instancia um tipo de ~video_processing_utils.VideoProcessorBase a partir de um dicionário Python de parâmetros.

from_json_file

< source >

( json_file: str | os.PathLike ) → A video processor of type ~video_processing_utils.VideoProcessorBase

Parâmetros

json_file (str ou os.PathLike) — Caminho para o arquivo JSON contendo os parâmetros.

Retorna

Um processador de vídeo do tipo ~video_processing_utils.VideoProcessorBase

O objeto video_processor instanciado a partir desse arquivo JSON.

Instancia um processador de vídeo do tipo ~video_processing_utils.VideoProcessorBase a partir do caminho para um arquivo JSON de parâmetros.

from_pretrained

< source >

Parâmetros

pretrained_model_name_or_path (str ou os.PathLike) — Pode ser:
- uma string, o model id de um vídeo pré-treinado hospedado em um repositório de modelos no huggingface.co.
- um caminho para um diretório contendo um arquivo de processador de vídeo salvo usando o método ~video_processing_utils.VideoProcessorBase.save_pretrained, por exemplo, ./my_model_directory/.
- um caminho para um arquivo JSON de processador de vídeo salvo arquivo, por exemplo, ./my_model_directory/video_preprocessor_config.json.
cache_dir (str ou os.PathLike, opcional) — Caminho para um diretório em que o processador de vídeo de um modelo pré-treinado baixado deve ser armazenado em cache, caso o cache padrão não deva ser usado.
force_download (bool, opcional, padrão False) — Se deve forçar o (re)download dos arquivos do processador de vídeo e sobrescrever as versões em cache, caso existam.
proxies (dict[str, str], opcional) — Um dicionário de servidores proxy a serem usados por protocolo ou endpoint, por exemplo, {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Os proxies são usados em cada solicitação.
token (str ou bool, opcional) — O token a ser usado como autorização bearer HTTP para arquivos remotos. Se True, ou não especificado, usará o token gerado ao executar hf auth login (armazenado em ~/.huggingface).
revision (str, opcional, padrão "main") — A versão específica do modelo a ser usada. Pode ser o nome de um branch, o nome de uma tag ou um id de commit, pois utilizamos um sistema baseado em git para armazenar modelos e outros artefatos no huggingface.co, de modo que revision pode ser qualquer identificador permitido pelo git.

Instancie um tipo de ~video_processing_utils.VideoProcessorBase a partir de um processador de vídeo.

Exemplos:

# We can't instantiate directly the base class *VideoProcessorBase* so let's show the examples on a
# derived class: *LlavaOnevisionVideoProcessor*
video_processor = LlavaOnevisionVideoProcessor.from_pretrained(
    "llava-hf/llava-onevision-qwen2-0.5b-ov-hf"
)  # Download video_processing_config from huggingface.co and cache.
video_processor = LlavaOnevisionVideoProcessor.from_pretrained(
    "./test/saved_model/"
)  # E.g. video processor (or model) was saved using *save_pretrained('./test/saved_model/')*
video_processor = LlavaOnevisionVideoProcessor.from_pretrained("./test/saved_model/video_preprocessor_config.json")
video_processor = LlavaOnevisionVideoProcessor.from_pretrained(
    "llava-hf/llava-onevision-qwen2-0.5b-ov-hf", do_normalize=False, foo=False
)
assert video_processor.do_normalize is False
video_processor, unused_kwargs = LlavaOnevisionVideoProcessor.from_pretrained(
    "llava-hf/llava-onevision-qwen2-0.5b-ov-hf", do_normalize=False, foo=False, return_unused_kwargs=True
)
assert video_processor.do_normalize is False
assert unused_kwargs == {"foo": False}

get_video_processor_dict

< source >

( pretrained_model_name_or_path: str | os.PathLike**kwargs ) → tuple[Dict, Dict]

Parâmetros

pretrained_model_name_or_path (str ou os.PathLike) — O identificador do checkpoint pré-treinado do qual queremos o dicionário de parâmetros.
subfolder (str, opcional, padrão "") — Caso os arquivos relevantes estejam localizados em uma subpasta do repositório do modelo no huggingface.co, você pode especificar o nome da pasta aqui.

Retorna

tuple[Dict, Dict]

O(s) dicionário(s) que será(ão) usado(s) para instanciar o objeto do processador de vídeo.

A partir de um pretrained_model_name_or_path, resolve para um dicionário de parâmetros, a ser usado para instanciar um processador de vídeo do tipo ~video_processing_utils.VideoProcessorBase usando from_dict.

pré-processamento

< source >

( videos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]]]**kwargs: *<class 'transformers.processing_utils.VideosKwargs'> ) → ~image_processing_base.BatchFeature

Parâmetros

videos (Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]]) — Vídeo a ser pré-processado. Espera um único vídeo ou um lote de vídeos com valores de pixel variando de 0 a 255. Se passar vídeos com valores de pixel entre 0 e 1, defina do_rescale=False.
do_convert_rgb (bool, kwargs, opcional) — Se a imagem deve ser convertida para RGB.
do_resize (bool, kwargs, opcional) — Se deve redimensionar a imagem.
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Descreve as dimensões máximas de entrada para o modelo.
default_to_square (bool, kwargs, opcional) — Se deve usar uma imagem quadrada por padrão ao redimensionar, caso o tamanho seja um inteiro.
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — Filtro de redimensionamento a ser usado ao redimensionar a imagem. Pode ser um dos valores da enumeração PILImageResampling. Tem efeito apenas se do_resize estiver definido como True.
do_rescale (bool, kwargs, opcional) — Se deve reescalar a imagem.
rescale_factor (float, kwargs, opcional) — Fator de redimensionamento para redimensionar a imagem, caso do_rescale esteja definido como True.
do_normalize (bool, kwargs, opcional) — Se a imagem deve ser normalizada.
image_mean (Union[float, list[float], tuple[float, ...]], kwargs, opcional) — Média da imagem a ser usada para normalização. Tem efeito apenas se do_normalize estiver definido como True.
image_std (Union[float, list[float], tuple[float, ...]], kwargs, opcional) — Desvio padrão da imagem a ser usado para normalização. Tem efeito apenas se do_normalize estiver definido como True.
do_center_crop (bool, kwargs, opcional) — Se deve recortar a imagem centralmente.
do_pad (bool, kwargs, opcional) — Indica se a imagem deve ser preenchida (padding). O preenchimento é feito até o maior tamanho do lote ou até um tamanho quadrado fixo por imagem. A estratégia exata de preenchimento depende do modelo.
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Tamanho da imagem de saída após a aplicação de center_crop.
data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opcional) — Apenas ChannelDimension.FIRST é suportado. Adicionado para compatibilidade com processadores lentos.
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opcional) — O formato da dimensão de canal para a imagem de entrada. Se não definido, o formato da dimensão de canal é inferido a partir da imagem de entrada. Pode ser um dos seguintes:
- "channels_first" ou ChannelDimension.FIRST: imagem no formato (num_channels, height, width).
- "channels_last" ou ChannelDimension.LAST: imagem no formato (altura, largura, num_canais).
- "none" ou ChannelDimension.NONE: imagem no formato (altura, largura).
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — O dispositivo em que os vídeos serão processados. Se não for definido, o dispositivo é inferido a partir dos vídeos de entrada.
do_sample_frames (bool, kwargs, opcional) — Se deve amostrar quadros do vídeo antes do processamento ou processar o vídeo inteiro.
video_metadata (Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — Metadados do vídeo contendo informações sobre a duração total, fps e o número total de quadros. Será usado para amostrar quadros do vídeo ou calcular timestamps. Não passe nenhum metadado, a menos que você esteja tentando decodificar o vídeo manualmente antes do processamento
fps (Annotated[int | float | None, None], kwargs) — Quantidade de quadros-alvo a amostrar por segundo quando do_sample_frames=True.
num_frames (Annotated[int | None, None], kwargs) — Número máximo de quadros a amostrar quando do_sample_frames=True.
return_metadata (bool, kwargs, opcional) — Se deve retornar ou não os metadados do vídeo. Os metadados do vídeo são um objeto contendo informações sobre a duração do vídeo, fps, backend de decodificação, etc.
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Retorna tensores empilhados se definido como 'pt'; caso contrário, retorna uma lista de tensores.

Retorna

~image_processing_base.BatchFeature

data (dict) — Dicionário de listas/arrays/tensors retornados pelo método call (‘pixel_values’, etc.).
tensor_type (Union[None, str, TensorType], opcional) — Você pode fornecer um tensor_type aqui para converter as listas de inteiros em Tensors do PyTorch/Numpy na inicialização.

register_for_auto_class

< source >

( auto_class = 'AutoVideoProcessor' )

Parâmetros

auto_class (str ou type, opcional, padrão "AutoVideoProcessor ") — A classe automática com a qual este novo processador de vídeo será registrado.

Registre esta classe em uma classe auto específica. Isso deve ser usado apenas para processadores de vídeo personalizados, pois os da biblioteca já estão mapeados com AutoVideoProcessor.

Esta API é experimental e pode apresentar pequenas alterações incompatíveis nas próximas versões.

save_pretrained

< source >

( save_directory: str | os.PathLikepush_to_hub: bool = False**kwargs )

Parâmetros

save_directory (str ou os.PathLike) — Diretório onde o arquivo JSON do processador de vídeo será salvo (será criado se não existir).
push_to_hub (bool, opcional, padrão False) — Indica se o modelo deve ser enviado para o Hugging Face model hub após ser salvo. Você pode especificar o repositório de destino com repo_id (por padrão, será usado o nome de save_directory no seu namespace).
kwargs (dict[str, Any], opcional) — Argumentos de palavra-chave adicionais passados ao método push_to_hub().

Salve um objeto de processador de vídeo no diretório save_directory, para que ele possa ser recarregado usando o método de classe ~video_processing_utils.VideoProcessorBase.from_pretrained.

to_dict

< source >

( ) → dict[str, Any]

Retorna

dict[str, Any]

Dicionário de todos os atributos que compõem esta instância do processador de vídeo.

Serializa esta instância em um dicionário Python.

BaseVideoProcessor

classe transformers.BaseVideoProcessor

< source >

( **kwargs: *<class 'transformers.processing_utils.VideosKwargs'> )

convert_to_rgb

< source >

( video: torch.Tensor ) → torch.Tensor

Parâmetros

video ("torch.Tensor") — O vídeo a ser convertido.

Retorna

torch.Tensor

O vídeo convertido.

Converte um vídeo para o formato RGB.

sample_frames

< source >

( metadata: VideoMetadatanum_frames: int | None = Nonefps: int | float | None = None**kwargs ) → np.ndarray

Parâmetros

metadata (VideoMetadata) — Metadados do vídeo, contendo informações sobre a duração total, o fps e o número total de quadros.
num_frames (int, opcional) — Número máximo de quadros a amostrar. O valor padrão é self.num_frames.
fps (int ou float, opcional) — Quantidade de quadros a amostrar por segundo. O valor padrão é self.fps.

Retorna

np.ndarray

Índices para amostrar quadros de vídeo.

Função de amostragem padrão que amostra uniformemente o número desejado de quadros entre 0 e o total de quadros. Se fps for passado junto com metadados, fps quadros por segundo são amostrados uniformemente. Os argumentos num_frames e fps são mutuamente exclusivos.

Update on GitHub

Transformers

Processador de vídeo

Exemplo de uso

Backends do processador de vídeo

Backends personalizados

Salvar e recarregar

Comportamento de amostragem

VideoProcessorMixin

classe transformers.VideoProcessorMixin

fetch_videos

from_dict

from_json_file

from_pretrained

get_video_processor_dict

pré-processamento

register_for_auto_class

save_pretrained

to_dict

BaseVideoProcessor

classe transformers.BaseVideoProcessor

convert_to_rgb

sample_frames