Transformers documentation
PE Audio
이 모델은 2025-04-17에 HF papers에 게시되었으며 2025-12-16에 Hugging Face Transformers에 기여되었습니다. 이 모델은 2025-04-17에 공개되었으며 2025-12-16에 Hugging Face Transformers에 추가되었습니다.
PE Audio
PE Audio는 Meta의 Perception Encoder 계열의 오디오 모델입니다. 원시 웨이브폼과 텍스트를 공유 임베딩 공간으로 대조적으로 정렬하며, 오디오-캡션 쌍 데이터로 학습되어 크로스모달 검색 및 제로샷 오디오 분류에 사용됩니다.
같은 encoder 위에 두 개의 head가 노출됩니다. PeAudioModel은 클립 수준 검색을 위해 클립당 하나의 풀링 임베딩을 반환하고, PeAudioFrameLevelModel은 이벤트 위치 파악과 세밀한 시간 분석을 위해 40ms마다 하나의 임베딩을 반환합니다.
공식 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로 다운샘플링되므로, feature extractor가 반환하는 원본 웨이브폼 해상도의 마스크를 전달해야 합니다. - PeAudioModel은
(n_audio, n_text)형태의 logits를 반환합니다. PeAudioFrameLevelModel은 40 ms마다 하나의 프레임을 포함하는(n_audio, n_text, n_frames)를 반환합니다. 작업에 맞는 클래스를 선택하세요. 두 클래스는 가중치를 공유하므로 교체 비용이 낮습니다. - 텍스트 타워는
config.text_config에서AutoModel을 통해 로드되는 공유 인코더입니다. 토크나이저는 전용 클래스가 아니라AutoTokenizer를 통해 프로세서에 연결됩니다.
PeAudioConfig
클래스 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와 유사한 구성이 생성됩니다.
Configuration 객체는 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
클래스 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 decoder의 숨겨진 레이어 수입니다. - num_attention_heads (
int, 선택 사항, 기본값14) — Transformer decoder의 각 attention layer에 사용할 attention head의 수입니다. - 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 헤드는 해당 그룹 내 모든 원래 헤드를 meanpooling하여 구성해야 합니다. 자세한 내용은 이 논문을 확인하세요. 지정되지 않으면num_attention_heads가 기본값으로 사용됩니다. - head_dim (
int, 선택 사항, 기본값128) — Attention head의 차원입니다. 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) — 자기 주의(self-attention) 시 query, key, value 및 출력 투영 계층에 bias를 사용할지 여부입니다. - attention_dropout (
Union[float, int], 선택 사항, 기본값0.0) — Attention 확률에 적용할 dropout 비율입니다.
이것은 PeAudioModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Pe Audio 모델을 인스턴스화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 facebook/pe-av-large와 유사한 구성이 생성됩니다.
Configuration 객체는 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
클래스 transformers.PeAudioFeatureExtractor
< source >( feature_size: int = 1sampling_rate: int = 48000padding_value: float = 0.0hop_length: int = 1920**kwargs )
PeAudioFeatureExtractor 피처 추출기를 생성합니다.
이 feature extractor는 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.Tensor)
매개변수
- input_values (
torch.Tensor, shape(batch_size, sequence_length)) — 입력 원시 음성 파형의 Float 값..flac또는.wav오디오 파일을list[float]타입의 배열,numpy.ndarray또는torch.Tensor로 로드하여 값을 얻을 수 있습니다. 예를 들어 torchcodec 라이브러리(pip install torchcodec) 또는 soundfile 라이브러리(pip install soundfile)를 사용할 수 있습니다. 배열을input_values로 준비하려면 패딩 및torch.Tensor타입의 텐서 변환을 위해 AutoProcessor를 사용해야 합니다. 자세한 내용은 PeAudioProcessor.call()를 참조하세요. - padding_mask (
torch.Tensor의 shape가(batch_size, sequence_length), 선택 사항) — 의 padding 샘플에 attention을 수행하지 않도록 하는 마스크input_values. 에서 선택된 마스크 값[0, 1]:- 마스크가 적용되지 않은 샘플의 경우 1
- 마스크된 샘플의 경우 0
반환값
BaseModelOutputWithPooling 또는 tuple(torch.Tensor)
torch.Tensor의 튜플 또는 BaseModelOutputWithPooling (return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(PeAudioConfig)과 입력에 따라 다양한 요소를 포함합니다.
PeAudioEncoder의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
last_hidden_state (
torch.Tensor, shape(batch_size, sequence_length, hidden_size)) — 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.pooler_output (
torch.Tensor, shape(batch_size, hidden_size)) — 보조 사전 학습 작업을 위해 사용되는 레이어들을 통해 추가 처리된 시퀀스의 첫 번째 토큰(분류 토큰)의 마지막 레이어 hidden-state입니다. 예를 들어 BERT 계열 모델의 경우, 선형 레이어와 tanh 활성화 함수를 통해 처리된 후의 분류 토큰을 반환합니다. 선형 레이어의 가중치는 사전 학습 동안 다음 문장 예측(분류) 목적 함수를 통해 학습됩니다.hidden_states (
tuple(torch.Tensor), 선택 사항,output_hidden_states=True가 전달되거나config.output_hidden_states=True인 경우 반환됨) —torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은(batch_size, sequence_length, hidden_size)입니다.각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
attentions (
tuple(torch.Tensor), 선택 사항,output_attentions=True가 전달되었거나config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, sequence_length, sequence_length)입니다.self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치.
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)
매개변수
- input_ids (
torch.Tensor의 shape(batch_size, sequence_length)) — 어휘 사전에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 Padding은 무시됩니다.AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.
- input_values (
torch.Tensor, shape(batch_size, sequence_length)) — 입력 원시 음성 파형의 Float 값..flac또는.wav오디오 파일을list[float]타입의 배열,numpy.ndarray또는torch.Tensor로 로드하여 값을 얻을 수 있습니다. 예를 들어 torchcodec 라이브러리(pip install torchcodec) 또는 soundfile 라이브러리(pip install soundfile)를 사용할 수 있습니다. 배열을input_values로 준비하려면 패딩 및torch.Tensor타입의 텐서 변환을 위해 AutoProcessor를 사용해야 합니다. 자세한 내용은 PeAudioProcessor.call()를 참조하세요. - attention_mask (
torch.Tensor형상이(batch_size, sequence_length), 선택 사항) — 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크. [0, 1]에서 선택된 마스크 값: 마스크되지 않은 토큰은 1, 마스크된 토큰은 0. attention mask란 무엇인가요?[0, 1]:- 마스크되지 않은 토큰에 대해 1
- 마스크된 토큰에 대해 0
- padding_mask (
torch.Tensor의 shape가(batch_size, sequence_length), 선택 사항) — 의 padding 샘플에 attention을 수행하지 않도록 하는 마스크input_values. 에서 선택된 마스크 값[0, 1]:- 마스크가 적용되지 않은 샘플의 경우 1
- 마스크된 샘플의 경우 0
- return_loss (
bool, 선택 사항) — 손실을 반환할지 여부입니다.
반환값
PeAudioOutput 또는 tuple(torch.Tensor)
PeAudioOutput 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(PeAudioConfig)과 입력에 따라 다양한 요소를 포함합니다.
PeAudioModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
- loss (
torch.Tensor, shape(1,), 선택 사항) — 오디오와 텍스트 표현 사이에 계산된 대조적 손실(contrastive loss). - logits_audio_text (
torch.Tensor, shape(batch_size, batch_size), 선택 사항) — 오디오 임베딩과 텍스트 임베딩 간의 유사도 logits. PeAudioFrameLevelModel은 대신 shape(batch_size, batch_size, sequence_length)의 프레임별 logits를 반환합니다. - text_audio_embeds (
torch.Tensor, shape(batch_size, hidden_size), 선택 사항) — 오디오-텍스트 공간으로 투영된 텍스트 임베딩. - audio_embeds (
torch.Tensor, shape(batch_size, hidden_size), 선택 사항) — 오디오-텍스트 공간으로 투영된 오디오 임베딩. PeAudioFrameLevelModel은 대신 shape(batch_size, sequence_length, hidden_size)의 프레임별 임베딩을 반환합니다. - text_outputs (
BaseModelOutputWithPooling, 선택 사항) — 텍스트 인코더의 모델 출력으로, 마지막 hidden state와 pooled output을 포함합니다. - 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.Tensor)
매개변수
- input_ids (
torch.Tensor의 shape(batch_size, sequence_length)) — 어휘 사전에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 Padding은 무시됩니다.AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.
- input_values (
torch.Tensor, shape(batch_size, sequence_length)) — 입력 원시 음성 파형의 Float 값..flac또는.wav오디오 파일을list[float]타입의 배열,numpy.ndarray또는torch.Tensor로 로드하여 값을 얻을 수 있습니다. 예를 들어 torchcodec 라이브러리(pip install torchcodec) 또는 soundfile 라이브러리(pip install soundfile)를 사용할 수 있습니다. 배열을input_values로 준비하려면 패딩 및torch.Tensor타입의 텐서 변환을 위해 AutoProcessor를 사용해야 합니다. 자세한 내용은 PeAudioProcessor.call()를 참조하세요. - attention_mask (
torch.Tensor형상이(batch_size, sequence_length), 선택 사항) — 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크. [0, 1]에서 선택된 마스크 값: 마스크되지 않은 토큰은 1, 마스크된 토큰은 0. attention mask란 무엇인가요?[0, 1]:- 마스크되지 않은 토큰에 대해 1
- 마스크된 토큰에 대해 0
- padding_mask (
torch.Tensor의 shape가(batch_size, sequence_length), 선택 사항) — 의 padding 샘플에 attention을 수행하지 않도록 하는 마스크input_values. 에서 선택된 마스크 값[0, 1]:- 마스크가 적용되지 않은 샘플의 경우 1
- 마스크된 샘플의 경우 0
- return_loss (
bool, 선택 사항) — 손실을 반환할지 여부입니다.
반환값
PeAudioOutput 또는 tuple(torch.Tensor)
PeAudioOutput 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(PeAudioConfig)과 입력에 따라 다양한 요소를 포함합니다.
PeAudioFrameLevelModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
- loss (
torch.Tensor, shape(1,), 선택 사항) — 오디오와 텍스트 표현 사이에 계산된 대조적 손실. - logits_audio_text (
torch.Tensor, shape(batch_size, batch_size), 선택 사항) — 오디오 임베딩과 텍스트 임베딩 간의 유사도 logits. PeAudioFrameLevelModel은 대신 shape(batch_size, batch_size, sequence_length)의 프레임별 logits를 반환합니다. - text_audio_embeds (
torch.Tensor, shape(batch_size, hidden_size), 선택 사항) — 오디오-텍스트 공간으로 투영된 텍스트 임베딩. - audio_embeds (
torch.Tensor, shape(batch_size, hidden_size), 선택 사항) — 오디오-텍스트 공간으로 투영된 오디오 임베딩. PeAudioFrameLevelModel은 대신 shape(batch_size, sequence_length, hidden_size)의 프레임별 임베딩을 반환합니다. - text_outputs (
BaseModelOutputWithPooling, 선택 사항) — 텍스트 인코더의 모델 출력으로, 마지막 hidden state와 pooled output을 포함합니다. - audio_outputs (
BaseModelOutputWithPooling, 선택 사항) — 오디오 인코더의 모델 출력으로, 마지막 숨겨진 상태와 풀링된 출력을 포함합니다.