Transformers documentation
PE Audio Video
Este modelo se publicó en HF papers el 17 de abril de 2025 y se contribuyó a Hugging Face Transformers el 16 de diciembre de 2025. Este modelo se lanzó el 17 de abril de 2025 y se añadió a Hugging Face Transformers el 16 de diciembre de 2025.
PE Audio Video
PE Audio Video es la rama conjunta de audio y vídeo de la familia Perception Encoder de Meta. Codifica flujos de audio y vídeo junto con una torre de texto compartida, generando embeddings contrastivos para cada combinación por pares, audio-texto, vídeo-texto, audio-vídeo y audio+texto-vídeo, a partir de una única pasada hacia adelante.
Internamente, el modelo alinea la secuencia de características del video con la resolución temporal del audio mediante interpolación de vecino más cercano, de modo que los clips con tasas de fotogramas diferentes a las tasas de muestreo se mantengan sincronizados. Los pesos del codificador de texto están vinculados entre las ramas de audio y video.
Puedes encontrar todos los puntos de control oficiales de PE Audio Video en la colección perception-encoder-audio-visual.
Introducción
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())Consejos y notas de uso
- PeAudioVideoModel requiere al menos dos de
input_ids,input_values,pixel_values_videos: si solo se proporcionan dos, se enruta al submodelo de solo audio o de solo video. Si se pasan los tres, se activa la ruta conjunta de audio, video y texto, así como el conjunto completo de matrices de logits enPeAudioVideoOutput. - El audio utiliza
padding_masky el video utilizapadding_mask_videossimultáneamente. Son máscaras independientes; no las confunda conattention_mask, que está reservada para la torre de texto. - La alineación de audio y vídeo se ejecuta por elemento del lote dentro de
_align_video_hidden_state, por lo que los lotes con longitudes de audio/vídeo muy diferentes se itera en lugar de vectorizar. Mantenga los elementos del lote aproximadamente equilibrados para mejorar el rendimiento. - Los pesos de la torre de texto están vinculados entre las ramas mediante
_tied_weights_keys; no intente cargar codificadores de texto separados para las mitades de audio y video.
PeAudioVideoConfig
clase 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) — El objeto de configuración o el diccionario del backbone de texto. - audio_video_config (
dictoPreTrainedConfig, opcional) — Configuración para el componente codificador de audio y video. - tie_word_embeddings (
bool, opcional, valor predeterminadoTrue) — Si se deben vincular las matrices de pesos de embeddings según el mapeotied_weights_keysdel modelo.
Esta es la clase de configuración para almacenar la configuración de un PeAudioVideoModel. Se utiliza para instanciar un modelo Pe Audio Video según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de facebook/pe-av-large
Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.
>>> 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
clase 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) — El objeto de configuración o el diccionario del backbone de audio. - video_config (
Union[PreTrainedConfig, dict], opcional) — Configuración para el codificador de video. Si se proporciona un diccionario, se utiliza para instanciar PeVideoEncoderConfig. - hidden_size (
int, opcional, valor predeterminado1792) — Dimensión de las representaciones ocultas. - intermediate_size (
int, opcional, valor predeterminado4800) — Dimensión de las representaciones del MLP. - num_hidden_layers (
int, opcional, valor predeterminado6) — Número de capas ocultas en el decodificador Transformer. - num_attention_heads (
int, opcional, valor predeterminado14) — Número de cabezas de atención para cada capa de atención en el decodificador Transformer. - num_key_value_heads (
int, opcional) — Este es el número de cabezas de key_value que se deben utilizar para implementar Grouped Query Attention. Sinum_key_value_heads=num_attention_heads, el modelo utilizará Multi Head Attention (MHA); sinum_key_value_heads=1, el modelo utilizará Multi Query Attention (MQA); en caso contrario, se utilizará GQA. Al convertir un checkpoint multi-head en un checkpoint GQA, cada cabeza de key y value del grupo debe construirse mediante el promedio (meanpooling) de todas las cabezas originales dentro de ese grupo. Para más detalles, consulta este artículo. Si no se especifica, el valor predeterminado seránum_attention_heads. - head_dim (
int, opcional, valor predeterminado128) — La dimensión de la cabeza de atención. Si es None, se establecerá en hidden_size // num_attention_heads - hidden_act (
str, opcional, valor predeterminadosilu) — La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo,"gelu","relu","silu", etc. - max_position_embeddings (
int, opcional, valor predeterminado10000) — La longitud máxima de secuencia con la que se podría utilizar este modelo. - initializer_range (
float, opcional, valor predeterminado0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos. - rms_norm_eps (
float, opcional, valor predeterminado1e-05) — La epsilon utilizada por las capas de normalización rms. - rope_parameters (
Union[~modeling_rope_utils.RopeParameters, dict], opcional) — Diccionario que contiene los parámetros de configuración para las incrustaciones RoPE. El diccionario debe contener un valor pararope_thetay, opcionalmente, parámetros utilizados para el escalado en caso de que desee usar RoPE conmax_position_embeddingsmás largos. - attention_bias (
bool, opcional, valor predeterminadoFalse) — Si se debe usar un sesgo en las capas de proyección de consulta, clave, valor y salida durante la autoatención. - attention_dropout (
Union[float, int], opcional, valor predeterminado0.0) — La proporción de dropout para las probabilidades de atención.
Esta es la clase de configuración para almacenar la configuración de un PeAudioVideoModel. Se utiliza para instanciar un modelo Pe Audio Video según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de facebook/pe-av-large
Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.
>>> 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
clase transformers.PeAudioVideoProcessor
< source >( feature_extractor = Nonevideo_processor = Nonetokenizer = None**kwargs )
PeAudioVideoEncoder
clase transformers.PeAudioVideoEncoder
< source >( config: PeAudioVideoEncoderConfig )
Parámetros
- config (PeAudioVideoEncoderConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.
El modelo PeAudioVideo Encoder.
Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).
Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.
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 flotantes de la forma de onda de audio cruda de entrada. Los valores se pueden obtener cargando un archivo de audio.flaco.waven un array de tipolist[float], unnumpy.ndarrayo untorch.Tensor, por ejemplo mediante la biblioteca torchcodec (pip install torchcodec) o la biblioteca soundfile (pip install soundfile). Para preparar el array comoinput_values, se debe utilizar AutoProcessor para el relleno y la conversión a un tensor de tipotorch.Tensor. Consulte PeAudioVideoProcessor.call() para más detalles. - pixel_values_videos (
torch.Tensorde forma(batch_size, num_frames, num_channels, frame_size, frame_size), opcional) — Los tensores correspondientes al video de entrada. Los valores de píxel para videos se pueden obtener utilizando PeVideoVideoProcessor. Consulte PeVideoVideoProcessor.call() para más detalles (PeAudioVideoProcessor utiliza PeVideoVideoProcessor para procesar videos). - padding_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en las muestras de relleno deinput_values. Los valores de la máscara seleccionados en[0, 1]:- 1 para las muestras que no están enmascaradas,
- 0 para las muestras que están enmascaradas.
- padding_mask_videos (
torch.Tensorde forma(batch_size, num_frames), opcional) — Máscara para evitar realizar atención en los fotogramas de relleno del video. Valores de la máscara seleccionados en[0, 1]:- 1 para los fotogramas que no están enmascarados,
- 0 para los fotogramas que están mascarados.
Devuelve
PeAudioVideoEncoderOutput o tuple(torch.Tensor)
Un PeAudioVideoEncoderOutput o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (PeAudioVideoConfig) y las entradas.
El método forward de PeAudioVideoEncoder reemplaza el método especial __call__.
Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de
Moduledespués en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.
last_hidden_state (
torch.Tensorde forma(batch_size, sequence_length, hidden_size)) — Secuencia de estados ocultos en la salida de la última capa del modelo.pooler_output (
torch.Tensorde forma(batch_size, hidden_size)) — Estado oculto de la última capa del primer token de la secuencia (token de clasificación) después de un procesamiento adicional a través de las capas utilizadas para la tarea de preentrenamiento auxiliar. Por ejemplo, para la familia de modelos BERT, esto devuelve el token de clasificación después de procesarlo a través de una capa lineal y una función de activación tanh. Los pesos de la capa lineal se entrenan a partir del objetivo de predicción de la siguiente oración (clasificación) durante el preentrenamiento.hidden_states (
tuple(torch.Tensor), opcional, devuelto cuando se pasaoutput_hidden_states=Trueo cuandoconfig.output_hidden_states=True) — Tupla detorch.Tensor(una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma(batch_size, sequence_length, hidden_size).Estados ocultos del modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.
attentions (
tuple(torch.Tensor), opcional, se devuelve cuando se pasaoutput_attentions=Trueo cuandoconfig.output_attentions=True) — Tupla detorch.Tensor(una por cada capa) de forma(batch_size, num_heads, sequence_length, sequence_length).Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
audio_model_output (
BaseModelOutputWithPooling, opcional) — Salida del codificador de audio, que contiene el último estado oculto, la salida agrupada y los estados ocultos y las atenciones opcionales. Consulte BaseModelOutputWithPooling para obtener más detalles.video_model_output (
BaseModelOutputWithPooling, opcional) — Salida del codificador de video, que contiene el último estado oculto, la salida agrupada y los estados ocultos y las atenciones opcionales. Consulte BaseModelOutputWithPooling para más detalles.
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 forma(batch_size, sequence_length), opcional) — Índices de los tokens de la secuencia de entrada en el vocabulario. El relleno se ignorará de forma predeterminada.Los índices se pueden obtener usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() y PreTrainedTokenizer.call() para más detalles.
- pixel_values_videos (
torch.Tensorde forma(batch_size, num_frames, num_channels, frame_size, frame_size), opcional) — Los tensores correspondientes al video de entrada. Los valores de píxel para videos se pueden obtener utilizando PeVideoVideoProcessor. Consulte PeVideoVideoProcessor.call() para más detalles (PeAudioVideoProcessor utiliza PeVideoVideoProcessor para procesar videos). - input_values (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Valores flotantes de la forma de onda de audio cruda de entrada. Los valores se pueden obtener cargando un archivo de audio.flaco.waven un array de tipolist[float], unnumpy.ndarrayo untorch.Tensor, por ejemplo mediante la biblioteca torchcodec (pip install torchcodec) o la biblioteca soundfile (pip install soundfile). Para preparar el array comoinput_values, se debe utilizar AutoProcessor para el relleno y la conversión a un tensor de tipotorch.Tensor. Consulte PeAudioVideoProcessor.call() para más detalles. - attention_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en los índices de tokens de relleno. Valores de máscara seleccionados en[0, 1]:- 1 para los tokens que no están enmascarados,
- 0 para los tokens que están enmascarados.
- padding_mask_videos (
torch.Tensorde forma(batch_size, num_frames), opcional) — Máscara para evitar realizar atención en los fotogramas de relleno del video. Valores de la máscara seleccionados en[0, 1]:- 1 para los fotogramas que no están enmascarados,
- 0 para los fotogramas que están mascarados.
- padding_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en las muestras de relleno deinput_values. Los valores de la máscara seleccionados en[0, 1]:- 1 para las muestras que no están enmascaradas,
- 0 para las muestras que están enmascaradas.
- return_loss (
bool, opcional) — Indica si se debe devolver la pérdida.
Devuelve
PeAudioVideoOutput o tuple(torch.Tensor)
Un PeAudioVideoOutput o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (PeAudioVideoConfig) y las entradas.
El método forward de PeAudioVideoModel reemplaza el método especial __call__.
Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de
Moduledespués en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.
- audio_embeds (
torch.Tensor, opcional) — Embeddings de la modalidad de audio. Forma(batch_size, sequence_length, hidden_size). - video_embeds (
torch.Tensor, opcional) — Embeddings de la modalidad de video. Forma(batch_size, sequence_length, hidden_size). - audio_video_embeds (
torch.Tensor, opcional) — Incrustaciones conjuntas de audio y vídeo generadas por un módulo de fusión. Forma(batch_size, sequence_length, hidden_size). - text_audio_embeds (
torch.Tensor, opcional) — Incrustaciones conjuntas de texto y audio. Forma(batch_size, sequence_length, hidden_size). - text_video_embeds (
torch.Tensor, opcional) — Incrustaciones conjuntas de texto y vídeo. Forma(batch_size, sequence_length, hidden_size). - text_audio_video_embeds (
torch.Tensor, opcional) — Incrustaciones conjuntas de texto, audio y video que combinan las tres modalidades. Forma(batch_size, sequence_length, hidden_size). - audio_plus_text_embeds (
torch.Tensor, opcional) — Incrustaciones combinadas de audio y texto (p. ej., concatenación o fusión aditiva). Forma(batch_size, sequence_length, hidden_size). - video_plus_text_embeds (
torch.Tensor, opcional) — Embeddings combinados de video y texto. Forma(batch_size, sequence_length, hidden_size). - text_outputs (
MaskedLMOutput, opcional) — Salidas del modelo para el codificador de texto. Incluye estados ocultos, atenciones y, opcionalmente, la pérdida. - audio_outputs (
BaseModelOutputWithPooling, opcional) — Salidas del modelo para el codificador de audio, que incluyen el último estado oculto y la salida agrupada. - video_outputs (
BaseModelOutputWithPooling, opcional) — Salidas del modelo para el codificador de video, que incluyen el último estado oculto y la salida agrupada. - audio_video_outputs (
BaseModelOutputWithPooling, opcional) — Salidas del modelo para el codificador conjunto de audio y video. - logits_audio_text (
torch.Tensor, opcional) — Logits de similitud entre los embeddings de audio y texto. Forma(batch_size, batch_size). - logits_video_text (
torch.Tensor, opcional) — Logits de similitud entre los embeddings de video y texto. Forma(batch_size, batch_size). - logits_audio_video (
torch.Tensor, opcional) — Logits de similitud entre los embeddings de audio y video. Forma(batch_size, batch_size). - logits_audio_video_text (
torch.Tensor, opcional) — Logits de similitud entre las modalidades de audio, vídeo y texto. - logits_audio_plus_text_video (
torch.Tensor, opcional) — Logits de similitud entre los embeddings fusionados (audio + texto) y los embeddings de video. - logits_video_plus_text_audio (
torch.Tensor, opcional) — Logits de similitud entre los embeddings fusionados (video + texto) y los embeddings de audio. - audio_text_loss (
torch.Tensor, opcional) — Pérdida contrastiva calculada entre las representaciones de audio y texto. - video_text_loss (
torch.Tensor, opcional) — Pérdida contrastiva calculada entre las representaciones de video y texto. - audio_video_loss (
torch.Tensor, opcional) — Pérdida contrastiva calculada entre las representaciones de audio y video. - audio_video_text_loss (
torch.Tensor, opcional) — Pérdida conjunta sobre las modalidades de audio, vídeo y texto. - audio_plus_text_video_loss (
torch.Tensor, opcional) — Pérdida entre las representaciones fusionadas (audio + texto) y el video. - video_plus_text_audio_loss (
torch.Tensor, opcional) — Pérdida entre las representaciones fusionadas (video + texto) y el audio. - loss (
torch.Tensor, opcional) — Pérdida combinada de todas las pérdidas por modalidad.