Model ini dipublikasikan di HF papers pada 2025-06-11 dan disumbangkan ke Hugging Face Transformers pada 2025-06-11.

V-JEPA 2

V-JEPA 2 (artikel blog) adalah pendekatan self-supervised untuk melatih video encoder yang dikembangkan oleh FAIR, Meta. Dengan menggunakan data video berskala internet, V-JEPA 2 mencapai kinerja state-of-the-art pada tugas pemahaman gerak dan antisipasi tindakan manusia. V-JEPA 2-AC adalah model dunia yang dikondisikan oleh aksi laten, yang dilatih ulang dari V-JEPA 2 (menggunakan sejumlah kecil data interaksi lintasan robot) dan mampu menyelesaikan tugas manipulasi robot tanpa pengumpulan data yang spesifik lingkungan, pelatihan yang spesifik tugas, atau kalibrasi.

Anda dapat menemukan semua checkpoint asli V-JEPA2 di bawah koleksi V-JEPA 2.

Model ini disumbangkan oleh koustuvs, yonigozlan dan qubvel. Kode aslinya dapat ditemukan di sini.

Contoh penggunaan

Snippet di bawah ini menunjukkan cara memuat model V-JEPA 2 untuk ekstraksi fitur menggunakan kelas 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 juga dapat difinetune untuk klasifikasi video. Pada cuplikan berikut, kami menunjukkan cara menggunakan model klasifikasi video Something-Something-V2 yang telah difinetune.

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

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

Parameter

patch_size (Union[int, list[int], tuple[int, int]], opsional, defaultnya 16) — Ukuran (resolusi) dari setiap patch.
crop_size (int, opsional, default 256) — Resolusi input model
frames_per_clip (int, opsional, default 64) — Jumlah frame yang digunakan saat model dilatih secara pra. Tidak memengaruhi inferensi.
tubelet_size (int, opsional, default 2) — Jumlah frame temporal yang digunakan untuk satu rastor; lihat makalah untuk informasi lebih lanjut.
hidden_size (int, opsional, default 1024) — Dimensi dari representasi tersembunyi.
in_chans (int, opsional, default 3) — Jumlah saluran input.
num_attention_heads (int, opsional, default 16) — Jumlah attention head untuk setiap lapisan attention di decoder Transformer.
num_hidden_layers (int, opsional, default 24) — Jumlah lapisan tersembunyi dalam decoder Transformer.
drop_path_rate (Union[float, int], opsional, defaultnya 0.0) — Tingkat drop path untuk fusi patch.
mlp_ratio (Union[int, float], opsional, default 4.0) — Rasio dimensi tersembunyi MLP terhadap dimensi embedding.
layer_norm_eps (float, opsional, defaultnya 1e-06) — Epsilon yang digunakan oleh lapisan normalisasi lapisan.
qkv_bias (bool, opsional, defaultnya True) — Apakah akan menambahkan bias ke queries, keys, dan values.
attention_probs_dropout_prob (Union[float, int], opsional, default 0.0) — Rasio dropout untuk probabilitas perhatian.
hidden_act (str, opsional, defaultnya gelu) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, "gelu", "relu", "silu", dan sebagainya.
initializer_range (float, opsional, defaultnya 0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.
attention_dropout (Union[float, int], opsional, default 0.0) — Rasio dropout untuk probabilitas perhatian.
num_pooler_layers (int, opsional, default 3) — Jumlah lapisan self-attention di dalam pooler.
pred_hidden_size (int, opsional, default 384) — Dimensi dari lapisan predictor
pred_num_attention_heads (int, opsional, default 12) — Jumlah attention head untuk setiap lapisan attention di Predictor
pred_num_hidden_layers (int, opsional, default 12) — Jumlah lapisan tersembunyi dalam Predictor
pred_num_mask_tokens (int, opsional, default 10) — Menentukan jumlah token mask yang akan digunakan di Predictor
pred_zero_init_mask_tokens (bool, opsional, default True) — Inisialisasi token mask pada predictor dengan 0.
pred_mlp_ratio (float, opsional, default 4.0) — Rasio ukuran tersembunyi dari MLP yang digunakan dalam Predictor relatif terhadap pred_hidden_size.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari VJEPA2Model. Kelas ini digunakan untuk membuat instans model Vjepa2 sesuai dengan argumen yang ditentukan, sehingga mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari facebook/vjepa2-vitl-fpc64-256

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

Contoh:

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

kelas transformers.VJEPA2Model

< source >

( config: VJEPA2Config )

Parameter

config (VJEPA2Config) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.

Model Vjepa2 polos yang menghasilkan hidden-states mentah tanpa head spesifik di atasnya.

Model ini mewarisi dari PreTrainedModel. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran embedding input, memangkas kepala, dll.)

Model ini juga merupakan subclass dari torch.nn.Module PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.

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)

Parameter

