Este modelo foi publicado em HF papers em 2025-04-17 e contribuído para Hugging Face Transformers em 2025-12-16. Este modelo foi lançado em 2025-04-17 e adicionado ao Hugging Face Transformers em 2025-12-16.

PE Vídeo

PE Video é o ramo de vídeo da família Perception Encoder da Meta. Ele alinha contrastivamente clipes de vídeo com texto em um espaço de incorporação compartilhado, permitindo classificação de vídeo zero-shot e recuperação vídeo–texto a partir de um único backbone pré-treinado.

Os embeddings rotacionais e o incorporador de patches do codificador tratam o eixo temporal como uma dimensão de primeira classe, permitindo que clipes de comprimento variável sejam codificados sem que cada quadro precise ser incorporado de forma independente.

Você pode encontrar todos os checkpoints oficiais do PE Audio na coleção perception-encoder-audio-visual.

Início rápido

import torch
from transformers import AutoProcessor, PeVideoModel
from transformers.video_utils import load_video

processor = AutoProcessor.from_pretrained("facebook/pe-av-large")
model = PeVideoModel.from_pretrained(
    "facebook/pe-av-large",
    device_map="auto",
)

video, _ = load_video("https://huggingface.co/datasets/hf-internal-testing/fixtures_videos/resolve/main/tennis.mp4")
labels = ["a person playing tennis", "a person cooking", "a cat sleeping"]

video_inputs = processor.video_processor(video, num_frames=16, return_tensors="pt").to(model.device)
text_inputs = processor.tokenizer(labels, padding=True, return_tensors="pt").to(model.device)
inputs = {**video_inputs, **text_inputs}

with torch.no_grad():
    outputs = model(**inputs)

probs = outputs.logits_video_text.sigmoid()
print({label: p.item() for label, p in zip(labels, probs[0])})

Dicas e observações de uso

Vídeos de comprimento variável usam padding_mask_videos (e não attention_mask). O processador de vídeo apenas aplica padding e retorna essa máscara quando return_tensors está definido — sem ele, você recebe uma lista de tensores por clipe e nenhuma máscara.
Passe num_frames para o processador de vídeo para amostragem uniforme de comprimento fixo em [0, total_frames-1]. Omita-o para recorrer à amostragem baseada em fps da classe base. Os checkpoints geralmente são treinados com uma contagem específica de quadros, então corresponda ao que o checkpoint espera.
A entrada do encoder é pixel_values_videos. O main_input_name do encoder é "pixel_values_videos", enquanto o do modelo completo é "input_ids", o que é importante ao rotear por utilitários genéricos que inspecionam main_input_name.

PeVideoConfig

classe transformers.PeVideoConfig

< source >

Parâmetros

text_config (Union[dict, ~configuration_utils.PreTrainedConfig], opcional) — O objeto de configuração ou dicionário do backbone de texto.
video_config (dict ou PreTrainedConfig, opcional) — Configuração para o componente codificador de vídeo.

Esta é a classe de configuração para armazenar a configuração de um PeVideoModel. Ela é usada para instanciar um modelo Pe Video de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do facebook/pe-av-large

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

>>> from transformers import PeVideoModel, PeVideoConfig

>>> # Initializing a PeVideoModel style configuration
>>> configuration = PeVideoConfig()

>>> # Initializing a model from the pe-av-large style configuration
>>> model = PeVideoModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

PeVideoEncoderConfig

classe transformers.PeVideoEncoderConfig

< source >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonehidden_size: int = 1792intermediate_size: int = 4800num_hidden_layers: int = 6num_attention_heads: int = 14num_key_value_heads: int | None = Nonehead_dim: int = 128hidden_act: str = 'silu'max_position_embeddings: int = 10000initializer_range: float = 0.02rms_norm_eps: float = 1e-05rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = Noneattention_bias: bool = Falseattention_dropout: float | int = 0.0 )

Parâmetros

