Transformers documentation
PE Audio Vidéo
Ce modèle a été publié dans HF papers le 2025-04-17 et ajouté à Hugging Face Transformers le 2025-12-16. Ce modèle a été publié le 2025-04-17 et ajouté à Hugging Face Transformers le 2025-12-16.
PE Audio Vidéo
PE Audio Video est la branche audio-vidéo conjointe de la famille Perception Encoder de Meta. Elle encode les flux audio et vidéo ensemble avec une tour de texte partagée, produisant des embeddings contrastifs pour chaque combinaison par paires, audio-texte, vidéo-texte, audio-vidéo et audio+texte-vidéo, à partir d'un seul passage avant.
En interne, le modèle aligne la séquence de caractéristiques vidéo sur la résolution temporelle de l’audio par interpolation du plus proche voisin, de sorte que les extraits dont les fréquences d’images et les fréquences d’échantillonnage diffèrent restent synchronisés. Les poids de l’encodeur de texte sont partagés entre les branches audio et vidéo.
Vous pouvez trouver tous les points de contrôle officiels PE Audio Video dans la collection perception-encoder-audio-visual.
Démarrage rapide
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())Conseils et notes d'utilisation
- PeAudioVideoModel nécessite au moins deux parmi
input_ids,input_values,pixel_values_videos— si seulement deux sont fournis, il délègue au sous-modèle audio uniquement ou vidéo uniquement. La transmission des trois déclenche le chemin conjoint audio-vidéo-texte et l’ensemble complet des matrices de logits dansPeAudioVideoOutput. - L’audio utilise
padding_masket la vidéo utilisepadding_mask_videossimultanément. Ce sont des masques indépendants ; ne les confondez pas avecattention_mask, qui est réservé à la tour de texte. - L’alignement audio-vidéo s’exécute par élément du lot à l’intérieur de
_align_video_hidden_state, de sorte que les lots dont les longueurs audio/vidéo varient fortement itèrent au lieu de vectoriser. Maintenez les éléments du lot approximativement équilibrés pour le débit. - Les poids de la tour de texte sont liés entre les branches via
_tied_weights_keys— ne tentez pas de charger des encodeurs de texte séparés pour les moitiés audio et vidéo.
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 )
Paramètres
- text_config (
Union[dict, ~configuration_utils.PreTrainedConfig], facultatif) — L'objet de configuration ou le dictionnaire du backbone de texte. - audio_video_config (
dictouPreTrainedConfig, facultatif) — Configuration du composant encodeur audio-vidéo. - tie_word_embeddings (
bool, facultatif, par défautTrue) — Indique s'il faut lier les embeddings de poids selon la correspondancetied_weights_keysdu modèle.
Ceci est la classe de configuration destinée à stocker la configuration d'un PeAudioVideoModel. Elle est utilisée pour instancier un modèle Pe Audio Video en fonction des arguments spécifiés, définissant ainsi l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de facebook/pe-av-large
Les objets de configuration héritent de PreTrainedConfig et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de PreTrainedConfig pour plus d’informations.
>>> 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 )
Paramètres
- audio_config (
Union[dict, ~configuration_utils.PreTrainedConfig], facultatif) — L'objet de configuration ou le dictionnaire du backbone audio. - video_config (
Union[PreTrainedConfig, dict], facultatif) — Configuration de l'encodeur vidéo. Si un dictionnaire est fourni, il est utilisé pour instancier PeVideoEncoderConfig. - hidden_size (
int, facultatif, par défaut1792) — Dimension des représentations cachées. - intermediate_size (
int, facultatif, par défaut4800) — Dimension des représentations du MLP. - num_hidden_layers (
int, facultatif, par défaut6) — Nombre de couches cachées dans le décodeur Transformer. - num_attention_heads (
int, facultatif, valeur par défaut14) — Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer. - num_key_value_heads (
int, facultatif) — Ceci est le nombre de têtes key_value à utiliser pour implémenter la Grouped Query Attention. Sinum_key_value_heads=num_attention_heads, le modèle utilisera la Multi Head Attention (MHA), sinum_key_value_heads=1le modèle utilisera la Multi Query Attention (MQA), sinon la GQA est utilisée. Lors de la conversion d'un checkpoint multi-têtes en checkpoint GQA, chaque tête clé et valeur de groupe doit être construite par moyennage (meanpooling) de toutes les têtes d'origine au sein de ce groupe. Pour plus de détails, consultez ce papier. S'il n'est pas spécifié, la valeur par défaut estnum_attention_heads. - head_dim (
int, facultatif, par défaut128) — La dimension des têtes d'attention. Si None, elle est par défaut égale à hidden_size // num_attention_heads - hidden_act (
str, facultatif, par défautsilu) — La fonction d'activation non linéaire (fonction ou chaîne de caractères) du décodeur. Par exemple,"gelu","relu","silu", etc. - max_position_embeddings (
int, facultatif, par défaut10000) — La longueur de séquence maximale avec laquelle ce modèle pourrait être utilisé. - initializer_range (
float, facultatif, par défaut0.02) — L'écart-type de la truncated_normal_initializer utilisé pour initialiser toutes les matrices de poids. - rms_norm_eps (
float, facultatif, valeur par défaut1e-05) — L'épsilon utilisé par les couches de normalisation rms. - rope_parameters (
Union[~modeling_rope_utils.RopeParameters, dict], facultatif) — Dictionnaire contenant les paramètres de configuration pour les embeddings RoPE. Le dictionnaire doit contenir une valeur pourrope_thetaet, le cas échéant, les paramètres utilisés pour le mise à l’échelle si vous souhaitez utiliser RoPE avec desmax_position_embeddingsplus longs. - attention_bias (
bool, facultatif, par défautFalse) — Indique s'il faut utiliser un biais dans les couches de projection des requêtes, des clés, des valeurs et de la sortie lors de l'auto-attention. - attention_dropout (
Union[float, int], facultatif, valeur par défaut0.0) — Le taux de dropout appliqué aux probabilités d'attention.
Ceci est la classe de configuration destinée à stocker la configuration d'un PeAudioVideoModel. Elle est utilisée pour instancier un modèle Pe Audio Video en fonction des arguments spécifiés, définissant ainsi l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de facebook/pe-av-large
Les objets de configuration héritent de PreTrainedConfig et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de PreTrainedConfig pour plus d’informations.
>>> 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 )
Paramètres
- config (PeAudioVideoEncoderConfig) — Classe de configuration du modèle contenant tous les paramètres du modèle. L’initialisation à partir d’un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode from_pretrained() pour charger les poids du modèle.
Le modèle PeAudioVideo Encoder.
Ce modèle hérite de PreTrainedModel. Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, la taille des têtes, etc.)
Ce modèle est également une sous-classe de torch.nn.Module de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l'utilisation et le comportement généraux.
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)
Paramètres
- input_values (
torch.Tensorde forme(batch_size, sequence_length), facultatif) — Valeurs flottantes de la forme d’onde brute de l’entrée audio. Les valeurs peuvent être obtenues en chargeant un fichier audio.flacou.wavdans un tableau de typelist[float], unnumpy.ndarrayou untorch.Tensor, par exemple via la bibliothèque torchcodec (pip install torchcodec) ou la bibliothèque soundfile (pip install soundfile). Pour préparer le tableau eninput_values, il faut utiliser AutoProcessor pour le bourrage (padding) et la conversion en tenseur de typetorch.Tensor. Voir PeAudioVideoProcessor.call() pour plus de détails. - pixel_values_videos (
torch.Tensorde forme(batch_size, num_frames, num_channels, frame_size, frame_size), facultatif) — Les tenseurs correspondant à la vidéo d’entrée. Les valeurs de pixels pour les vidéos peuvent être obtenues à l’aide de PeVideoVideoProcessor. Voir PeVideoVideoProcessor.call() pour plus de détails (PeAudioVideoProcessor utilise PeVideoVideoProcessor pour le traitement des vidéos). - padding_mask (
torch.Tensorde forme(batch_size, sequence_length), facultatif) — Masque pour éviter d'appliquer l'attention aux échantillons de bourrage deinput_values. Les valeurs du masque sont choisies dans[0, 1]:- 1 pour les échantillons qui ne sont pas masqués,
- 0 pour les échantillons masqués.
- padding_mask_videos (
torch.Tensorde forme(batch_size, num_frames), facultatif) — Masque pour éviter d'appliquer l'attention sur les images vidéo de bourrage. Les valeurs du masque sont choisies dans[0, 1]:- 1 pour les images qui ne sont pas masquées,
- 0 pour les images masquées.
Retourne
PeAudioVideoEncoderOutput ou tuple(torch.Tensor)
Un PeAudioVideoEncoderOutput ou un tuple de
torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers
éléments en fonction de la configuration (PeAudioVideoConfig) et des entrées.
La méthode forward de PeAudioVideoEncoder redéfinit la méthode spéciale __call__.
Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance
Moduleplutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.
last_hidden_state (
torch.Tensorde forme(batch_size, sequence_length, hidden_size)) — Séquence d'états cachés à la sortie de la dernière couche du modèle.pooler_output (
torch.Tensorde forme(batch_size, hidden_size)) — État caché de la dernière couche du premier jeton de la séquence (jeton de classification) après un traitement supplémentaire par les couches utilisées pour la tâche de pré-entraînement auxiliaire. Par exemple, pour les modèles de la famille BERT, cela renvoie le jeton de classification après traitement par une couche linéaire et une fonction d'activation tanh. Les poids de la couche linéaire sont entraînés à partir de l'objectif de prédiction de la phrase suivante (classification) pendant le pré-entraînement.hidden_states (
tuple(torch.Tensor), facultatif, renvoyé lorsqueoutput_hidden_states=Trueest passé ou lorsqueconfig.output_hidden_states=True) — Tuple detorch.Tensor(un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme(batch_size, sequence_length, hidden_size).États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives.
attentions (
tuple(torch.Tensor), facultatif, renvoyé lorsqueoutput_attentions=Trueest passé ou lorsqueconfig.output_attentions=True) — Tuple detorch.Tensor(un par couche) de forme(batch_size, num_heads, sequence_length, sequence_length).Poids des attentions après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.
audio_model_output (
BaseModelOutputWithPooling, facultatif) — Sortie de l’encodeur audio, contenant l’état caché final, la sortie agrégée et, le cas échéant, les états cachés et les attentions. Voir BaseModelOutputWithPooling pour plus de détails.video_model_output (
BaseModelOutputWithPooling, facultatif) — Sortie de l’encodeur vidéo, contenant l’état caché final, la sortie agrégée et, le cas échéant, les états cachés et les attentions. Voir BaseModelOutputWithPooling pour plus de détails.
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)
Paramètres
- input_ids (
torch.Tensorde forme(batch_size, sequence_length), facultatif) — Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut.Les indices peuvent être obtenus à l'aide de AutoTokenizer. Consultez PreTrainedTokenizer.encode() et PreTrainedTokenizer.call() pour plus de détails.
- pixel_values_videos (
torch.Tensorde forme(batch_size, num_frames, num_channels, frame_size, frame_size), facultatif) — Les tenseurs correspondant à la vidéo d’entrée. Les valeurs de pixels pour les vidéos peuvent être obtenues à l’aide de PeVideoVideoProcessor. Voir PeVideoVideoProcessor.call() pour plus de détails (PeAudioVideoProcessor utilise PeVideoVideoProcessor pour le traitement des vidéos). - input_values (
torch.Tensorde forme(batch_size, sequence_length), facultatif) — Valeurs flottantes de la forme d’onde brute de l’entrée audio. Les valeurs peuvent être obtenues en chargeant un fichier audio.flacou.wavdans un tableau de typelist[float], unnumpy.ndarrayou untorch.Tensor, par exemple via la bibliothèque torchcodec (pip install torchcodec) ou la bibliothèque soundfile (pip install soundfile). Pour préparer le tableau eninput_values, il faut utiliser AutoProcessor pour le bourrage (padding) et la conversion en tenseur de typetorch.Tensor. Voir PeAudioVideoProcessor.call() pour plus de détails. - attention_mask (
torch.Tensorde forme(batch_size, sequence_length), facultatif) — Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans[0, 1]:- 1 pour les jetons qui ne sont pas masqués,
- 0 pour les jetons masqués.
- padding_mask_videos (
torch.Tensorde forme(batch_size, num_frames), facultatif) — Masque pour éviter d'appliquer l'attention sur les images vidéo de bourrage. Les valeurs du masque sont choisies dans[0, 1]:- 1 pour les images qui ne sont pas masquées,
- 0 pour les images masquées.
- padding_mask (
torch.Tensorde forme(batch_size, sequence_length), facultatif) — Masque pour éviter d'appliquer l'attention aux échantillons de bourrage deinput_values. Les valeurs du masque sont choisies dans[0, 1]:- 1 pour les échantillons qui ne sont pas masqués,
- 0 pour les échantillons masqués.
- return_loss (
bool, facultatif) — Indique s'il faut renvoyer la perte.
Retourne
PeAudioVideoOutput ou tuple(torch.Tensor)
Un PeAudioVideoOutput ou un tuple de
torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers
éléments en fonction de la configuration (PeAudioVideoConfig) et des entrées.
La méthode forward du PeAudioVideoModel redéfinit la méthode spéciale __call__.
Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance
Moduleplutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.
- audio_embeds (
torch.Tensor, facultatif) — Embeddings de la modalité audio. Forme(batch_size, sequence_length, hidden_size). - video_embeds (
torch.Tensor, facultatif) — Embeddings de la modalité vidéo. Forme(batch_size, sequence_length, hidden_size). - audio_video_embeds (
torch.Tensor, facultatif) — Incrustations audio-vidéo conjointes produites par un module de fusion. Forme(batch_size, sequence_length, hidden_size). - text_audio_embeds (
torch.Tensor, facultatif) — Embeddings conjoints texte-audio. Forme(batch_size, sequence_length, hidden_size). - text_video_embeds (
torch.Tensor, facultatif) — Embeddings conjoints texte-vidéo. Forme(batch_size, sequence_length, hidden_size). - text_audio_video_embeds (
torch.Tensor, facultatif) — Embeddings conjoints texte-audio-vidéo combinant les trois modalités. Forme(batch_size, sequence_length, hidden_size). - audio_plus_text_embeds (
torch.Tensor, facultatif) — Incrustations combinées audio et texte (par exemple, concaténation ou fusion additive). Forme(batch_size, sequence_length, hidden_size). - video_plus_text_embeds (
torch.Tensor, facultatif) — Embeddings combinés de la vidéo et du texte. Forme(batch_size, sequence_length, hidden_size). - text_outputs (
MaskedLMOutput, facultatif) — Sorties du modèle pour l’encodeur de texte. Inclut les états cachés, les attentions et, le cas échéant, la perte. - audio_outputs (
BaseModelOutputWithPooling, facultatif) — Sorties du modèle pour l’encodeur audio, incluant l’état caché final et la sortie agrégée. - video_outputs (
BaseModelOutputWithPooling, facultatif) — Sorties du modèle pour l’encodeur vidéo, incluant l’état caché final et la sortie agrégée. - audio_video_outputs (
BaseModelOutputWithPooling, facultatif) — Sorties du modèle pour l'encodeur audio-vidéo conjoint. - logits_audio_text (
torch.Tensor, facultatif) — Logits de similarité entre les embeddings audio et texte. Forme(batch_size, batch_size). - logits_video_text (
torch.Tensor, facultatif) — Logits de similarité entre les embeddings vidéo et texte. Forme(batch_size, batch_size). - logits_audio_video (
torch.Tensor, facultatif) — Logits de similarité entre les embeddings audio et vidéo. Forme(batch_size, batch_size). - logits_audio_video_text (
torch.Tensor, facultatif) — Logits de similarité entre les modalités audio, vidéo et texte. - logits_audio_plus_text_video (
torch.Tensor, facultatif) — Logits de similarité entre les embeddings fusionnés (audio + texte) et les embeddings vidéo. - logits_video_plus_text_audio (
torch.Tensor, facultatif) — Logits de similarité entre les embeddings fusionnés (vidéo + texte) et les embeddings audio. - audio_text_loss (
torch.Tensor, facultatif) — Perte contrastive calculée entre les représentations audio et texte. - video_text_loss (
torch.Tensor, facultatif) — Perte contrastive calculée entre les représentations vidéo et texte. - audio_video_loss (
torch.Tensor, facultatif) — Perte contrastive calculée entre les représentations audio et vidéo. - audio_video_text_loss (
torch.Tensor, facultatif) — Perte conjointe sur les modalités audio, vidéo et texte. - audio_plus_text_video_loss (
torch.Tensor, facultatif) — Perte entre les représentations fusionnées (audio + texte) et la vidéo. - video_plus_text_audio_loss (
torch.Tensor, facultatif) — Perte entre les représentations fusionnées (vidéo + texte) et l’audio. - loss (
torch.Tensor, facultatif) — Perte combinée de toutes les pertes par modalité.