Эта модель была опубликована в HF papers 11.06.2025 и добавлена в Hugging Face Transformers 11.06.2025.

V-JEPA 2

V-JEPA 2 (статья в блоге) — это подход к обучению видео-энкодеров в режиме самообучения, разработанный FAIR, Meta. Используя видеоданные интернет-масштаба, V-JEPA 2 демонстрирует наилучшие результаты в задачах понимания движения и предсказания действий человека. V-JEPA 2-AC — это модель мира в латентном пространстве, управляемая действиями, дообученная на основе V-JEPA 2 (с использованием небольшого объема данных взаимодействий робота), которая решает задачи манипуляции роботом без сбора данных, специфичных для конкретной среды, или обучения и калибровки, специфичных для конкретной задачи.

Все исходные контрольные точки V-JEPA2 можно найти в коллекции V-JEPA 2.

Эта модель была предоставлена koustuvs, yonigozlan и qubvel. Исходный код можно найти здесь.

Пример использования

Приведённый ниже фрагмент кода показывает, как загрузить модель V-JEPA 2 для извлечения признаков с помощью класса 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 также можно дообучить для классификации видео. В следующем фрагменте кода показано, как использовать модель классификации видео, дообученную на 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) — Количество временных кадров, используемых для одного растера; подробности см. в статье.
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) — Коэффициент drop path для слияния патчей.
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) — Коэффициент dropout для вероятностей внимания.
hidden_act (str, необязательный, по умолчанию gelu) — Нелинейная функция активации (функция или строка) в декодере. Например, "gelu", "relu", "silu" и т. д.
initializer_range (float, необязательный, по умолчанию 0.02) — Стандартное отклонение truncated_normal_initializer, используемое для инициализации всех матриц весов.
attention_dropout (Union[float, int], необязательный, по умолчанию 0.0) — Коэффициент dropout для вероятностей внимания.
num_pooler_layers (int, необязательный, по умолчанию 3) — Количество слоев само-внимания в пулере.
pred_hidden_size (int, необязательный, по умолчанию 384) — Размерность слоёв предиктора
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) — Инициализировать токены маски в предикторе нулями.
pred_mlp_ratio (float, необязательный, по умолчанию 4.0) — Отношение скрытого размера MLP, используемых в Predictor, к pred_hidden_size.

Это класс конфигурации для хранения конфигурации модели VJEPA2Model. Он используется для создания модели 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

класс transformers.VJEPA2Model

< source >

( config: VJEPA2Config )

Параметры

config (VJEPA2Config) — Класс конфигурации модели, содержащий все параметры модели. Инициализация по файлу конфигурации не загружает веса, связанные с моделью, только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().

Модель Vjepa2 без дополнительных слоёв, выводящая необработанные скрытые состояния.

Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)

Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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.Tensor)

Параметры

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 с формой [batch_size, patch_size, 1], необязательный) — Идентификаторы позиций маски, указывающие, какие патчи выходных данных кодировщика будут доступны предиктору. По умолчанию эта маска создаётся как torch.arange(N).unsqueeze(0).repeat(B,1), что означает полный доступ предиктора к контексту.
target_mask (torch.Tensor с формой [batch_size, patch_size, 1], необязательный) — Маска, задающая идентификаторы позиций, указывающих, какие патчи выходных данных кодировщика будут использоваться в качестве целевых для предсказателя. По умолчанию эта маска создаётся как torch.arange(N).unsqueeze(0).repeat(B,1), что означает, что предсказателю следует предсказывать все патчи кодировщика.
skip_predictor (bool, необязательный, по умолчанию False) — флаг для пропуска прямого прохода предиктора, полезен, если нужны только выходные данные энкодера

Возвращает

VJEPA2WithMaskedInputModelOutput или tuple(torch.Tensor)

VJEPA2WithMaskedInputModelOutput или кортеж из torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные элементы в зависимости от конфигурации (VJEPA2Config) и входных данных.

Метод forward модели VJEPA2Model переопределяет специальный метод __call__.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.

