Este modelo foi publicado no HF papers em 2025-06-11 e contribuído para o Hugging Face Transformers em 2025-06-11.

V-JEPA 2

V-JEPA 2 (post no blog) é uma abordagem auto-supervisionada para o treinamento de codificadores de vídeo, desenvolvida pela FAIR, da Meta. Utilizando dados de vídeo em escala de internet, o V-JEPA 2 atinge desempenho de estado da arte em tarefas de compreensão de movimento e antecipação de ações humanas. O V-JEPA 2-AC é um modelo de mundo condicionado por ações latentes, treinado a partir do V-JEPA 2 (usando uma pequena quantidade de dados de interação de trajetórias de robôs), que resolve tarefas de manipulação robótica sem a necessidade de coleta de dados específica do ambiente ou de treinamento/calibração específica da tarefa.

Você pode encontrar todos os checkpoints originais do V-JEPA2 na coleção V-JEPA 2.

Este modelo foi contribuído por koustuvs, yonigozlan e qubvel. O código original pode ser encontrado aqui.

Exemplo de uso

O trecho abaixo mostra como carregar o modelo V-JEPA 2 para extração de recursos usando a 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

O V-JEPA 2 também pode ser ajustado para classificação de vídeo. No trecho a seguir, mostramos como usar o modelo ajustado para classificação de vídeo no 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 )

Parâmetros

patch_size (Union[int, list[int], tuple[int, int]], opcional, padrão 16) — O tamanho (resolução) de cada patch.
crop_size (int, opcional, padrão 256) — Resolução de entrada do modelo
frames_per_clip (int, opcional, padrão 64) — O número de quadros com os quais o modelo foi pré-treinado. Não afeta a inferência.
tubelet_size (int, opcional, padrão 2) — O número de quadros temporais usados para um único rastor; consulte o artigo para mais informações.
hidden_size (int, opcional, padrão 1024) — Dimensão das representações ocultas.
in_chans (int, opcional, padrão 3) — O número de canais de entrada.
num_attention_heads (int, opcional, padrão 16) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.
num_hidden_layers (int, opcional, padrão 24) — Número de camadas ocultas no decodificador do Transformer.
drop_path_rate (Union[float, int], opcional, padrão 0.0) — Taxa de drop path para a fusão de patches.
mlp_ratio (Union[int, float], opcional, padrão 4.0) — Proporção entre a dimensão oculta do MLP e a dimensão de incorporação.
layer_norm_eps (float, opcional, padrão 1e-06) — O epsilon usado pelas camadas de normalização de camada.
qkv_bias (bool, opcional, padrão True) — Se deve adicionar um viés às queries, keys e values.
attention_probs_dropout_prob (Union[float, int], opcional, padrão 0.0) — A taxa de dropout para as probabilidades de atenção.
hidden_act (str, opcional, padrão gelu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo, "gelu", "relu", "silu", etc.
initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.
attention_dropout (Union[float, int], opcional, padrão 0.0) — A taxa de dropout para as probabilidades de atenção.
num_pooler_layers (int, opcional, padrão 3) — O número de camadas de autoatenção no pooler.
pred_hidden_size (int, opcional, padrão 384) — Dimensão das camadas do preditor
pred_num_attention_heads (int, opcional, padrão 12) — Número de cabeças de atenção para cada camada de atenção no Predictor
pred_num_hidden_layers (int, opcional, padrão 12) — Número de camadas ocultas no Predictor
pred_num_mask_tokens (int, opcional, padrão 10) — Define o número de tokens de máscara a serem usados no Predictor
pred_zero_init_mask_tokens (bool, opcional, padrão True) — Inicializa os tokens de máscara no preditor com 0.
pred_mlp_ratio (float, opcional, padrão 4.0) — Proporção do tamanho oculto dos MLPs usados no Predictor em relação ao pred_hidden_size.

Esta é a classe de configuração para armazenar a configuração de um VJEPA2Model. Ela é usada para instanciar um modelo Vjepa2 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do facebook/vjepa2-vitl-fpc64-256

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Exemplo:

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

Parâmetros

config (VJEPA2Config) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.

O modelo Vjepa2 puro, que produz estados ocultos brutos sem nenhum cabeçalho específico no topo.

Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)

Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

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)) — Os tensors correspondentes ao vídeo de entrada. Os valores de pixels para vídeos podem ser obtidos usando VJEPA2VideoProcessor. Consulte VJEPA2VideoProcessor.call() para mais detalhes (processor_class usa VJEPA2VideoProcessor para processar vídeos).
context_mask (torch.Tensor com forma [batch_size, patch_size, 1], opcional) — Os ids de posição da máscara que indicam quais patches de saída do codificador serão expostos ao preditor. Por padrão, essa máscara é criada como torch.arange(N).unsqueeze(0).repeat(B,1), indicando contexto completo disponível para o preditor.
target_mask (torch.Tensor com forma [batch_size, patch_size, 1], opcional) — Os ids de posição da máscara que indicam quais patches da saída do codificador serão usados como alvo de previsão para o preditor. Por padrão, essa máscara é criada como torch.arange(N).unsqueeze(0).repeat(B,1), indicando que o preditor deve prever todos os patches do codificador.
skip_predictor (bool, opcional, padrão False) — flag para pular a forward do predictor, útil se você precisar apenas das saídas do encoder

