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 Vidéo

PE Video est la branche vidéo de la famille Perception Encoder de Meta. Il aligne de manière contrastive des clips vidéo et du texte dans un espace d’embeddings partagé, permettant la classification vidéo en zéro tir et la récupération vidéo–texte à partir d’un seul backbone pré-entraîné.

Les embeddings rotationnels de l’encodeur et son embedder de patches traitent l’axe temporel comme une dimension à part entière, ce qui permet d’encoder des clips de longueur variable sans avoir à tuiler chaque image indépendamment.

Vous pouvez trouver tous les points de contrôle officiels de PE Audio dans la collection perception-encoder-audio-visual.

Démarrage rapide

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])})

Conseils et notes d'utilisation

Les vidéos de longueur variable utilisent padding_mask_videos (et non attention_mask). Le processeur de vidéo n’effectue le bourrage et ne renvoie ce masque que si return_tensors est défini — sans cela, vous obtenez une liste de tenseurs par clip et aucun masque.
Passez num_frames au processeur vidéo pour un échantillonnage uniforme de longueur fixe sur [0, total_frames-1]. Omettez-le pour revenir à l’échantillonnage basé sur le fps de la classe de base. Les points de contrôle sont généralement entraînés avec un nombre de frames spécifique, donc alignez-vous sur ce que le point de contrôle attend.
L’entrée de l’encodeur est pixel_values_videos. Le main_input_name de l’encodeur est "pixel_values_videos", tandis que celui du modèle complet est "input_ids", ce qui est important lors du routage via des utilitaires génériques qui inspectent main_input_name.

PeVideoConfig

classe transformers.PeVideoConfig

< source >

Paramètres

text_config (Union[dict, ~configuration_utils.PreTrainedConfig], facultatif) — L'objet de configuration ou le dictionnaire du backbone de texte.
video_config (dict ou PreTrainedConfig, facultatif) — Configuration du composant encodeur vidéo.

Ceci est la classe de configuration destinée à stocker la configuration d'un PeVideoModel. Elle est utilisée pour instancier un modèle Pe 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 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 )

Paramètres

vision_config (Union[dict, ~configuration_utils.PreTrainedConfig], facultatif) — L'objet de configuration ou le dictionnaire du backbone visuel.
hidden_size (int, facultatif, par défaut 1792) — Dimension des représentations cachées.
intermediate_size (int, facultatif, par défaut 4800) — Dimension des représentations du MLP.
num_hidden_layers (int, facultatif, par défaut 6) — Nombre de couches cachées dans le décodeur Transformer.
num_attention_heads (int, facultatif, valeur par défaut 14) — 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. Si num_key_value_heads=num_attention_heads, le modèle utilisera la Multi Head Attention (MHA), si num_key_value_heads=1 le 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 est num_attention_heads.
head_dim (int, facultatif, par défaut 128) — 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éfaut silu) — 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éfaut 10000) — La longueur de séquence maximale avec laquelle ce modèle pourrait être utilisé.
initializer_range (float, facultatif, par défaut 0.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éfaut 1e-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 pour rope_theta et, le cas échéant, les paramètres utilisés pour le mise à l’échelle si vous souhaitez utiliser RoPE avec des max_position_embeddings plus longs.
attention_bias (bool, facultatif, par défaut False) — 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éfaut 0.0) — Le taux de dropout appliqué aux probabilités d'attention.

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.

Exemple :

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

Paramètres

