Transformers documentation
PE Audio Video
このモデルは2025年4月17日にHF papersで公開され、2025年12月16日にHugging Face Transformersに貢献されました。 このモデルは2025年4月17日にリリースされ、2025年12月16日にHugging Face Transformersに追加されました。
PE Audio Video
PE Audio Videoは、MetaのPerception Encoderファミリーにおける音声・動画の統合ブランチです。共有テキストタワーを用いて音声ストリームと動画ストリームを同時にエンコードし、1回のフォワードパスから、音声-テキスト、動画-テキスト、音声-動画、音声+テキスト-動画のすべてのペアワイズ組み合わせに対する対照的埋め込みを生成します。
モデル内部では、最近傍補間によって動画の特徴量シーケンスを音声の時間分解能に整列させるため、フレームレートとサンプリングレートが異なるクリップでも同期が保たれます。テキストエンコーダーの重みは、音声ブランチと動画ブランチの間で共有されています。
公式の PE Audio Video チェックポイントはすべて、perception-encoder-audio-visual コレクションの下で確認できます。
クイックスタート
import torch
from datasets import load_dataset
from transformers import AutoProcessor, PeAudioVideoModel
from transformers.video_utils import load_video
processor = AutoProcessor.from_pretrained("facebook/pe-av-large")
model = PeAudioVideoModel.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"]
video, _ = load_video("https://huggingface.co/datasets/hf-internal-testing/fixtures_videos/resolve/main/tennis.mp4")
labels = ["a person playing tennis with background crowd", "a dog barking in a park"]
audio_inputs = processor.feature_extractor(audio, sampling_rate=48_000, return_tensors="pt").to(model.device)
video_inputs = processor.video_processor(video, num_frames=16, return_tensors="pt").to(model.device)
text_inputs = processor.tokenizer(labels, padding=True, return_tensors="pt").to(model.device)
inputs = {**audio_inputs, **video_inputs, **text_inputs}
with torch.no_grad():
outputs = model(**inputs)
print("audio-text:", outputs.logits_audio_text.sigmoid().tolist())
print("video-text:", outputs.logits_video_text.sigmoid().tolist())
print("audio-video:", outputs.logits_audio_video.sigmoid().tolist())使用上のヒントと注意点
- PeAudioVideoModel には、
input_ids、input_values、pixel_values_videosのうち少なくとも 2 つが必要です。2 つのみが指定された場合、オーディオ専用またはビデオ専用のサブモデルにディスパッチされます。3 つすべてが指定された場合、オーディオ・ビデオ・テキストの統合パスがトリガーされ、PeAudioVideoOutputの完全な logit 行列セットが返されます。 - Audio では
padding_maskを、video ではpadding_mask_videosを同時に使用します。これらは独立したマスクであり、テキストタワー用に予約されているattention_maskと混同しないでください。 - Audio–video alignment は
_align_video_hidden_state内でバッチ要素ごとに実行されるため、音声と動画の長さが大きく異なるバッチではベクトル化されず、イテレーションで処理されます。スループットを確保するには、バッチ内のアイテムの長さを概ね均一に保ってください。 - テキストタワーの重みは
_tied_weights_keysを通じてブランチ間で共有されています。オーディオ側とビデオ側でそれぞれ別のテキストエンコーダーを読み込もうとしないでください。
PeAudioVideoConfig
クラス transformers.PeAudioVideoConfig
< 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_video_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonetie_word_embeddings: bool = True )
これは PeAudioVideoModel の設定を保存するための設定クラスです。指定された引数に基づいて Pe Audio Video モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、facebook/pe-av-large と同様の設定が得られます。
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
>>> from transformers import PeAudioVideoModel, PeAudioVideoConfig
>>> # Initializing a PeAudioVideoModel style configuration
>>> configuration = PeAudioVideoConfig()
>>> # Initializing a model from the pe-av-large style configuration
>>> model = PeAudioModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configPeAudioVideoEncoderConfig
クラス transformers.PeAudioVideoEncoderConfig
< 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 = Noneaudio_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonevideo_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 )
パラメータ
- audio_config (
Union[dict, ~configuration_utils.PreTrainedConfig]、任意) — オーディオバックボーンの config オブジェクトまたは辞書。 - video_config (
Union[PreTrainedConfig, dict], 任意) — ビデオエンコーダーの設定です。辞書が指定された場合、PeVideoEncoderConfig のインスタンス化に使用されます。 - 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) — アテンション確率のドロップアウト率です。
これは PeAudioVideoModel の設定を保存するための設定クラスです。指定された引数に基づいて Pe Audio Video モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、facebook/pe-av-large と同様の設定が得られます。
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
>>> from transformers import PeAudioVideoEncoder, PeAudioVideoEncoderConfig
>>> # Initializing a PeAudioVideoEncoder style configuration
>>> configuration = PeAudioVideoEncoderConfig()
>>> # Initializing a model from the pe-av-large style configuration
>>> model = PeAudioVideoEncoder(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configPeAudioVideoProcessor
class transformers.PeAudioVideoProcessor
< source >( feature_extractor = Nonevideo_processor = Nonetokenizer = None**kwargs )
PeAudioVideoEncoder
class transformers.PeAudioVideoEncoder
< source >( config: PeAudioVideoEncoderConfig )
パラメータ
- config (PeAudioVideoEncoderConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを使用してください。
PeAudioVideo Encoderモデル。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
forward
< source >( input_values: typing.Optional[torch.Tensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Nonepadding_mask: typing.Optional[torch.Tensor] = Nonepadding_mask_videos: typing.Optional[torch.Tensor] = None**kwargs ) → PeAudioVideoEncoderOutput 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 を使用してください。詳細は PeAudioVideoProcessor.call() を参照してください。 - pixel_values_videos (
torch.Tensor、形状(batch_size, num_frames, num_channels, frame_size, frame_size)、任意) — 入力動画に対応するテンソルです。動画のピクセル値は、PeVideoVideoProcessor を使用して取得できます。詳細については、PeVideoVideoProcessor.call() を参照してください（PeAudioVideoProcessor は動画の処理に PeVideoVideoProcessor を使用します）。 - padding_mask (
torch.Tensorの形状(batch_size, sequence_length), 、任意) — の padding サンプルに対して attention を実行しないためのマスクinput_values. の値は[0, 1]:- マスクされていないサンプルに対して1
- マスクされたサンプルには 0。
- padding_mask_videos (
torch.Tensorの形状(batch_size, num_frames), 、任意) — パディングされた動画フレームに対してアテンションを実行しないためのマスク。マスクの値は[0, 1]:- マスクされていないフレームに対して1
- マスクされたフレームは 0 です。
戻り値
PeAudioVideoEncoderOutput または tuple(torch.FloatTensor)
PeAudioVideoEncoderOutput、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（PeAudioVideoConfig）と入力に応じて、さまざまな要素で構成されます。
PeAudioVideoEncoderの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後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
audio_model_output (
BaseModelOutputWithPooling、任意) — オーディオエンコーダーの出力。最後の隠れ状態、プーリングされた出力、および任意の隠れ状態とアテンションを含みます。詳細は BaseModelOutputWithPooling を参照してください。video_model_output (
BaseModelOutputWithPooling、任意) — ビデオエンコーダーの出力。最後の隠れ状態、プーリング済み出力、および任意の隠れ状態とアテンションを含みます。詳細は BaseModelOutputWithPooling を参照してください。
PeAudioVideoModel
forward
< source >( input_ids: typing.Optional[torch.Tensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Noneinput_values: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Nonepadding_mask_videos: typing.Optional[torch.Tensor] = Nonepadding_mask: typing.Optional[torch.Tensor] = Nonereturn_loss = False**kwargs ) → PeAudioVideoOutput or tuple(torch.FloatTensor)
パラメータ
- input_ids (
torch.Tensorの形状(batch_size, sequence_length), 、任意) — 語彙における入力シーケンスのトークンインデックスです。デフォルトでは、パディングは無視されます。インデックスはAutoTokenizerを使用して取得できます。詳細については、PreTrainedTokenizer.encode()およびPreTrainedTokenizer.call()を参照してください。
- pixel_values_videos (
torch.Tensor、形状(batch_size, num_frames, num_channels, frame_size, frame_size)、任意) — 入力動画に対応するテンソルです。動画のピクセル値は、PeVideoVideoProcessor を使用して取得できます。詳細については、PeVideoVideoProcessor.call() を参照してください（PeAudioVideoProcessor は動画の処理に PeVideoVideoProcessor を使用します）。 - input_values (
torch.Tensor、形状(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 を使用してください。詳細は PeAudioVideoProcessor.call() を参照してください。 - attention_mask (
torch.Tensorの形状(batch_size, sequence_length), 、任意) — パディングトークンのインデックスに対するアテンションを回避するためのマスク。[0, 1]:- マスクされていないトークンに対して1
- マスクされたトークンに対しては 0 です。
- padding_mask_videos (
torch.Tensorの形状(batch_size, num_frames), 、任意) — パディングされた動画フレームに対してアテンションを実行しないためのマスク。マスクの値は[0, 1]:- マスクされていないフレームに対して1
- マスクされたフレームは 0 です。
- padding_mask (
torch.Tensorの形状(batch_size, sequence_length), 、任意) — の padding サンプルに対して attention を実行しないためのマスクinput_values. の値は[0, 1]:- マスクされていないサンプルに対して1
- マスクされたサンプルには 0。
- return_loss (
bool, 任意) — 損失を返すかどうかを指定します。
戻り値
PeAudioVideoOutput または tuple(torch.FloatTensor)
PeAudioVideoOutput、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（PeAudioVideoConfig）と入力に応じて、さまざまな要素で構成されます。
PeAudioVideoModelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
- audio_embeds (
torch.FloatTensor、任意) — 音声モダリティの埋め込み。形状は(batch_size, sequence_length, hidden_size)です。 - video_embeds (
torch.FloatTensor、任意) — ビデオモダリティの埋め込み。形状は(batch_size, sequence_length, hidden_size)です。 - audio_video_embeds (
torch.FloatTensor、任意) — 融合モジュールによって生成される、音声と動画の結合埋め込み。形状は(batch_size, sequence_length, hidden_size)です。 - text_audio_embeds (
torch.FloatTensor、任意) — テキストとオーディオの結合埋め込み。形状は(batch_size, sequence_length, hidden_size)です。 - text_video_embeds (
torch.FloatTensor、任意) — 結合テキスト・ビデオ埋め込み。形状は(batch_size, sequence_length, hidden_size)です。 - text_audio_video_embeds (
torch.FloatTensor, 任意) — テキスト・オーディオ・ビデオの3つのモーダルを統合した埋め込み。形状は(batch_size, sequence_length, hidden_size)です。 - audio_plus_text_embeds (
torch.FloatTensor、任意) — 音声とテキストの埋め込みを結合したもの（例：連結または加法的フュージョン）。形状は(batch_size, sequence_length, hidden_size)です。 - video_plus_text_embeds (
torch.FloatTensor、任意) — 動画とテキストの埋め込みを結合したもの。形状は(batch_size, sequence_length, hidden_size)です。 - text_outputs (
MaskedLMOutput、任意) — テキストエンコーダーのモデル出力。hidden states、attentions、および任意で loss を含みます。 - audio_outputs (
BaseModelOutputWithPooling、任意) — 音声エンコーダーの出力。最終隠れ状態とプーリング済み出力を含みます。 - video_outputs (
BaseModelOutputWithPooling、任意) — ビデオエンコーダーのモデル出力。最後の隠れ状態とプーリング済み出力を含みます。 - audio_video_outputs (
BaseModelOutputWithPooling、任意) — 音声・動画統合エンコーダーのモデル出力。 - logits_audio_text (
torch.FloatTensor、任意) — 音声とテキストの埋め込み間の類似度ロジット。形状は(batch_size, batch_size)です。 - logits_video_text (
torch.FloatTensor、任意) — 動画とテキストの埋め込み間の類似度ロジット。形状は(batch_size, batch_size)です。 - logits_audio_video (
torch.FloatTensor、任意) — 音声と動画の埋め込み間の類似度ロジット。形状は(batch_size, batch_size)です。 - logits_audio_video_text (
torch.FloatTensor、任意) — 音声、動画、テキストの各モダリティ間の類似度ロジット。 - logits_audio_plus_text_video (
torch.FloatTensor、任意) — 融合された（音声 + テキスト）埋め込みと動画埋め込みの間の類似度 logits。 - logits_video_plus_text_audio (
torch.FloatTensor、任意) — 融合された（動画 + テキスト）埋め込みと音声埋め込みの間の類似度 logits。 - audio_text_loss (
torch.FloatTensor、任意) — 音声とテキストの表現間で計算される対比損失。 - video_text_loss (
torch.FloatTensor、任意) — 動画とテキストの表現間で計算される対比損失。 - audio_video_loss (
torch.FloatTensor、任意) — 音声と動画の表現間で計算される対比損失。 - audio_video_text_loss (
torch.FloatTensor、任意) — 音声、動画、テキストの各モダリティにわたる結合損失です。 - audio_plus_text_video_loss (
torch.FloatTensor、任意) — 融合された（音声 + テキスト）表現と動画との間の損失。 - video_plus_text_audio_loss (
torch.FloatTensor、任意) — 融合された（動画 + テキスト）表現と音声との間の損失。 - loss (
torch.FloatTensor, オプション) — 各モダリティの損失を合計した損失です。