pixel_values_videos (torch.Tensor dengan bentuk (batch_size, num_frames, num_channels, frame_size, frame_size)) — Tensor yang sesuai dengan video input. Nilai piksel untuk video dapat diperoleh menggunakan VJEPA2VideoProcessor. Lihat VJEPA2VideoProcessor.call() untuk detailnya (processor_class menggunakan VJEPA2VideoProcessor untuk memproses video).
context_mask (torch.Tensor dengan bentuk [batch_size, patch_size, 1], opsional) — ID posisi mask yang menunjukkan patch output encoder mana yang akan diekspos ke predictor. Secara default, mask ini dibuat sebagai torch.arange(N).unsqueeze(0).repeat(B,1), yang menunjukkan konteks penuh yang tersedia untuk predictor.
target_mask (torch.Tensor dengan bentuk [batch_size, patch_size, 1], opsional) — ID posisi mask yang menunjukkan patch output encoder mana yang akan digunakan sebagai target prediksi bagi predictor. Secara default, mask ini dibuat sebagai torch.arange(N).unsqueeze(0).repeat(B,1), yang menunjukkan bahwa predictor harus memprediksi semua patch encoder.
skip_predictor (bool, opsional, default False) — flag untuk melewati forward predictor, berguna jika Anda hanya membutuhkan output encoder

Mengembalikan

VJEPA2WithMaskedInputModelOutput atau tuple(torch.Tensor)

Sebuah VJEPA2WithMaskedInputModelOutput atau tuple dari torch.Tensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (VJEPA2Config) dan input.

Metode forward dari VJEPA2Model menimpa metode khusus __call__.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

