Transformers documentation
PE Audio Video
Эта модель была опубликована в HF papers 17.04.2025 и добавлена в Hugging Face Transformers 16.12.2025. Эта модель была выпущена 17.04.2025 и добавлена в Hugging Face Transformers 16.12.2025.
PE Audio Video
PE Audio Video — это совместная аудиовидеоветвь семейства Perception Encoder от Meta. Она кодирует аудиопоток и видеопоток вместе с общей текстовой башней, формируя контрастивные эмбеддинги для каждой парной комбинации: аудио-текст, видео-текст, аудио-видео и аудио+текст-видео, за один прямой проход.
Внутри модель выравнивает последовательность признаков видео по временному разрешению аудио с помощью интерполяции ближайшего соседа, благодаря чему клипы с различными частотами кадров и частотами дискретизации остаются синхронизированными. Веса текстового энкодера связаны между аудио- и видеоветвями.
Все официальные контрольные точки PE Audio Video можно найти в коллекции perception-encoder-audio-visual.
Быстрый старт
import torch
from datasets import load_dataset
from transformers import AutoProcessor, PeAudioVideoModel
from transformers.video_utils import load_video
processor = AutoProcessor.from_pretrained("facebook/pe-av-large")
model = PeAudioVideoModel.from_pretrained(
"facebook/pe-av-large",
device_map="auto",
)
ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
audio = ds[0]["audio"]["array"]
video, _ = load_video("https://huggingface.co/datasets/hf-internal-testing/fixtures_videos/resolve/main/tennis.mp4")
labels = ["a person playing tennis with background crowd", "a dog barking in a park"]
audio_inputs = processor.feature_extractor(audio, sampling_rate=48_000, return_tensors="pt").to(model.device)
video_inputs = processor.video_processor(video, num_frames=16, return_tensors="pt").to(model.device)
text_inputs = processor.tokenizer(labels, padding=True, return_tensors="pt").to(model.device)
inputs = {**audio_inputs, **video_inputs, **text_inputs}
with torch.no_grad():
outputs = model(**inputs)
print("audio-text:", outputs.logits_audio_text.sigmoid().tolist())
print("video-text:", outputs.logits_video_text.sigmoid().tolist())
print("audio-video:", outputs.logits_audio_video.sigmoid().tolist())Советы и примечания по использованию
- PeAudioVideoModel требует как минимум два из
input_ids,input_values,pixel_values_videos— если переданы только два, вызывается подмодель только для аудио или только для видео. Передача всех трёх активирует совместный путь аудио-видео-текст и полный набор матриц логитов вPeAudioVideoOutput. - Для аудио используется
padding_mask, а для видео —padding_mask_videosодновременно. Это независимые маски; не путайте их сattention_mask, которая зарезервирована для текстовой башни. - Выравнивание аудио и видео выполняется поэлементно внутри
_align_video_hidden_state, поэтому при сильно различающейся длине аудио и видео в батче происходит итерация, а не векторизация. Для повышения пропускной способности старайтесь, чтобы элементы в батче были примерно одинаковой длины. - Веса текстовой башни связаны между ветвями через
_tied_weights_keys— не пытайтесь загружать отдельные текстовые энкодеры для аудиочасти и видеочасти.
PeAudioVideoConfig
класс transformers.PeAudioVideoConfig
< 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 = Nonetext_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneaudio_video_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonetie_word_embeddings: bool = True )
Параметры
- text_config (
Union[dict, ~configuration_utils.PreTrainedConfig], необязательный) — Объект конфигурации или словарь конфигурации текстового бэкбона. - audio_video_config (
dictилиPreTrainedConfig, необязательный) — Конфигурация компонента аудио-видео кодировщика. - tie_word_embeddings (
bool, необязательный, по умолчаниюTrue) — Определяет, следует ли связывать веса эмбеддингов согласно маппингуtied_weights_keysмодели.
Это класс конфигурации для хранения настроек модели PeAudioVideoModel. Он используется для создания модели Pe Audio Video в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации facebook/pe-av-large
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
>>> from transformers import PeAudioVideoModel, PeAudioVideoConfig
>>> # Initializing a PeAudioVideoModel style configuration
>>> configuration = PeAudioVideoConfig()
>>> # Initializing a model from the pe-av-large style configuration
>>> model = PeAudioModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configPeAudioVideoEncoderConfig
класс transformers.PeAudioVideoEncoderConfig
< 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 = Noneaudio_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonevideo_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonehidden_size: int = 1792intermediate_size: int = 4800num_hidden_layers: int = 6num_attention_heads: int = 14num_key_value_heads: int | None = Nonehead_dim: int = 128hidden_act: str = 'silu'max_position_embeddings: int = 10000initializer_range: float = 0.02rms_norm_eps: float = 1e-05rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = Noneattention_bias: bool = Falseattention_dropout: float | int = 0.0 )
Параметры
- audio_config (
Union[dict, ~configuration_utils.PreTrainedConfig], необязательный) — Объект конфигурации или словарь конфигурации аудио-бэкбона. - video_config (
Union[PreTrainedConfig, dict], необязательный) — Конфигурация для видео-энкодера. Если передан словарь, он используется для создания экземпляра PeVideoEncoderConfig. - hidden_size (
int, необязательный, по умолчанию1792) — Размерность скрытых представлений. - intermediate_size (
int, необязательный, по умолчанию4800) — Размерность представлений MLP. - num_hidden_layers (
int, необязательный, по умолчанию6) — Количество скрытых слоев в декодере Transformer. - num_attention_heads (
int, необязательный, по умолчанию14) — Количество головок внимания в каждом слое внимания декодера Transformer. - num_key_value_heads (
int, необязательный) — Количество ключевых и value-голов, используемых для реализации Grouped Query Attention. Еслиnum_key_value_heads=num_attention_heads, модель использует Multi Head Attention (MHA); еслиnum_key_value_heads=1— Multi Query Attention (MQA); в остальных случаях применяется GQA. При конвертации мультиголовного чекпоинта в GQA-чекпоинт каждая групповая ключевая и value-голова должна построиться путём усреднения (meanpooling) всех исходных голов в этой группе. Дополнительные сведения см. в этой статье. Если параметр не задан, по умолчанию используетсяnum_attention_heads. - head_dim (
int, необязательный, по умолчанию128) — Размерность головы внимания. Если значение равно None, по умолчанию используется hidden_size // num_attention_heads - hidden_act (
str, необязательный, по умолчаниюsilu) — Нелинейная функция активации (функция или строка) в декодере. Например,"gelu","relu","silu"и т. д. - max_position_embeddings (
int, необязательный, по умолчанию10000) — Максимальная длина последовательности, с которой может использоваться эта модель. - initializer_range (
float, необязательный, по умолчанию0.02) — Стандартное отклонение truncated_normal_initializer, используемое для инициализации всех матриц весов. - rms_norm_eps (
float, необязательный, по умолчанию1e-05) — Значение epsilon, используемое слоями нормализации rms. - rope_parameters (
Union[~modeling_rope_utils.RopeParameters, dict], необязательный) — Словарь, содержащий параметры конфигурации для эмбеддингов RoPE. Словарь должен содержать значение дляrope_thetaи, при необходимости, параметры, используемые для масштабирования, если вы хотите использовать RoPE с более длиннымиmax_position_embeddings. - attention_bias (
bool, необязательный, по умолчаниюFalse) — Использовать ли смещение (bias) в слоях проекции query, key, value и output при само-внимании. - attention_dropout (
Union[float, int], необязательный, по умолчанию0.0) — Коэффициент dropout для вероятностей внимания.
Это класс конфигурации для хранения настроек модели PeAudioVideoModel. Он используется для создания модели Pe Audio Video в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации facebook/pe-av-large
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
>>> from transformers import PeAudioVideoEncoder, PeAudioVideoEncoderConfig
>>> # Initializing a PeAudioVideoEncoder style configuration
>>> configuration = PeAudioVideoEncoderConfig()
>>> # Initializing a model from the pe-av-large style configuration
>>> model = PeAudioVideoEncoder(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configPeAudioVideoProcessor
класс transformers.PeAudioVideoProcessor
< source >( feature_extractor = Nonevideo_processor = Nonetokenizer = None**kwargs )
PeAudioVideoEncoder
класс transformers.PeAudioVideoEncoder
< source >( config: PeAudioVideoEncoderConfig )
Параметры
- config (PeAudioVideoEncoderConfig) — Класс конфигурации модели, содержащий все параметры модели. Инициализация с помощью файла конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().
Модель PeAudioVideo Encoder.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
forward
< source >( input_values: typing.Optional[torch.Tensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Nonepadding_mask: typing.Optional[torch.Tensor] = Nonepadding_mask_videos: typing.Optional[torch.Tensor] = None**kwargs ) → PeAudioVideoEncoderOutput or tuple(torch.Tensor)
Параметры
- input_values (
torch.Tensorформы(batch_size, sequence_length), необязательный) — Значения типа float для входной необработанной звуковой волны. Значения можно получить, загрузив аудиофайл.flacили.wavв массив типаlist[float],numpy.ndarrayилиtorch.Tensor, например, с помощью библиотеки torchcodec (pip install torchcodec) или библиотеки soundfile (pip install soundfile). Для подготовки массива вinput_valuesследует использовать AutoProcessor для выравнивания (padding) и преобразования в тензор типаtorch.Tensor. Подробности см. в PeAudioVideoProcessor.call(). - pixel_values_videos (
torch.Tensorформы(batch_size, num_frames, num_channels, frame_size, frame_size), необязательный) — Тензоры, соответствующие входному видео. Пиксельные значения для видео можно получить с помощью PeVideoVideoProcessor. Подробности см. в PeVideoVideoProcessor.call() (PeAudioVideoProcessor использует PeVideoVideoProcessor для обработки видео). - padding_mask (
torch.Tensorформы(batch_size, sequence_length), необязательный) — Маска для исключения padding-элементов изinput_values. Значения маски из диапазона[0, 1]:- 1 для образцов, которые не замаскированы,
- 0 для образцов, которые замаскированы.
- padding_mask_videos (
torch.Tensorформы(batch_size, num_frames), , необязательный) — Маска для исключения кадров с заполнением из вычислений внимания. Значения маски из диапазона[0, 1]:- 1 для кадров, которые не замаскированы,
- 0 для кадров, которые замаскированы.
Возвращает
PeAudioVideoEncoderOutput или tuple(torch.Tensor)
PeAudioVideoEncoderOutput или кортеж из
torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (PeAudioVideoConfig) и входных данных.
Метод forward класса PeAudioVideoEncoder переопределяет специальный метод __call__.
Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр
Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.
last_hidden_state (
torch.Tensorформы(batch_size, sequence_length, hidden_size)) — Последовательность скрытых состояний на выходе последнего слоя модели.pooler_output (
torch.Tensorформы(batch_size, hidden_size)) — Скрытое состояние последнего слоя для первого токена последовательности (токен классификации) после дополнительной обработки слоями, используемыми для вспомогательной задачи предварительного обучения. Например, для моделей семейства BERT это возвращает токен классификации после обработки линейным слоем и функцией активации tanh. Веса линейного слоя обучаются по задаче предсказания следующего предложения (классификации) во время предварительного обучения.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, sequence_length, sequence_length).Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
audio_model_output (
BaseModelOutputWithPooling, необязательный) — Выход аудиоконвейера, содержащий последнее скрытое состояние, агрегированный выход и необязательные скрытые состояния и внимания. Подробности см. в BaseModelOutputWithPooling.video_model_output (
BaseModelOutputWithPooling, необязательный) — Выход видео-энкодера, содержащий последнее скрытое состояние, агрегированный выход, а также необязательные скрытые состояния и внимания. Подробности см. в BaseModelOutputWithPooling.
PeAudioVideoModel
forward
< source >( input_ids: typing.Optional[torch.Tensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Noneinput_values: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Nonepadding_mask_videos: typing.Optional[torch.Tensor] = Nonepadding_mask: typing.Optional[torch.Tensor] = Nonereturn_loss = False**kwargs ) → PeAudioVideoOutput or tuple(torch.Tensor)
Параметры
- input_ids (
torch.Tensorформы(batch_size, sequence_length), необязательный) — Индексы токенов входной последовательности в словаре. По умолчанию padding игнорируется.Индексы можно получить с помощью AutoTokenizer. Подробности см. в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call().
- pixel_values_videos (
torch.Tensorформы(batch_size, num_frames, num_channels, frame_size, frame_size), необязательный) — Тензоры, соответствующие входному видео. Пиксельные значения для видео можно получить с помощью PeVideoVideoProcessor. Подробности см. в PeVideoVideoProcessor.call() (PeAudioVideoProcessor использует PeVideoVideoProcessor для обработки видео). - input_values (
torch.Tensorформы(batch_size, sequence_length), необязательный) — Значения типа float для входной необработанной звуковой волны. Значения можно получить, загрузив аудиофайл.flacили.wavв массив типаlist[float],numpy.ndarrayилиtorch.Tensor, например, с помощью библиотеки torchcodec (pip install torchcodec) или библиотеки soundfile (pip install soundfile). Для подготовки массива вinput_valuesследует использовать AutoProcessor для выравнивания (padding) и преобразования в тензор типаtorch.Tensor. Подробности см. в PeAudioVideoProcessor.call(). - attention_mask (
torch.Tensorформы(batch_size, sequence_length), , необязательный) — Маска для исключения токенов-заполнителей из внимания. Значения маски из диапазона[0, 1]:- 1 для токенов, которые не замаскированы,
- 0 для токенов, которые замаскированы.
- padding_mask_videos (
torch.Tensorформы(batch_size, num_frames), , необязательный) — Маска для исключения кадров с заполнением из вычислений внимания. Значения маски из диапазона[0, 1]:- 1 для кадров, которые не замаскированы,
- 0 для кадров, которые замаскированы.
- padding_mask (
torch.Tensorформы(batch_size, sequence_length), необязательный) — Маска для исключения padding-элементов изinput_values. Значения маски из диапазона[0, 1]:- 1 для образцов, которые не замаскированы,
- 0 для образцов, которые замаскированы.
- return_loss (
bool, необязательный) — Указывает, нужно ли возвращать значение функции потерь.
Возвращает
PeAudioVideoOutput или tuple(torch.Tensor)
PeAudioVideoOutput или кортеж
torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (PeAudioVideoConfig) и входных данных.
Метод forward модели PeAudioVideoModel переопределяет специальный метод __call__.
Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр
Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.
- audio_embeds (
torch.Tensor, необязательный) — Вложения аудиомодальности. Форма(batch_size, sequence_length, hidden_size). - video_embeds (
torch.Tensor, необязательный) — Вложения модальности видео. Форма(batch_size, sequence_length, hidden_size). - audio_video_embeds (
torch.Tensor, необязательный) — Совместные аудио-видео эмбеддинги, полученные модулем слияния. Форма(batch_size, sequence_length, hidden_size). - text_audio_embeds (
torch.Tensor, необязательный) — Совместные эмбеддинги текста и аудио. Форма(batch_size, sequence_length, hidden_size). - text_video_embeds (
torch.Tensor, необязательный) — Совместные эмбеддинги текста и видео. Форма(batch_size, sequence_length, hidden_size). - text_audio_video_embeds (
torch.Tensor, необязательный) — Совместные эмбеддинги текста, аудио и видео, объединяющие все три модальности. Форма(batch_size, sequence_length, hidden_size). - audio_plus_text_embeds (
torch.Tensor, необязательный) — Соединённые аудио- и текстовые эмбеддинги (например, конкатенация или аддитивное слияние). Форма(batch_size, sequence_length, hidden_size). - video_plus_text_embeds (
torch.Tensor, необязательный) — Соединённые эмбеддинги видео и текста. Форма(batch_size, sequence_length, hidden_size). - text_outputs (
MaskedLMOutput, необязательный) — Выходные данные модели для текстового энкодера. Включает скрытые состояния, внимания и, при необходимости, потерю. - audio_outputs (
BaseModelOutputWithPooling, необязательный) — Выходы модели для аудио-кодера, включая последнее скрытое состояние и агрегированный выход. - video_outputs (
BaseModelOutputWithPooling, необязательный) — Выходы модели для видео-энкодера, включая последнее скрытое состояние и агрегированный выход. - audio_video_outputs (
BaseModelOutputWithPooling, необязательный) — Выходные данные модели для совместного аудио-видео кодировщика. - logits_audio_text (
torch.Tensor, необязательный) — Логиты сходства между аудио- и текстовыми эмбеддингами. Форма(batch_size, batch_size). - logits_video_text (
torch.Tensor, необязательный) — Логиты сходства между эмбеддингами видео и текста. Форма(batch_size, batch_size). - logits_audio_video (
torch.Tensor, необязательный) — Логиты сходства между аудио- и видеоэмбеддингами. Форма(batch_size, batch_size). - logits_audio_video_text (
torch.Tensor, необязательный) — Логиты сходства между модальностями аудио, видео и текста. - logits_audio_plus_text_video (
torch.Tensor, optional) — Логиты сходности между объединёнными (аудио + текст) эмбеддингами и эмбеддингами видео. - logits_video_plus_text_audio (
torch.Tensor, optional) — Логиты сходности между объединёнными (видео + текст) эмбеддингами и аудио-эмбеддингами. - audio_text_loss (
torch.Tensor, необязательный) — Контрастивная функция потерь, вычисленная между представлениями аудио и текста. - video_text_loss (
torch.Tensor, необязательный) — Контрастивная функция потерь, вычисленная между представлениями видео и текста. - audio_video_loss (
torch.Tensor, необязательный) — Контрастивная функция потерь, вычисленная между аудио- и видеопредставлениями. - audio_video_text_loss (
torch.Tensor, необязательный) — Совместная функция потерь для модальностей аудио, видео и текста. - audio_plus_text_video_loss (
torch.Tensor, optional) — Потери между слиянными (аудио + текст) представлениями и видео. - video_plus_text_audio_loss (
torch.Tensor, необязательный) — Потери между слиянными (видео + текст) представлениями и аудио. - loss (
torch.Tensor, необязательный) — Суммарная функция потерь для всех модальностей.