Este modelo se publicó en HF papers el 2025-06-11 y se contribuyó a Hugging Face Transformers el 2025-06-11.

V-JEPA 2

V-JEPA 2 (publicación en el blog) es un enfoque de autoaprendizaje para entrenar codificadores de video desarrollado por FAIR, Meta. Utilizando datos de video a escala de internet, V-JEPA 2 alcanza un rendimiento líder en tareas de comprensión del movimiento y anticipación de acciones humanas. V-JEPA 2-AC es un modelo de mundo condicional en acciones latentes, entrenado a partir de V-JEPA 2 (utilizando una pequeña cantidad de datos de interacción de trayectorias de robots), que resuelve tareas de manipulación robótica sin necesidad de recopilar datos específicos del entorno ni de realizar entrenamiento o calibración específicos de la tarea.

Puedes encontrar todos los puntos de control originales de V-JEPA2 en la colección V-JEPA 2.

Este modelo fue aportado por koustuvs, yonigozlan y qubvel. El código original se puede encontrar aquí.

Ejemplo de uso

El fragmento de código siguiente muestra cómo cargar el modelo V-JEPA 2 para la extracción de características usando la clase 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 también se puede ajustar para la clasificación de videos. En el siguiente fragmento, mostramos cómo usar el modelo de clasificación de videos ajustado en 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

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

Parámetros

patch_size (Union[int, list[int], tuple[int, int]], opcional, valor predeterminado 16) — El tamaño (resolución) de cada parche.
crop_size (int, opcional, valor predeterminado 256) — Resolución de entrada del modelo
frames_per_clip (int, opcional, valor predeterminado: 64) — El número de fotogramas con los que se ha preentrenado el modelo. No afecta a la inferencia.
tubelet_size (int, opcional, valor predeterminado: 2) — El número de fotogramas temporales utilizados para un solo rastor; consulte el artículo para obtener más información.
hidden_size (int, opcional, valor predeterminado 1024) — Dimensión de las representaciones ocultas.
in_chans (int, opcional, valor predeterminado 3) — El número de canales de entrada.
num_attention_heads (int, opcional, valor predeterminado 16) — Número de cabezas de atención para cada capa de atención en el decodificador Transformer.
num_hidden_layers (int, opcional, valor predeterminado 24) — Número de capas ocultas en el decodificador del Transformer.
drop_path_rate (Union[float, int], opcional, valor predeterminado 0.0) — Tasa de drop path para la fusión de parches.
mlp_ratio (Union[int, float], opcional, valor predeterminado 4.0) — Relación entre la dimensión oculta del MLP y la dimensión de incrustación.
layer_norm_eps (float, opcional, valor predeterminado 1e-06) — La epsilon utilizada por las capas de normalización de capa.
qkv_bias (bool, opcional, valor predeterminado True) — Si se debe añadir un sesgo a las consultas, claves y valores.
attention_probs_dropout_prob (Union[float, int], opcional, valor predeterminado 0.0) — La proporción de dropout para las probabilidades de atención.
hidden_act (str, opcional, valor predeterminado gelu) — La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo, "gelu", "relu", "silu", etc.
initializer_range (float, opcional, valor predeterminado 0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos.
attention_dropout (Union[float, int], opcional, valor predeterminado 0.0) — La proporción de dropout para las probabilidades de atención.
num_pooler_layers (int, opcional, valor predeterminado: 3) — El número de capas de autoatención en el pooler.
pred_hidden_size (int, opcional, valor predeterminado 384) — Dimensionalidad de las capas del predictor
pred_num_attention_heads (int, opcional, valor predeterminado 12) — Número de cabezas de atención para cada capa de atención en el Predictor
pred_num_hidden_layers (int, opcional, valor predeterminado 12) — Número de capas ocultas en el Predictor
pred_num_mask_tokens (int, opcional, valor predeterminado: 10) — Define el número de tokens de máscara que se usarán en el Predictor
pred_zero_init_mask_tokens (bool, opcional, valor predeterminado True) — Inicializa los tokens de máscara en el predictor con 0.
pred_mlp_ratio (float, opcional, valor predeterminado 4.0) — Proporción del tamaño oculto de los MLP utilizados en Predictor respecto a pred_hidden_size.

Esta es la clase de configuración para almacenar la configuración de un VJEPA2Model. Se utiliza para instanciar un modelo Vjepa2 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/vjepa2-vitl-fpc64-256

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.

Ejemplo:

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

clase transformers.VJEPA2Model

< source >

( config: VJEPA2Config )

Parámetros

config (VJEPA2Config) — 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 Vjepa2 sin modificar, que genera estados ocultos sin procesar sin ninguna cabeza específica en la parte superior.

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 >

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

Parámetros

pixel_values_videos (torch.Tensor de forma (batch_size, num_frames, num_channels, frame_size, frame_size)) — Los tensores correspondientes al video de entrada. Los valores de píxel para los videos se pueden obtener utilizando VJEPA2VideoProcessor. Consulte VJEPA2VideoProcessor.call() para obtener más detalles (processor_class utiliza VJEPA2VideoProcessor para procesar videos).
context_mask (torch.Tensor con forma [batch_size, patch_size, 1], opcional) — Las ids de posición de la máscara que indican qué parches de la salida del codificador se van a exponer al predictor. Por defecto, esta máscara se crea como torch.arange(N).unsqueeze(0).repeat(B,1), lo que indica que el predictor tiene acceso al contexto completo.
target_mask (torch.Tensor con forma [batch_size, patch_size, 1], opcional) — Los ids de posición de la máscara que indican qué parches de salida del codificador se van a utilizar como objetivo de predicción para el predictor. De forma predeterminada, esta máscara se crea como torch.arange(N).unsqueeze(0).repeat(B,1), lo que indica que el predictor debe predecir todos los parches del codificador.
skip_predictor (bool, opcional, valor predeterminado False) — bandera para omitir la propagación hacia adelante del predictor, útil si solo necesitas las salidas del codificador

Devuelve

VJEPA2WithMaskedInputModelOutput o tuple(torch.Tensor)

Un VJEPA2WithMaskedInputModelOutput 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 (VJEPA2Config) y las entradas.

El método forward de VJEPA2Model 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 Module despué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.Tensor de forma (batch_size, sequence_length, hidden_size)) — Secuencia de estados ocultos en la salida de la última capa del modelo.
masked_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size), opcional, se devuelve cuando se proporciona context_mask, que se aplica a las salidas de VJEPA2Encoder) — El estado oculto enmascarado del modelo.
hidden_states (tuple[torch.Tensor, ...], opcional, se devuelve cuando se pasa output_hidden_states=True o cuando config.output_hidden_states=True) — Tupla de torch.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 pasa output_attentions=True o cuando config.output_attentions=True) — Tupla de torch.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.
predictor_output (VJEPA2WithMaskedInputPredictorOutput, opcional) — La salida del módulo Predictor.

