Transformers documentation
PE Audio
このモデルは2025年4月17日にHF papersで公開され、2025年12月16日にHugging Face Transformersに貢献されました。 このモデルは2025年4月17日にリリースされ、2025年12月16日にHugging Face Transformersに追加されました。
PE Audio
PE Audioは、MetaのPerception Encoderファミリーの音声系モデルです。生波形とテキストを対照的にアラインして共有埋め込み空間にマッピングし、音声とキャプションのペアデータで学習することで、クロスモーダル検索とゼロショット音声分類を実現します。
同じエンコーダーの上に2つのヘッドが公開されています。PeAudioModelはクリップレベルの検索用に1クリップあたり1つのプーリング済み埋め込みを返し、PeAudioFrameLevelModelはイベントの位置特定と細粒度の時間解析用に40 msごとに1つの埋め込みを返します。
公式の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])})使用上のヒントと注意点
- Audio はモノラル (
feature_size=1) である必要があります。また、48 kHz にリサンプリングされている必要があります。feature extractor は警告は出しますが、リサンプリングは行いません。ステレオ入力はサポートされていません。 - 可変長のオーディオは
padding_mask（通常のattention_maskではなく）で処理されます。マスクはエンコーダーに到達する前にdac_config.hop_lengthで内部的にダウンサンプリングされるため、特徴抽出器が返す生波形解像度のマスクを渡してください。 - PeAudioModel は、形状が
(n_audio, n_text)の logits を返します。PeAudioFrameLevelModel は、40 ms ごとに 1 フレームとなる(n_audio, n_text, n_frames)を返します。タスクに合ったクラスを選択してください。両者は重みを共有しているため、切り替えのコストは低いです。 - テキストタワーは、
config.text_configからAutoModelを介して読み込まれる共有エンコーダーです。トークナイザーは専用クラスではなく、AutoTokenizerを介してプロセッサーに接続されます。
PeAudioConfig
class 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 )
これは 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.configPeAudioEncoderConfig
class 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 )
パラメータ
- dac_config (
Union[PreTrainedConfig, dict], 任意) — 生オーディオ入力をトークン化するために使用される DAC オーディオエンコーダーの設定です。辞書が渡された場合、デフォルトの DAC ハイパーパラメータを使用して DacConfig をインスタンス化するために使用されます。 - 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, 任意) — Grouped Query Attention を実装するために使用する key_value ヘッドの数です。num_key_value_heads=num_attention_headsの場合、モデルは Multi Head Attention (MHA) を使用し、num_key_value_heads=1の場合は Multi Query Attention (MQA) を使用し、それ以外の場合は GQA が使用されます。 マルチヘッドのチェックポイントを GQA チェックポイントに変換する際は、各グループの key ヘッドと value ヘッドは、そのグループ内の元のすべてのヘッドを平均プーリングして構築する必要があります。詳細については、この論文を参照してください。指定されない場合、デフォルトで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) — RMS正規化レイヤーで使用するepsilonです。 - rope_parameters (
Union[~modeling_rope_utils.RopeParameters, dict], 省略可) — RoPE 埋め込みの設定パラメータを含む辞書です。この辞書にはrope_thetaの値が含まれており、より長いmax_position_embeddingsで RoPE を使用する場合にスケーリングに使用されるパラメータが任意で含まれます。 - attention_bias (
bool、任意、デフォルトはFalse) — 自己注意機構において、クエリ、キー、バリュー、出力の投影層にバイアスを使用するかどうかを指定します。 - attention_dropout (
Union[float, int]、任意、デフォルトは0.0) — アテンション確率のドロップアウト率です。
これは 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.configPeAudioFeatureExtractor
class transformers.PeAudioFeatureExtractor
< source >( feature_size: int = 1sampling_rate: int = 48000padding_value: float = 0.0hop_length: int = 1920**kwargs )
PeAudioFeatureExtractor 特徴抽出器を構築します。
このフィーチャーエクストラクターは、主要なメソッドの大部分を含む SequenceFeatureExtractor を継承しています。これらのメソッドに関する詳細については、このスーパークラスを参照してください。
__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
class transformers.PeAudioEncoder
< source >( config: PeAudioEncoderConfig )
パラメータ
- config (PeAudioEncoderConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
PeAudio Encoder モデル。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
forward
< source >( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = None**kwargs ) → BaseModelOutputWithPooling or tuple(torch.FloatTensor)
パラメータ
- input_values (
torch.Tensor、shape(batch_size, sequence_length)) — 入力生の音声波形の浮動小数点数値。値は、.flacまたは.wav形式のオーディオファイルを読み込み、list[float]、numpy.ndarray、またはtorch.Tensor型の配列に変換することで取得できます。例えば、torchcodec ライブラリ（pip install torchcodec）や soundfile ライブラリ（pip install soundfile）を通じて行います。 配列をinput_valuesに整えるには、パディングとtorch.FloatTensor型への変換のために AutoProcessor を使用してください。詳細は PeAudioProcessor.call() を参照してください。 - padding_mask (
torch.Tensorの形状(batch_size, sequence_length), 、任意) — の padding サンプルに対して attention を実行しないためのマスクinput_values. の値は[0, 1]:- マスクされていないサンプルに対して1
- マスクされたサンプルには 0。
戻り値
BaseModelOutputWithPooling または tuple(torch.FloatTensor)
torch.FloatTensor のタプル、または return_dict=False が渡された場合、あるいは config.return_dict=False の場合は torch.FloatTensor のタプル、または BaseModelOutputWithPooling を返します。構成要素は、設定 (PeAudioConfig) および入力に応じて異なります。
PeAudioEncoderのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
last_hidden_state (
torch.FloatTensor、shape(batch_size, sequence_length, hidden_size)) — モデルの最終層の出力における隠れ状態のシーケンス。pooler_output (
torch.FloatTensor、shape(batch_size, hidden_size)) — 補助事前学習タスクに使用される層をさらに通して処理された後、シーケンスの最初のトークン（分類トークン）の最終層の隠れ状態。例えば、BERT 系のモデルでは、線形層と tanh 活性化関数を経て処理された後の分類トークンを返します。この線形層の重みは、事前学習中の次文予測（分類）目的から学習されます。hidden_states (
tuple(torch.FloatTensor)、optional、output_hidden_states=Trueが渡された場合またはconfig.output_hidden_states=Trueの場合に返されます)—torch.FloatTensorのタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は(batch_size, sequence_length, hidden_size)です。各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
attentions (
tuple(torch.FloatTensor)、optional、output_attentions=Trueが渡された場合またはconfig.output_attentions=Trueの場合に返されます)—torch.FloatTensorのタプル（各レイヤーごとに1つ）、形状は(batch_size, num_heads, sequence_length, sequence_length)。アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
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.FloatTensor)
パラメータ
- input_ids (
torch.Tensorの形状(batch_size, sequence_length)) — 語彙における入力シーケンスのトークンインデックスです。デフォルトでは、パディングは無視されます。インデックスはAutoTokenizerを使用して取得できます。詳細については、PreTrainedTokenizer.encode()およびPreTrainedTokenizer.call()を参照してください。
- input_values (
torch.Tensor、shape(batch_size, sequence_length)) — 入力生の音声波形の浮動小数点数値。値は、.flacまたは.wav形式のオーディオファイルを読み込み、list[float]、numpy.ndarray、またはtorch.Tensor型の配列に変換することで取得できます。例えば、torchcodec ライブラリ（pip install torchcodec）や soundfile ライブラリ（pip install soundfile）を通じて行います。 配列をinput_valuesに整えるには、パディングとtorch.FloatTensor型への変換のために AutoProcessor を使用してください。詳細は PeAudioProcessor.call() を参照してください。 - attention_mask (
torch.Tensorの形状(batch_size, sequence_length), 、任意) — パディングトークンのインデックスに対するアテンションを回避するためのマスク。[0, 1]:- マスクされていないトークンに対して1
- マスクされたトークンに対しては 0 です。
- padding_mask (
torch.Tensorの形状(batch_size, sequence_length), 、任意) — の padding サンプルに対して attention を実行しないためのマスクinput_values. の値は[0, 1]:- マスクされていないサンプルに対して1
- マスクされたサンプルには 0。
- return_loss (
bool, 任意) — 損失を返すかどうかを指定します。
戻り値
PeAudioOutput または tuple(torch.FloatTensor)
PeAudioOutput、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（PeAudioConfig）と入力に応じて、さまざまな要素で構成されます。
PeAudioModelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
- loss (
torch.FloatTensor、shape(1,)、optional) — 音声とテキストの表現間で計算される対比損失。 - logits_audio_text (
torch.FloatTensor、shape(batch_size, batch_size)、optional) — 音声とテキストの埋め込み間の類似度 logits。PeAudioFrameLevelModel は、代わりに shape(batch_size, batch_size, sequence_length)のフレームごとの logits を返します。 - text_audio_embeds (
torch.FloatTensor、shape(batch_size, hidden_size)、任意) — 音声テキスト空間に射影されたテキスト埋め込み。 - audio_embeds (
torch.FloatTensor、shape(batch_size, hidden_size)、optional) — オーディオテキスト空間に射影されたオーディオ埋め込み。 PeAudioFrameLevelModel は、代わりに shape(batch_size, sequence_length, hidden_size)のフレームごとの埋め込みを返します。 - text_outputs (
BaseModelOutputWithPooling、任意) — テキストエンコーダーのモデル出力。最終隠れ状態とプーリング済み出力を含みます。 - audio_outputs (
BaseModelOutputWithPooling、任意) — 音声エンコーダーの出力。最終隠れ状態とプーリング済み出力を含みます。
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.FloatTensor)
パラメータ
- input_ids (
torch.Tensorの形状(batch_size, sequence_length)) — 語彙における入力シーケンスのトークンインデックスです。デフォルトでは、パディングは無視されます。インデックスはAutoTokenizerを使用して取得できます。詳細については、PreTrainedTokenizer.encode()およびPreTrainedTokenizer.call()を参照してください。
- input_values (
torch.Tensor、shape(batch_size, sequence_length)) — 入力生の音声波形の浮動小数点数値。値は、.flacまたは.wav形式のオーディオファイルを読み込み、list[float]、numpy.ndarray、またはtorch.Tensor型の配列に変換することで取得できます。例えば、torchcodec ライブラリ（pip install torchcodec）や soundfile ライブラリ（pip install soundfile）を通じて行います。 配列をinput_valuesに整えるには、パディングとtorch.FloatTensor型への変換のために AutoProcessor を使用してください。詳細は PeAudioProcessor.call() を参照してください。 - attention_mask (
torch.Tensorの形状(batch_size, sequence_length), 、任意) — パディングトークンのインデックスに対するアテンションを回避するためのマスク。[0, 1]:- マスクされていないトークンに対して1
- マスクされたトークンに対しては 0 です。
- padding_mask (
torch.Tensorの形状(batch_size, sequence_length), 、任意) — の padding サンプルに対して attention を実行しないためのマスクinput_values. の値は[0, 1]:- マスクされていないサンプルに対して1
- マスクされたサンプルには 0。
- return_loss (
bool, 任意) — 損失を返すかどうかを指定します。
戻り値
PeAudioOutput または tuple(torch.FloatTensor)
PeAudioOutput、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（PeAudioConfig）と入力に応じて、さまざまな要素で構成されます。
PeAudioFrameLevelModelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
- loss (
torch.FloatTensor、shape(1,)、optional) — 音声とテキストの表現間で計算される対比損失。 - logits_audio_text (
torch.FloatTensor、shape(batch_size, batch_size)、optional) — 音声とテキストの埋め込み間の類似度 logits。PeAudioFrameLevelModel は、代わりに shape(batch_size, batch_size, sequence_length)のフレームごとの logits を返します。 - text_audio_embeds (
torch.FloatTensor、shape(batch_size, hidden_size)、任意) — 音声テキスト空間に射影されたテキスト埋め込み。 - audio_embeds (
torch.FloatTensor、shape(batch_size, hidden_size)、optional) — オーディオテキスト空間に射影されたオーディオ埋め込み。 PeAudioFrameLevelModel は、代わりに shape(batch_size, sequence_length, hidden_size)のフレームごとの埋め込みを返します。 - text_outputs (
BaseModelOutputWithPooling、任意) — テキストエンコーダーのモデル出力。最終隠れ状態とプーリング済み出力を含みます。 - audio_outputs (
BaseModelOutputWithPooling、任意) — 音声エンコーダーの出力。最終隠れ状態とプーリング済み出力を含みます。