Hugging Face's logo

Transformers documentation

PE Audio

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

PE Audio

PE Audio — это аудиовариант семейства Perception Encoder от Meta. Он контрастно выравнивает исходные звуковые сигналы и текст в общем пространстве эмбеддингов, обучаясь на парных данных «аудио — описание» для кросс-модального поиска и классификации аудио в режиме zero-shot.

На вершине одного и того же энкодера размещены две головки. PeAudioModel возвращает одно пул-эмбеддинг на каждый клип для поиска на уровне клипов, а PeAudioFrameLevelModel возвращает одно эмбеддинг каждые 40 мс для локализации событий и детального временного анализа.

Все официальные контрольные точки PE Audio можно найти в коллекции perception-encoder-audio-visual.

Быстрый старт

import torch
from datasets import load_dataset
from transformers import AutoProcessor, PeAudioModel

processor = AutoProcessor.from_pretrained("facebook/pe-av-large")
model = PeAudioModel.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"]
labels = ["a dog barking", "a person speaking", "music playing"]

audio_inputs = processor.feature_extractor(audio, sampling_rate=48_000, return_tensors="pt").to(model.device)
text_inputs = processor.tokenizer(labels, padding=True, return_tensors="pt").to(model.device)
inputs = {**audio_inputs, **text_inputs}

with torch.no_grad():
    outputs = model(**inputs)

probs = outputs.logits_audio_text.sigmoid()
print({label: p.item() for label, p in zip(labels, probs[0])})

Советы и примечания по использованию

  • Аудио должно быть моно (feature_size=1) и пересэмплировано до 48 кГц — экстрактор признаков выводит предупреждение, но не выполняет пересэмплирование за вас. Стерео-вход не поддерживается.
  • Аудио переменной длины обрабатывается с помощью padding_mask (а не стандартного attention_mask). Маска внутренним образом уменьшается в dac_config.hop_length раз до того, как попадёт в энкодер, поэтому передавайте маску в разрешении исходной формы волны, которую возвращает извлекатель признаков.
  • PeAudioModel возвращает логиты формы (n_audio, n_text). PeAudioFrameLevelModel возвращает (n_audio, n_text, n_frames) с одним кадром каждые 40 мс. Выберите класс, соответствующий задаче, — они разделяют веса, поэтому переключение между ними дёшево.
  • Башня текста представляет собой общий энкодер, загружаемый через AutoModel из config.text_config. Токенизатор подключается к процессору через AutoTokenizer, а не через отдельный класс.

PeAudioConfig

класс transformers.PeAudioConfig

< >

( 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_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None )

Параметры

  • text_config (Union[dict, ~configuration_utils.PreTrainedConfig], необязательный) — Объект конфигурации или словарь конфигурации текстового бэкбона.
  • audio_config (Union[dict, ~configuration_utils.PreTrainedConfig], необязательный) — Объект конфигурации или словарь конфигурации аудио-бэкбона.

Это класс конфигурации для хранения конфигурации модели PeAudioModel. Он используется для создания модели Pe Audio в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации facebook/pe-av-large

Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.

Пример:

>>> from transformers import PeAudioModel, PeAudioConfig

>>> # Initializing a PeAudioModel style configuration
>>> configuration = PeAudioConfig()

>>> # Initializing a model from the pe-av-large style configuration
>>> model = PeAudioModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

PeAudioEncoderConfig

класс transformers.PeAudioEncoderConfig

< >

( 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 = Nonedac_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 )

Параметры

  • dac_config (Union[PreTrainedConfig, dict], необязательный) — Конфигурация аудио-энкодера DAC, используемого для токенизации входных аудиоданных. Если передан словарь, он будет использован для создания экземпляра DacConfig с параметрами DAC по умолчанию.
  • 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 для вероятностей внимания.

Это класс конфигурации для хранения конфигурации модели PeAudioModel. Он используется для создания модели Pe Audio в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации facebook/pe-av-large

Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.

>>> from transformers import PeAudioEncoder, PeAudioEncoderConfig

