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

Ce modèle a été publié dans HF papers le 2025-04-17 et ajouté à Hugging Face Transformers le 2025-12-16. Ce modèle a été publié le 2025-04-17 et ajouté à Hugging Face Transformers le 2025-12-16.

PE Audio

PE Audio est la branche audio de la famille Perception Encoder de Meta. Il aligne de manière contrastive les formes d’onde brutes avec du texte dans un espace d’incorporation partagé, entraîné sur des données appariées audio–légende pour la récupération intermodale et la classification audio en zéro tirage.

Deux têtes sont exposées au sommet du même encodeur. PeAudioModel renvoie un seul embedding agrégé par clip pour la récupération au niveau du clip, tandis que PeAudioFrameLevelModel renvoie un embedding toutes les 40 ms pour la localisation d'événements et l'analyse temporelle fine.

Vous pouvez trouver tous les points de contrôle officiels de PE Audio dans la collection perception-encoder-audio-visual.

Démarrage rapide

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])})

Conseils et notes d'utilisation

  • L'audio doit être en mono (feature_size=1) et rééchantillonné à 48 kHz — l'extracteur de caractéristiques émet un avertissement mais ne procède pas à la rééchantillonnage à votre place. L'entrée stéréo n'est pas prise en charge.
  • Les audio de longueur variable sont gérés avec padding_mask (et non le attention_mask habituel). Le masque est sous-échantillonné en interne par dac_config.hop_length avant d’atteindre l’encodeur ; passez donc le masque à la résolution de la forme d’onde brute renvoyé par l’extracteur de caractéristiques.
  • PeAudioModel renvoie des logits de forme (n_audio, n_text). PeAudioFrameLevelModel renvoie (n_audio, n_text, n_frames) avec une frame toutes les 40 ms. Choisissez la classe qui correspond à la tâche — elles partagent les poids, donc le changement est peu coûteux.
  • La tour de texte est un encodeur partagé chargé via AutoModel à partir de config.text_config. Le tokeniseur est rattaché au processeur via AutoTokenizer, et non par une classe dédiée.

PeAudioConfig

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

Paramètres

  • text_config (Union[dict, ~configuration_utils.PreTrainedConfig], facultatif) — L'objet de configuration ou le dictionnaire du backbone de texte.
  • audio_config (Union[dict, ~configuration_utils.PreTrainedConfig], facultatif) — L'objet de configuration ou le dictionnaire du backbone audio.

Ceci est la classe de configuration destinée à stocker la configuration d'un PeAudioModel. Elle est utilisée pour instancier un modèle Pe Audio en fonction des arguments spécifiés, définissant ainsi l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de facebook/pe-av-large

Les objets de configuration héritent de PreTrainedConfig et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de PreTrainedConfig pour plus d’informations.

Exemple :

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

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

