Hugging Face's logo

Transformers documentation

PE Audio Video

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

Model ini dipublikasikan di HF papers pada 2025-04-17 dan disumbangkan ke Hugging Face Transformers pada 2025-12-16. Model ini dirilis pada 2025-04-17 dan ditambahkan ke Hugging Face Transformers pada 2025-12-16.

PE Audio Video

PE Audio Video adalah cabang audio-video gabungan dari keluarga Perception Encoder milik Meta. Model ini mengkodekan aliran audio dan video secara bersama-sama dengan menara teks bersama, menghasilkan embedding kontras untuk setiap kombinasi pairwise, yaitu audio-teks, video-teks, audio-video, dan audio+teks-video, dari satu langkah forward pass.

Secara internal, model menyelaraskan urutan fitur video ke resolusi temporal audio melalui interpolasi tetangga terdekat, sehingga klip dengan frame rate yang berbeda dari sample rate tetap sinkron. Bobot encoder teks diikat di antara cabang audio dan video.

Anda dapat menemukan semua checkpoint resmi PE Audio Video di bawah koleksi perception-encoder-audio-visual.

Mulai Cepat

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

Tips dan catatan penggunaan

  • PeAudioVideoModel membutuhkan setidaknya dua dari input_ids, input_values, pixel_values_videos — jika hanya dua yang diberikan, model akan mengalihkan proses ke sub-model audio saja atau video saja. Menyerahkan ketiga parameter akan memicu jalur audio-video-teks gabungan dan seluruh set matriks logit di PeAudioVideoOutput.
  • Audio menggunakan padding_mask dan video menggunakan padding_mask_videos secara bersamaan. Keduanya adalah mask yang independen; jangan mencampurkannya dengan attention_mask, yang khusus untuk menara teks.
  • Penyelarasan audio–video berjalan per elemen batch di dalam _align_video_hidden_state, sehingga batch dengan panjang audio/video yang sangat berbeda akan diproses secara iteratif alih-alih divektorisasi. Jaga agar item dalam batch seimbang agar throughput tetap optimal.
  • Bobot menara teks diikat di antara cabang melalui _tied_weights_keys — jangan mencoba memuat encoder teks terpisah untuk bagian audio dan video.

PeAudioVideoConfig

kelas transformers.PeAudioVideoConfig

< >

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

Parameter

  • text_config (Union[dict, ~configuration_utils.PreTrainedConfig], opsional) — Objek config atau dictionary dari text backbone.
  • audio_video_config (dict atau PreTrainedConfig, opsional) — Konfigurasi untuk komponen encoder audio-video.
  • tie_word_embeddings (bool, opsional, default True) — Apakah akan mengikat bobot embedding sesuai dengan pemetaan tied_weights_keys model.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari PeAudioVideoModel. Kelas ini digunakan untuk membuat model Pe Audio Video sesuai dengan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari facebook/pe-av-large

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

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

PeAudioVideoEncoderConfig

kelas transformers.PeAudioVideoEncoderConfig

< >

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

