Hugging Face's logo

Transformers documentation

EnCodec

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

이 모델은 2022-10-24에 HF papers에 게시되었으며, 2023-06-14에 Hugging Face Transformers에 기여되었습니다.

EnCodec

개요

EnCodec 신경 코덱 모델은 Alexandre Défossez, Jade Copet, Gabriel Synnaeve, Yossi Adi가 High Fidelity Neural Audio Compression에서 제안했습니다.

해당 논문의 초록은 다음과 같습니다:

신경망을 활용하는 최첨단 실시간 고해상도 오디오 코덱을 소개합니다. 이 코덱은 스트리밍 인코더-디코더 아키텍처와 양자화된 잠재 공간으로 구성되며, 엔드투엔드 방식으로 학습됩니다. 단일 멀티스케일 스펙트로그램 어드버서리를 사용하여 아티팩트를 효율적으로 줄이고 고품질 샘플을 생성함으로써 학습을 단순화하고 가속화합니다. 학습을 안정화하기 위해 새로운 손실 밸런서 메커니즘을 도입했습니다. 이제 손실의 가중치는 전체 그래디언트에서 해당 손실이 차지해야 하는 비율을 정의하므로, 이 하이퍼파라미터의 선택이 손실의 일반적인 규모와 분리됩니다. 마지막으로, 실시간보다 빠른 속도를 유지하면서 얻은 표현을 최대 40%까지 추가로 압축할 수 있도록 경량 Transformer 모델을 활용하는 방법을 연구했습니다. 제안된 모델의 주요 설계 선택 사항, 즉 학습 목표, 아키텍처 변경 사항, 다양한 지각 손실 함수에 대한 연구를 자세히 설명합니다. 음성, 소음이 섞인 잔향 있는 음성, 음악 등 다양한 대역폭과 오디오 도메인에 대해 광범위한 주관적 평가(MUSHRA 테스트)와 아블레이션 연구를 함께 제시합니다. 24 kHz 모노포닉 및 48 kHz 스테레오포닉 오디오를 모두 고려할 때, 평가된 모든 설정에서 제안된 접근 방식이 베이스라인 방법보다 우수합니다.

이 모델은 Matthijs, Patrick Von Platen, Arthur Zucker가 기여했습니다. 원본 코드는 여기에서 찾을 수 있습니다.

사용 예시

이 모델을 사용하여 오디오를 인코딩하고 디코딩하는 간단한 예시입니다:

from datasets import Audio, load_dataset

from transformers import AutoProcessor, EncodecModel


librispeech_dummy = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")

model = EncodecModel.from_pretrained("facebook/encodec_24khz", device_map="auto")
processor = AutoProcessor.from_pretrained("facebook/encodec_24khz")
librispeech_dummy = librispeech_dummy.cast_column("audio", Audio(sampling_rate=processor.sampling_rate))
audio_sample = librispeech_dummy[-1]["audio"]["array"]
inputs = processor(raw_audio=audio_sample, sampling_rate=processor.sampling_rate, return_tensors="pt").to(model.device)

encoder_outputs = model.encode(inputs["input_values"], inputs["padding_mask"])
# `encoder_outputs.audio_codes` contains discrete codes
audio_values = model.decode(**encoder_outputs, padding_mask=inputs["padding_mask"])[0]
# or the equivalent with a forward pass
audio_values = model(inputs["input_values"], inputs["padding_mask"]).audio_values

EncodecConfig

클래스 transformers.EncodecConfig

< >

( 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 = Nonetarget_bandwidths: list[float] | tuple[float, ...] = (1.5, 3.0, 6.0, 12.0, 24.0)sampling_rate: int = 24000audio_channels: int = 1normalize: bool = Falsechunk_length_s: int | float | None = Noneoverlap: float | None = Nonehidden_size: int = 128num_filters: int = 32num_residual_layers: int = 1upsampling_ratios: list[int] | tuple[int, ...] = (8, 5, 4, 2)norm_type: str = 'weight_norm'kernel_size: int = 7last_kernel_size: int = 7residual_kernel_size: int = 3dilation_growth_rate: int = 2use_causal_conv: bool = Truepad_mode: str = 'reflect'compress: int = 2num_lstm_layers: int = 2trim_right_ratio: float = 1.0codebook_size: int = 1024codebook_dim: int | None = Noneuse_conv_shortcut: bool = True )

