Transformers documentation
EnCodec
Mô hình này được công bố trên HF papers vào ngày 2022-10-24 và được đóng góp cho Hugging Face Transformers vào ngày 2023-06-14.
EnCodec
Tổng quan
Mô hình mã hóa thần kinh EnCodec được đề xuất trong High Fidelity Neural Audio Compression bởi Alexandre Défossez, Jade Copet, Gabriel Synnaeve, Yossi Adi.
Tóm tắt từ bài báo như sau:
Chúng tôi giới thiệu một bộ mã hóa âm thanh thời gian thực, độ trung thực cao, đạt trạng thái nghệ thuật hiện tại, tận dụng các mạng nơ-ron. Nó bao gồm kiến trúc mã hóa-giải mã dạng luồng với không gian tiềm ẩn được lượng tử hóa, được huấn luyện theo phương pháp đầu-cuối. Chúng tôi đơn giản hóa và tăng tốc quá trình huấn luyện bằng cách sử dụng một đối thủ phổ biến đa tỷ lệ (multiscale spectrogram adversary) duy nhất, giúp giảm hiệu quả các hiện tượng méo (artifacts) và tạo ra các mẫu chất lượng cao. Chúng tôi giới thiệu một cơ chế cân bằng tổn thất (loss balancer) mới để ổn định quá trình huấn luyện: trọng số của một tổn thất giờ đây xác định tỷ lệ phần trăm của tổng gradient mà nó nên đại diện, do đó tách biệt việc lựa chọn siêu tham số này khỏi quy mô điển hình của tổn thất. Cuối cùng, chúng tôi nghiên cứu cách các mô hình Transformer nhẹ có thể được sử dụng để nén thêm biểu diễn thu được lên đến 40%, trong khi vẫn nhanh hơn thời gian thực. Chúng tôi cung cấp mô tả chi tiết về các lựa chọn thiết kế chính của mô hình được đề xuất, bao gồm: mục tiêu huấn luyện, các thay đổi kiến trúc và nghiên cứu về các hàm tổn thất cảm nhận khác nhau. Chúng tôi trình bày một đánh giá chủ quan toàn diện (các bài kiểm tra MUSHRA) cùng với một nghiên cứu loại bỏ (ablation study) cho một loạt các băng thông và lĩnh vực âm thanh, bao gồm giọng nói, giọng nói có tiếng ồn và vang, và nhạc. Phương pháp của chúng tôi vượt trội hơn so với các phương pháp cơ sở trong tất cả các cài đặt được đánh giá, xét cả âm thanh đơn kênh 24 kHz và âm thanh stereo 48 kHz.
Mô hình này được đóng góp bởi Matthijs, Patrick Von Platen và Arthur Zucker. Mã nguồn gốc có thể được tìm thấy tại đây.
Ví dụ sử dụng
Dưới đây là một ví dụ nhanh về cách mã hóa và giải mã âm thanh bằng mô hình này:
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_valuesEncodecConfig
lớp transformers.EncodecConfig
< 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 = 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 )
Tham số
- target_bandwidths (
list[float], tùy chọn, mặc định là[1.5, 3.0, 6.0, 12.0, 24.0]) — Khoảng các băng thông khác nhau mà mô hình có thể dùng để mã hóa âm thanh. - sampling_rate (
int, tùy chọn, mặc định là24000) — Tần số lấy mẫu (tính bằng hertz (Hz)) mà các tệp âm thanh cần được số hóa. - audio_channels (
int, tùy chọn, mặc định là1) — Số lượng kênh đầu vào. - normalize (
bool, tùy chọn, mặc định làFalse) — Liệu âm thanh có được chuẩn hóa khi được truyền vào hay không. - chunk_length_s (
float, tùy chọn) — Nếu được định nghĩa, âm thanh sẽ được tiền xử lý thành các đoạn có độ dàichunk_length_strước khi được mã hóa. - overlap (
float, tùy chọn) — Xác định phần chồng lấn giữa các chunk. Tham số này được dùng để tínhchunk_stridetheo công thức sau:int((1.0 - self.overlap) * self.chunk_length). - hidden_size (
int, tùy chọn, mặc định là128) — Kích thước của các biểu diễn ẩn. - num_filters (
int, tùy chọn, mặc định là 32) — Số lượng bộ lọc tích chập của lớp hạ mẫuEncodecConv1dđầu tiên. - num_residual_layers (
int, tùy chọn, mặc định là 1) — Số lượng lớp residual. - upsampling_ratios (
Sequence[int], tùy chọn, mặc định là[8, 5, 4, 2]) — Tỷ lệ kích thước kernel và stride. Encoder sử dụng tỷ lệ hạ mẫu thay vì tỷ lệ tăng mẫu, do đó nó sẽ sử dụng các tỷ lệ theo thứ tự ngược lại so với thứ tự được chỉ định ở đây, và thứ tự này phải khớp với thứ tự của decoder. - norm_type (
str, tùy chọn, mặc định là"weight_norm") — Phương pháp chuẩn hóa. Phải nằm trong["weight_norm", "time_group_norm"] - kernel_size (
int, tùy chọn, mặc định là 7) — Kích thước kernel cho phép tích chập ban đầu. - last_kernel_size (
int, tùy chọn, mặc định là 7) — Kích thước kernel cho lớp convolution cuối cùng. - residual_kernel_size (
int, tùy chọn, mặc định là 3) — Kích thước kernel cho các lớp residual. - dilation_growth_rate (
int, tùy chọn, mặc định là 2) — Mức độ tăng dilation ở mỗi lớp. - use_causal_conv (
bool, tùy chọn, mặc định làTrue) — Có sử dụng convolution hoàn toàn causal hay không. - pad_mode (
str, tùy chọn, mặc định là"reflect") — Chế độ đệm cho các phép tích chập. - compress (
int, tuỳ chọn, mặc định là 2) — Chiều giảm trong các nhánh residual (từ Demucs v3). - num_lstm_layers (
int, tùy chọn, mặc định là 2) — Số lượng lớp LSTM ở cuối bộ mã hóa. - trim_right_ratio (
float, tùy chọn, mặc định là 1.0) — Tỷ lệ để cắt bỏ ở phía bên phải của phép tích chập chuyển vị trong cấu hìnhuse_causal_conv = True. Nếu bằng 1.0, điều này có nghĩa là toàn bộ việc cắt bỏ được thực hiện ở phía bên phải. - codebook_size (
int, tùy chọn, mặc định là1024) — Số lượng codebook song song được mô hình sử dụng. - codebook_dim (
int, tùy chọn) — Số chiều của mỗi vector nhúng trong codebook. - use_conv_shortcut (
bool, tùy chọn, mặc định làTrue) — Có sử dụng một lớp tích chập làm kết nối ‘skip’ trong khốiEncodecResnetBlockhay không. Nếu là False, một hàm đồng nhất sẽ được sử dụng, tạo ra một kết nối dư (residual) tổng quát.
Đây là lớp cấu hình để lưu trữ cấu hình của một EncodecModel. Nó được sử dụng để khởi tạo một mô hình Encodec theo các đối số được chỉ định, xác định kiến trúc của mô hình. Khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như của facebook/encodec_24khz
Các đối tượng cấu hình kế thừa từ PreTrainedConfig và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ PreTrainedConfig để biết thêm thông tin.
Ví dụ:
>>> 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.configEncodecFeatureExtractor
lớp transformers.EncodecFeatureExtractor
< source >( feature_size: int = 1sampling_rate: int = 24000padding_value: float = 0.0chunk_length_s: float | None = Noneoverlap: float | None = None**kwargs )
Tham số
- feature_size (
int, tuỳ chọn, mặc định là 1) — Kích thước chiều của các đặc trưng đã trích xuất. Dùng 1 cho âm đơn, 2 cho âm stereo. - sampling_rate (
int, tùy chọn, mặc định là 24000) — Tần số lấy mẫu (tính bằng hertz (Hz)) mà tại đó dạng sóng âm thanh cần được số hóa. - padding_value (
float, tùy chọn, mặc định là 0.0) — Giá trị được sử dụng để điền vào các giá trị đệm. - chunk_length_s (
float, tùy chọn) — Nếu được định nghĩa, âm thanh sẽ được tiền xử lý thành các đoạn có độ dàichunk_length_strước khi được mã hóa. - overlap (
float, tùy chọn) — Xác định phần chồng lấn giữa các chunk. Tham số này được dùng để tínhchunk_stridetheo công thức sau:int((1.0 - self.overlap) * self.chunk_length).
Tạo một bộ trích xuất đặc trưng EnCodec.
Feature extractor này kế thừa từ SequenceFeatureExtractor, bao gồm hầu hết các phương thức chính. Người dùng nên tham khảo lớp cha này để biết thêm thông tin về các phương thức đó.
Việc khởi tạo một feature extractor với các giá trị mặc định sẽ cho ra cấu hình tương tự như kiến trúc facebook/encodec_24khz.
__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 )
Tham số
- raw_audio (
np.ndarray,list[float],list[np.ndarray],list[list[float]]) — Chuỗi hoặc lô các chuỗi cần được xử lý. Mỗi chuỗi có thể là một mảng numpy, một danh sách các giá trị float, một danh sách các mảng numpy hoặc một danh sách các danh sách giá trị float. Mảng numpy phải có hình dạng(num_samples,)cho âm thanh mono (feature_size = 1), hoặc(2, num_samples)cho âm thanh stereo (feature_size = 2). - padding (
bool,strhoặc PaddingStrategy, tùy chọn, mặc định làTrue) — Chọn một chiến lược để đệm các chuỗi trả về (theo phía đệm và chỉ số đệm của mô hình) trong số các lựa chọn sau:Truehoặc'longest': Lấp đầy đến trình tự dài nhất trong lô (hoặc không lấp đầy nếu chỉ có một trình tự được cung cấp).'max_length': Đệm (pad) đến độ dài tối đa được chỉ định bằng tham sốmax_lengthhoặc đến độ dài đầu vào tối đa mà mô hình chấp nhận được nếu tham số đó không được cung cấp.Falsehoặc'do_not_pad'(mặc định): Không đệm (tức là có thể xuất ra một lô với các chuỗi có độ dài khác nhau).
- truncation (
bool, tùy chọn, mặc định làFalse) — Bật tính năng cắt ngắn để giảm các chuỗi đầu vào dài hơnmax_lengthxuống cònmax_length. - max_length (
int, tùy chọn) — Độ dài tối đa của danh sách trả về và tùy chọn độ dài padding (xem bên trên). - return_tensors (
strhoặc TensorType, tùy chọn) — Nếu được đặt, sẽ trả về tensor thay vì danh sách các số nguyên Python. Các giá trị chấp nhận được là:'pt': Trả về các đối tượngtorch.Tensorcủa PyTorch.'np': Trả về các đối tượng Numpynp.ndarray.
- sampling_rate (
int, tùy chọn) — Tần số lấy mẫu mà đầu vàoaudiođược lấy mẫu. Rất khuyến nghị truyềnsampling_ratetrong lời gọi forward để ngăn các lỗi âm thầm.
Phương thức chính để tạo đặc trưng và chuẩn bị một hoặc nhiều chuỗi cho mô hình.
EncodecModel
lớp transformers.EncodecModel
< source >( config: EncodecConfig )
Tham số
- config (EncodecConfig) — Lớp cấu hình mô hình chứa tất cả các tham số của mô hình. Khởi tạo bằng tệp cấu hình sẽ không tải trọng số liên quan đến mô hình, chỉ tải cấu hình. Xem phương thức from_pretrained() để tải trọng số của mô hình.
Mô hình mã hóa âm thanh neural EnCodec.
Mô hình này kế thừa từ PreTrainedModel. Xem tài liệu của lớp cha để biết các phương thức chung mà thư viện triển khai cho tất cả các mô hình của nó (chẳng hạn như tải xuống hoặc lưu trữ, thay đổi kích thước các nhúng đầu vào, cắt tỉa các đầu, v.v.)
Mô hình này cũng là một lớp con của torch.nn.Module trong PyTorch. Hãy sử dụng nó như một Module PyTorch thông thường và tham khảo tài liệu PyTorch cho mọi vấn đề liên quan đến cách sử dụng và hành vi chung.
decode
< source >( audio_codes: LongTensoraudio_scales: Tensorpadding_mask: typing.Optional[torch.Tensor] = Nonereturn_dict: bool | None = Nonelast_frame_pad_length: int | None = 0 )
Tham số
- audio_codes (
torch.LongTensorcó hình dạng(nb_frames, batch_size, nb_quantizers, frame_len), tùy chọn) — Các nhúng mã rời rạc được tính toán bằngmodel.encode. - audio_scales (list có độ dài
nb_framesgồm cáctorch.Tensorcó hình dạng(batch_size, 1), tùy chọn) — Hệ số tỷ lệ cho mỗi đầu vàoaudio_codes. - padding_mask (
torch.Tensorcó hình dạng(channels, sequence_length)) — Mặt nạ đệm (padding mask) được sử dụng để đệm choinput_values. - return_dict (
bool, tùy chọn) — Có nên trả về một ModelOutput thay vì một tuple thông thường hay không. - last_frame_pad_length (
int, tùy chọn) — Số nguyên đại diện cho độ dài của phần đệm trong khung cuối cùng, phần này sẽ bị loại bỏ trong quá trình giải mã.
Giải mã các khung đã cho thành dạng sóng âm thanh đầu ra.
Lưu ý rằng đầu ra có thể lớn hơn một chút so với đầu vào. Trong trường hợp đó, các bước thừa ở cuối có thể được cắt bỏ.
encode
< source >( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = Nonebandwidth: float | None = Nonereturn_dict: bool | None = None ) → EncodecEncoderOutput dict or a tuple containing
Tham số
- input_values (
torch.Tensorcó hình dạng(batch_size, channels, sequence_length)) — Các giá trị float của dạng sóng âm thanh đầu vào. - padding_mask (
torch.Tensorcó hình dạng(batch_size, channels, sequence_length)) — Mặt nạ đệm (padding mask) được sử dụng để đệm choinput_values. - bandwidth (
float, tùy chọn) — Băng thông mục tiêu. Phải là một trong sốconfig.target_bandwidths. NếuNone, sẽ sử dụng băng thông nhỏ nhất có thể. bandwidth được biểu diễn bằng phần nghìn của giá trị thực, ví dụ băng thông 6kbps được biểu diễn là bandwidth == 6.0
Trả về
EncodecEncoderOutput dict hoặc một tuple chứa
- audio_codes (
torch.LongTensorcó hình dạng(nb_frames, batch_size, nb_quantizers, frame_len), tùy chọn), - audio_scales (list có độ dài
nb_framesgồm cáctorch.Tensorcó hình dạng(batch_size, 1), tùy chọn), - last_frame_pad_length (
int, tùy chọn).
Mã hóa dạng sóng âm thanh đầu vào thành các mã rời rạc có hình dạng (nb_frames, batch_size, nb_quantizers, frame_len).
nb_frames=1nếuself.config.chunk_length=None(vì encoder được áp dụng trên toàn bộ âm thanh), đây là trường hợp của mô hình 24kHz. Ngược lại,nb_frames=ceil(input_length/self.config.chunk_stride), đây là trường hợp của mô hình 48kHz.frame_lenlà độ dài của mỗi khung, bằngceil(input_length/self.config.hop_length)nếuself.config.chunk_length=None(ví dụ, với mô hình 24kHz). Ngược lại, nếuself.config.chunk_lengthđược định nghĩa,frame_len=self.config.chunk_length/self.config.hop_length, ví dụ trường hợp của mô hình 48kHz vớiframe_len=150.
forward
< source >( 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)
Tham số
- input_values (
torch.Tensorcó hình dạng(batch_size, channels, sequence_length), tùy chọn) — Dữ liệu âm thanh thô được chuyển đổi sang Float và đệm (padding) đến độ dài phù hợp để được mã hóa bằng các khối (chunks) có độ dài self.chunk_length và bước nhảy (stride) làconfig.chunk_stride. - padding_mask (
torch.BoolTensorcó shape(batch_size, channels, sequence_length), tùy chọn) — Mặt nạ để tránh tính toán các hệ số tỷ lệ trên các chỉ số token padding (có thể tránh tính toán conv trên các token này không?). Giá trị mặt nạ được chọn trong [0, 1]: 1 cho các token không bị che, 0 cho các token bị che. padding_mask luôn nên được truyền, trừ khi đầu vào đã bị cắt ngắn hoặc không được đệm. Điều này là vì để xử lý tensor hiệu quả, âm thanh đầu vào nên được đệm sao cho input_length % stride = step với step = chunk_length-stride. Điều này đảm bảo rằng tất cả các chunk đều có cùng shape[0, 1]:- 1 cho các token không bị che,
- 0 cho các token bị che.
padding_maskluôn phải được truyền, trừ khi đầu vào đã bị cắt bớt hoặc không được đệm. Điều này là vì để xử lý các tensor hiệu quả, âm thanh đầu vào cần được đệm sao choinput_length % stride = stepvớistep = chunk_length-stride. Điều này đảm bảo rằng tất cả các chunk đều có cùng hình dạng - bandwidth (
float, tùy chọn) — Băng thông mục tiêu. Phải là một trong các giá trị củaconfig.target_bandwidths. Nếu làNone, sẽ sử dụng băng thông nhỏ nhất có thể. bandwidth được biểu diễn bằng phần nghìn của giá trị thực, ví dụ băng thông 6kbps được biểu diễn làbandwidth == 6.0 - audio_codes (
torch.LongTensorcó hình dạng(nb_frames, batch_size, nb_quantizers, frame_len), tùy chọn) — Các nhúng mã rời rạc được tính toán bằngmodel.encode. - audio_scales (
listcó độ dàinb_framesgồm cáctorch.Tensorcó shape(batch_size, 1), optional) — Hệ số scale cho mỗi đầu vàoaudio_codes. - return_dict (
bool, tùy chọn) — Có trả về kết quả dưới dạng dict hay không. - last_frame_pad_length (
int, tùy chọn) — Độ dài của phần đệm trong khung cuối cùng, nếu có. Giá trị này được dùng để đảm bảo các khung đã mã hóa có thể được xuất ra dưới dạng tensor. Cần truyền giá trị này trong quá trình giải mã để đảm bảo phần đệm được loại bỏ khỏi các khung đã mã hóa.
Trả về
EncodecOutput hoặc tuple(torch.Tensor)
Một EncodecOutput hoặc một tuple của
torch.Tensor (nếu return_dict=False được truyền hoặc khi config.return_dict=False) bao gồm các
thành phần khác nhau tùy thuộc vào cấu hình (EncodecConfig) và đầu vào.
Phương thức forward của EncodecModel ghi đè lên phương thức đặc biệt __call__.
Mặc dù công thức cho bước truyền tiến cần được định nghĩa bên trong hàm này, người dùng nên gọi instance của
Modulesau đó thay vì gọi hàm này, vì instanceModulesẽ đảm nhận việc thực hiện các bước tiền xử lý và hậu xử lý, trong khi hàm này sẽ lặng lẽ bỏ qua chúng.
- audio_codes (
torch.LongTensorcó hình dạng(nb_frames, batch_size, nb_quantizers, frame_len), tùy chọn) — Các mã nhúng rời rạc được tính toán bằngmodel.encode. - audio_values (
torch.Tensorcó hình dạng(batch_size, segment_length), tùy chọn) — Các giá trị âm thanh đã giải mã, được lấy bằng cách sử dụng phần giải mã của Encodec.
Ví dụ:
>>> 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