このモデルは2025年6月11日にHF papersで公開され、2025年6月11日にHugging Face Transformersに貢献されました。

V-JEPA 2

V-JEPA 2（ブログ記事）は、Meta の FAIR が開発した、動画エンコーダーを自己教師あり学習で訓練するためのアプローチです。インターネット規模の動画データを用いることで、V-JEPA 2 は、モーション理解や人間の行動予測タスクにおいて最先端の性能を達成しています。V-JEPA 2-AC は、V-JEPA 2 から後訓練された潜在アクション条件付きワールドモデルであり、少量のロボット軌跡インタラクションデータを用いて訓練されます。これにより、環境固有のデータ収集や、タスク固有の訓練・キャリブレーションなしで、ロボットの操作タスクを解決できます。

すべてのオリジナルのV-JEPA2チェックポイントは、V-JEPA 2コレクション内で確認できます。

このモデルは、koustuvs、yonigozlan、qubvel によって提供されました。元のコードはこちらで確認できます。

使用例

以下のスニペットは、AutoModel クラスを使用して V-JEPA 2 モデルを特徴抽出用にロードする方法を示しています。

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 は、動画分類用のファインチューニングにも対応しています。以下のスニペットでは、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

クラス 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 )

パラメータ

patch_size (Union[int, list[int], tuple[int, int]]、任意、デフォルトは16) — 各パッチのサイズ（解像度）です。
crop_size (int、任意、デフォルトは 256) — モデルの入力解像度
frames_per_clip (int、任意、デフォルトは 64) — モデルが事前学習で使用したフレーム数です。推論には影響しません。
tubelet_size (int, 任意、デフォルトは 2) — 1 つのラスタに使用される時間フレームの数です。詳細は論文を参照してください。
hidden_size (int、任意、デフォルトは 1024) — 隠れ表現の次元数。
in_chans (int、任意、デフォルトは 3) — 入力チャネル数。
num_attention_heads (int、任意、デフォルトは 16) — Transformer デコーダーの各アテンション層におけるアテンションヘッドの数。
num_hidden_layers (int、任意、デフォルトは24) — Transformer デコーダーの隠れ層の数。
drop_path_rate (Union[float, int]、任意、デフォルトは 0.0) — パッチ融合におけるドロップパスの率。
mlp_ratio (Union[int, float]、任意、デフォルトは 4.0) — MLPの隠れ層の次元と埋め込みの次元の比率。
layer_norm_eps (float、任意、デフォルトは 1e-06) — レイヤーノーマル層で使用する epsilon です。
qkv_bias (bool、省略可、デフォルトは True) — クエリ、キー、バリューにバイアスを追加するかどうか。
attention_probs_dropout_prob (Union[float, int]、任意、デフォルトは 0.0) — アテンション確率のドロップアウト率です。
hidden_act (str、任意、デフォルトは gelu) — デコーダーで使用する非線形活性化関数（関数または文字列）。例えば、"gelu"、 "relu"、"silu" など。
initializer_range (float、任意、デフォルトは 0.02) — すべての重み行列を初期化するための truncated_normal_initializer の標準偏差です。
attention_dropout (Union[float, int]、任意、デフォルトは 0.0) — アテンション確率のドロップアウト率です。
num_pooler_layers (int、任意、デフォルト値は 3)— プーラー内の自己アテンション層の数です。
pred_hidden_size (int、省略可、デフォルト値は 384) — predictor 層の次元
pred_num_attention_heads (int、任意、デフォルトは 12) — Predictor の各アテンション層におけるアテンションヘッドの数
pred_num_hidden_layers (int, 省略可能、デフォルト値は 12) — Predictor の隠れ層の数
pred_num_mask_tokens (int、任意、デフォルト値は 10)— Predictor で使用するマスクトークンの数を定義します。
pred_zero_init_mask_tokens (bool、省略可、デフォルトは True) — predictor のマスクトークンを 0 で初期化します。
pred_mlp_ratio (float、任意、デフォルト値は 4.0) — Predictor で使用される MLP の隠れ層サイズと pred_hidden_size の比率。

This is the configuration class to store the configuration of a VJEPA2Model. It is used to instantiate a Vjepa2 model according to the specified arguments, defining the model architecture. Instantiating a configuration with the defaults will yield a similar configuration to that of the facebook/vjepa2-vitl-fpc64-256

設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。

例:

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

クラス transformers.VJEPA2Model

< source >

( config: VJEPA2Config )

パラメータ

config (VJEPA2Config) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。

特定のヘッドを付加せず、生のhidden-statesを出力する素のVjepa2 Model。

このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

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

パラメータ