매개변수

  • target_bandwidths (list[float], 선택 사항, 기본값 [1.5, 3.0, 6.0, 12.0, 24.0]) — 모델이 오디오를 인코딩할 수 있는 다양한 대역폭의 범위입니다.
  • sampling_rate (int, 선택 사항, 기본값 24000) — 오디오 파일을 디지털화할 때 사용할 샘플링 레이트를 헤르츠(Hz) 단위로 나타낸 값입니다.
  • audio_channels (int, 선택 사항, 기본값 1) — 입력 채널의 수입니다.
  • normalize (bool, 선택 사항, 기본값 False) — 음성이 전달될 때 정규화할지 여부입니다.
  • chunk_length_s (float, 선택 사항) — 정의된 경우, 오디오는 chunk_length_s 길이의 청크로 사전 처리된 후 인코딩됩니다.
  • overlap (float, 선택 사항) — 각 청크 사이의 겹침을 정의합니다. 다음 수식을 사용하여 chunk_stride를 계산하는 데 사용됩니다: int((1.0 - self.overlap) * self.chunk_length).
  • hidden_size (int, 선택 사항, 기본값 128) — 숨겨진 표현의 차원입니다.
  • num_filters (int, 선택 사항, 기본값 32) — 첫 번째 EncodecConv1d 다운샘플링 레이어의 컨볼루션 커널 수.
  • num_residual_layers (int, 선택 사항, 기본값 1) — 잔차 레이어의 개수입니다.
  • upsampling_ratios (Sequence[int] , 선택 사항, 기본값 [8, 5, 4, 2]) — 커널 크기 및 스트라이드 비율입니다. 인코더는 업샘플링 비율 대신 다운샘플링 비율을 사용하므로, 여기에서 지정된 비율과 일치해야 하는 디코더 순서와 반대 순서로 비율을 사용합니다.
  • norm_type (str, 선택 사항, 기본값 "weight_norm") — 정규화 방법. ["weight_norm", "time_group_norm"] 중 하나여야 합니다.
  • kernel_size (int, 선택 사항, 기본값 7) — 초기 컨볼루션에 사용할 커널 크기.
  • last_kernel_size (int, 선택 사항, 기본값 7) — 마지막 컨볼루션 레이어의 커널 크기.
  • residual_kernel_size (int, 선택 사항, 기본값 3) — 잔차 레이어의 커널 크기입니다.
  • dilation_growth_rate (int, 선택 사항, 기본값 2) — 각 레이어마다 dilation을 얼마나 증가시킬지 지정합니다.
  • use_causal_conv (bool, 선택 사항, 기본값 True) — 완전 인과적 컨볼루션을 사용할지 여부입니다.
  • pad_mode (str, 선택 사항, 기본값 "reflect") — 합성곱에 사용할 패딩 모드입니다.
  • compress (int, 선택 사항, 기본값 2) — 잔차 분기의 축소된 차원 (Demucs v3에서 도입).
  • num_lstm_layers (int, 선택 사항, 기본값 2) — 인코더 끝부분의 LSTM 레이어 수.
  • trim_right_ratio (float, 선택 사항, 기본값 1.0) — use_causal_conv = True 설정에서 전치 합성곱의 오른쪽을 잘라낼 때 사용할 비율입니다. 1.0과 같으면 모든 잘라내기가 오른쪽에서 수행됨을 의미합니다.
  • codebook_size (int, 선택 사항, 기본값 1024) — 모델이 사용하는 병렬 코드북의 수입니다.
  • codebook_dim (int, 선택 사항) — 각 codebook 임베딩 벡터의 차원.
  • use_conv_shortcut (bool, 선택 사항, 기본값 True) — EncodecResnetBlock 블록에서 ‘skip’ 연결로 합성곱 계층을 사용할지 여부입니다. False인 경우, 일반 잔차 연결을 제공하기 위해 항등 함수가 사용됩니다.