VJEPA2ForVideoClassification

clase transformers.VJEPA2ForVideoClassification

< source >

( config: VJEPA2Config )

Parámetros

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

V-JEPA 2 Modelo transformer con una cabeza de clasificación de vídeo en la parte superior (una capa lineal sobre el pooler atencional).

forward

< source >

( pixel_values_videos: Tensorlabels: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → ImageClassifierOutput or tuple(torch.Tensor)

Parámetros

pixel_values_videos (torch.Tensor de forma (batch_size, num_frames, num_channels, frame_size, frame_size)) — Los tensores correspondientes al video de entrada. Los valores de píxel para los videos se pueden obtener utilizando VJEPA2VideoProcessor. Consulte VJEPA2VideoProcessor.call() para obtener más detalles (processor_class utiliza VJEPA2VideoProcessor para procesar videos).
labels (torch.LongTensor de forma (batch_size,), opcional) — Etiquetas para calcular la pérdida de clasificación/regresión de imágenes. Los índices deben estar en [0, ..., config.num_labels - 1]. Si config.num_labels == 1 se calcula una pérdida de regresión (pérdida de error cuadrático medio), si config.num_labels > 1 se calcula una pérdida de clasificación (entropía cruzada).

Devuelve

ImageClassifierOutput o tuple(torch.Tensor)

Un ImageClassifierOutput 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 (VJEPA2Config) y las entradas.

El método forward de VJEPA2ForVideoClassification 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 Module despué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.

loss (torch.Tensor de forma (1,), opcional, se devuelve cuando se proporciona labels) — Pérdida de clasificación (o de regresión si config.num_labels==1).
logits (torch.Tensor de forma (batch_size, config.num_labels)) — Puntuaciones de clasificación (o de regresión si config.num_labels==1) (antes de SoftMax).
hidden_states (tuple(torch.Tensor), opcional, devuelto cuando se pasa output_hidden_states=True o cuando config.output_hidden_states=True) — Tupla de torch.Tensor (una para la salida de las incrustaciones, si el modelo tiene una capa de incrustación, + una para la salida de cada etapa) de forma (batch_size, sequence_length, hidden_size). Estados ocultos (también llamados mapas de características) del modelo en la salida de cada etapa.
attentions (tuple(torch.Tensor), opcional, se devuelve cuando se pasa output_attentions=True o cuando config.output_attentions=True) — Tupla de torch.Tensor (una por cada capa) de forma (batch_size, num_heads, patch_size, sequence_length).

Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.

Ejemplos:

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

clase transformers.VJEPA2VideoProcessor

< source >

( **kwargs: *<class 'transformers.processing_utils.VideosKwargs'> )

Parámetros

do_convert_rgb (bool, kwargs, opcional) — Si se debe convertir la imagen a RGB.
do_resize (bool, kwargs, opcional, valor predeterminado True) — Si se debe redimensionar la imagen.
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, por defecto {'shortest_edge' -- 292}): Describe las dimensiones máximas de entrada para el modelo.
default_to_square (bool, kwargs, opcional, valor predeterminado True) — Si se debe usar una imagen cuadrada por defecto al redimensionar, si size es un int.
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs, por defecto 2) — Filtro de remuestreo a utilizar si se redimensiona la imagen. Puede ser uno de los valores de la enumeración PILImageResampling. Solo tiene efecto si do_resize está establecido en True.
do_rescale (bool, kwargs, opcional, valor predeterminado True) — Si se debe reescalar la imagen.
rescale_factor (float, kwargs, opcional, valor predeterminado 0.00392156862745098) — Factor de reescalado para reescalar la imagen si do_rescale está establecido en True.
do_normalize (bool, kwargs, opcional, valor predeterminado True) — Si se debe normalizar la imagen.
image_mean (Union[float, list[float], tuple[float, ...]], kwargs, opcional, valor predeterminado [0.485, 0.456, 0.406]) — Media de la imagen a utilizar para la normalización. Solo tiene efecto si do_normalize está establecido en True.
image_std (Union[float, list[float], tuple[float, ...]], kwargs, opcional, valor predeterminado [0.229, 0.224, 0.225]) — Desviación estándar de la imagen a utilizar para la normalización. Solo tiene efecto si do_normalize está establecido en True.
do_center_crop (bool, kwargs, opcional, valor predeterminado True) — Si se debe recortar la imagen centrada.
do_pad (bool, kwargs, opcional) — Indica si se debe aplicar relleno a la imagen. El relleno se realiza hasta el tamaño más grande del lote o hasta un tamaño cuadrado fijo por imagen. La estrategia exacta de relleno depende del modelo.
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, valor predeterminado 256) — Tamaño de la imagen de salida tras aplicar center_crop.
data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opcional) — Solo se admite ChannelDimension.FIRST. Se añadió para garantizar la compatibilidad con los procesadores lentos.
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opcional) — El formato de la dimensión de canales para la imagen de entrada. Si no se establece, el formato de la dimensión de canales se infiere a partir de la imagen de entrada. Puede ser uno de:
- "channels_first" o ChannelDimension.FIRST: imagen en formato (num_channels, height, width).
- "channels_last" o ChannelDimension.LAST: imagen en formato (altura, ancho, num_canales).
- "none" o ChannelDimension.NONE: imagen en formato (altura, ancho).
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — El dispositivo en el que se procesarán los videos. Si no se establece, el dispositivo se infiere a partir de los videos de entrada.
do_sample_frames (bool, kwargs, opcional) — Si se deben muestrear fotogramas del video antes de procesarlo o si se debe procesar el video completo.
video_metadata (Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — Metadatos del video que contienen información sobre la duración total, los fps y el número total de fotogramas. Se utilizarán para muestrear fotogramas del video o calcular marcas de tiempo. No pase ningún metadato a menos que intente decodificar el video manualmente antes de procesarlo
fps (Annotated[int | float | None, None], kwargs) — Fotogramas objetivo a muestrear por segundo cuando do_sample_frames=True.
num_frames (Annotated[int | None, None], kwargs) — Número máximo de fotogramas a muestrear cuando do_sample_frames=True.
return_metadata (bool, kwargs, opcional, valor predeterminado False) — Indica si se debe devolver o no la metadatos del vídeo. Los metadatos del vídeo son un objeto que contiene información sobre la duración del vídeo, los fps, el backend de decodificación, etc.
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Si se establece, devolverá tensores de un marco de trabajo específico. Los valores aceptables son:
- 'pt': Devuelve objetos torch.Tensor de PyTorch.
- 'np': Devuelve objetos np.ndarray de NumPy.
**kwargs (VideosKwargs, opcional) — Opciones de procesamiento adicionales para cada modalidad (texto, imágenes, vídeos, audio). Los parámetros específicos del modelo se enumeran arriba; consulte la clase TypedDict para obtener la lista completa de argumentos admitidos.

Construye un procesador de video VJEPA2VideoProcessor.

Update on GitHub