last_hidden_state (torch.Tensor формы (batch_size, sequence_length, hidden_size)) — Последовательность скрытых состояний на выходе последнего слоя модели.
masked_hidden_state (torch.Tensor формы (batch_size, sequence_length, hidden_size), необязательный, возвращается, если предоставлен context_mask, который применяется к выводам VJEPA2Encoder) — Скрытое состояние модели с маской.
hidden_states (tuple[torch.Tensor, ...], необязательный, возвращается при передаче output_hidden_states=True или когда config.output_hidden_states=True) — Кортеж из torch.Tensor (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы (batch_size, sequence_length, hidden_size).

Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.
attentions (tuple[torch.Tensor, ...], необязательный, возвращается при передаче output_attentions=True или когда config.output_attentions=True) — Кортеж torch.Tensor (по одному на каждый слой) формы (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 — трансформер с головкой для классификации видео (линейный слой поверх attentive pooler).

forward

< source >

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

Параметры

pixel_values_videos (torch.Tensor формы (batch_size, num_frames, num_channels, frame_size, frame_size)) — Тензоры, соответствующие входному видео. Пиксельные значения для видео можно получить с помощью VJEPA2VideoProcessor. Подробности см. в VJEPA2VideoProcessor.call() (processor_class использует VJEPA2VideoProcessor для обработки видео).
labels (torch.LongTensor формы (batch_size,), необязательный) — Метки для вычисления функции потерь классификации/регрессии изображений. Индексы должны находиться в диапазоне [0, ..., config.num_labels - 1]. Если config.num_labels == 1, вычисляется функция потерь регрессии (среднеквадратичная ошибка), если config.num_labels > 1 — функция потерь классификации (кросс-энтропия).

Возвращает

ImageClassifierOutput или tuple(torch.Tensor)

Объект ImageClassifierOutput или кортеж из torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные элементы в зависимости от конфигурации (VJEPA2Config) и входных данных.

Метод VJEPA2ForVideoClassification forward переопределяет специальный метод __call__.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.

loss (torch.Tensor формы (1,), необязательный, возвращается, если задан labels) — Потери классификации (или регрессии, если config.num_labels==1).
logits (torch.Tensor формы (batch_size, config.num_labels)) — Оценки для классификации (или регрессии, если config.num_labels==1) до применения SoftMax.
hidden_states (tuple(torch.Tensor), optional, возвращается, если передано output_hidden_states=True или если config.output_hidden_states=True) — Кортеж из torch.Tensor (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого этапа) формы (batch_size, sequence_length, hidden_size). Скрытые состояния (также называемые картами признаков) модели на выходе каждого этапа.
attentions (tuple(torch.Tensor), необязательный, возвращается при передаче output_attentions=True или при config.output_attentions=True) — Кортеж torch.Tensor (по одному на каждый слой) формы (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

класс transformers.VJEPA2VideoProcessor

< source >

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

Параметры

do_convert_rgb (bool, kwargs, optional) — Следует ли преобразовать изображение в RGB.
do_resize (bool, kwargs, optional, по умолчанию True) — Указывает, нужно ли изменять размер изображения.
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, по умолчанию {'shortest_edge' -- 292}): Определяет максимальные размеры входных данных для модели.
default_to_square (bool, kwargs, optional, по умолчанию True) — Определяет, следует ли по умолчанию использовать квадратное изображение при изменении размера, если size задано как int.
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs, по умолчанию 2) — Фильтр ресемплинга, используемый при изменении размера изображения. Может быть одним из значений перечисления PILImageResampling. Влияет только в том случае, если do_resize установлено в True.
do_rescale (bool, kwargs, optional, по умолчанию True) — Указывает, следует ли выполнять рескейлинг изображения.
rescale_factor (float, kwargs, optional, по умолчанию 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, optional) — Поддерживается только ChannelDimension.FIRST. Добавлено для совместимости с медленными процессорами.
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, optional) — Следует ли извлекать кадры из видео перед обработкой или обрабатывать видео целиком.
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.
num_frames (Annotated[int | None, None], kwargs) — Максимальное количество кадров для выборки при do_sample_frames=True.
return_metadata (bool, kwargs, optional, по умолчанию False) — Указывает, следует ли возвращать метаданные видео. Метаданные видео — это объект, содержащий информацию о длительности видео, частоте кадров (fps), используемом бэкенде декодирования и т. д.
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:
- 'pt': возвращает объекты torch.Tensor PyTorch.
- 'np': возвращает объекты NumPy np.ndarray.
**kwargs (VideosKwargs, optional) — Дополнительные параметры обработки для каждой модальности (текст, изображения, видео, аудио). Специфичные для модели параметры перечислены выше; полный список поддерживаемых аргументов см. в классе TypedDict.

Создаёт видеопроцессор VJEPA2VideoProcessor.

Update on GitHub