Paramètres

  • dac_config (Union[PreTrainedConfig, dict], facultatif) — Configuration de l'encodeur audio DAC utilisé pour tokeniser les entrées audio brutes. Si un dictionnaire est transmis, il servira à instancier un DacConfig avec les hyperparamètres DAC par défaut.
  • hidden_size (int, facultatif, par défaut 1792) — Dimension des représentations cachées.
  • intermediate_size (int, facultatif, par défaut 4800) — Dimension des représentations du MLP.
  • num_hidden_layers (int, facultatif, par défaut 6) — Nombre de couches cachées dans le décodeur Transformer.
  • num_attention_heads (int, facultatif, valeur par défaut 14) — Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer.
  • num_key_value_heads (int, facultatif) — Ceci est le nombre de têtes key_value à utiliser pour implémenter la Grouped Query Attention. Si num_key_value_heads=num_attention_heads, le modèle utilisera la Multi Head Attention (MHA), si num_key_value_heads=1 le modèle utilisera la Multi Query Attention (MQA), sinon la GQA est utilisée. Lors de la conversion d'un checkpoint multi-têtes en checkpoint GQA, chaque tête clé et valeur de groupe doit être construite par moyennage (meanpooling) de toutes les têtes d'origine au sein de ce groupe. Pour plus de détails, consultez ce papier. S'il n'est pas spécifié, la valeur par défaut est num_attention_heads.
  • head_dim (int, facultatif, par défaut 128) — La dimension des têtes d'attention. Si None, elle est par défaut égale à hidden_size // num_attention_heads
  • hidden_act (str, facultatif, par défaut silu) — La fonction d'activation non linéaire (fonction ou chaîne de caractères) du décodeur. Par exemple, "gelu", "relu", "silu", etc.
  • max_position_embeddings (int, facultatif, par défaut 10000) — La longueur de séquence maximale avec laquelle ce modèle pourrait être utilisé.
  • initializer_range (float, facultatif, par défaut 0.02) — L'écart-type de la truncated_normal_initializer utilisé pour initialiser toutes les matrices de poids.
  • rms_norm_eps (float, facultatif, valeur par défaut 1e-05) — L'épsilon utilisé par les couches de normalisation rms.
  • rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], facultatif) — Dictionnaire contenant les paramètres de configuration pour les embeddings RoPE. Le dictionnaire doit contenir une valeur pour rope_theta et, le cas échéant, les paramètres utilisés pour le mise à l’échelle si vous souhaitez utiliser RoPE avec des max_position_embeddings plus longs.
  • attention_bias (bool, facultatif, par défaut False) — Indique s'il faut utiliser un biais dans les couches de projection des requêtes, des clés, des valeurs et de la sortie lors de l'auto-attention.
  • attention_dropout (Union[float, int], facultatif, valeur par défaut 0.0) — Le taux de dropout appliqué aux probabilités d'attention.

Ceci est la classe de configuration destinée à stocker la configuration d'un PeAudioModel. Elle est utilisée pour instancier un modèle Pe Audio en fonction des arguments spécifiés, définissant ainsi l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de facebook/pe-av-large

Les objets de configuration héritent de PreTrainedConfig et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de PreTrainedConfig pour plus d’informations.

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

classe transformers.PeAudioFeatureExtractor

< >

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

Paramètres

  • feature_size (int, facultatif, par défaut 1) — La dimension des caractéristiques des fonctionnalités extraites. Utilisez 1 pour le mono, 2 pour le stéréo.
  • sampling_rate (int, facultatif, valeur par défaut 48000) — La fréquence d'échantillonnage à laquelle la forme d'onde audio doit être numérisée, exprimée en hertz (Hz).
  • padding_value (float, facultatif, par défaut 0.0) — La valeur utilisée pour le bourrage.
  • hop_length (int, facultatif, par défaut 1920) — Longueur de chevauchement entre les fenêtres successives.

Construit un extracteur de fonctionnalités PeAudioFeatureExtractor.

Cet extracteur de fonctionnalités hérite de SequenceFeatureExtractor, qui contient la plupart des méthodes principales. Les utilisateurs doivent se référer à cette superclasse pour plus d'informations sur ces méthodes.

__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

classe transformers.PeAudioProcessor

< >

( *args**kwargs )

PeAudioEncoder

classe transformers.PeAudioEncoder

< >

( config: PeAudioEncoderConfig )

Paramètres

  • config (PeAudioEncoderConfig) — Classe de configuration du modèle contenant tous les paramètres du modèle. L’initialisation à partir d’un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode from_pretrained() pour charger les poids du modèle.

Le modèle PeAudio Encoder.

Ce modèle hérite de PreTrainedModel. Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, la taille des têtes, etc.)

Ce modèle est également une sous-classe de torch.nn.Module de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l'utilisation et le comportement généraux.

forward

< >

( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = None**kwargs ) → BaseModelOutputWithPooling or tuple(torch.Tensor)

Paramètres

  • input_values (torch.Tensor de forme (batch_size, sequence_length)) — Valeurs flottantes de la forme d'onde brute de l'entrée audio. Les valeurs peuvent être obtenues en chargeant un fichier audio .flac ou .wav dans un tableau de type list[float], un numpy.ndarray ou un torch.Tensor, par exemple via la bibliothèque torchcodec (pip install torchcodec) ou la bibliothèque soundfile (pip install soundfile). Pour préparer le tableau en input_values, le AutoProcessor doit être utilisé pour le bourrage (padding) et la conversion en tenseur de type torch.Tensor. Voir PeAudioProcessor.call() pour plus de détails.
  • padding_mask (torch.Tensor de forme (batch_size, sequence_length), facultatif) — Masque pour éviter d'appliquer l'attention aux échantillons de bourrage de input_values. Les valeurs du masque sont choisies dans [0, 1]:
    • 1 pour les échantillons qui ne sont pas masqués,
    • 0 pour les échantillons masqués.