>>> # Initializing a PeAudioEncoder style configuration
>>> configuration = PeAudioEncoderConfig()

>>> # Initializing a model from the pe-av-large style configuration
>>> model = PeAudioEncoder(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

PeAudioFeatureExtractor

класс transformers.PeAudioFeatureExtractor

< >

( feature_size: int = 1sampling_rate: int = 48000padding_value: float = 0.0hop_length: int = 1920**kwargs )

Параметры

  • feature_size (int, необязательный, по умолчанию 1) — Размерность признаков извлечённых признаков. Используйте 1 для моно, 2 для стерео.
  • sampling_rate (int, необязательный, по умолчанию 48000) — Частота дискретизации, с которой аудиосигнал должен быть оцифрован, выраженная в герцах (Гц).
  • padding_value (float, необязательный, по умолчанию 0.0) — Значение, используемое для дополнения (padding).
  • hop_length (int, необязательный, по умолчанию 1920) — Длина перекрытия между последовательными окнами.

Создаёт экстрактор признаков PeAudioFeatureExtractor.

Этот экстрактор признаков наследуется от SequenceFeatureExtractor, который содержит большинство основных методов. За дополнительной информацией о них следует обращаться к этому суперклассу.

__call__

< >

( raw_audio: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]] | str | list[str]padding: bool | str | transformers.utils.generic.PaddingStrategy | None = Nonetruncation: bool | None = Falsemax_length: int | None = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = Nonesampling_rate: int | None = None )

PeAudioProcessor

класс transformers.PeAudioProcessor

< >

( *args**kwargs )

PeAudioEncoder

класс transformers.PeAudioEncoder

< >

( config: PeAudioEncoderConfig )

Параметры

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

Модель PeAudio Encoder.

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

Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

forward

< >

( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = None**kwargs ) → BaseModelOutputWithPooling 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. Подробности см. в PeAudioProcessor.call().
  • padding_mask (torch.Tensor формы (batch_size, sequence_length), необязательный) — Маска для исключения padding-элементов из input_values. Значения маски из диапазона [0, 1]:
    • 1 для образцов, которые не замаскированы,
    • 0 для образцов, которые замаскированы.

Возвращает

BaseModelOutputWithPooling или tuple(torch.Tensor)

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

Метод forward класса PeAudioEncoder переопределяет специальный метод __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 в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

PeAudioModel

класс transformers.PeAudioModel

< >

( config: PeAudioConfig )

forward

< >

( input_ids: Tensorinput_values: Tensorattention_mask: typing.Optional[torch.Tensor] = Nonepadding_mask: typing.Optional[torch.Tensor] = Nonereturn_loss: bool | None = None**kwargs ) → PeAudioOutput or tuple(torch.Tensor)

Параметры

  • input_ids (torch.Tensor формы (batch_size, sequence_length)) — Индексы токенов входной последовательности в словаре. По умолчанию токены отступов игнорируются. Индексы можно получить с помощью AutoTokenizer. Подробности — в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call(). Что такое входные идентификаторы?

    Индексы можно получить с помощью AutoTokenizer. Подробности см. в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call().

    Что такое входные идентификаторы?

  • 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. Подробности см. в PeAudioProcessor.call().
  • attention_mask (torch.Tensor формы (batch_size, sequence_length), , необязательный) — Маска для исключения токенов-заполнителей из внимания. Значения маски из диапазона [0, 1]:
    • 1 для токенов, которые не замаскированы,
    • 0 для токенов, которые замаскированы.

    Что такое маски внимания?

  • padding_mask (torch.Tensor формы (batch_size, sequence_length), необязательный) — Маска для исключения padding-элементов из input_values. Значения маски из диапазона [0, 1]:
    • 1 для образцов, которые не замаскированы,
    • 0 для образцов, которые замаскированы.
  • return_loss (bool, необязательный) — Указывает, нужно ли возвращать значение функции потерь.

Возвращает