do_convert_rgb (bool, kwargs, facultatif) — Indique s'il faut convertir l'image en RGB.
do_resize (bool, kwargs, facultatif) — Indique s'il faut redimensionner l'image.
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Définit les dimensions maximales des entrées du modèle.
default_to_square (bool, kwargs, facultatif, valeur par défaut True) — Indique s'il faut utiliser une image carrée par défaut lors du redimensionnement, si la taille est un entier.
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs, par défaut 2) — Filtre de rééchantillonnage à utiliser lors du redimensionnement de l’image. Il peut s’agir de l’une des valeurs de l’enum PILImageResampling. N’a un effet que si do_resize est défini sur True.
do_rescale (bool, kwargs, facultatif) — Indique s'il faut rééchelonner l'image.
rescale_factor (float, kwargs, facultatif, valeur par défaut 0.00392156862745098) — Facteur de remise à l'échelle appliqué à l'image si do_rescale est défini sur True.
do_normalize (bool, kwargs, facultatif) — Indique s'il faut normaliser l'image.
image_mean (Union[float, list[float], tuple[float, ...]], kwargs, facultatif) — Moyenne de l'image à utiliser pour la normalisation. N'a un effet que si do_normalize est défini sur True.
image_std (Union[float, list[float], tuple[float, ...]], kwargs, facultatif) — Écart-type de l'image à utiliser pour la normalisation. N'a un effet que si do_normalize est défini sur True.
do_center_crop (bool, kwargs, facultatif) — Indique s'il faut effectuer un recadrage centré de l'image.
do_pad (bool, kwargs, facultatif) — Indique s'il faut effectuer un bourrage (padding) de l'image. Le bourrage est effectué soit jusqu'à la plus grande taille du lot, soit jusqu'à une taille carrée fixe par image. La stratégie de bourrage exacte dépend du modèle.
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Taille de l'image de sortie après application de center_crop.
data_format (Union[str, ~image_utils.ChannelDimension], kwargs, facultatif) — Seul ChannelDimension.FIRST est pris en charge. Ajouté pour la compatibilité avec les processeurs lents.
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, facultatif) — Le format de la dimension des canaux pour l'image d'entrée. Si non défini, le format de la dimension des canaux est déduit de l'image d'entrée. Peut être l'un des éléments suivants :
- "channels_first" ou ChannelDimension.FIRST : image au format (num_channels, height, width).
- "channels_last" ou ChannelDimension.LAST : image au format (hauteur, largeur, nombre de canaux).
- "none" ou ChannelDimension.NONE : image au format (hauteur, largeur).
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — L’appareil sur lequel traiter les vidéos. Si non défini, l’appareil est déduit des vidéos d’entrée.
do_sample_frames (bool, kwargs, facultatif) — Indique s'il faut échantillonner des images de la vidéo avant le traitement ou traiter la vidéo entière.
video_metadata (Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — Métadonnées de la vidéo contenant des informations sur la durée totale, le fps et le nombre total d’images. Elles seront utilisées pour échantillonner des images de la vidéo ou calculer des horodatages. Ne passez aucune métadonnée à moins de chercher à décoder la vidéo manuellement avant le traitement
fps (Annotated[int | float | None, None], kwargs) — Nombre de cibles d'images à échantillonner par seconde lorsque do_sample_frames=True.
num_frames (Annotated[int | None, None], kwargs) — Nombre maximal de frames à échantillonner lorsque do_sample_frames=True.
return_metadata (bool, kwargs, facultatif, par défaut False) — Indique s'il faut renvoyer les métadonnées de la vidéo ou non. Les métadonnées vidéo sont un objet contenant des informations sur la durée de la vidéo, le fps, le backend de décodage, etc.
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Si défini, renvoie des tenseurs d'un framework particulier. Les valeurs acceptables sont :
- 'pt' : Renvoie des objets torch.Tensor de PyTorch.
- 'np' : Renvoie des objets NumPy np.ndarray.
**kwargs (VideosKwargs, facultatif) — Options de traitement supplémentaires pour chaque modalité (texte, images, vidéos, audio). Les paramètres spécifiques au modèle sont répertoriés ci-dessus ; consultez la classe TypedDict pour la liste complète des arguments pris en charge.

Construit un processeur vidéo PeVideoVideoProcessor.

PeVideoProcessor

classe transformers.PeVideoProcessor

< source >

( *args**kwargs )

PeVideoEncoder

classe transformers.PeVideoEncoder

< source >

( config: PeVideoEncoderConfig )

Paramètres

config (PeVideoEncoderConfig) — 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 PeVideo 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 >

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

Paramètres

pixel_values_videos (torch.Tensor de forme (batch_size, num_frames, num_channels, frame_size, frame_size)) — 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 (PeVideoProcessor utilise PeVideoVideoProcessor pour le traitement des vidéos).
padding_mask_videos (torch.Tensor de 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

BaseModelOutputWithPooling ou tuple(torch.Tensor)

Un BaseModelOutputWithPooling 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 (PeVideoConfig) et des entrées.

La méthode forward de PeVideoEncoder 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 Module plutô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.Tensor de 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.Tensor de 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é lorsque output_hidden_states=True est passé ou lorsque config.output_hidden_states=True) — Tuple de torch.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é lorsque output_attentions=True est passé ou lorsque config.output_attentions=True) — Tuple de torch.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.

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)

Paramètres

input_ids (torch.Tensor de forme (batch_size, sequence_length)) — 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.

Qu'est-ce que les identifiants d'entrée ?
pixel_values_videos (torch.Tensor de forme (batch_size, num_frames, num_channels, frame_size, frame_size)) — 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 (PeVideoProcessor utilise PeVideoVideoProcessor pour le traitement des vidéos).
attention_mask (torch.Tensor de 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.
Qu'est-ce que les masques d'attention ?
padding_mask_videos (torch.Tensor de 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.
return_loss (bool, facultatif) — Indique s'il faut renvoyer la perte.

Retourne

PeVideoOutput ou tuple(torch.Tensor)

Un PeVideoOutput 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 (PeVideoConfig) et des entrées.

La méthode forward du PeVideoModel 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 Module plutô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.

loss (torch.Tensor de forme (1,), facultatif) — Perte contrastive calculée entre les représentations vidéo et texte.
logits_video_text (torch.Tensor de forme (batch_size, batch_size), facultatif) — Logits de similarité entre les embeddings vidéo et texte.
text_video_embeds (torch.Tensor de forme (batch_size, hidden_size), facultatif) — Embeddings de texte projetés dans l'espace vidéo-texte.
video_embeds (torch.Tensor de forme (batch_size, hidden_size), facultatif) — Embeddings vidéo projetés dans l'espace vidéo-texte.
text_outputs (BaseModelOutputWithPooling, facultatif) — Sorties du modèle pour l’encodeur de texte, 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.

Update on GitHub