V-JEPA 2

V-JEPA 2 是 FAIR, Meta 开发的一种用于训练视频编码器的自监督方法。V-JEPA 2 使用互联网规模的视频数据，在运动理解和人类动作预测任务上取得了最先进的性能。V-JEPA 2-AC 是一种潜在的动作条件世界模型，由 V-JEPA 2 后训练而来（使用少量机器人轨迹交互数据），无需环境特定数据收集或任务特定训练或校准即可解决机器人操作任务。

您可以在 V-JEPA 2 集合中找到所有原始 V-JEPA2 检查点。

此模型由 koustuvs、yonigozlan 和 qubvel 贡献。原始代码可在此处找到。

用法示例

以下代码片段展示了如何使用 AutoModel 类加载 V-JEPA 2 模型进行特征提取。

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

processor = AutoVideoProcessor.from_pretrained("facebook/vjepa2-vitl-fpc64-256")
model = AutoModel.from_pretrained(
    "facebook/vjepa2-vitl-fpc64-256",
    torch_dtype=torch.float16,
    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 torch
import numpy as np

from torchcodec.decoders import VideoDecoder
from transformers import AutoVideoProcessor, AutoModelForVideoClassification

device = "cuda" if torch.cuda.is_available() else "cpu"

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

model = AutoModelForVideoClassification.from_pretrained(hf_repo).to(device)
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

class transformers.VJEPA2Config

< 来源 >

( patch_size = 16 crop_size = 256 frames_per_clip = 64 tubelet_size = 2 hidden_size = 1024 in_chans = 3 num_attention_heads = 16 num_hidden_layers = 24 drop_path_rate = 0.0 mlp_ratio = 4.0 layer_norm_eps = 1e-06 qkv_bias = True attention_probs_dropout_prob = 0.0 hidden_act = 'gelu' initializer_range = 0.02 attention_dropout = 0.0 num_pooler_layers = 3 pred_hidden_size = 384 pred_num_attention_heads = 12 pred_num_hidden_layers = 12 pred_num_mask_tokens = 10 pred_zero_init_mask_tokens = True pred_mlp_ratio = 4.0 **kwargs )

参数

patch_size (int, 可选, 默认为 16) — 每个补丁的大小（分辨率）。
crop_size (int, 可选, 默认为 256) — 模型的输入分辨率
frames_per_clip (int, 可选, 默认为 64) — 模型预训练时使用的帧数。不影响推理。
tubelet_size (int, 可选, 默认为 2) — 用于单个栅格的 temporal 帧数，更多信息请参阅论文。
hidden_size (int, 可选, 默认为 1024) — 编码器层的维度
in_chans (int, 可选, 默认为 3) — 输入通道数
num_attention_heads (int, 可选, 默认为 16) — 编码器中每个注意力层的注意力头数量
num_hidden_layers (int, 可选, 默认为 24) — 隐藏层数量
drop_path_rate (float, 可选, 默认为 0.0) — 每个样本的随机深度率（应用于残差层的主路径时）。
mlp_ratio (float, 可选, 默认为 4.0) — 编码器中使用的 MLPs 隐藏层大小与 hidden_size 的比率。
layer_norm_eps (float, 可选, 默认为 1e-06) — 层归一化层使用的 epsilon。
qkv_bias (bool, 可选, 默认为 True) — 是否为查询、键和值添加偏置。
attention_probs_dropout_prob (float, 可选, 默认为 0.0) — 注意力的 dropout 概率。所有全连接层的 dropout 概率。
hidden_act (str, 可选, 默认为 "gelu") — 编码器和池化器中的非线性激活函数（函数或字符串）。如果是字符串，支持 "gelu"、"relu"、"selu" 和 "gelu_new"。
initializer_range (float, 可选, 默认为 0.02) — 用于初始化所有权重矩阵的截断正态初始化器的标准差。
attention_dropout (float, 可选, 默认为 0.0) — 注意力的 dropout 概率。
num_pooler_layers (int, 可选, 默认为 3) — 池化器中自注意力层的数量。
pred_hidden_size (int, 可选, 默认为 384) — 预测器层的维度
pred_num_attention_heads (int, 可选, 默认为 12) — 预测器中每个注意力层的注意力头数量
pred_num_hidden_layers (int, 可选, 默认为 12) — 预测器中隐藏层的数量
pred_num_mask_tokens (int, 可选, 默认为 10) — 定义预测器中使用的掩码标记数量
pred_zero_init_mask_tokens (bool, 可选, 默认为 True) — 将预测器中的掩码标记初始化为 0。
pred_mlp_ratio (float, 可选, 默认为 4.0) — 预测器中使用的 MLPs 隐藏层大小与 pred_hidden_size 的比率。

这是一个配置类，用于存储 VJEPA2Model 的配置。它用于根据指定的参数实例化 VJEPA2 模型，定义模型架构。使用默认值实例化配置将生成与 VJEPA2 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

class transformers.VJEPA2Model

< 来源 >

( config: VJEPA2Config )

参数

config (VJEPA2Config) — 模型配置类，包含模型的所有参数。使用配置文件初始化不会加载与模型相关的权重，只加载配置。请查阅 from_pretrained() 方法以加载模型权重。

裸 Vjepa2 模型输出原始隐藏状态，顶部没有任何特定头部。

此模型继承自 PreTrainedModel。请查阅超类文档以了解库为其所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、修剪头部等）

此模型也是 PyTorch torch.nn.Module 的子类。将其用作常规 PyTorch 模块，并参考 PyTorch 文档了解所有与通用用法和行为相关的事项。

向前传播

< 来源 >

( pixel_values_videos: Tensor context_head_mask: typing.Optional[torch.Tensor] = None context_mask: typing.Optional[list[torch.Tensor]] = None target_head_mask: typing.Optional[torch.Tensor] = None target_mask: typing.Optional[list[torch.Tensor]] = None skip_predictor: bool = False output_attentions: typing.Optional[bool] = None output_hidden_states: typing.Optional[bool] = None ) → transformers.models.vjepa2.modeling_vjepa2.VJEPA2WithMaskedInputModelOutput 或 tuple(torch.FloatTensor)

参数

pixel_values_videos (torch.Tensor 形状为 [批量大小 x 帧数 x 通道数 x 高度 x 宽度], 必需) — 由 VJEPA2VideoProcessor 处理的输入视频像素。
context_head_mask (torch.Tensor 形状为 [头数] 或 [隐藏层数 x 头数], 可选) — 指示上下文是否保留头部的掩码（1.0 为保留，0.0 为丢弃）。
context_mask (torch.Tensor 形状为 [批量大小, 补丁大小, 1], 可选) — 指示哪些编码器输出补丁将暴露给预测器的掩码位置 ID。默认情况下，此掩码创建为 torch.arange(N).unsqueeze(0).repeat(B,1)，表示预测器可获取所有上下文。
target_head_mask (torch.Tensor 形状为 [头数] 或 [隐藏层数 x 头数], 可选) — 指示目标是否保留头部的掩码（1.0 为保留，0.0 为丢弃）。
target_mask (torch.Tensor 形状为 [批量大小, 补丁大小, 1], 可选) — 指示哪些编码器输出补丁将用作预测器预测目标的掩码位置 ID。默认情况下，此掩码创建为 torch.arange(N).unsqueeze(0).repeat(B,1)，表示预测器应预测所有编码器补丁。
skip_predictor (bool, 默认为 False) — 跳过预测器前向传播的标志，如果您只需要编码器输出，则很有用
output_attentions (bool, 可选) — 是否返回所有注意力层的注意力张量。有关更多详细信息，请参阅返回张量下的 attentions。
output_hidden_states (bool, 可选) — 是否返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量下的 hidden_states。

transformers.models.vjepa2.modeling_vjepa2.VJEPA2WithMaskedInputModelOutput 或 tuple(torch.FloatTensor)

一个 transformers.models.vjepa2.modeling_vjepa2.VJEPA2WithMaskedInputModelOutput 或一个 torch.FloatTensor 元组（如果传递 return_dict=False 或 config.return_dict=False 时），其中包含各种元素，具体取决于配置 (VJEPA2Config) 和输入。

last_hidden_state (形状为 (批量大小, 序列长度, 隐藏大小) 的 <class 'torch.FloatTensor'>.last_hidden_state) — 模型最后一层输出的隐藏状态序列。
masked_hidden_state (形状为 (批量大小, 序列长度, 隐藏大小) 的 torch.FloatTensor, 可选, 当提供应用于 VJEPA2Encoder 输出的 context_mask 时返回) — 模型的掩码隐藏状态。
hidden_states (tuple[torch.FloatTensor, ...], 可选, 当传递 output_hidden_states=True 或 config.output_hidden_states=True 时返回) — 形状为 (批量大小, 序列长度, 隐藏大小) 的 torch.FloatTensor 元组（一个用于嵌入层输出，如果模型有嵌入层，+ 一个用于每个层的输出）。

模型在每个层输出的隐藏状态以及可选的初始嵌入输出。
attentions (tuple[torch.FloatTensor, ...], 可选, 当传递 output_attentions=True 或 config.output_attentions=True 时返回) — 形状为 (批量大小, 头数, 序列长度, 序列长度) 的 torch.FloatTensor 元组（每个层一个）。

注意力 softmax 后的注意力权重，用于计算自注意力头中的加权平均值。
predictor_output (VJEPA2WithMaskedInputPredictorOutput, 可选) — 预测器模块的输出。

VJEPA2Model 前向方法，覆盖 __call__ 特殊方法。

尽管前向传播的配方需要在此函数中定义，但此后应调用 Module 实例而不是此函数，因为前者负责运行预处理和后处理步骤，而后者则默默地忽略它们。

VJEPA2ForVideoClassification

class transformers.VJEPA2ForVideoClassification

< 来源 >

( config: VJEPA2Config )

参数

config (VJEPA2Config) — 模型配置类，包含模型的所有参数。使用配置文件初始化不会加载与模型相关的权重，只加载配置。请查阅 from_pretrained() 方法以加载模型权重。

V-JEPA 2 模型 Transformer，顶部带有一个视频分类头（注意力池化器顶部的一个线性层）。

此模型继承自 PreTrainedModel。请查阅超类文档以了解库为其所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、修剪头部等）

此模型也是 PyTorch torch.nn.Module 的子类。将其用作常规 PyTorch 模块，并参考 PyTorch 文档了解所有与通用用法和行为相关的事项。

向前传播

< 来源 >

( pixel_values_videos: Tensor labels: typing.Optional[torch.Tensor] = None output_attentions: typing.Optional[bool] = None output_hidden_states: typing.Optional[bool] = None ) → transformers.modeling_outputs.ImageClassifierOutput 或 tuple(torch.FloatTensor)

参数

pixel_values_videos (形状为 [batch size x num_frames x num_channels x height x width] 的 torch.Tensor) — 由 VJEPA2VideoProcessor 处理的输入视频像素。
labels (形状为 (batch_size,) 的 torch.LongTensor，可选) — 用于计算图像分类/回归损失的标签。索引应在 [0, ..., config.num_labels - 1] 之间。如果 config.num_labels == 1，则计算回归损失（均方损失）；如果 config.num_labels > 1，则计算分类损失（交叉熵）。
output_attentions (bool，可选) — 是否返回所有注意力层的注意力张量。更多详细信息请参阅返回张量下的 attentions。
output_hidden_states (bool，可选) — 是否返回所有层的隐藏状态。更多详细信息请参阅返回张量下的 hidden_states。

transformers.modeling_outputs.ImageClassifierOutput 或 tuple(torch.FloatTensor)

一个 transformers.modeling_outputs.ImageClassifierOutput 或一个 torch.FloatTensor 元组（如果传递了 return_dict=False 或 config.return_dict=False），包含根据配置（VJEPA2Config）和输入的不同元素。

loss (形状为 (1,) 的 torch.FloatTensor，可选，当提供 labels 时返回) — 分类损失（如果 config.num_labels==1，则为回归损失）。
logits (形状为 (batch_size, config.num_labels) 的 torch.FloatTensor) — 分类（如果 config.num_labels==1，则为回归）分数（SoftMax 之前）。
hidden_states (tuple(torch.FloatTensor)，可选，当传递 output_hidden_states=True 或 config.output_hidden_states=True 时返回) — torch.FloatTensor 元组（一个用于嵌入层输出，如果模型有嵌入层，+ 一个用于每个阶段的输出），形状为 (batch_size, sequence_length, hidden_size)。模型在每个阶段输出的隐藏状态（也称为特征图）。
attentions (tuple(torch.FloatTensor)，可选，当传递 output_attentions=True 或 config.output_attentions=True 时返回) — torch.FloatTensor 元组（每层一个），形状为 (batch_size, num_heads, patch_size, sequence_length)。

注意力 softmax 后的注意力权重，用于计算自注意力头中的加权平均值。

VJEPA2ForVideoClassification 的 forward 方法，覆盖了 __call__ 特殊方法。

示例

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

< 源 >

( **kwargs: typing_extensions.Unpack[transformers.models.vjepa2.video_processing_vjepa2.VJEPA2VideoProcessorInitKwargs] )

< > 在 GitHub 上更新

Transformers

V-JEPA 2

用法示例

VJEPA2Config

class transformers.VJEPA2Config

VJEPA2Model

class transformers.VJEPA2Model

向前传播

VJEPA2ForVideoClassification

class transformers.VJEPA2ForVideoClassification

向前传播

VJEPA2VideoProcessor

class transformers.VJEPA2VideoProcessor