Retourne

BaseModelOutputWithPooling ou tuple(torch.Tensor)

Un BaseModelOutputWithPooling ou un tuple de torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers éléments en fonction de la configuration (PeAudioConfig) et des entrées.

La méthode forward de PeAudioEncoder redéfinit la méthode spéciale __call__.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance Module plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

  • last_hidden_state (torch.Tensor de forme (batch_size, sequence_length, hidden_size)) — Séquence d'états cachés à la sortie de la dernière couche du modèle.

  • pooler_output (torch.Tensor de forme (batch_size, hidden_size)) — État caché de la dernière couche du premier jeton de la séquence (jeton de classification) après un traitement supplémentaire par les couches utilisées pour la tâche de pré-entraînement auxiliaire. Par exemple, pour les modèles de la famille BERT, cela renvoie le jeton de classification après traitement par une couche linéaire et une fonction d'activation tanh. Les poids de la couche linéaire sont entraînés à partir de l'objectif de prédiction de la phrase suivante (classification) pendant le pré-entraînement.

  • hidden_states (tuple(torch.Tensor), facultatif, renvoyé lorsque output_hidden_states=True est passé ou lorsque config.output_hidden_states=True) — Tuple de torch.Tensor (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme (batch_size, sequence_length, hidden_size).

    États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives.

  • attentions (tuple(torch.Tensor), facultatif, renvoyé lorsque output_attentions=True est passé ou lorsque config.output_attentions=True) — Tuple de torch.Tensor (un par couche) de forme (batch_size, num_heads, sequence_length, sequence_length).

    Poids des attentions après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.

PeAudioModel

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

Paramètres

  • input_ids (torch.Tensor de forme (batch_size, sequence_length)) — Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut.

    Les indices peuvent être obtenus à l'aide de AutoTokenizer. Consultez PreTrainedTokenizer.encode() et PreTrainedTokenizer.call() pour plus de détails.

    Qu'est-ce que les identifiants d'entrée ?

  • input_values (torch.Tensor de forme (batch_size, sequence_length)) — Valeurs flottantes de la forme d'onde brute de l'entrée audio. Les valeurs peuvent être obtenues en chargeant un fichier audio .flac ou .wav dans un tableau de type list[float], un numpy.ndarray ou un torch.Tensor, par exemple via la bibliothèque torchcodec (pip install torchcodec) ou la bibliothèque soundfile (pip install soundfile). Pour préparer le tableau en input_values, le AutoProcessor doit être utilisé pour le bourrage (padding) et la conversion en tenseur de type torch.Tensor. Voir PeAudioProcessor.call() pour plus de détails.
  • attention_mask (torch.Tensor de forme (batch_size, sequence_length), facultatif) — Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans [0, 1]:
    • 1 pour les jetons qui ne sont pas masqués,
    • 0 pour les jetons masqués.

    Qu'est-ce que les masques d'attention ?

  • padding_mask (torch.Tensor de forme (batch_size, sequence_length), facultatif) — Masque pour éviter d'appliquer l'attention aux échantillons de bourrage de input_values. Les valeurs du masque sont choisies dans [0, 1]:
    • 1 pour les échantillons qui ne sont pas masqués,
    • 0 pour les échantillons masqués.
  • return_loss (bool, facultatif) — Indique s'il faut renvoyer la perte.

Retourne

PeAudioOutput ou tuple(torch.Tensor)

Un PeAudioOutput ou un tuple de torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers éléments en fonction de la configuration (PeAudioConfig) et des entrées.

La méthode forward du PeAudioModel redéfinit la méthode spéciale __call__.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance Module plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

  • loss (torch.Tensor de forme (1,), facultatif) — Perte contrastive calculée entre les représentations audio et texte.
  • logits_audio_text (torch.Tensor de forme (batch_size, batch_size), facultatif) — Logits de similarité entre les embeddings audio et texte. PeAudioFrameLevelModel renvoie à la place des logits par trame de forme (batch_size, batch_size, sequence_length).
  • text_audio_embeds (torch.Tensor de forme (batch_size, hidden_size), facultatif) — Embeddings de texte projetés dans l'espace audio-texte.
  • audio_embeds (torch.Tensor de forme (batch_size, hidden_size), facultatif) — Embeddings audio projetés dans l'espace audio-texte. PeAudioFrameLevelModel renvoie à la place des embeddings par trame de forme (batch_size, sequence_length, hidden_size).
  • text_outputs (BaseModelOutputWithPooling, facultatif) — Sorties du modèle pour l’encodeur de texte, incluant l’état caché final et la sortie agrégée.
  • audio_outputs (BaseModelOutputWithPooling, facultatif) — Sorties du modèle pour l’encodeur audio, incluant l’état caché final et la sortie agrégée.

PeAudioFrameLevelModel

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

Paramètres

  • input_ids (torch.Tensor de forme (batch_size, sequence_length)) — Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut.

    Les indices peuvent être obtenus à l'aide de AutoTokenizer. Consultez PreTrainedTokenizer.encode() et PreTrainedTokenizer.call() pour plus de détails.

    Qu'est-ce que les identifiants d'entrée ?

  • input_values (torch.Tensor de forme (batch_size, sequence_length)) — Valeurs flottantes de la forme d'onde brute de l'entrée audio. Les valeurs peuvent être obtenues en chargeant un fichier audio .flac ou .wav dans un tableau de type list[float], un numpy.ndarray ou un torch.Tensor, par exemple via la bibliothèque torchcodec (pip install torchcodec) ou la bibliothèque soundfile (pip install soundfile). Pour préparer le tableau en input_values, le AutoProcessor doit être utilisé pour le bourrage (padding) et la conversion en tenseur de type torch.Tensor. Voir PeAudioProcessor.call() pour plus de détails.
  • attention_mask (torch.Tensor de forme (batch_size, sequence_length), facultatif) — Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans [0, 1]:
    • 1 pour les jetons qui ne sont pas masqués,
    • 0 pour les jetons masqués.

    Qu'est-ce que les masques d'attention ?

  • padding_mask (torch.Tensor de forme (batch_size, sequence_length), facultatif) — Masque pour éviter d'appliquer l'attention aux échantillons de bourrage de input_values. Les valeurs du masque sont choisies dans [0, 1]:
    • 1 pour les échantillons qui ne sont pas masqués,
    • 0 pour les échantillons masqués.
  • return_loss (bool, facultatif) — Indique s'il faut renvoyer la perte.

Retourne

PeAudioOutput ou tuple(torch.Tensor)

Un PeAudioOutput ou un tuple de torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers éléments en fonction de la configuration (PeAudioConfig) et des entrées.

La méthode forward du modèle PeAudioFrameLevelModel redéfinit la méthode spéciale __call__.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance Module plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

  • loss (torch.Tensor de forme (1,), facultatif) — Perte contrastive calculée entre les représentations audio et texte.
  • logits_audio_text (torch.Tensor de forme (batch_size, batch_size), facultatif) — Logits de similarité entre les embeddings audio et texte. PeAudioFrameLevelModel renvoie à la place des logits par trame de forme (batch_size, batch_size, sequence_length).
  • text_audio_embeds (torch.Tensor de forme (batch_size, hidden_size), facultatif) — Embeddings de texte projetés dans l'espace audio-texte.
  • audio_embeds (torch.Tensor de forme (batch_size, hidden_size), facultatif) — Embeddings audio projetés dans l'espace audio-texte. PeAudioFrameLevelModel renvoie à la place des embeddings par trame de forme (batch_size, sequence_length, hidden_size).
  • text_outputs (BaseModelOutputWithPooling, facultatif) — Sorties du modèle pour l’encodeur de texte, incluant l’état caché final et la sortie agrégée.
  • audio_outputs (BaseModelOutputWithPooling, facultatif) — Sorties du modèle pour l’encodeur audio, incluant l’état caché final et la sortie agrégée.
Update on GitHub

←Parakeet Pocket TTS→