vision_config (Union[dict, ~configuration_utils.PreTrainedConfig], opcional) — O objeto de configuração ou dicionário do backbone de visão.
hidden_size (int, opcional, padrão 1792) — Dimensão das representações ocultas.
intermediate_size (int, opcional, padrão 4800) — Dimensão das representações do MLP.
num_hidden_layers (int, opcional, padrão 6) — Número de camadas ocultas no decodificador do Transformer.
num_attention_heads (int, opcional, padrão 14) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.
num_key_value_heads (int, opcional) — Este é o número de cabeças de key_value que devem ser usadas para implementar Grouped Query Attention. Se num_key_value_heads=num_attention_heads, o modelo usará Multi Head Attention (MHA); se num_key_value_heads=1, o modelo usará Multi Query Attention (MQA); caso contrário, será usado GQA. Ao converter um checkpoint multi-head para um checkpoint GQA, cada grupo de cabeças de chave e valor deve ser construído por meio do meanpooling de todas as cabeças originais dentro desse grupo. Para mais detalhes, consulte este artigo. Se não for especificado, o valor padrão será num_attention_heads.
head_dim (int, opcional, padrão 128) — A dimensão da cabeça de atenção. Se for None, o valor padrão será hidden_size // num_attention_heads
hidden_act (str, opcional, padrão silu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo, "gelu", "relu", "silu", etc.
max_position_embeddings (int, opcional, padrão 10000) — O comprimento máximo de sequência com o qual este modelo pode ser utilizado.
initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.
rms_norm_eps (float, opcional, padrão 1e-05) — O epsilon usado pelas camadas de normalização rms.
rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], opcional) — Dicionário contendo os parâmetros de configuração para os embeddings RoPE. O dicionário deve conter um valor para rope_theta e, opcionalmente, parâmetros usados para escalonamento, caso você queira usar RoPE com max_position_embeddings maiores.
attention_bias (bool, opcional, padrão False) — Indica se deve ser usado um viés nas camadas de projeção de query, key, value e output durante a autoatenção.
attention_dropout (Union[float, int], opcional, padrão 0.0) — A taxa de dropout para as probabilidades de atenção.

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Exemplo:

>>> from transformers import PeAudioEncoder, PeAudioEncoderConfig

>>> # Initializing a PeAudioEncoder style configuration
>>> configuration = PeAudioEncoderConfig()

>>> # Initializing a model from the pe-av-large style configuration
>>> model = PeAudioEncoder(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

PeVideoVideoProcessor

classe transformers.PeVideoVideoProcessor

< source >

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

Parâmetros

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, padrão True) — 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, padrão 2) — Filtro de reamostragem 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, padrão 0.00392156862745098) — Fator de reescala para reescalar 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, padrão False) — 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) — Se definido, retornará tensors de um framework específico. Os valores aceitos são:
- 'pt': Retorna objetos torch.Tensor do PyTorch.
- 'np': Retorna objetos np.ndarray do NumPy.
**kwargs (VideosKwargs, opcional) — Opções de processamento adicionais para cada modalidade (texto, imagens, vídeos, áudio). Os parâmetros específicos do modelo estão listados acima; consulte a classe TypedDict para a lista completa de argumentos suportados.

Constrói um processador de vídeo PeVideoVideoProcessor.

PeVideoProcessor

classe transformers.PeVideoProcessor

< source >

( *args**kwargs )

PeVideoEncoder

classe transformers.PeVideoEncoder

< source >

( config: PeVideoEncoderConfig )

Parâmetros

config (PeVideoEncoderConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.

O modelo PeVideo Encoder.

Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)

Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

forward

< source >

( pixel_values_videos: Tensorpadding_mask_videos: typing.Optional[torch.Tensor] = None**kwargs ) → BaseModelOutputWithPooling or tuple(torch.Tensor)

Parâmetros

