Transformers documentation
PE Audio
Este modelo se publicó en HF papers el 17 de abril de 2025 y se contribuyó a Hugging Face Transformers el 16 de diciembre de 2025. Este modelo se lanzó el 17 de abril de 2025 y se añadió a Hugging Face Transformers el 16 de diciembre de 2025.
PE Audio
PE Audio es la rama de audio de la familia Perception Encoder de Meta. Alinea de forma contrastiva las formas de onda crudas con texto en un espacio de incrustaciones compartido, entrenado con datos de audio y descripciones emparejados para la recuperación entre modalidades y la clasificación de audio sin ejemplos.
Se exponen dos cabezas sobre el mismo codificador. PeAudioModel devuelve una única representación agrupada por clip para la recuperación a nivel de clip, mientras que PeAudioFrameLevelModel devuelve una representación cada 40 ms para la localización de eventos y el análisis temporal de granularidad fina.
Puedes encontrar todos los puntos de control oficiales de PE Audio en la colección perception-encoder-audio-visual.
Introducción
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])})Consejos y notas de uso
- El audio debe ser mono (
feature_size=1) y re-muestreado a 48 kHz: el extractor de características emite una advertencia, pero no realiza la re-muestreada por ti. No se admite la entrada estéreo. - El audio de longitud variable se maneja con
padding_mask(no con el habitualattention_mask). La máscara se submuestrea internamente pordac_config.hop_lengthantes de llegar al codificador, por lo que debe pasarse la máscara en la resolución de la forma de onda cruda que devuelve el extractor de características. - PeAudioModel devuelve logits de forma
(n_audio, n_text). PeAudioFrameLevelModel devuelve(n_audio, n_text, n_frames)con un frame cada 40 ms. Elige la clase que corresponda a la tarea: comparten pesos, por lo que cambiar de una a otra tiene un coste bajo. - La torre de texto es un codificador compartido que se carga mediante
AutoModeldesdeconfig.text_config. El tokenizador se adjunta al procesador a través deAutoTokenizer, no mediante una clase dedicada.
PeAudioConfig
clase transformers.PeAudioConfig
< 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_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None )
Esta es la clase de configuración para almacenar la configuración de un PeAudioModel. Se utiliza para instanciar un modelo Pe Audio según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de facebook/pe-av-large
Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.
Ejemplo:
>>> 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.configPeAudioEncoderConfig
clase transformers.PeAudioEncoderConfig
< 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 = 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 )
Parámetros
- dac_config (
Union[PreTrainedConfig, dict], opcional) — Configuración del codificador de audio DAC utilizado para tokenizar las entradas de audio sin procesar. Si se pasa un diccionario, se utilizará para instanciar un DacConfig con los hiperparámetros predeterminados de DAC. - hidden_size (
int, opcional, valor predeterminado1792) — Dimensión de las representaciones ocultas. - intermediate_size (
int, opcional, valor predeterminado4800) — Dimensión de las representaciones del MLP. - num_hidden_layers (
int, opcional, valor predeterminado6) — Número de capas ocultas en el decodificador Transformer. - num_attention_heads (
int, opcional, valor predeterminado14) — Número de cabezas de atención para cada capa de atención en el decodificador Transformer. - num_key_value_heads (
int, opcional) — Este es el número de cabezas de key_value que se deben utilizar para implementar Grouped Query Attention. Sinum_key_value_heads=num_attention_heads, el modelo utilizará Multi Head Attention (MHA); sinum_key_value_heads=1, el modelo utilizará Multi Query Attention (MQA); en caso contrario, se utilizará GQA. Al convertir un checkpoint multi-head en un checkpoint GQA, cada cabeza de key y value del grupo debe construirse mediante el promedio (meanpooling) de todas las cabezas originales dentro de ese grupo. Para más detalles, consulta este artículo. Si no se especifica, el valor predeterminado seránum_attention_heads. - head_dim (
int, opcional, valor predeterminado128) — La dimensión de la cabeza de atención. Si es None, se establecerá en hidden_size // num_attention_heads - hidden_act (
str, opcional, valor predeterminadosilu) — La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo,"gelu","relu","silu", etc. - max_position_embeddings (
int, opcional, valor predeterminado10000) — La longitud máxima de secuencia con la que se podría utilizar este modelo. - initializer_range (
float, opcional, valor predeterminado0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos. - rms_norm_eps (
float, opcional, valor predeterminado1e-05) — La epsilon utilizada por las capas de normalización rms. - rope_parameters (
Union[~modeling_rope_utils.RopeParameters, dict], opcional) — Diccionario que contiene los parámetros de configuración para las incrustaciones RoPE. El diccionario debe contener un valor pararope_thetay, opcionalmente, parámetros utilizados para el escalado en caso de que desee usar RoPE conmax_position_embeddingsmás largos. - attention_bias (
bool, opcional, valor predeterminadoFalse) — Si se debe usar un sesgo en las capas de proyección de consulta, clave, valor y salida durante la autoatención. - attention_dropout (
Union[float, int], opcional, valor predeterminado0.0) — La proporción de dropout para las probabilidades de atención.
Esta es la clase de configuración para almacenar la configuración de un PeAudioModel. Se utiliza para instanciar un modelo Pe Audio según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de facebook/pe-av-large
Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.
>>> 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.configPeAudioFeatureExtractor
clase transformers.PeAudioFeatureExtractor
< source >( feature_size: int = 1sampling_rate: int = 48000padding_value: float = 0.0hop_length: int = 1920**kwargs )
Parámetros
- feature_size (
int, opcional, valor predeterminado 1) — La dimensión de las características de las características extraídas. Use 1 para mono y 2 para estéreo. - sampling_rate (
int, opcional, valor predeterminado 48000) — La tasa de muestreo a la que la forma de onda de audio debe digitalizarse, expresada en hercios (Hz). - padding_value (
float, opcional, valor predeterminado 0.0) — El valor que se utiliza para el relleno. - hop_length (
int, opcional, valor predeterminado 1920) — Longitud de solapamiento entre las ventanas sucesivas.
Construye un extractor de características PeAudioFeatureExtractor.
Este extractor de características hereda de SequenceFeatureExtractor, que contiene la mayoría de los métodos principales. Los usuarios deben consultar esta superclase para obtener más información sobre dichos métodos.
__call__
< source >( 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
PeAudioEncoder
clase transformers.PeAudioEncoder
< source >( config: PeAudioEncoderConfig )
Parámetros
- config (PeAudioEncoderConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.
El modelo PeAudio Encoder.
Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).
Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.
forward
< source >( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = None**kwargs ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
Parámetros
- input_values (
torch.Tensorde forma(batch_size, sequence_length)) — Valores flotantes de la forma de onda de audio de entrada. Los valores se pueden obtener cargando un archivo de audio.flaco.waven un array de tipolist[float], unnumpy.ndarrayo untorch.Tensor, por ejemplo mediante la biblioteca torchcodec (pip install torchcodec) o la biblioteca soundfile (pip install soundfile). Para preparar el array comoinput_values, se debe utilizar AutoProcessor para el relleno y la conversión a un tensor de tipotorch.Tensor. Consulte PeAudioProcessor.call() para más detalles. - padding_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en las muestras de relleno deinput_values. Los valores de la máscara seleccionados en[0, 1]:- 1 para las muestras que no están enmascaradas,
- 0 para las muestras que están enmascaradas.
Devuelve
BaseModelOutputWithPooling o tuple(torch.Tensor)
Un BaseModelOutputWithPooling o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (PeAudioConfig) y las entradas.
El método forward de PeAudioEncoder reemplaza el método especial __call__.
Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de
Moduledespués en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.
last_hidden_state (
torch.Tensorde forma(batch_size, sequence_length, hidden_size)) — Secuencia de estados ocultos en la salida de la última capa del modelo.pooler_output (
torch.Tensorde forma(batch_size, hidden_size)) — Estado oculto de la última capa del primer token de la secuencia (token de clasificación) después de un procesamiento adicional a través de las capas utilizadas para la tarea de preentrenamiento auxiliar. Por ejemplo, para la familia de modelos BERT, esto devuelve el token de clasificación después de procesarlo a través de una capa lineal y una función de activación tanh. Los pesos de la capa lineal se entrenan a partir del objetivo de predicción de la siguiente oración (clasificación) durante el preentrenamiento.hidden_states (
tuple(torch.Tensor), opcional, devuelto cuando se pasaoutput_hidden_states=Trueo cuandoconfig.output_hidden_states=True) — Tupla detorch.Tensor(una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma(batch_size, sequence_length, hidden_size).Estados ocultos del modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.
attentions (
tuple(torch.Tensor), opcional, se devuelve cuando se pasaoutput_attentions=Trueo cuandoconfig.output_attentions=True) — Tupla detorch.Tensor(una por cada capa) de forma(batch_size, num_heads, sequence_length, sequence_length).Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
PeAudioModel
forward
< source >( 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)
Parámetros
- input_ids (
torch.Tensorde forma(batch_size, sequence_length)) — Índices de los tokens de la secuencia de entrada en el vocabulario. El relleno se ignorará de forma predeterminada.Los índices se pueden obtener usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() y PreTrainedTokenizer.call() para más detalles.
- input_values (
torch.Tensorde forma(batch_size, sequence_length)) — Valores flotantes de la forma de onda de audio de entrada. Los valores se pueden obtener cargando un archivo de audio.flaco.waven un array de tipolist[float], unnumpy.ndarrayo untorch.Tensor, por ejemplo mediante la biblioteca torchcodec (pip install torchcodec) o la biblioteca soundfile (pip install soundfile). Para preparar el array comoinput_values, se debe utilizar AutoProcessor para el relleno y la conversión a un tensor de tipotorch.Tensor. Consulte PeAudioProcessor.call() para más detalles. - attention_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en los índices de tokens de relleno. Valores de máscara seleccionados en[0, 1]:- 1 para los tokens que no están enmascarados,
- 0 para los tokens que están enmascarados.
- padding_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en las muestras de relleno deinput_values. Los valores de la máscara seleccionados en[0, 1]:- 1 para las muestras que no están enmascaradas,
- 0 para las muestras que están enmascaradas.
- return_loss (
bool, opcional) — Indica si se debe devolver la pérdida.
Devuelve
PeAudioOutput o tuple(torch.Tensor)
Un PeAudioOutput o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (PeAudioConfig) y las entradas.
El método forward de PeAudioModel reemplaza el método especial __call__.
Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de
Moduledespués en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.
- loss (
torch.Tensorde forma(1,), opcional) — Pérdida contrastiva calculada entre las representaciones de audio y texto. - logits_audio_text (
torch.Tensorde forma(batch_size, batch_size), opcional) — Logits de similitud entre embeddings de audio y texto. PeAudioFrameLevelModel devuelve logits por cuadro de forma(batch_size, batch_size, sequence_length)en su lugar. - text_audio_embeds (
torch.Tensorde forma(batch_size, hidden_size), opcional) — Embeddings de texto proyectados al espacio de audio-texto. - audio_embeds (
torch.Tensorde forma(batch_size, hidden_size), opcional) — Incrustaciones de audio proyectadas al espacio audio-texto. PeAudioFrameLevelModel devuelve incrustaciones por cuadro de forma(batch_size, sequence_length, hidden_size)en su lugar. - text_outputs (
BaseModelOutputWithPooling, opcional) — Salidas del modelo para el codificador de texto, que incluyen el último estado oculto y la salida agrupada. - audio_outputs (
BaseModelOutputWithPooling, opcional) — Salidas del modelo para el codificador de audio, que incluyen el último estado oculto y la salida agrupada.
PeAudioFrameLevelModel
forward
< source >( 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)
Parámetros
- input_ids (
torch.Tensorde forma(batch_size, sequence_length)) — Índices de los tokens de la secuencia de entrada en el vocabulario. El relleno se ignorará de forma predeterminada.Los índices se pueden obtener usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() y PreTrainedTokenizer.call() para más detalles.
- input_values (
torch.Tensorde forma(batch_size, sequence_length)) — Valores flotantes de la forma de onda de audio de entrada. Los valores se pueden obtener cargando un archivo de audio.flaco.waven un array de tipolist[float], unnumpy.ndarrayo untorch.Tensor, por ejemplo mediante la biblioteca torchcodec (pip install torchcodec) o la biblioteca soundfile (pip install soundfile). Para preparar el array comoinput_values, se debe utilizar AutoProcessor para el relleno y la conversión a un tensor de tipotorch.Tensor. Consulte PeAudioProcessor.call() para más detalles. - attention_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en los índices de tokens de relleno. Valores de máscara seleccionados en[0, 1]:- 1 para los tokens que no están enmascarados,
- 0 para los tokens que están enmascarados.
- padding_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en las muestras de relleno deinput_values. Los valores de la máscara seleccionados en[0, 1]:- 1 para las muestras que no están enmascaradas,
- 0 para las muestras que están enmascaradas.
- return_loss (
bool, opcional) — Indica si se debe devolver la pérdida.
Devuelve
PeAudioOutput o tuple(torch.Tensor)
Un PeAudioOutput o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (PeAudioConfig) y las entradas.
El método forward de PeAudioFrameLevelModel sobrescribe el método especial __call__.
Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de
Moduledespués en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.
- loss (
torch.Tensorde forma(1,), opcional) — Pérdida contrastiva calculada entre las representaciones de audio y texto. - logits_audio_text (
torch.Tensorde forma(batch_size, batch_size), opcional) — Logits de similitud entre embeddings de audio y texto. PeAudioFrameLevelModel devuelve logits por cuadro de forma(batch_size, batch_size, sequence_length)en su lugar. - text_audio_embeds (
torch.Tensorde forma(batch_size, hidden_size), opcional) — Embeddings de texto proyectados al espacio de audio-texto. - audio_embeds (
torch.Tensorde forma(batch_size, hidden_size), opcional) — Incrustaciones de audio proyectadas al espacio audio-texto. PeAudioFrameLevelModel devuelve incrustaciones por cuadro de forma(batch_size, sequence_length, hidden_size)en su lugar. - text_outputs (
BaseModelOutputWithPooling, opcional) — Salidas del modelo para el codificador de texto, que incluyen el último estado oculto y la salida agrupada. - audio_outputs (
BaseModelOutputWithPooling, opcional) — Salidas del modelo para el codificador de audio, que incluyen el último estado oculto y la salida agrupada.