Retorna

VJEPA2WithMaskedInputModelOutput ou tuple(torch.Tensor)

Uma VJEPA2WithMaskedInputModelOutput ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False), contendo vários elementos dependendo da configuração (VJEPA2Config) e das entradas.

O método forward do VJEPA2Model substitui o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.
masked_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size), opcional, retornado quando context_mask é fornecida, sendo aplicada às saídas do VJEPA2Encoder) — O estado oculto mascarado do modelo.
hidden_states (tuple[torch.Tensor, ...], opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.Tensor (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma (batch_size, sequence_length, hidden_size).

Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
attentions (tuple[torch.Tensor, ...], opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, sequence_length, sequence_length).

Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.
predictor_output (VJEPA2WithMaskedInputPredictorOutput, opcional) — A saída do módulo Predictor.

VJEPA2ForVideoClassification

classe transformers.VJEPA2ForVideoClassification

< source >

( config: VJEPA2Config )

Parâmetros

config (VJEPA2Config) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.

Modelo transformer V-JEPA 2 com uma cabeça de classificação de vídeo no topo (uma camada linear no topo do pooler atencioso).

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)) — Os tensors correspondentes ao vídeo de entrada. Os valores de pixels para vídeos podem ser obtidos usando VJEPA2VideoProcessor. Consulte VJEPA2VideoProcessor.call() para mais detalhes (processor_class usa VJEPA2VideoProcessor para processar vídeos).
labels (torch.LongTensor de forma (batch_size,), opcional) — Rótulos para o cálculo da perda de classificação/regressão de imagem. Os índices devem estar em [0, ..., config.num_labels - 1]. Se config.num_labels == 1, uma perda de regressão é calculada (perda de erro quadrático médio); se config.num_labels > 1, uma perda de classificação é calculada (entropia cruzada).

Retorna

ImageClassifierOutput ou tuple(torch.Tensor)

Um ImageClassifierOutput ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (VJEPA2Config) e das entradas.

O método forward de VJEPA2ForVideoClassification substitui o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

loss (torch.Tensor de forma (1,), opcional, retornado quando labels é fornecido) — Perda de classificação (ou regressão se config.num_labels==1).
logits (torch.Tensor de forma (batch_size, config.num_labels)) — Pontuações de classificação (ou regressão, se config.num_labels==1) (antes do SoftMax).
hidden_states (tuple(torch.Tensor), opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.Tensor (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada estágio) de forma (batch_size, sequence_length, hidden_size). Hidden-states (também chamados de feature maps) do modelo na saída de cada estágio.
attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, patch_size, sequence_length).

Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.

Exemplos:

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

Parâmetros