pixel_values_videos (torch.Tensor de forma (batch_size, num_frames, num_channels, frame_size, frame_size)) — Os tensores correspondentes ao vídeo de entrada. Os valores de pixels para vídeos podem ser obtidos usando PeVideoVideoProcessor. Consulte PeVideoVideoProcessor.call() para obter detalhes (PeVideoProcessor usa PeVideoVideoProcessor para processar vídeos).
padding_mask_videos (torch.Tensor de forma (batch_size, num_frames), opcional) — Máscara para evitar a execução de atenção em quadros de vídeo de preenchimento. Valores da máscara selecionados em [0, 1]:
- 1 para os quadros que não estão mascarados,
- 0 para os quadros que estão mascarados.

Retorna

BaseModelOutputWithPooling ou tuple(torch.Tensor)

Um BaseModelOutputWithPooling ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (PeVideoConfig) e das entradas.

O método forward de PeVideoEncoder substitui o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.
pooler_output (torch.Tensor de forma (batch_size, hidden_size)) — Estado oculto da última camada do primeiro token da sequência (token de classificação) após processamento adicional através das camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para a família de modelos BERT, isso retorna o token de classificação após o processamento através de uma camada linear e uma função de ativação tanh. Os pesos da camada linear são treinados a partir do objetivo de previsão da próxima frase (classificação) durante o pré-treinamento.
hidden_states (tuple(torch.Tensor), opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.Tensor (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma (batch_size, sequence_length, hidden_size).

Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, sequence_length, sequence_length).

Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.

PeVideoModel

classe transformers.PeVideoModel

< source >

( config: PeVideoConfig )

forward

< source >

( input_ids: Tensorpixel_values_videos: Tensorattention_mask: typing.Optional[torch.Tensor] = Nonepadding_mask_videos: typing.Optional[torch.Tensor] = Nonereturn_loss: bool | None = None**kwargs ) → PeVideoOutput or tuple(torch.Tensor)

Parâmetros

input_ids (torch.Tensor de formato (batch_size, sequence_length)) — Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão.
Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.

O que são IDs de entrada?
pixel_values_videos (torch.Tensor de forma (batch_size, num_frames, num_channels, frame_size, frame_size)) — Os tensores correspondentes ao vídeo de entrada. Os valores de pixels para vídeos podem ser obtidos usando PeVideoVideoProcessor. Consulte PeVideoVideoProcessor.call() para obter detalhes (PeVideoProcessor usa PeVideoVideoProcessor para processar vídeos).
attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em [0, 1]:
- 1 para tokens que não estão mascarados,
- 0 para tokens que estão mascarados.
O que são máscaras de atenção?
padding_mask_videos (torch.Tensor de forma (batch_size, num_frames), opcional) — Máscara para evitar a execução de atenção em quadros de vídeo de preenchimento. Valores da máscara selecionados em [0, 1]:
- 1 para os quadros que não estão mascarados,
- 0 para os quadros que estão mascarados.
return_loss (bool, opcional) — Indica se a perda deve ser retornada ou não.

Retorna

PeVideoOutput ou tuple(torch.Tensor)

Um PeVideoOutput ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (PeVideoConfig) e das entradas.

O método forward do PeVideoModel substitui o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

loss (torch.Tensor de forma (1,), opcional) — Perda contrastiva calculada entre as representações de vídeo e texto.
logits_video_text (torch.Tensor de forma (batch_size, batch_size), opcional) — Logits de similaridade entre embeddings de vídeo e texto.
text_video_embeds (torch.Tensor de forma (batch_size, hidden_size), opcional) — Embeddings de texto projetados para o espaço vídeo-texto.
video_embeds (torch.Tensor de forma (batch_size, hidden_size), opcional) — Embebedings de vídeo projetados no espaço vídeo-texto.
text_outputs (BaseModelOutputWithPooling, opcional) — Saídas do modelo para o codificador de texto, incluindo o último estado oculto e a saída agregada.
video_outputs (BaseModelOutputWithPooling, opcional) — Saídas do modelo para o codificador de vídeo, incluindo o último estado oculto e a saída agregada.

Update on GitHub