Ce modèle a été publié dans les papiers HF le 2025-06-11 et contribué à Hugging Face Transformers le 2025-06-11.

V-JEPA 2

V-JEPA 2 (article de blog) est une approche auto-supervisée pour l'entraînement d'encodeurs vidéo, développée par FAIR, Meta. En utilisant des données vidéo à l'échelle d'Internet, V-JEPA 2 atteint des performances de pointe sur les tâches de compréhension du mouvement et d'anticipation des actions humaines. V-JEPA 2-AC est un modèle du monde conditionné par des actions latentes, entraîné à partir de V-JEPA 2 (en utilisant une petite quantité de données d'interaction de trajectoires robotiques), qui résout des tâches de manipulation robotique sans collecte de données spécifiques à l'environnement ni entraînement ou calibration spécifiques à la tâche.

Vous pouvez trouver tous les points de contrôle originaux de V-JEPA2 dans la collection V-JEPA 2.

Ce modèle a été contribué par koustuvs, yonigozlan et qubvel. Le code d’origine est disponible ici.

Exemple d'utilisation

L'extrait ci-dessous montre comment charger le modèle V-JEPA 2 pour l'extraction de caractéristiques à l'aide de la classe AutoModel.

import numpy as np
from torchcodec.decoders import VideoDecoder


processor = AutoVideoProcessor.from_pretrained("facebook/vjepa2-vitl-fpc64-256")
model = AutoModel.from_pretrained(
    "facebook/vjepa2-vitl-fpc64-256",
    device_map="auto",
    attn_implementation="sdpa"
)

video_url = "https://huggingface.co/datasets/nateraw/kinetics-mini/resolve/main/val/archery/-Qz25rXdMjE_000014_000024.mp4"

vr = VideoDecoder(video_url)
frame_idx = np.arange(0, 64) # choosing some frames. here, you can define more complex sampling strategy
video = vr.get_frames_at(indices=frame_idx).data  # T x C x H x W
video = processor(video, return_tensors="pt").to(model.device)
outputs = model(**video)

# V-JEPA 2 encoder outputs, same as calling `model.get_vision_features()`
encoder_outputs = outputs.last_hidden_state

# V-JEPA 2 predictor outputs
predictor_outputs = outputs.predictor_output.last_hidden_state

V-JEPA 2 peut également être affiné pour la classification de vidéos. Dans l'extrait de code suivant, nous montrons comment utiliser le modèle de classification de vidéos affiné sur Something-Something-V2.

import numpy as np
import torch
from torchcodec.decoders import VideoDecoder

from transformers import AutoModelForVideoClassification, AutoVideoProcessor


# Load model and video preprocessor
hf_repo = "facebook/vjepa2-vitl-fpc16-256-ssv2"

model = AutoModelForVideoClassification.from_pretrained(hf_repo, device_map="auto")
processor = AutoVideoProcessor.from_pretrained(hf_repo)

# To load a video, sample the number of frames according to the model.
video_url = "https://huggingface.co/datasets/nateraw/kinetics-mini/resolve/main/val/bowling/-WH-lxmGJVY_000005_000015.mp4"
vr = VideoDecoder(video_url)
frame_idx = np.arange(0, model.config.frames_per_clip, 8) # you can define more complex sampling strategy
video = vr.get_frames_at(indices=frame_idx).data  # frames x channels x height x width

# Preprocess and run inference
inputs = processor(video, return_tensors="pt").to(model.device)
with torch.no_grad():
    outputs = model(**inputs)
logits = outputs.logits

print("Top 5 predicted class names:")
top5_indices = logits.topk(5).indices[0]
top5_probs = torch.softmax(logits, dim=-1).topk(5).values[0]
for idx, prob in zip(top5_indices, top5_probs):
    text_label = model.config.id2label[idx.item()]
    print(f" - {text_label}: {prob:.2f}")

VJEPA2Config

classe transformers.VJEPA2Config

< 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 = Nonepatch_size: int | list[int] | tuple[int, int] = 16crop_size: int = 256frames_per_clip: int = 64tubelet_size: int = 2hidden_size: int = 1024in_chans: int = 3num_attention_heads: int = 16num_hidden_layers: int = 24drop_path_rate: float | int = 0.0mlp_ratio: int | float = 4.0layer_norm_eps: float = 1e-06qkv_bias: bool = Trueattention_probs_dropout_prob: float | int = 0.0hidden_act: str = 'gelu'initializer_range: float = 0.02attention_dropout: float | int = 0.0num_pooler_layers: int = 3pred_hidden_size: int = 384pred_num_attention_heads: int = 12pred_num_hidden_layers: int = 12pred_num_mask_tokens: int = 10pred_zero_init_mask_tokens: bool = Truepred_mlp_ratio: int | float = 4.0 )