Parameter

  • audio_config (Union[dict, ~configuration_utils.PreTrainedConfig], opsional) — Objek config atau dictionary dari audio backbone.
  • video_config (Union[PreTrainedConfig, dict], opsional) — Konfigurasi untuk video encoder. Jika dictionary diberikan, digunakan untuk menginstansiasi PeVideoEncoderConfig.
  • hidden_size (int, opsional, default 1792) — Dimensi dari representasi tersembunyi.
  • intermediate_size (int, opsional, default 4800) — Dimensi representasi MLP.
  • num_hidden_layers (int, opsional, default 6) — Jumlah lapisan tersembunyi dalam decoder Transformer.
  • num_attention_heads (int, opsional, default 14) — Jumlah attention head untuk setiap lapisan attention di decoder Transformer.
  • num_key_value_heads (int, opsional) — Ini adalah jumlah key_value heads yang harus digunakan untuk mengimplementasikan Grouped Query Attention. Jika num_key_value_heads=num_attention_heads, model akan menggunakan Multi Head Attention (MHA), jika num_key_value_heads=1 model akan menggunakan Multi Query Attention (MQA), selain itu GQA yang digunakan. Saat mengkonversi checkpoint multi-head menjadi checkpoint GQA, setiap group key dan value head harus dibangun dengan meanpooling semua head asli di dalam grup tersebut. Untuk detail lebih lanjut, lihat paper ini. Jika tidak ditentukan, akan default ke num_attention_heads.
  • head_dim (int, opsional, default 128) — Dimensi head perhatian. Jika None, nilainya akan default ke hidden_size // num_attention_heads
  • hidden_act (str, opsional, defaultnya silu) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, "gelu", "relu", "silu", dan sebagainya.
  • max_position_embeddings (int, opsional, default 10000) — Panjang maksimum urutan yang mungkin digunakan dengan model ini.
  • initializer_range (float, opsional, defaultnya 0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.
  • rms_norm_eps (float, opsional, defaultnya 1e-05) — Epsilon yang digunakan oleh lapisan normalisasi rms.
  • rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], opsional) — Kamus yang berisi parameter konfigurasi untuk embedding RoPE. Kamus tersebut harus berisi nilai untuk rope_theta dan secara opsional parameter yang digunakan untuk penskalaan jika Anda ingin menggunakan RoPE dengan max_position_embeddings yang lebih panjang.
  • attention_bias (bool, opsional, default False) — Apakah akan menggunakan bias pada lapisan proyeksi query, key, value, dan output selama self-attention.
  • attention_dropout (Union[float, int], opsional, default 0.0) — Rasio dropout untuk probabilitas perhatian.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari PeAudioVideoModel. Kelas ini digunakan untuk membuat model Pe Audio Video sesuai dengan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari facebook/pe-av-large

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

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

PeAudioVideoProcessor

kelas transformers.PeAudioVideoProcessor

< >

( feature_extractor = Nonevideo_processor = Nonetokenizer = None**kwargs )

PeAudioVideoEncoder

kelas transformers.PeAudioVideoEncoder

< >

( config: PeAudioVideoEncoderConfig )

Parameter

  • config (PeAudioVideoEncoderConfig) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.

Model PeAudioVideo Encoder.

Model ini mewarisi dari PreTrainedModel. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran embedding input, memangkas kepala, dll.)

Model ini juga merupakan subclass dari torch.nn.Module PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.

forward

< >

( 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.Tensor)

Parameter

  • input_values (torch.Tensor dengan bentuk (batch_size, sequence_length), opsional) — Nilai float dari waveform ucapan mentah input. Nilai dapat diperoleh dengan memuat file audio .flac atau .wav ke dalam array bertipe list[float], numpy.ndarray atau torch.Tensor, misalnya melalui pustaka torchcodec (pip install torchcodec) atau pustaka soundfile (pip install soundfile). Untuk menyiapkan array menjadi input_values, gunakan AutoProcessor untuk padding dan konversi menjadi tensor bertipe torch.Tensor. Lihat PeAudioVideoProcessor.call() untuk detailnya.
  • pixel_values_videos (torch.Tensor dengan bentuk (batch_size, num_frames, num_channels, frame_size, frame_size), opsional) — Tensor yang sesuai dengan video input. Nilai piksel untuk video dapat diperoleh menggunakan PeVideoVideoProcessor. Lihat PeVideoVideoProcessor.call() untuk detailnya (PeAudioVideoProcessor menggunakan PeVideoVideoProcessor untuk memproses video).
  • padding_mask (torch.Tensor dengan bentuk (batch_size, sequence_length), opsional) — Mask untuk menghindari eksekusi attention pada sampel padding dari input_values. Nilai mask dipilih dari [0, 1]:
    • 1 untuk sampel yang tidak dimasker,
    • 0 untuk sampel yang dimasker.
  • padding_mask_videos (torch.Tensor dengan bentuk (batch_size, num_frames), opsional) — Mask untuk menghindari eksekusi attention pada frame video padding. Nilai mask dipilih dari [0, 1]:
    • 1 untuk frame yang tidak dimasker,
    • 0 untuk frame yang dimasker.

Mengembalikan

PeAudioVideoEncoderOutput atau tuple(torch.Tensor)

PeAudioVideoEncoderOutput atau tuple dari torch.Tensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (PeAudioVideoConfig) dan input.

