Transformers documentation
PE Audio
Este modelo foi publicado em HF papers em 2025-04-17 e contribuído para Hugging Face Transformers em 2025-12-16. Este modelo foi lançado em 2025-04-17 e adicionado ao Hugging Face Transformers em 2025-12-16.
PE Audio
PE Audio é o ramo de áudio da família Perception Encoder da Meta. Ele alinha contrastivamente formas de onda brutas com texto em um espaço de incorporação compartilhado, treinado em dados de áudio e legendas pareados para recuperação entre modalidades e classificação de áudio zero-shot.
Duas cabeças são expostas no topo do mesmo codificador. PeAudioModel retorna um embedding agregado por clipe para recuperação em nível de clipe, enquanto PeAudioFrameLevelModel retorna um embedding a cada 40 ms para localização de eventos e análise temporal de granularidade fina.
Você pode encontrar todos os checkpoints oficiais do PE Audio na coleção perception-encoder-audio-visual.
Início rápido
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])})Dicas e observações de uso
- O áudio deve ser mono (
feature_size=1) e reamostrado para 48 kHz — o extrator de recursos emite um aviso, mas não realiza a reamostragem por você. A entrada estéreo não é suportada. - Áudio de comprimento variável é tratado com
padding_mask(e não com o habitualattention_mask). A máscara é reduzida internamente pordac_config.hop_lengthantes de chegar ao codificador, portanto, passe a máscara na resolução da forma de onda bruta que o extrator de recursos retorna. - PeAudioModel retorna logits com a forma
(n_audio, n_text). PeAudioFrameLevelModel retorna(n_audio, n_text, n_frames)com um frame a cada 40 ms. Escolha a classe que corresponde à tarefa — elas compartilham pesos, então a troca é barata. - A torre de texto é um codificador compartilhado carregado via
AutoModela partir deconfig.text_config. O tokenizador é anexado ao processador viaAutoTokenizer, e não por meio de uma classe dedicada.
PeAudioConfig
classe 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 é a classe de configuração para armazenar a configuração de um PeAudioModel. Ela é usada para instanciar um modelo Pe Audio de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do facebook/pe-av-large
Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.
Exemplo:
>>> 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
classe 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) — Configuração para o codificador de áudio DAC usado para tokenizar as entradas de áudio bruto. Se um dicionário for passado, ele será usado para instanciar um DacConfig com os hiperparâmetros padrão do DAC. - hidden_size (
int, opcional, padrão1792) — Dimensão das representações ocultas. - intermediate_size (
int, opcional, padrão4800) — Dimensão das representações do MLP. - num_hidden_layers (
int, opcional, padrão6) — Número de camadas ocultas no decodificador do Transformer. - num_attention_heads (
int, opcional, padrão14) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer. - num_key_value_heads (
int, opcional) — Este é o número de cabeças de key_value que devem ser usadas para implementar Grouped Query Attention. Senum_key_value_heads=num_attention_heads, o modelo usará Multi Head Attention (MHA); senum_key_value_heads=1, o modelo usará Multi Query Attention (MQA); caso contrário, será usado GQA. Ao converter um checkpoint multi-head para um checkpoint GQA, cada grupo de cabeças de chave e valor deve ser construído por meio do meanpooling de todas as cabeças originais dentro desse grupo. Para mais detalhes, consulte este artigo. Se não for especificado, o valor padrão seránum_attention_heads. - head_dim (
int, opcional, padrão128) — A dimensão da cabeça de atenção. Se for None, o valor padrão será hidden_size // num_attention_heads - hidden_act (
str, opcional, padrãosilu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo,"gelu","relu","silu", etc. - max_position_embeddings (
int, opcional, padrão10000) — O comprimento máximo de sequência com o qual este modelo pode ser utilizado. - initializer_range (
float, opcional, padrão0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos. - rms_norm_eps (
float, opcional, padrão1e-05) — O epsilon usado pelas camadas de normalização rms. - rope_parameters (
Union[~modeling_rope_utils.RopeParameters, dict], opcional) — Dicionário contendo os parâmetros de configuração para os embeddings RoPE. O dicionário deve conter um valor pararope_thetae, opcionalmente, parâmetros usados para escalonamento, caso você queira usar RoPE commax_position_embeddingsmaiores. - attention_bias (
bool, opcional, padrãoFalse) — Indica se deve ser usado um viés nas camadas de projeção de query, key, value e output durante a autoatenção. - attention_dropout (
Union[float, int], opcional, padrão0.0) — A taxa de dropout para as probabilidades de atenção.
Esta é a classe de configuração para armazenar a configuração de um PeAudioModel. Ela é usada para instanciar um modelo Pe Audio de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do facebook/pe-av-large
Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.
>>> 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
classe transformers.PeAudioFeatureExtractor
< source >( feature_size: int = 1sampling_rate: int = 48000padding_value: float = 0.0hop_length: int = 1920**kwargs )
Parâmetros
- feature_size (
int, opcional, padrão 1) — A dimensão dos recursos dos recursos extraídos. Use 1 para mono e 2 para estéreo. - sampling_rate (
int, opcional, padrão 48000) — A taxa de amostragem na qual a forma de onda de áudio deve ser digitalizada, expressa em hertz (Hz). - padding_value (
float, opcional, padrão 0.0) — O valor utilizado para preenchimento. - hop_length (
int, opcional, padrão 1920) — Comprimento de sobreposição entre janelas sucessivas.
Constrói um extrator de recursos de áudio PeAudioFeatureExtractor.
Este extrator de características herda de SequenceFeatureExtractor, que contém a maioria dos métodos principais. Os usuários devem consultar essa superclasse para obter mais informações sobre esses 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
classe transformers.PeAudioEncoder
< source >( config: PeAudioEncoderConfig )
Parâmetros
- config (PeAudioEncoderConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.
O modelo PeAudio Encoder.
Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)
Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.
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 em ponto flutuante da forma de onda bruta de fala de entrada. Os valores podem ser obtidos carregando um arquivo de áudio.flacou.wavem um array do tipolist[float], umnumpy.ndarrayou umtorch.Tensor, por exemplo, por meio da biblioteca torchcodec (pip install torchcodec) ou da biblioteca soundfile (pip install soundfile). Para preparar o array parainput_values, o AutoProcessor deve ser usado para padding e conversão em um tensor do tipotorch.Tensor. Consulte PeAudioProcessor.call() para mais detalhes. - padding_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção em amostras de preenchimento deinput_values. Valores de máscara selecionados em[0, 1]:- 1 para amostras que não estão mascaradas,
- 0 para amostras que estão mascaradas.
Retorna
BaseModelOutputWithPooling ou tuple(torch.Tensor)
Um BaseModelOutputWithPooling ou uma tupla de
torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários
elementos, dependendo da configuração (PeAudioConfig) e das entradas.
O método forward do PeAudioEncoder substitui o método especial __call__.
Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de
Moduleem seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.
last_hidden_state (
torch.Tensorde forma(batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.pooler_output (
torch.Tensorde forma(batch_size, hidden_size)) — Estado oculto da última camada do primeiro token da sequência (token de classificação) após processamento adicional através das camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para a família de modelos BERT, isso retorna o token de classificação após o processamento através de uma camada linear e uma função de ativação tanh. Os pesos da camada linear são treinados a partir do objetivo de previsão da próxima frase (classificação) durante o pré-treinamento.hidden_states (
tuple(torch.Tensor), opcional, retornado quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.Tensor(um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma(batch_size, sequence_length, hidden_size).Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
attentions (
tuple(torch.Tensor), opcional, retornado quandooutput_attentions=Trueé passado ou quandoconfig.output_attentions=True) — Tupla detorch.Tensor(um para cada camada) com forma(batch_size, num_heads, sequence_length, sequence_length).Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.
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 formato(batch_size, sequence_length)) — Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão.Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.
- input_values (
torch.Tensorde forma(batch_size, sequence_length)) — Valores em ponto flutuante da forma de onda bruta de fala de entrada. Os valores podem ser obtidos carregando um arquivo de áudio.flacou.wavem um array do tipolist[float], umnumpy.ndarrayou umtorch.Tensor, por exemplo, por meio da biblioteca torchcodec (pip install torchcodec) ou da biblioteca soundfile (pip install soundfile). Para preparar o array comoinput_values, o AutoProcessor deve ser usado para o preenchimento (padding) e a conversão em um tensor do tipotorch.Tensor. Consulte PeAudioProcessor.call() para mais detalhes. - attention_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em[0, 1]:- 1 para tokens que não estão mascarados,
- 0 para tokens que estão mascarados.
- padding_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção em amostras de preenchimento deinput_values. Valores de máscara selecionados em[0, 1]:- 1 para amostras que não estão mascaradas,
- 0 para amostras que estão mascaradas.
- return_loss (
bool, opcional) — Indica se a perda deve ser retornada ou não.
Retorna
PeAudioOutput ou tuple(torch.Tensor)
Um PeAudioOutput ou uma tupla de
torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários
elementos, dependendo da configuração (PeAudioConfig) e das entradas.
O método forward do PeAudioModel sobrescreve o método especial __call__.
Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de
Moduleem seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.
- loss (
torch.Tensorde forma(1,), opcional) — Perda contrastiva calculada entre as representações de áudio e texto. - logits_audio_text (
torch.Tensorde forma(batch_size, batch_size), opcional) — Logits de similaridade entre embeddings de áudio e texto. O PeAudioFrameLevelModel retorna logits por quadro de forma(batch_size, batch_size, sequence_length)em vez disso. - text_audio_embeds (
torch.Tensorde forma(batch_size, hidden_size), opcional) — Embeddings de texto projetados para o espaço áudio-texto. - audio_embeds (
torch.Tensorde forma(batch_size, hidden_size), opcional) — Embebidings de áudio projetados no espaço áudio-texto. PeAudioFrameLevelModel retorna embebidings por quadro de forma(batch_size, sequence_length, hidden_size)em vez disso. - text_outputs (
BaseModelOutputWithPooling, opcional) — Saídas do modelo para o codificador de texto, incluindo o último estado oculto e a saída agregada. - audio_outputs (
BaseModelOutputWithPooling, opcional) — Saídas do modelo para o codificador de áudio, incluindo o último estado oculto e a saída agregada.
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 formato(batch_size, sequence_length)) — Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão.Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.
- input_values (
torch.Tensorde forma(batch_size, sequence_length)) — Valores em ponto flutuante da forma de onda bruta de fala de entrada. Os valores podem ser obtidos carregando um arquivo de áudio.flacou.wavem um array do tipolist[float], umnumpy.ndarrayou umtorch.Tensor, por exemplo, por meio da biblioteca torchcodec (pip install torchcodec) ou da biblioteca soundfile (pip install soundfile). Para preparar o array parainput_values, o AutoProcessor deve ser usado para padding e conversão em um tensor do tipotorch.Tensor. Consulte PeAudioProcessor.call() para mais detalhes. - attention_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em[0, 1]:- 1 para tokens que não estão mascarados,
- 0 para tokens que estão mascarados.
- padding_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção em amostras de preenchimento deinput_values. Valores de máscara selecionados em[0, 1]:- 1 para amostras que não estão mascaradas,
- 0 para amostras que estão mascaradas.
- return_loss (
bool, opcional) — Indica se a perda deve ser retornada ou não.
Retorna
PeAudioOutput ou tuple(torch.Tensor)
Um PeAudioOutput ou uma tupla de
torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários
elementos, dependendo da configuração (PeAudioConfig) e das entradas.
O método forward do PeAudioFrameLevelModel substitui o método especial __call__.
Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de
Moduleem seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.
- loss (
torch.Tensorde forma(1,), opcional) — Perda contrastiva calculada entre as representações de áudio e texto. - logits_audio_text (
torch.Tensorde forma(batch_size, batch_size), opcional) — Logits de similaridade entre embeddings de áudio e texto. PeAudioFrameLevelModel retorna logits por quadro de forma(batch_size, batch_size, sequence_length)em vez disso. - text_audio_embeds (
torch.Tensorde forma(batch_size, hidden_size), opcional) — Embeddings de texto projetados para o espaço áudio-texto. - audio_embeds (
torch.Tensorde forma(batch_size, hidden_size), opcional) — Embebedings de áudio projetados no espaço áudio-texto. PeAudioFrameLevelModel retorna embebedings por quadro de forma(batch_size, sequence_length, hidden_size)em vez disso. - text_outputs (
BaseModelOutputWithPooling, opcional) — Saídas do modelo para o codificador de texto, incluindo o último estado oculto e a saída agregada. - audio_outputs (
BaseModelOutputWithPooling, opcional) — Saídas do modelo para o codificador de áudio, incluindo o último estado oculto e a saída agregada.