do_convert_rgb (bool, kwargs, opcional) — Se a imagem deve ser convertida para RGB.
do_resize (bool, kwargs, opcional, padrão True) — Se deve redimensionar a imagem.
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, padrão {'shortest_edge' -- 292}): Descreve as dimensões máximas de entrada para o modelo.
default_to_square (bool, kwargs, opcional, padrão True) — Se deve usar uma imagem quadrada por padrão ao redimensionar, caso o tamanho seja um inteiro.
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs, padrão 2) — Filtro de reamostragem a ser usado ao redimensionar a imagem. Pode ser um dos valores da enumeração PILImageResampling. Tem efeito apenas se do_resize estiver definido como True.
do_rescale (bool, kwargs, opcional, padrão True) — Se deve reescalar a imagem.
rescale_factor (float, kwargs, opcional, padrão 0.00392156862745098) — Fator de reescala para reescalar a imagem, caso do_rescale esteja definido como True.
do_normalize (bool, kwargs, opcional, padrão True) — Se a imagem deve ser normalizada.
image_mean (Union[float, list[float], tuple[float, ...]], kwargs, opcional, padrão [0.485, 0.456, 0.406]) — Média da imagem a ser usada para normalização. Tem efeito apenas se do_normalize estiver definido como True.
image_std (Union[float, list[float], tuple[float, ...]], kwargs, opcional, padrão [0.229, 0.224, 0.225]) — Desvio padrão da imagem a ser usado para normalização. Tem efeito apenas se do_normalize estiver definido como True.
do_center_crop (bool, kwargs, opcional, padrão True) — Se deve recortar a imagem pelo centro.
do_pad (bool, kwargs, opcional) — Indica se a imagem deve ser preenchida (padding). O preenchimento é feito até o maior tamanho do lote ou até um tamanho quadrado fixo por imagem. A estratégia exata de preenchimento depende do modelo.
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, padrão 256) — Tamanho da imagem de saída após aplicar center_crop.
data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opcional) — Apenas ChannelDimension.FIRST é suportado. Adicionado para compatibilidade com processadores lentos.
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opcional) — O formato da dimensão de canal para a imagem de entrada. Se não definido, o formato da dimensão de canal é inferido a partir da imagem de entrada. Pode ser um dos seguintes:
- "channels_first" ou ChannelDimension.FIRST: imagem no formato (num_channels, height, width).
- "channels_last" ou ChannelDimension.LAST: imagem no formato (altura, largura, num_canais).
- "none" ou ChannelDimension.NONE: imagem no formato (altura, largura).
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — O dispositivo em que os vídeos serão processados. Se não for definido, o dispositivo é inferido a partir dos vídeos de entrada.
do_sample_frames (bool, kwargs, opcional) — Se deve amostrar quadros do vídeo antes do processamento ou processar o vídeo inteiro.
video_metadata (Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — Metadados do vídeo contendo informações sobre a duração total, fps e o número total de quadros. Será usado para amostrar quadros do vídeo ou calcular timestamps. Não passe nenhum metadado, a menos que você esteja tentando decodificar o vídeo manualmente antes do processamento
fps (Annotated[int | float | None, None], kwargs) — Quantidade de quadros-alvo a amostrar por segundo quando do_sample_frames=True.
num_frames (Annotated[int | None, None], kwargs) — Número máximo de quadros a amostrar quando do_sample_frames=True.
return_metadata (bool, kwargs, opcional, padrão False) — Se deve retornar ou não os metadados do vídeo. Os metadados do vídeo são um objeto contendo informações sobre a duração do vídeo, fps, backend de decodificação, etc.
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Se definido, retornará tensors de um framework específico. Os valores aceitos são:
- 'pt': Retorna objetos torch.Tensor do PyTorch.
- 'np': Retorna objetos np.ndarray do NumPy.
**kwargs (VideosKwargs, opcional) — Opções de processamento adicionais para cada modalidade (texto, imagens, vídeos, áudio). Os parâmetros específicos do modelo estão listados acima; consulte a classe TypedDict para a lista completa de argumentos suportados.

Constrói um processador de vídeo VJEPA2VideoProcessor.

Update on GitHub