Paramètres

patch_size (Union[int, list[int], tuple[int, int]], facultatif, par défaut 16) — La taille (résolution) de chaque patch.
crop_size (int, facultatif, valeur par défaut : 256) — Résolution d'entrée du modèle
frames_per_clip (int, facultatif, valeur par défaut : 64) — Le nombre d'images avec lesquelles le modèle a été pré-entraîné. N'a pas d'impact sur l'inférence.
tubelet_size (int, facultatif, valeur par défaut : 2) — Nombre de trames temporelles utilisées pour un seul rastor ; consultez le papier pour plus d'informations.
hidden_size (int, facultatif, par défaut 1024) — Dimension des représentations cachées.
in_chans (int, facultatif, par défaut 3) — Le nombre de canaux d'entrée.
num_attention_heads (int, facultatif, valeur par défaut 16) — Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer.
num_hidden_layers (int, facultatif, par défaut 24) — Nombre de couches cachées dans le décodeur Transformer.
drop_path_rate (Union[float, int], facultatif, par défaut 0.0) — Taux de drop path pour la fusion des patches.
mlp_ratio (Union[int, float], facultatif, valeur par défaut 4.0) — Ratio de la dimension cachée du MLP par rapport à la dimension d'embedding.
layer_norm_eps (float, facultatif, valeur par défaut 1e-06) — L'épsilon utilisé par les couches de normalisation de couche.
qkv_bias (bool, facultatif, par défaut True) — Indique s'il faut ajouter un biais aux requêtes, clés et valeurs.
attention_probs_dropout_prob (Union[float, int], facultatif, par défaut 0.0) — Le taux de dropout appliqué aux probabilités d'attention.
hidden_act (str, facultatif, par défaut gelu) — La fonction d'activation non linéaire (fonction ou chaîne de caractères) du décodeur. Par exemple, "gelu", "relu", "silu", etc.
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.
attention_dropout (Union[float, int], facultatif, valeur par défaut 0.0) — Le taux de dropout appliqué aux probabilités d'attention.
num_pooler_layers (int, facultatif, valeur par défaut : 3) — Le nombre de couches d'auto-attention dans le pooler.
pred_hidden_size (int, facultatif, par défaut 384) — Dimension des couches du prédicteur
pred_num_attention_heads (int, facultatif, valeur par défaut : 12) — Nombre de têtes d'attention pour chaque couche d'attention du Predictor
pred_num_hidden_layers (int, facultatif, valeur par défaut : 12) — Nombre de couches cachées dans le Predictor
pred_num_mask_tokens (int, facultatif, valeur par défaut : 10) — Définit le nombre de jetons de masque à utiliser dans le Predictor
pred_zero_init_mask_tokens (bool, facultatif, valeur par défaut True) — Initialise les jetons de masque du prédicteur avec 0.
pred_mlp_ratio (float, facultatif, valeur par défaut 4.0) — Ratio de la taille cachée des MLP utilisés dans Predictor par rapport à pred_hidden_size.

Ceci est la classe de configuration destinée à stocker la configuration d'un VJEPA2Model. Elle est utilisée pour instancier un modèle Vjepa2 en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de facebook/vjepa2-vitl-fpc64-256

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 VJEPA2Config, VJEPA2Model

>>> # Initializing a VJEPA2 vjepa2-vitl-fpc64-256 style configuration
>>> configuration = VJEPA2Config()

>>> # Initializing a model (with random weights) from the vjepa2-vitl-fpc64-256  style configuration
>>> model = VJEPA2Model(configuration)

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

VJEPA2Model

classe transformers.VJEPA2Model

< source >

( config: VJEPA2Config )

Paramètres

