Transformers documentation
DAC
이 모델은 2023-06-11에 HF papers에 게시되었으며, 2024-08-19에 Hugging Face Transformers에 기여되었습니다.
DAC
개요
DAC 모델은 Rithesh Kumar, Prem Seetharaman, Alejandro Luebs, Ishaan Kumar, Kundan Kumar가 Descript Audio Codec: High-Fidelity Audio Compression with Improved RVQGAN에서 제안했습니다.
Descript Audio Codec(DAC) 모델은 오디오 데이터를 압축하는 강력한 도구로, 저장 및 전송에 매우 효율적입니다. 44.1 KHz 오디오를 8kbps의 대역폭으로 토큰을 압축하여 DAC 모델은 데이터 크기를 크게 줄이면서도 고품질 오디오 처리를 가능하게 합니다. 이는 스트리밍 애플리케이션, 원격 회의, 대규모 오디오 데이터셋 아카이빙과 같이 대역폭이 제한적이거나 저장 공간이 중요한 시나리오에서 특히 유용합니다.
해당 논문의 초록은 다음과 같습니다:
Language model은 이미지, 음성, 음악과 같은 자연 신호를 모델링하는 데 성공적으로 활용되어 왔습니다. 이러한 모델의 핵심 구성 요소는 고차원 자연 신호를 저차원 이산 토큰으로 압축할 수 있는 고품질 신경 압축 모델입니다. 이를 위해, 44.1 KHz 오디오를 8kbps 대역폭의 토큰으로 약 90배 압축하는 고충실도 범용 신경 오디오 압축 알고리즘을 소개합니다. 이는 고충실도 오디오 생성 기술의 발전과 이미지 도메인에서 유래한 더 나은 벡터 양자화 기법, 그리고 개선된 적대적 손실 및 재구성 손실을 결합하여 달성했습니다. 단일 범용 모델로 모든 도메인(음성, 환경, 음악 등)을 압축하여 모든 오디오의 생성 모델링에 널리 적용할 수 있습니다. 경쟁 오디오 압축 알고리즘과 비교한 결과, 제안한 방법이 현저히 우수한 성능을 보였습니다. 모든 설계 선택에 대한 철저한 아블레이션 분석과 오픈소스 코드, 학습된 모델 가중치를 제공합니다. 본 연구가 차세대 고충실도 오디오 모델링의 기반이 되기를 바랍니다.
이 모델은 Kamil Akesbi님이 기여했습니다. 원본 코드는 여기에서 찾을 수 있습니다.
모델 구조
Descript Audio Codec(DAC) 모델은 세 가지 단계로 구성됩니다:
- Encoder Model: 이 단계에서는 입력 오디오를 압축하여 크기를 줄이되, 필수적인 정보는 유지합니다.
- Residual Vector Quantizer (RVQ) 모델: 인코더와 함께 작동하여 오디오의 잠재 코드를 양자화하고, 압축을 정제하며 고품질 재구성을 보장합니다.
- Decoder Model: 이 최종 단계에서는 압축된 형태에서 오디오를 재구성하여 원래 입력과 매우 유사한 상태로 복원합니다.
사용 예시
이 모델을 사용하여 오디오를 인코딩하고 디코딩하는 간단한 예시입니다:
from datasets import Audio, load_dataset
from transformers import AutoProcessor, DacModel
librispeech_dummy = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
model = DacModel.from_pretrained("descript/dac_16khz", device_map="auto")
processor = AutoProcessor.from_pretrained("descript/dac_16khz")
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"])
# Get the intermediate audio codes
audio_codes = encoder_outputs.audio_codes
# Reconstruct the audio from its quantized representation
audio_values = model.decode(encoder_outputs.quantized_representation)
# or the equivalent with a forward pass
audio_values = model(inputs["input_values"]).audio_valuesDacConfig
클래스 transformers.DacConfig
< 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 = Noneencoder_hidden_size: int = 64downsampling_ratios: list[int] | tuple[int, ...] = (2, 4, 8, 8)decoder_hidden_size: int = 1536n_codebooks: int = 9codebook_size: int = 1024codebook_dim: int = 8quantizer_dropout: float | int = 0.0commitment_loss_weight: float = 0.25codebook_loss_weight: float = 1.0sampling_rate: int = 16000 )
매개변수
- encoder_hidden_size (
int, 선택 사항, 기본값64) — 숨겨진 표현의 차원입니다. - downsampling_ratios (
list[int], 선택 사항, 기본값[2, 4, 8, 8]) — 인코더에서 다운샘플링에 사용되는 비율입니다. 디코더의 업샘플링에서는 역순으로 사용됩니다. - decoder_hidden_size (
int, 선택 사항, 기본값1536) — 숨겨진 표현의 차원입니다. - n_codebooks (
int, 선택 사항, 기본값9) — 모델이 사용하는 병렬 코드북의 수입니다. - codebook_size (
int, 선택 사항, 기본값1024) — 모델이 사용하는 병렬 코드북의 수입니다. - codebook_dim (
int, 선택 사항, 기본값8) — 각 codebook 임베딩 벡터의 차원입니다. - quantizer_dropout (
bool, 선택 사항, 기본값 0) — quantizer에 dropout을 적용할지 여부. - commitment_loss_weight (
float, 선택 사항, 기본값 0.25) — VQVAE 손실 함수에서 commitment loss 항의 가중치입니다. - codebook_loss_weight (
float, 선택 사항, 기본값 1.0) — VQVAE 손실 함수에서 codebook loss 항의 가중치입니다. - sampling_rate (
int, 선택 사항, 기본값16000) — 오디오 파일을 디지털화할 때 사용할 샘플링 주파수입니다. 헤르츠(Hz) 단위로 표시됩니다.
이것은 DacModel의 설정을 저장하기 위한 설정 클래스입니다. 지정된 인자에 따라 Dac 모델을 인스턴스화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 설정을 인스턴스화하면 descript/dac_16khz와 유사한 설정이 생성됩니다.
Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.
예:
>>> from transformers import DacModel, DacConfig
>>> # Initializing a "descript/dac_16khz" style configuration
>>> configuration = DacConfig()
>>> # Initializing a model (with random weights) from the "descript/dac_16khz" style configuration
>>> model = DacModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configDacFeatureExtractor
클래스 transformers.DacFeatureExtractor
< source >( feature_size: int = 1sampling_rate: int = 16000padding_value: float = 0.0hop_length: int = 512**kwargs )
Dac feature extractor를 생성합니다.
이 feature extractor는 SequenceFeatureExtractor를 상속하며, 이 클래스에는 대부분의 주요 메서드가 포함되어 있습니다. 해당 메서드에 대한 자세한 내용은 이 상위 클래스를 참고하세요.
__call__
< source >( 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, 선택 사항, 기본값은 'pt'입니다. 설정하면 Python 정수 목록 대신 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:'pt': PyTorchtorch.Tensor객체를 반환합니다.'np': Numpynp.ndarray객체를 반환합니다.
- sampling_rate (
int, 선택 사항) —audio입력이 샘플링된 샘플링 레이트입니다. 조용한 오류를 방지하려면 forward 호출 시sampling_rate를 전달하는 것이 강력히 권장됩니다.
하나 이상의 시퀀스를 특징화(featurize)하고 모델에 맞게 준비하는 주요 메서드입니다.
DacModel
클래스 transformers.DacModel
< source >( config: DacConfig )
매개변수
- config (DacConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
DAC(Descript Audio Codec) 모델.
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.
decode
< source >( quantized_representation: typing.Optional[torch.Tensor] = Noneaudio_codes: typing.Optional[torch.Tensor] = Nonereturn_dict: bool | None = None ) → DacDecoderOutput or tuple(torch.Tensor)
매개변수
- quantized_representation (
torch.Tensor, shape(batch_size, dimension, time_steps), 선택 사항) — 입력의 양자화 연속 표현입니다. - audio_codes (
torch.Tensor, shape(batch_size, num_codebooks, time_steps), 선택 사항) — 각 codebook에 대한 codebook 인덱스로, 입력의 양자화된 이산 표현을 나타냅니다. 오디오 코드에서 직접 디코딩하려면 이 매개변수를 제공해야 합니다(quantized_representation을 덮어씀). - return_dict (
bool, 선택 사항, 기본값True) — 일반 tuple 대신DacDecoderOutput를 반환할지 여부.
반환값
DacDecoderOutput 또는 tuple(torch.Tensor)
DacDecoderOutput 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(DacConfig)과 입력에 따라 다양한 요소를 포함합니다.
- audio_values (
torch.Tensor, shape(batch_size, input_length), 선택 사항) — Dac의 디코더 부분을 사용하여 얻은 디코딩된 오디오 값입니다.
encode
< source >( input_values: Tensorn_quantizers: int | None = Nonereturn_dict: bool | None = None ) → DacEncoderOutput or tuple(torch.Tensor)
매개변수
- input_values (
torch.Tensor of shape(batch_size, 1, time_steps)`) — 인코딩할 입력 오디오 데이터, - n_quantizers (
int, 선택 사항) — 사용할 양자화기(quantizer)의 수입니다. None인 경우 모든 양자화기가 사용됩니다. 기본값은 None입니다. - return_dict (
bool, 선택) — 일반 튜플 대신 ModelOutput를 반환할지 여부.
반환값
DacEncoderOutput 또는 tuple(torch.Tensor)
DacEncoderOutput 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(DacConfig)과 입력에 따라 다양한 요소를 포함합니다.
- loss (
torch.Tensor, 선택 사항) — 인코더 모델의 손실로, 커밋먼트 손실과 코드북 손실의 가중 합으로 구성됩니다. - quantized_representation (
torch.Tensor, shape(batch_size, dimension, time_steps), 선택 사항) — 입력의 양자화 연속 표현입니다. - audio_codes (
torch.Tensor, shape(batch_size, num_codebooks, time_steps), 선택 사항) — 각 codebook에 대한 codebook 인덱스(입력의 양자화된 이산 표현). - projected_latents (
torch.Tensor, shape(batch_size, num_codebooks * dimension, time_steps), 선택 사항) — 투영된 latents(양자화 이전 입력의 연속 표현).
forward
< source >( input_values: Tensorn_quantizers: int | None = Nonereturn_dict: bool | None = None ) → DacOutput or tuple(torch.Tensor)
매개변수
- input_values (
torch.Tensor, shape(batch_size, 1, time_steps)) — 인코딩할 오디오 데이터. - n_quantizers (
int, 선택 사항) — 사용할 quantizer의 수입니다.None인 경우 모든 quantizer가 사용됩니다. 기본값은None입니다. - return_dict (
bool, 선택) — 일반 튜플 대신 ModelOutput를 반환할지 여부.
반환값
DacOutput 또는 tuple(torch.Tensor)
DacOutput 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(DacConfig)과 입력에 따라 다양한 요소를 포함합니다.
DacModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
- loss (
torch.Tensor, 선택 사항) — 인코더 모델의 손실로, 커밋먼트 손실과 코드북 손실의 가중 합으로 구성됩니다. - audio_values (
torch.Tensor, shape(batch_size, input_length)) — 재구성된 오디오 데이터. - quantized_representation (
torch.Tensor, shape(batch_size, dimension, time_steps)) — 입력의 양자화 연속 표현. - audio_codes (
torch.LongTensor, shape(batch_size, num_codebooks, time_steps)) — 각 codebook에 대한 codebook 인덱스(입력의 양자화된 이산 표현). - projected_latents (
torch.Tensor, shape(batch_size, num_codebooks * dimension, time_steps)) — 투영된 latents(양자화 이전 입력의 연속 표현).
예:
>>> from datasets import load_dataset, Audio
>>> from transformers import DacModel, AutoProcessor
>>> librispeech_dummy = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> model = DacModel.from_pretrained("descript/dac_16khz")
>>> processor = AutoProcessor.from_pretrained("descript/dac_16khz")
>>> 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")
>>> encoder_outputs = model.encode(inputs["input_values"])
>>> # Get the intermediate audio codes
>>> audio_codes = encoder_outputs.audio_codes
>>> # Reconstruct the audio from its quantized representation
>>> audio_values = model.decode(encoder_outputs.quantized_representation)
>>> # or the equivalent with a forward pass
>>> audio_values = model(inputs["input_values"]).audio_values