Metode forward dari PeAudioVideoEncoder menimpa metode khusus __call__.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

  • last_hidden_state (torch.Tensor dengan bentuk (batch_size, sequence_length, hidden_size)) — Urutan hidden-states pada keluaran lapisan terakhir model.

  • pooler_output (torch.Tensor dengan bentuk (batch_size, hidden_size)) — Hidden-state lapisan terakhir dari token pertama dalam urutan (token klasifikasi) setelah diproses lebih lanjut melalui lapisan yang digunakan untuk tugas pra-pelatihan tambahan. Misalnya, untuk keluarga model BERT, ini mengembalikan token klasifikasi setelah diproses melalui lapisan linear dan fungsi aktivasi tanh. Bobot lapisan linear dilatih dari tujuan prediksi kalimat berikutnya (klasifikasi) selama pra-pelatihan.

  • hidden_states (tuple(torch.Tensor), opsional, dikembalikan saat output_hidden_states=True dilewatkan atau saat config.output_hidden_states=True) — Tuple dari torch.Tensor (satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk (batch_size, sequence_length, hidden_size).

    Hidden-states model pada output setiap layer ditambah output embedding awal yang opsional.

  • attentions (tuple(torch.Tensor), opsional, dikembalikan saat output_attentions=True dilewatkan atau saat config.output_attentions=True) — Tuple dari torch.Tensor (satu untuk setiap layer) dengan bentuk (batch_size, num_heads, sequence_length, sequence_length).

    Bobot perhatian setelah softmax perhatian, digunakan untuk menghitung rata-rata berbobot di kepala perhatian diri (self-attention).

  • audio_model_output (BaseModelOutputWithPooling, opsional) — Output dari audio encoder, berisi last hidden state, pooled output, serta hidden states dan attentions opsional. Lihat BaseModelOutputWithPooling untuk detailnya.

  • video_model_output (BaseModelOutputWithPooling, opsional) — Output dari video encoder, berisi last hidden state, pooled output, serta hidden states dan attentions opsional. Lihat BaseModelOutputWithPooling untuk detailnya.

PeAudioVideoModel

kelas transformers.PeAudioVideoModel

< >

( config: PeAudioVideoConfig )

forward

< >

( 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.Tensor)

Parameter

  • input_ids (torch.Tensor dengan bentuk (batch_size, sequence_length), opsional) — Indeks token dari urutan input dalam kosakata. Padding akan diabaikan secara default.

    Indeks dapat diperoleh menggunakan AutoTokenizer. Lihat PreTrainedTokenizer.encode() dan PreTrainedTokenizer.call() untuk detailnya.

    Apa itu input ID?

  • pixel_values_videos (torch.Tensor dengan bentuk (batch_size, num_frames, num_channels, frame_size, frame_size), opsional) — Tensor yang sesuai dengan video input. Nilai piksel untuk video dapat diperoleh menggunakan PeVideoVideoProcessor. Lihat PeVideoVideoProcessor.call() untuk detailnya (PeAudioVideoProcessor menggunakan PeVideoVideoProcessor untuk memproses video).
  • input_values (torch.Tensor dengan bentuk (batch_size, sequence_length), opsional) — Nilai float dari waveform ucapan mentah input. Nilai dapat diperoleh dengan memuat file audio .flac atau .wav ke dalam array bertipe list[float], numpy.ndarray atau torch.Tensor, misalnya melalui pustaka torchcodec (pip install torchcodec) atau pustaka soundfile (pip install soundfile). Untuk menyiapkan array menjadi input_values, gunakan AutoProcessor untuk padding dan konversi menjadi tensor bertipe torch.Tensor. Lihat PeAudioVideoProcessor.call() untuk detailnya.
  • attention_mask (torch.Tensor dengan bentuk (batch_size, sequence_length), opsional) — Mask untuk menghindari eksekusi attention pada indeks token padding. Nilai mask dipilih dari [0, 1]:
    • 1 untuk token yang tidak dimasker,
    • 0 untuk token yang dimasker.

    Apa itu attention mask?

  • padding_mask_videos (torch.Tensor dengan bentuk (batch_size, num_frames), opsional) — Mask untuk menghindari eksekusi attention pada frame video padding. Nilai mask dipilih dari [0, 1]:
    • 1 untuk frame yang tidak dimasker,
    • 0 untuk frame yang dimasker.
  • padding_mask (torch.Tensor dengan bentuk (batch_size, sequence_length), opsional) — Mask untuk menghindari eksekusi attention pada sampel padding dari input_values. Nilai mask dipilih dari [0, 1]:
    • 1 untuk sampel yang tidak dimasker,
    • 0 untuk sampel yang dimasker.
  • return_loss (bool, opsional) — Apakah akan mengembalikan loss atau tidak.

Mengembalikan

PeAudioVideoOutput atau tuple(torch.Tensor)

PeAudioVideoOutput atau tuple dari torch.Tensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (PeAudioVideoConfig) dan input.

Metode forward dari PeAudioVideoModel menimpa metode khusus __call__.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

  • audio_embeds (torch.Tensor, opsional) — Embedding modality audio. Bentuk (batch_size, sequence_length, hidden_size).
  • video_embeds (torch.Tensor, opsional) — Embedding modalitas video. Bentuk (batch_size, sequence_length, hidden_size).
  • audio_video_embeds (torch.Tensor, opsional) — Embedding audio-video gabungan yang dihasilkan oleh modul fusi. Bentuk (batch_size, sequence_length, hidden_size).
  • text_audio_embeds (torch.Tensor, opsional) — Embedding gabungan teks dan audio. Bentuk (batch_size, sequence_length, hidden_size).
  • text_video_embeds (torch.Tensor, opsional) — Embedding teks-video gabungan. Bentuk (batch_size, sequence_length, hidden_size).
  • text_audio_video_embeds (torch.Tensor, opsional) — Embedding gabungan teks-audio-video yang menggabungkan ketiga modalitas. Bentuk (batch_size, sequence_length, hidden_size).
  • audio_plus_text_embeds (torch.Tensor, opsional) — Embedding audio dan teks yang digabungkan (misalnya, konkatenasi atau fusi aditif). Bentuk (batch_size, sequence_length, hidden_size).
  • video_plus_text_embeds (torch.Tensor, opsional) — Embedding video dan teks yang digabungkan. Bentuk (batch_size, sequence_length, hidden_size).
  • text_outputs (MaskedLMOutput, opsional) — Output model untuk encoder teks. Termasuk hidden states, attentions, dan secara opsional loss.
  • audio_outputs (BaseModelOutputWithPooling, opsional) — Output model untuk encoder audio, termasuk last hidden state dan pooled output.
  • video_outputs (BaseModelOutputWithPooling, opsional) — Output model untuk encoder video, termasuk last hidden state dan pooled output.
  • audio_video_outputs (BaseModelOutputWithPooling, opsional) — Output model untuk encoder audio-video gabungan.
  • logits_audio_text (torch.Tensor, opsional) — Logit kemiripan antara embedding audio dan teks. Bentuk (batch_size, batch_size).
  • logits_video_text (torch.Tensor, opsional) — Logit kemiripan antara embedding video dan teks. Bentuk (batch_size, batch_size).
  • logits_audio_video (torch.Tensor, opsional) — Logit kemiripan antara embedding audio dan video. Bentuk (batch_size, batch_size).
  • logits_audio_video_text (torch.Tensor, opsional) — Logit kemiripan di antara modalitas audio, video, dan teks.
  • logits_audio_plus_text_video (torch.Tensor, opsional) — Logit kemiripan antara embedding yang digabungkan (audio + teks) dan embedding video.
  • logits_video_plus_text_audio (torch.Tensor, opsional) — Logit kemiripan antara embedding yang digabungkan (video + teks) dan embedding audio.
  • audio_text_loss (torch.Tensor, opsional) — Loss kontrastif yang dihitung antara representasi audio dan teks.
  • video_text_loss (torch.Tensor, opsional) — Loss kontrastif yang dihitung antara representasi video dan teks.
  • audio_video_loss (torch.Tensor, opsional) — Loss kontrastif yang dihitung antara representasi audio dan video.
  • audio_video_text_loss (torch.Tensor, opsional) — Loss gabungan atas modalitas audio, video, dan teks.
  • audio_plus_text_video_loss (torch.Tensor, opsional) — Loss antara representasi yang digabungkan (audio + teks) dan video.
  • video_plus_text_audio_loss (torch.Tensor, opsional) — Loss antara representasi yang digabungkan (video + teks) dan audio.
  • loss (torch.Tensor, opsional) — Loss gabungan untuk semua loss per modalitas.
Update on GitHub

←PaliGemma Perceiver→