config (VJEPA2Config) — 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 Vjepa2 brut, qui produit des états cachés bruts sans aucune tête spécifique au sommet.

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: Tensorcontext_mask: list[torch.Tensor] | None = Nonetarget_mask: list[torch.Tensor] | None = Noneskip_predictor: bool = False**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → VJEPA2WithMaskedInputModelOutput 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 des vidéos peuvent être obtenues à l’aide de VJEPA2VideoProcessor. Consultez VJEPA2VideoProcessor.call() pour plus de détails (processor_class utilise VJEPA2VideoProcessor pour le traitement des vidéos).
context_mask (torch.Tensor de forme [batch_size, patch_size, 1], facultatif) — Les identifiants de position du masque indiquant quels patches de sortie de l’encodeur seront exposés au prédicteur. Par défaut, ce masque est créé via torch.arange(N).unsqueeze(0).repeat(B,1), ce qui indique un contexte complet disponible pour le prédicteur.
target_mask (torch.Tensor de forme [batch_size, patch_size, 1], facultatif) — Les identifiants de position du masque indiquant quels patches de sortie de l’encodeur seront utilisés comme cible de prédiction pour le prédicteur. Par défaut, ce masque est créé via torch.arange(N).unsqueeze(0).repeat(B,1), ce qui indique que le prédicteur doit prédire tous les patches de l’encodeur.
skip_predictor (bool, facultatif, valeur par défaut False) — indicateur pour ignorer le passage avant du prédicteur, utile si vous avez uniquement besoin des sorties de l'encodeur

Retourne

VJEPA2WithMaskedInputModelOutput ou tuple(torch.Tensor)

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

La méthode forward du modèle VJEPA2Model 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.
masked_hidden_state (torch.Tensor de forme (batch_size, sequence_length, hidden_size), facultatif, renvoyé lorsque context_mask est fourni et appliqué aux sorties de VJEPA2Encoder) — L’état caché masqué du modèle.
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.
predictor_output (VJEPA2WithMaskedInputPredictorOutput, facultatif) — La sortie du module Predictor.

VJEPA2ForVideoClassification

classe transformers.VJEPA2ForVideoClassification

< source >

( config: VJEPA2Config )

Paramètres

config (VJEPA2Config) — 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.

Transformateur du modèle V-JEPA 2 avec une tête de classification vidéo au sommet (une couche linéaire au-dessus du pooler attentif).

forward

< source >

( pixel_values_videos: Tensorlabels: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → ImageClassifierOutput 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 des vidéos peuvent être obtenues à l’aide de VJEPA2VideoProcessor. Consultez VJEPA2VideoProcessor.call() pour plus de détails (processor_class utilise VJEPA2VideoProcessor pour le traitement des vidéos).
labels (torch.LongTensor de forme (batch_size,), facultatif) — Étiquettes pour le calcul de la perte de classification/régression d'image. Les indices doivent être dans [0, ..., config.num_labels - 1]. Si config.num_labels == 1, une perte de régression est calculée (perte du carré moyen). Si config.num_labels > 1, une perte de classification est calculée (entropie croisée).

Retourne

ImageClassifierOutput ou tuple(torch.Tensor)

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

La méthode forward de VJEPA2ForVideoClassification 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, renvoyé lorsque labels est fourni) — Perte de classification (ou de régression si config.num_labels==1).
logits (torch.Tensor de forme (batch_size, config.num_labels)) — Scores de classification (ou de régression si config.num_labels==1) (avant SoftMax).
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 étape) de forme (batch_size, sequence_length, hidden_size). États cachés (également appelés cartes de caractéristiques) du modèle à la sortie de chaque étape.
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, patch_size, 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.

Exemples :

>>> import torch
>>> import numpy as np
>>> from transformers import AutoVideoProcessor, VJEPA2ForVideoClassification

>>> device = "cuda"

>>> video_processor = AutoVideoProcessor.from_pretrained("facebook/vjepa2-vitl-fpc16-256-ssv2")
>>> model = VJEPA2ForVideoClassification.from_pretrained("facebook/vjepa2-vitl-fpc16-256-ssv2").to(device)

>>> video = np.ones((64, 256, 256, 3))  # 64 frames, 256x256 RGB
>>> inputs = video_processor(video, return_tensors="pt").to(device)

>>> # For inference
>>> with torch.no_grad():
...     outputs = model(**inputs)
>>> logits = outputs.logits

>>> predicted_label = logits.argmax(-1).item()
>>> print(model.config.id2label[predicted_label])

>>> # For training
>>> labels = torch.ones(1, dtype=torch.long, device=device)
>>> loss = model(**inputs, labels=labels).loss

VJEPA2VideoProcessor

classe transformers.VJEPA2VideoProcessor

< 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, valeur par défaut True) — Indique s'il faut redimensionner l'image.
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, par défaut {'shortest_edge' -- 292}) : Définit les dimensions d'entrée maximales 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, par défaut True) — 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, valeur par défaut True) — Indique s'il faut normaliser l'image.
image_mean (Union[float, list[float], tuple[float, ...]], kwargs, facultatif, valeur par défaut [0.485, 0.456, 0.406]) — 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, valeur par défaut [0.229, 0.224, 0.225]) — É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, valeur par défaut True) — 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, par défaut 256) — 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 VJEPA2VideoProcessor.

Update on GitHub