Transformers documentation
PE Áudio Vídeo
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 Áudio Vídeo
PE Audio Video é o ramo conjunto de áudio e vídeo da família Perception Encoder da Meta. Ele codifica fluxos de áudio e vídeo juntos com uma torre de texto compartilhada, produzindo embeddings contrastivos para todas as combinações em pares, áudio-texto, vídeo-texto, áudio-vídeo e áudio+texto-vídeo, a partir de uma única passagem direta.
Internamente, o modelo alinha a sequência de recursos do vídeo à resolução temporal do áudio por meio de interpolação de vizinho mais próximo, de modo que clipes com taxas de quadros diferentes das taxas de amostragem permaneçam sincronizados. Os pesos do codificador de texto são compartilhados entre os ramos de áudio e vídeo.
Você pode encontrar todos os checkpoints oficiais de PE Audio Video na coleção perception-encoder-audio-visual.
Início rápido
import torch
from datasets import load_dataset
from transformers import AutoProcessor, PeAudioVideoModel
from transformers.video_utils import load_video
processor = AutoProcessor.from_pretrained("facebook/pe-av-large")
model = PeAudioVideoModel.from_pretrained(
"facebook/pe-av-large",
device_map="auto",
)
ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
audio = ds[0]["audio"]["array"]
video, _ = load_video("https://huggingface.co/datasets/hf-internal-testing/fixtures_videos/resolve/main/tennis.mp4")
labels = ["a person playing tennis with background crowd", "a dog barking in a park"]
audio_inputs = processor.feature_extractor(audio, sampling_rate=48_000, return_tensors="pt").to(model.device)
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 = {**audio_inputs, **video_inputs, **text_inputs}
with torch.no_grad():
outputs = model(**inputs)
print("audio-text:", outputs.logits_audio_text.sigmoid().tolist())
print("video-text:", outputs.logits_video_text.sigmoid().tolist())
print("audio-video:", outputs.logits_audio_video.sigmoid().tolist())Dicas e observações de uso
- PeAudioVideoModel requer pelo menos dois de
input_ids,input_values,pixel_values_videos— se apenas dois forem fornecidos, ele direciona para o submodelo somente de áudio ou somente de vídeo. Passar os três ativa o caminho conjunto de áudio-vídeo-texto e o conjunto completo de matrizes de logits emPeAudioVideoOutput. - O áudio usa
padding_maske o vídeo usapadding_mask_videossimultaneamente. São máscaras independentes; não as confunda comattention_mask, que é reservada para a torre de texto. - O alinhamento de áudio e vídeo é executado por elemento do lote dentro de
_align_video_hidden_state, de modo que lotes com comprimentos de áudio/vídeo muito diferentes itera em vez de vetorizar. Mantenha os itens do lote aproximadamente equilibrados para garantir o desempenho. - Os pesos da torre de texto são compartilhados entre os ramos por meio de
_tied_weights_keys— não tente carregar codificadores de texto separados para as metades de áudio e vídeo.
PeAudioVideoConfig
classe transformers.PeAudioVideoConfig
< 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 = Nonetext_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneaudio_video_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonetie_word_embeddings: bool = True )
Parâmetros
- text_config (
Union[dict, ~configuration_utils.PreTrainedConfig], opcional) — O objeto de configuração ou dicionário do backbone de texto. - audio_video_config (
dictouPreTrainedConfig, opcional) — Configuração para o componente codificador de áudio e vídeo. - tie_word_embeddings (
bool, opcional, padrãoTrue) — Se deve vincular as embeddings de pesos de acordo com o mapeamentotied_weights_keysdo modelo.
Esta é a classe de configuração para armazenar a configuração de um PeAudioVideoModel. Ela é usada para instanciar um modelo Pe Audio 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 PeAudioVideoModel, PeAudioVideoConfig
>>> # Initializing a PeAudioVideoModel style configuration
>>> configuration = PeAudioVideoConfig()
>>> # Initializing a model from the pe-av-large style configuration
>>> model = PeAudioModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configPeAudioVideoEncoderConfig
classe transformers.PeAudioVideoEncoderConfig
< 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 = Noneaudio_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonevideo_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
- audio_config (
Union[dict, ~configuration_utils.PreTrainedConfig], opcional) — O objeto de configuração ou dicionário do backbone de áudio. - video_config (
Union[PreTrainedConfig, dict], opcional) — Configuração para o codificador de vídeo. Se um dicionário for fornecido, ele será usado para instanciar PeVideoEncoderConfig. - hidden_size (
int, opcional, padrão1792) — Dimensão das representações ocultas. - intermediate_size (
int, opcional, padrão4800) — Dimensão das representações do MLP. - num_hidden_layers (
int, opcional, padrão6) — Número de camadas ocultas no decodificador do Transformer. - num_attention_heads (
int, opcional, padrão14) — 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. Senum_key_value_heads=num_attention_heads, o modelo usará Multi Head Attention (MHA); senum_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ão128) — 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ãosilu) — 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ão10000) — O comprimento máximo de sequência com o qual este modelo pode ser utilizado. - initializer_range (
float, opcional, padrão0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos. - rms_norm_eps (
float, opcional, padrão1e-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 pararope_thetae, opcionalmente, parâmetros usados para escalonamento, caso você queira usar RoPE commax_position_embeddingsmaiores. - attention_bias (
bool, opcional, padrãoFalse) — 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ão0.0) — A taxa de dropout para as probabilidades de atenção.
Esta é a classe de configuração para armazenar a configuração de um PeAudioVideoModel. Ela é usada para instanciar um modelo Pe Audio 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 PeAudioVideoEncoder, PeAudioVideoEncoderConfig
>>> # Initializing a PeAudioVideoEncoder style configuration
>>> configuration = PeAudioVideoEncoderConfig()
>>> # Initializing a model from the pe-av-large style configuration
>>> model = PeAudioVideoEncoder(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configPeAudioVideoProcessor
classe transformers.PeAudioVideoProcessor
< source >( feature_extractor = Nonevideo_processor = Nonetokenizer = None**kwargs )
PeAudioVideoEncoder
classe transformers.PeAudioVideoEncoder
< source >( config: PeAudioVideoEncoderConfig )
Parâmetros
- config (PeAudioVideoEncoderConfig) — 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 PeAudioVideo 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 >( input_values: typing.Optional[torch.Tensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Nonepadding_mask: typing.Optional[torch.Tensor] = Nonepadding_mask_videos: typing.Optional[torch.Tensor] = None**kwargs ) → PeAudioVideoEncoderOutput or tuple(torch.Tensor)
Parâmetros
- input_values (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Valores em ponto flutuante da forma de onda bruta de fala de entrada. Os valores podem ser obtidos carregando um arquivo de áudio.flacou.wavem um array do tipolist[float], umnumpy.ndarrayou umtorch.Tensor, por exemplo, por meio da biblioteca torchcodec (pip install torchcodec) ou da biblioteca soundfile (pip install soundfile). Para preparar o array parainput_values, o AutoProcessor deve ser usado para padding e conversão em um tensor do tipotorch.Tensor. Consulte PeAudioVideoProcessor.call() para mais detalhes. - pixel_values_videos (
torch.Tensorde forma(batch_size, num_frames, num_channels, frame_size, frame_size), opcional) — Os tensores correspondentes ao vídeo de entrada. Os valores de pixels para vídeos podem ser obtidos usando PeVideoVideoProcessor. Consulte PeVideoVideoProcessor.call() para detalhes (PeAudioVideoProcessor usa PeVideoVideoProcessor para processar vídeos). - padding_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção em amostras de preenchimento deinput_values. Valores de máscara selecionados em[0, 1]:- 1 para amostras que não estão mascaradas,
- 0 para amostras que estão mascaradas.
- padding_mask_videos (
torch.Tensorde 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
PeAudioVideoEncoderOutput ou tuple(torch.Tensor)
Uma PeAudioVideoEncoderOutput 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 (PeAudioVideoConfig) e das entradas.
O método forward de PeAudioVideoEncoder 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
Moduleem 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.Tensorde forma(batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.pooler_output (
torch.Tensorde 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 quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.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 quandooutput_attentions=Trueé passado ou quandoconfig.output_attentions=True) — Tupla detorch.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.
audio_model_output (
BaseModelOutputWithPooling, opcional) — Saída do codificador de áudio, contendo o último estado oculto, a saída agregada e estados ocultos e atenções opcionais. Consulte BaseModelOutputWithPooling para mais detalhes.video_model_output (
BaseModelOutputWithPooling, opcional) — Saída do codificador de vídeo, contendo o último estado oculto, a saída agregada e estados ocultos e atenções opcionais. Consulte BaseModelOutputWithPooling para mais detalhes.
PeAudioVideoModel
forward
< source >( input_ids: typing.Optional[torch.Tensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Noneinput_values: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Nonepadding_mask_videos: typing.Optional[torch.Tensor] = Nonepadding_mask: typing.Optional[torch.Tensor] = Nonereturn_loss = False**kwargs ) → PeAudioVideoOutput or tuple(torch.Tensor)
Parâmetros
- input_ids (
torch.Tensorde formato(batch_size, sequence_length), opcional) — Índices dos tokens da sequência de entrada no vocabulário. O padding será ignorado por padrão.Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.
- pixel_values_videos (
torch.Tensorde forma(batch_size, num_frames, num_channels, frame_size, frame_size), opcional) — Os tensores correspondentes ao vídeo de entrada. Os valores de pixels para vídeos podem ser obtidos usando PeVideoVideoProcessor. Consulte PeVideoVideoProcessor.call() para detalhes (PeAudioVideoProcessor usa PeVideoVideoProcessor para processar vídeos). - input_values (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Valores em ponto flutuante da forma de onda bruta de fala de entrada. Os valores podem ser obtidos carregando um arquivo de áudio.flacou.wavem um array do tipolist[float], umnumpy.ndarrayou umtorch.Tensor, por exemplo, por meio da biblioteca torchcodec (pip install torchcodec) ou da biblioteca soundfile (pip install soundfile). Para preparar o array parainput_values, o AutoProcessor deve ser usado para padding e conversão em um tensor do tipotorch.Tensor. Consulte PeAudioVideoProcessor.call() para mais detalhes. - attention_mask (
torch.Tensorde 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.
- padding_mask_videos (
torch.Tensorde 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.
- padding_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção em amostras de preenchimento deinput_values. Valores de máscara selecionados em[0, 1]:- 1 para amostras que não estão mascaradas,
- 0 para amostras que estão mascaradas.
- return_loss (
bool, opcional) — Indica se a perda deve ser retornada ou não.
Retorna
PeAudioVideoOutput ou tuple(torch.Tensor)
Um PeAudioVideoOutput 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 (PeAudioVideoConfig) e das entradas.
O método forward do PeAudioVideoModel 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
Moduleem 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.
- audio_embeds (
torch.Tensor, opcional) — Embeddings da modalidade de áudio. Formato(batch_size, sequence_length, hidden_size). - video_embeds (
torch.Tensor, opcional) — Embeddings da modalidade de vídeo. Formato(batch_size, sequence_length, hidden_size). - audio_video_embeds (
torch.Tensor, opcional) — Embeddings conjuntos de áudio e vídeo produzidos por um módulo de fusão. Formato(batch_size, sequence_length, hidden_size). - text_audio_embeds (
torch.Tensor, opcional) — Incorporações conjuntas de texto e áudio. Formato(batch_size, sequence_length, hidden_size). - text_video_embeds (
torch.Tensor, opcional) — Incorporações conjuntas de texto e vídeo. Formato(batch_size, sequence_length, hidden_size). - text_audio_video_embeds (
torch.Tensor, opcional) — Embeddings conjuntos de texto, áudio e vídeo que combinam as três modalidades. Formato(batch_size, sequence_length, hidden_size). - audio_plus_text_embeds (
torch.Tensor, opcional) — Embeddings combinados de áudio e texto (por exemplo, concatenação ou fusão aditiva). Formato(batch_size, sequence_length, hidden_size). - video_plus_text_embeds (
torch.Tensor, opcional) — Embeddings combinados de vídeo e texto. Formato(batch_size, sequence_length, hidden_size). - text_outputs (
MaskedLMOutput, opcional) — Saídas do modelo para o codificador de texto. Inclui estados ocultos, atenções e, opcionalmente, a perda. - audio_outputs (
BaseModelOutputWithPooling, opcional) — Saídas do modelo para o codificador de áudio, 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. - audio_video_outputs (
BaseModelOutputWithPooling, opcional) — Saídas do modelo para o codificador conjunto de áudio e vídeo. - logits_audio_text (
torch.Tensor, opcional) — Logits de similaridade entre embeddings de áudio e texto. Formato(batch_size, batch_size). - logits_video_text (
torch.Tensor, opcional) — Logits de similaridade entre embeddings de vídeo e texto. Formato(batch_size, batch_size). - logits_audio_video (
torch.Tensor, opcional) — Logits de similaridade entre os embeddings de áudio e vídeo. Formato(batch_size, batch_size). - logits_audio_video_text (
torch.Tensor, opcional) — Logits de similaridade entre as modalidades de áudio, vídeo e texto. - logits_audio_plus_text_video (
torch.Tensor, opcional) — Logits de similaridade entre os embeddings fundidos (áudio + texto) e os embeddings de vídeo. - logits_video_plus_text_audio (
torch.Tensor, opcional) — Logits de similaridade entre os embeddings fundidos (vídeo + texto) e os embeddings de áudio. - audio_text_loss (
torch.Tensor, opcional) — Perda contrastiva calculada entre as representações de áudio e texto. - video_text_loss (
torch.Tensor, opcional) — Perda contrastiva calculada entre as representações de vídeo e texto. - audio_video_loss (
torch.Tensor, opcional) — Perda contrastiva calculada entre as representações de áudio e vídeo. - audio_video_text_loss (
torch.Tensor, opcional) — Perda conjunta sobre as modalidades de áudio, vídeo e texto. - audio_plus_text_video_loss (
torch.Tensor, opcional) — Perda entre as representações fundidas (áudio + texto) e o vídeo. - video_plus_text_audio_loss (
torch.Tensor, opcional) — Perda entre as representações fundidas (vídeo + texto) e o áudio. - loss (
torch.Tensor, opcional) — Perda combinada para todas as perdas por modalidade.