이것은 EncodecModel의 설정을 저장하기 위한 설정 클래스입니다. 지정된 인자에 따라 Encodec 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 설정을 인스턴스화하면 facebook/encodec_24khz와 유사한 설정이 생성됩니다.

Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.

예:

>>> from transformers import EncodecModel, EncodecConfig

>>> # Initializing a "facebook/encodec_24khz" style configuration
>>> configuration = EncodecConfig()

>>> # Initializing a model (with random weights) from the "facebook/encodec_24khz" style configuration
>>> model = EncodecModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

EncodecFeatureExtractor

class transformers.EncodecFeatureExtractor

< >

( feature_size: int = 1sampling_rate: int = 24000padding_value: float = 0.0chunk_length_s: float | None = Noneoverlap: float | None = None**kwargs )

매개변수

  • feature_size (int, 선택 사항, 기본값 1) — 추출된 특징의 차원입니다. 모노는 1, 스테레오는 2를 사용합니다.
  • sampling_rate (int, 선택 사항, 기본값 24000) — 오디오 웨이브포름을 디지털화할 때 사용할 샘플링 레이트를 헤르츠(Hz) 단위로 나타낸 값입니다.
  • padding_value (float, 선택 사항, 기본값 0.0) — 패딩 값으로 채우는 데 사용되는 값입니다.
  • chunk_length_s (float, 선택 사항) — 정의된 경우, 오디오는 chunk_length_s 길이의 청크로 사전 처리된 후 인코딩됩니다.
  • overlap (float, 선택 사항) — 각 청크 사이의 겹침을 정의합니다. 다음 수식을 사용하여 chunk_stride를 계산하는 데 사용됩니다: int((1.0 - self.overlap) * self.chunk_length).

EnCodec feature extractor를 생성합니다.

이 feature extractor는 SequenceFeatureExtractor를 상속하며, 이 클래스에는 대부분의 주요 메서드가 포함되어 있습니다. 해당 메서드에 대한 자세한 내용은 이 상위 클래스를 참고하세요.

기본값으로 feature extractor를 인스턴스화하면 facebook/encodec_24khz 아키텍처와 유사한 구성이 생성됩니다.

__call__

< >

( raw_audio: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]]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 )

매개변수

  • raw_audio (np.ndarray, list[float], list[np.ndarray], list[list[float]]) — 처리할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 numpy 배열, float 값의 리스트, numpy 배열의 리스트, float 값의 리스트의 리스트일 수 있습니다. numpy 배열은 모노 오디오(feature_size = 1)의 경우 (num_samples,) 형태여야 하고, 스테레오 오디오(feature_size = 2)의 경우 (2, num_samples) 형태여야 합니다.
  • padding (bool, str 또는 PaddingStrategy, 선택 사항, 기본값은 True) — 모델의 패딩 방향과 패딩 인덱스에 따라 반환된 시퀀스에 적용할 패딩 전략을 다음 중 선택합니다:
    • True 또는 'longest': 배치 내 가장 긴 시퀀스 길이에 맞게 패딩을 수행합니다(단일 시퀀스만 제공된 경우 패딩을 하지 않음).
    • 'max_length': max_length 인수로 지정된 최대 길이로 패딩하거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 패딩합니다.
    • False 또는 'do_not_pad' (기본값): 패딩을 하지 않습니다(즉, 서로 다른 길이의 시퀀스로 구성된 배치로 출력할 수 있습니다).
  • truncation (bool, 선택 사항, 기본값 False) — max_length보다 긴 입력 시퀀스를 max_length로 잘라내는 truncation을 활성화합니다.
  • max_length (int, 선택 사항) — 반환되는 목록의 최대 길이 및 선택적으로 패딩 길이(위 참조).
  • return_tensors (str 또는 TensorType, 선택 사항) — 설정된 경우, Python 정수 목록 대신 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:
    • 'pt': PyTorch torch.Tensor 객체를 반환합니다.
    • 'np': Numpy np.ndarray 객체를 반환합니다.
  • sampling_rate (int, 선택 사항) — audio 입력이 샘플링된 샘플링 레이트입니다. 조용한 오류를 방지하려면 forward 호출 시 sampling_rate를 전달하는 것이 강력히 권장됩니다.