PeAudioOutput или tuple(torch.Tensor)

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

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

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

  • loss (torch.Tensor формы (1,), необязательный) — Контрастивная функция потерь, вычисленная между представлениями аудио и текста.
  • logits_audio_text (torch.Tensor формы (batch_size, batch_size), необязательный) — Логиты сходности между аудио- и текстовыми эмбеддингами. PeAudioFrameLevelModel возвращает логиты для каждого кадра формы (batch_size, batch_size, sequence_length).
  • text_audio_embeds (torch.Tensor формы (batch_size, hidden_size), необязательный) — Векторы текста, спроецированные в пространство «аудио-текст».
  • audio_embeds (torch.Tensor формы (batch_size, hidden_size), необязательный) — Встраивания аудио, спроецированные в пространство «аудио-текст». PeAudioFrameLevelModel возвращает встраивания для каждого кадра формы (batch_size, sequence_length, hidden_size).
  • text_outputs (BaseModelOutputWithPooling, необязательный) — Выходы модели для текстового энкодера, включая последнее скрытое состояние и агрегированный выход.
  • audio_outputs (BaseModelOutputWithPooling, необязательный) — Выходы модели для аудио-кодера, включая последнее скрытое состояние и агрегированный выход.

PeAudioFrameLevelModel

класс transformers.PeAudioFrameLevelModel

< >

( config: PeAudioConfig )

forward

< >

( input_ids: Tensorinput_values: Tensorattention_mask: typing.Optional[torch.Tensor] = Nonepadding_mask: typing.Optional[torch.Tensor] = Nonereturn_loss: bool | None = None**kwargs ) → PeAudioOutput or tuple(torch.Tensor)

Параметры

  • input_ids (torch.Tensor формы (batch_size, sequence_length)) — Индексы токенов входной последовательности в словаре. По умолчанию токены отступов игнорируются. Индексы можно получить с помощью AutoTokenizer. Подробности — в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call(). Что такое входные идентификаторы?

    Индексы можно получить с помощью AutoTokenizer. Подробности см. в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call().

    Что такое входные идентификаторы?

  • 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. Подробности см. в PeAudioProcessor.call().
  • attention_mask (torch.Tensor формы (batch_size, sequence_length), , необязательный) — Маска для исключения токенов-заполнителей из внимания. Значения маски из диапазона [0, 1]:
    • 1 для токенов, которые не замаскированы,
    • 0 для токенов, которые замаскированы.

    Что такое маски внимания?

  • padding_mask (torch.Tensor формы (batch_size, sequence_length), необязательный) — Маска для исключения padding-элементов из input_values. Значения маски из диапазона [0, 1]:
    • 1 для образцов, которые не замаскированы,
    • 0 для образцов, которые замаскированы.
  • return_loss (bool, необязательный) — Указывает, нужно ли возвращать значение функции потерь.

Возвращает

PeAudioOutput или tuple(torch.Tensor)

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

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

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

  • loss (torch.Tensor формы (1,), необязательный) — Контрастивная функция потерь, вычисленная между представлениями аудио и текста.
  • logits_audio_text (torch.Tensor формы (batch_size, batch_size), необязательный) — Логиты сходности между аудио- и текстовыми эмбеддингами. PeAudioFrameLevelModel возвращает логиты для каждого кадра формы (batch_size, batch_size, sequence_length).
  • text_audio_embeds (torch.Tensor формы (batch_size, hidden_size), необязательный) — Векторы текста, спроецированные в пространство «аудио-текст».
  • audio_embeds (torch.Tensor формы (batch_size, hidden_size), необязательный) — Встраивания аудио, спроецированные в пространство «аудио-текст». PeAudioFrameLevelModel возвращает встраивания для каждого кадра формы (batch_size, sequence_length, hidden_size).
  • text_outputs (BaseModelOutputWithPooling, необязательный) — Выходы модели для текстового энкодера, включая последнее скрытое состояние и агрегированный выход.
  • audio_outputs (BaseModelOutputWithPooling, необязательный) — Выходы модели для аудио-кодера, включая последнее скрытое состояние и агрегированный выход.
Update on GitHub

←Parakeet Pocket TTS→