pixel_values_videos (torch.Tensor、形状 (batch_size, num_frames, num_channels, frame_size, frame_size)) — 入力動画に対応するテンソルです。動画のピクセル値は、VJEPA2VideoProcessor を使用して取得できます。詳細については、VJEPA2VideoProcessor.call() を参照してください（processor_class は動画の処理に VJEPA2VideoProcessor を使用します）。
context_mask (torch.Tensor、shape [batch_size, patch_size, 1]、任意) — predictor に公開されるエンコーダー出力の patch を示すマスクの位置 ID です。デフォルトでは、このマスクは torch.arange(N).unsqueeze(0).repeat(B,1) として作成され、predictor が利用可能な完全なコンテキストを示します。
target_mask (torch.Tensor、shape [batch_size, patch_size, 1]、任意) — predictor が予測対象として使用する encoder 出力の patch を示すマスクの位置 ID です。デフォルトでは、このマスクは torch.arange(N).unsqueeze(0).repeat(B,1) として作成され、predictor がすべての encoder patch を予測すべきであることを示します。
skip_predictor (bool、任意、デフォルトはFalse) — predictor のフォワードをスキップするためのフラグです。エンコーダーの出力のみが必要な場合に便利です。

戻り値

VJEPA2WithMaskedInputModelOutput または tuple(torch.FloatTensor)

VJEPA2WithMaskedInputModelOutput、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（VJEPA2Config）や入力に応じて、さまざまな要素で構成されます。

VJEPA2Model の forward メソッドは、__call__ という特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなくModuleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。

last_hidden_state (torch.FloatTensor、shape (batch_size, sequence_length, hidden_size)) — モデルの最終層の出力における隠れ状態のシーケンス。
masked_hidden_state (torch.FloatTensor、shape (batch_size, sequence_length, hidden_size)、optional、context_mask が提供され、VJEPA2Encoder の出力に適用される場合に返されます) — モデルのマスクされた隠れ状態です。
hidden_states (tuple[torch.FloatTensor, ...]、optional、output_hidden_states=True が渡された場合または config.output_hidden_states=True の場合に返されます) — torch.FloatTensor のタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は (batch_size, sequence_length, hidden_size) です。

各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
attentions (tuple[torch.FloatTensor, ...]、optional、output_attentions=True が渡された場合または config.output_attentions=True の場合に返されます)— torch.FloatTensor のタプル（各レイヤーごとに1つ）、形状は (batch_size, num_heads, sequence_length, sequence_length) です。

アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
predictor_output (VJEPA2WithMaskedInputPredictorOutput、任意) — Predictor モジュールからの出力です。

VJEPA2ForVideoClassification

クラス transformers.VJEPA2ForVideoClassification

< source >

( config: VJEPA2Config )

パラメータ

config (VJEPA2Config) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。

V-JEPA 2 モデルは、アテンティブプーラーの上に線形層を配置した動画分類ヘッドを備えた transformer です。

forward

< source >

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

パラメータ

pixel_values_videos (torch.Tensor、形状 (batch_size, num_frames, num_channels, frame_size, frame_size)) — 入力動画に対応するテンソルです。動画のピクセル値は、VJEPA2VideoProcessor を使用して取得できます。詳細については、VJEPA2VideoProcessor.call() を参照してください（processor_class は動画の処理に VJEPA2VideoProcessor を使用します）。
labels (torch.LongTensor、shape (batch_size,)、任意) — 画像分類/回帰の損失を計算するためのラベル。インデックスは [0, ..., config.num_labels - 1] の範囲である必要があります。config.num_labels == 1 の場合は回帰損失(平均二乗誤差)が計算され、config.num_labels > 1 の場合は分類損失(クロスエントロピー)が計算されます。

戻り値

ImageClassifierOutput または tuple(torch.FloatTensor)

torch.FloatTensor のタプル、または ImageClassifierOutput（return_dict=False が渡された場合、または config.return_dict=False の場合）。設定（VJEPA2Config）や入力に応じて、さまざまな要素で構成されます。

VJEPA2ForVideoClassificationのforwardメソッドは、__call__特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなくModuleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。

loss (torch.FloatTensor、shape (1,)、optional、labels が指定された場合に返されます) — 分類損失（config.num_labels==1 の場合は回帰損失）。
logits (torch.FloatTensor、shape (batch_size, config.num_labels)) — SoftMax 適用前の分類スコア（config.num_labels==1 の場合は回帰スコア）。
hidden_states (tuple(torch.FloatTensor)、optional、output_hidden_states=True が渡された場合または config.output_hidden_states=True の場合に返されます) — torch.FloatTensor のタプル（埋め込み層を持つモデルの場合、埋め込みの出力用が 1 つ、各ステージの出力用がそれぞれ 1 つずつ）で、形状は (batch_size, sequence_length, hidden_size) です。各ステージの出力におけるモデルの隠れ状態（特徴マップとも呼ばれます）。
attentions (tuple(torch.FloatTensor)、optional、output_attentions=True が渡された場合または config.output_attentions=True の場合に返されます)— torch.FloatTensor のタプル（各レイヤーごとに1つ）、形状は (batch_size, num_heads, patch_size, sequence_length)。

アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。

例:

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

class transformers.VJEPA2VideoProcessor

< source >

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

パラメータ

do_convert_rgb (bool、kwargs、任意) — 画像を RGB に変換するかどうかを指定します。
do_resize (bool、kwargs、任意、デフォルトはTrue) — 画像をリサイズするかどうか。
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs、デフォルトは {'shortest_edge' -- 292}): モデルへの最大入力サイズを指定します。
default_to_square (bool、kwargs、任意、デフォルトは True) — size が int の場合、リサイズ時に正方形の画像をデフォルトとするかどうかを指定します。
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs, デフォルトは 2) — 画像のリサイズ時に使用するリサンプリングフィルタです。PILImageResampling の列挙型のいずれかを使用できます。do_resize が True に設定されている場合のみ、効果が現れます。
do_rescale (bool、kwargs、任意、デフォルトはTrue) — 画像をリスケールするかどうかを指定します。
rescale_factor (float、kwargs、任意、デフォルト値は 0.00392156862745098) — do_rescale が True に設定されている場合、画像をリスケールするための係数です。
do_normalize (bool、kwargs、optional、デフォルトはTrue) — 画像を正規化するかどうかを指定します。
image_mean (Union[float, list[float], tuple[float, ...]]、kwargs、optional、デフォルト値は [0.485, 0.456, 0.406]) — 正規化に使用する画像の平均値。do_normalize が True に設定されている場合のみ有効です。
image_std (Union[float, list[float], tuple[float, ...]]、kwargs、optional、デフォルト値は [0.229, 0.224, 0.225]) — 正規化に使用する画像の標準偏差。do_normalize が True に設定されている場合のみ有効です。
do_center_crop (bool、kwargs、optional、デフォルトは True) — 画像を中央クロップするかどうか。
do_pad (bool, kwargs, optional) — 画像をパディングするかどうかを指定します。パディングは、バッチ内の最大サイズに合わせるか、画像ごとに固定の正方形サイズに合わせるかのいずれかで行われます。具体的なパディング戦略はモデルによって異なります。
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs、デフォルトは 256) — center_crop を適用した後の出力画像のサイズ。
data_format (Union[str, ~image_utils.ChannelDimension]、kwargs、任意) — サポートされているのは ChannelDimension.FIRST のみです。slow processors との互換性のために追加されました。
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 省略可) — 入力画像のチャネル次元の形式です。設定されていない場合、入力画像からチャネル次元の形式が推測されます。次のいずれかになります:
- "channels_first" または ChannelDimension.FIRST: (num_channels, height, width) 形式の画像。
- "channels_last" または ChannelDimension.LAST: (高さ, 幅, チャネル数) 形式の画像。
- "none" または ChannelDimension.NONE: (height, width) 形式の画像。
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — 動画を処理するデバイスです。未設定の場合、入力動画からデバイスが推論されます。
do_sample_frames (bool、kwargs、任意) — 処理前に動画からフレームをサンプリングするか、動画全体を処理するかどうかを指定します。
video_metadata (Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — 動画のメタデータで、総再生時間、fps、総フレーム数に関する情報を含みます。動画からのフレームサンプリングやタイムスタンプの計算に使用されます。動画を処理する前に手動でデコードしようとしている場合を除き、メタデータは渡さないでください。
fps (Annotated[int | float | None, None], kwargs) — do_sample_frames=True の場合、1 秒あたりサンプリングするターゲットフレーム数。
num_frames (Annotated[int | None, None], kwargs) — do_sample_frames=True の場合、サンプリングするフレームの最大数。
return_metadata (bool、kwargs、任意、デフォルトは False) — 動画メタデータを返すかどうかを指定します。動画メタデータは、動画の長さ、fps、デコードバックエンドなどの情報を含むオブジェクトです。
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 設定されている場合、特定のフレームワークのテンソルを返します。受け入れられる値は以下の通りです:
- 'pt': PyTorchのtorch.Tensorオブジェクトを返します。
- 'np': NumPyのnp.ndarrayオブジェクトを返します。
**kwargs (VideosKwargs、optional) — テキスト、画像、動画、音声の各モダリティに対する追加の処理オプション。モデル固有のパラメータは上記にリストされています。サポートされている引数の完全なリストについては、TypedDictクラスを参照してください。

VJEPA2VideoProcessorの動画プロセッサを構築します。

Update on GitHub