last_hidden_state (torch.Tensor dengan bentuk (batch_size, sequence_length, hidden_size)) — Urutan hidden-states pada keluaran lapisan terakhir model.
masked_hidden_state (torch.Tensor dengan bentuk (batch_size, sequence_length, hidden_size), opsional, dikembalikan ketika context_mask diberikan, yang diterapkan pada output VJEPA2Encoder) — State tersembunyi yang dimasker dari model.
hidden_states (tuple[torch.Tensor, ...], opsional, dikembalikan ketika output_hidden_states=True dilewatkan atau ketika config.output_hidden_states=True) — Tuple dari torch.Tensor (satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk (batch_size, sequence_length, hidden_size).

Hidden-states model pada output setiap layer ditambah output embedding awal yang opsional.
attentions (tuple[torch.Tensor, ...], opsional, dikembalikan saat output_attentions=True dilewatkan atau saat config.output_attentions=True) — Tuple dari torch.Tensor (satu untuk setiap layer) dengan bentuk (batch_size, num_heads, sequence_length, sequence_length).

Bobot perhatian setelah softmax perhatian, digunakan untuk menghitung rata-rata berbobot di kepala perhatian diri (self-attention).
predictor_output (VJEPA2WithMaskedInputPredictorOutput, opsional) — Output dari modul Predictor.

VJEPA2ForVideoClassification

kelas transformers.VJEPA2ForVideoClassification

< source >

( config: VJEPA2Config )

Parameter

config (VJEPA2Config) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.

Model transformer V-JEPA 2 dengan kepala klasifikasi video di atasnya (lapisan linear di atas attentive pooler).

forward

< source >

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

Parameter

pixel_values_videos (torch.Tensor dengan bentuk (batch_size, num_frames, num_channels, frame_size, frame_size)) — Tensor yang sesuai dengan video input. Nilai piksel untuk video dapat diperoleh menggunakan VJEPA2VideoProcessor. Lihat VJEPA2VideoProcessor.call() untuk detailnya (processor_class menggunakan VJEPA2VideoProcessor untuk memproses video).
labels (torch.LongTensor dengan bentuk (batch_size,), opsional) — Label untuk menghitung loss klasifikasi/regresi gambar. Indeks harus berada dalam [0, ..., config.num_labels - 1]. Jika config.num_labels == 1, loss regresi dihitung (Mean-Square loss). Jika config.num_labels > 1, loss klasifikasi dihitung (Cross-Entropy).

Mengembalikan

ImageClassifierOutput atau tuple(torch.Tensor)

Sebuah ImageClassifierOutput atau tuple dari torch.Tensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (VJEPA2Config) dan input.

Metode forward dari VJEPA2ForVideoClassification menimpa metode khusus __call__.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

loss (torch.Tensor dengan bentuk (1,), opsional, dikembalikan saat labels disediakan) — Loss klasifikasi (atau regresi jika config.num_labels==1).
logits (torch.Tensor dengan bentuk (batch_size, config.num_labels)) — Skor klasifikasi (atau regresi jika config.num_labels==1) (sebelum SoftMax).
hidden_states (tuple(torch.Tensor), opsional, dikembalikan saat output_hidden_states=True dilewatkan atau saat config.output_hidden_states=True) — Tuple dari torch.Tensor (satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap tahap) dengan bentuk (batch_size, sequence_length, hidden_size). Hidden-states (juga disebut feature maps) dari model pada output dari setiap tahap.
attentions (tuple(torch.Tensor), opsional, dikembalikan saat output_attentions=True dilewatkan atau saat config.output_attentions=True) — Tuple dari torch.Tensor (satu untuk setiap layer) dengan bentuk (batch_size, num_heads, patch_size, sequence_length).

Bobot perhatian setelah softmax perhatian, digunakan untuk menghitung rata-rata berbobot di kepala perhatian diri (self-attention).

Contoh:

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

kelas transformers.VJEPA2VideoProcessor

< source >

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

Parameter

do_convert_rgb (bool, kwargs, opsional) — Apakah akan mengonversi gambar ke RGB.
do_resize (bool, kwargs, opsional, default True) — Apakah akan mengubah ukuran gambar.
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, defaultnya {'shortest_edge' -- 292}): Menggambarkan dimensi input maksimum ke model.
default_to_square (bool, kwargs, opsional, defaultnya True) — Apakah akan menggunakan gambar persegi sebagai default saat melakukan resize, jika size berupa int.
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs, defaultnya 2) — Filter resampling yang digunakan jika mengubah ukuran gambar. Ini bisa berupa salah satu enum PILImageResampling. Hanya berpengaruh jika do_resize diatur ke True.
do_rescale (bool, kwargs, opsional, default True) — Apakah akan melakukan penskalaan ulang pada gambar.
rescale_factor (float, kwargs, opsional, default 0.00392156862745098) — Faktor rescale untuk menskalakan ulang gambar jika do_rescale diatur ke True.
do_normalize (bool, kwargs, opsional, default True) — Apakah akan menormalisasi gambar.
image_mean (Union[float, list[float], tuple[float, ...]], kwargs, opsional, defaultnya [0.485, 0.456, 0.406]) — Rata-rata gambar yang digunakan untuk normalisasi. Hanya berpengaruh jika do_normalize diatur ke True.
image_std (Union[float, list[float], tuple[float, ...]], kwargs, opsional, defaultnya [0.229, 0.224, 0.225]) — Standar deviasi gambar yang digunakan untuk normalisasi. Hanya berpengaruh jika do_normalize diatur ke True.
do_center_crop (bool, kwargs, opsional, default True) — Apakah akan melakukan center crop pada gambar.
do_pad (bool, kwargs, opsional) — Apakah akan melakukan padding pada gambar. Padding dilakukan ke ukuran terbesar dalam batch atau ke ukuran persegi tetap per gambar. Strategi padding yang tepat bergantung pada model.
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, defaultnya 256) — Ukuran gambar keluaran setelah menerapkan center_crop.
data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opsional) — Hanya ChannelDimension.FIRST yang didukung. Ditambahkan untuk kompatibilitas dengan prosesor lambat.
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opsional) — Format dimensi channel untuk gambar input. Jika tidak diset, format dimensi channel akan disimpulkan dari gambar input. Bisa berupa salah satu dari:
- "channels_first" atau ChannelDimension.FIRST: gambar dalam format (num_channels, height, width).
- "channels_last" atau ChannelDimension.LAST: gambar dalam format (height, width, num_channels).
- "none" atau ChannelDimension.NONE: gambar dalam format (height, width).
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — Perangkat untuk memproses video. Jika tidak disetel, perangkat akan disimpulkan dari video input.
do_sample_frames (bool, kwargs, opsional) — Apakah akan mengambil sampel frame dari video sebelum diproses atau memproses seluruh video.
video_metadata (Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — Metadata dari video yang berisi informasi tentang durasi total, fps, dan jumlah total frame. Metadata ini akan digunakan untuk mengambil sampel frame dari video atau menghitung timestamp. Jangan kirimkan metadata apa pun kecuali Anda mencoba mendekode video secara manual sebelum diproses
fps (Annotated[int | float | None, None], kwargs) — Target frame yang akan disampel per detik ketika do_sample_frames=True.
num_frames (Annotated[int | None, None], kwargs) — Jumlah maksimum frame yang akan disampelkan saat do_sample_frames=True.
return_metadata (bool, kwargs, opsional, default False) — Apakah akan mengembalikan metadata video atau tidak. Metadata video adalah objek yang berisi informasi tentang durasi video, fps, backend decoding, dll.
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Jika diset, akan mengembalikan tensor dari framework tertentu. Nilai yang dapat diterima adalah:
- 'pt': Mengembalikan objek PyTorch torch.Tensor.
- 'np': Mengembalikan objek NumPy np.ndarray.
**kwargs (VideosKwargs, opsional) — Opsi pemrosesan tambahan untuk setiap modalitas (teks, gambar, video, audio). Parameter spesifik model tercantum di atas; lihat kelas TypedDict untuk daftar lengkap argumen yang didukung.

Membangun pemroses video VJEPA2VideoProcessor.

Update on GitHub