하나 이상의 시퀀스를 특징화(featurize)하고 모델에 맞게 준비하는 주요 메서드입니다.

EncodecModel

class transformers.EncodecModel

< >

( config: EncodecConfig )

매개변수

  • config (EncodecConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 연관된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.

EnCodec 신경 오디오 코덱 모델입니다.

이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.

decode

< >

( audio_codes: LongTensoraudio_scales: Tensorpadding_mask: typing.Optional[torch.Tensor] = Nonereturn_dict: bool | None = Nonelast_frame_pad_length: int | None = 0 )

매개변수

  • audio_codes (torch.LongTensor, shape (nb_frames, batch_size, nb_quantizers, frame_len), 선택) — model.encode를 사용하여 계산된 이산 코드 임베딩.
  • audio_scales (길이 nb_frames인 torch.Tensor 리스트, 각 텐서의 shape은 (batch_size, 1), 선택 사항) — 각 audio_codes 입력에 대한 스케일링 계수.
  • padding_mask (torch.Tensor, shape (channels, sequence_length)) — input_values를 패딩하는 데 사용되는 패딩 마스크입니다.
  • return_dict (bool, 선택) — 일반 튜플 대신 ModelOutput를 반환할지 여부.
  • last_frame_pad_length (int, 선택 사항) — 마지막 프레임의 패딩 길이를 나타내는 정수입니다. 디코딩 과정에서 제거됩니다.

… 주어진 프레임을 출력 오디오 웨이브폼으로 디코딩합니다.

출력이 입력보다 약간 더 클 수 있습니다. 이 경우, 끝부분의 추가 단계는 잘라낼 수 있습니다.

encode

< >

( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = Nonebandwidth: float | None = Nonereturn_dict: bool | None = None ) → EncodecEncoderOutput dict or a tuple containing

매개변수

  • input_values (torch.Tensor, shape (batch_size, channels, sequence_length)) — 입력 오디오 웨이브폼의 부동소수점 값.
  • padding_mask (torch.Tensor, shape (batch_size, channels, sequence_length)) — input_values에 패딩을 적용할 때 사용되는 패딩 마스크입니다.
  • bandwidth (float, 선택 사항) — 목표 대역폭입니다. config.target_bandwidths 중 하나여야 합니다. None인 경우 가능한 가장 작은 대역폭을 사용합니다. bandwidth는 실제 값의 1/1000으로 표현되며, 예를 들어 6kbps 대역폭은 bandwidth == 6.0으로 표현됩니다.

반환값

EncodecEncoderOutput dict 또는 튜플을 포함

  • audio_codes (torch.LongTensor, shape (nb_frames, batch_size, nb_quantizers, frame_len), 선택 사항),
  • nb_frames 길이의 torch.Tensor 리스트, 각 텐서의 shape은 (batch_size, 1), 선택 사항
  • last_frame_pad_length (int, 선택 사항).

입력 오디오 웨이브폼을 (nb_frames, batch_size, nb_quantizers, frame_len) 형태의 이산 코드로 인코딩합니다.

  • 24kHz 모델의 경우 인코더가 전체 오디오에 적용되므로 self.config.chunk_length=None이면 nb_frames=1입니다. 그렇지 않은 경우, 즉 48kHz 모델의 경우 nb_frames=ceil(input_length/self.config.chunk_stride)입니다.
  • frame_len은 각 프레임의 길이를 나타내며, self.config.chunk_length=None인 경우(예: 24kHz 모델)에는 ceil(input_length/self.config.hop_length)과 같습니다. 그렇지 않고 self.config.chunk_length가 정의되어 있다면, frame_len=self.config.chunk_length/self.config.hop_length가 됩니다. 예를 들어 frame_len=150인 48kHz 모델의 경우입니다.

forward

< >

( input_values: Tensorpadding_mask: typing.Optional[torch.BoolTensor] = Nonebandwidth: float | None = Noneaudio_codes: typing.Optional[torch.LongTensor] = Noneaudio_scales: typing.Optional[torch.Tensor] = Nonereturn_dict: bool | None = Nonelast_frame_pad_length: int | None = 0 ) → EncodecOutput or tuple(torch.Tensor)

매개변수

  • input_values (torch.Tensor, shape (batch_size, channels, sequence_length), 선택 사항) — Float로 변환되고, config.chunk_stride의 스트라이드와 self.chunk_length 길이의 청크를 사용하여 인코딩되도록 적절한 길이로 패딩된 원시 오디오 입력
  • padding_mask (torch.BoolTensor shape (batch_size, channels, sequence_length), 선택 사항) — padding 토큰 인덱스에 대해 스케일링 계수를 계산하지 않도록 하는 마스크입니다. [0, 1] 범위의 값을 사용합니다. 1은 마스크되지 않은 토큰, 0은 마스크된 토큰을 나타냅니다. 입력이 잘리거나 패딩되지 않은 경우를 제외하고는 padding_mask를 항상 전달해야 합니다. 이는 텐서를 효율적으로 처리하기 위해 입력 오디오를 패딩하여 input_length % stride = step (여기서 step = chunk_length - stride)을 만족하도록 해야 하기 때문입니다. 이렇게 하면 모든 청크의 형태가 동일해집니다. [0, 1]:
    • 마스크되지 않은 토큰에 대해 1
    • 마스크된 토큰에 대해 0

    padding_mask는 입력이 잘리거나 패딩되지 않은 경우를 제외하고는 항상 전달해야 합니다. 이는 텐서를 효과적으로 처리하려면 input_length % stride = step이 되도록, 여기서 step = chunk_length-stride이며, 입력 오디오를 패딩해야 하기 때문입니다. 이를 통해 모든 청크가 동일한 형태를 갖도록 보장됩니다.

  • bandwidth (float, 선택 사항) — 목표 대역폭입니다. config.target_bandwidths 중 하나여야 합니다. None인 경우 가능한 가장 작은 대역폭을 사용합니다. bandwidth는 실제 값의 1/1000으로 표현되며, 예를 들어 6kbps 대역폭은 bandwidth == 6.0으로 표현됩니다.
  • audio_codes (torch.LongTensor, shape (nb_frames, batch_size, nb_quantizers, frame_len), 선택) — model.encode를 사용하여 계산된 이산 코드 임베딩.
  • audio_scales (list, 길이 nb_frames, 각 요소는 (batch_size, 1) 모양의 torch.Tensor, 선택 사항) — 각 audio_codes 입력에 적용할 스케일링 계수.
  • return_dict (bool, 선택) — 출력을 dict로 반환할지 여부.
  • last_frame_pad_length (int, 선택 사항) — 마지막 프레임에 패딩이 있는 경우 그 패딩의 길이입니다. 이는 인코딩된 프레임을 텐서로 출력할 수 있도록 보장하는 데 사용됩니다. 인코딩된 프레임에서 패딩이 제거되도록 보장하려면 디코딩 시 이 값을 전달해야 합니다.

반환값

EncodecOutput 또는 tuple(torch.Tensor)

EncodecOutput 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(EncodecConfig)과 입력에 따라 다양한 요소를 포함합니다.

EncodecModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.

이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신 Module 인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.

  • audio_codes (torch.LongTensor, shape (nb_frames, batch_size, nb_quantizers, frame_len), 선택 사항) — model.encode를 사용하여 계산된 이산 코드 임베딩.
  • audio_values (torch.Tensor, shape (batch_size, segment_length), 선택 사항) — Encodec의 디코더 부분을 사용하여 얻은 디코딩된 오디오 값입니다.

예:

>>> from datasets import load_dataset
>>> from transformers import AutoProcessor, EncodecModel

>>> dataset = load_dataset("hf-internal-testing/ashraq-esc50-1-dog-example")
>>> audio_sample = dataset["train"]["audio"][0]["array"]

>>> model_id = "facebook/encodec_24khz"
>>> model = EncodecModel.from_pretrained(model_id)
>>> processor = AutoProcessor.from_pretrained(model_id)

>>> inputs = processor(raw_audio=audio_sample, return_tensors="pt")

>>> outputs = model(**inputs)
>>> audio_codes = outputs.audio_codes
>>> audio_values = outputs.audio_values
Update on GitHub

←Dia FastSpeech2Conformer→