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 带宽的 token，DAC 模型在显著降低数据占用的同时，实现了高质量的音频处理。这在带宽受限或存储空间宝贵的场景中尤为有用，例如流媒体应用、远程会议以及大型音频数据集的归档。
该论文的摘要如下：
语言模型已被成功用于对图像、语音和音乐等自然信号进行建模。这些模型的一个关键组成部分是高质量的神经压缩模型，它能够将高维自然信号压缩为低维离散 token。为此，我们提出了一种高保真的通用神经音频压缩算法，可将 44.1 KHz 音频以仅 8kbps 的带宽压缩为 token，实现约 90 倍的压缩率。我们通过将高保真音频生成的最新进展与图像领域中更优的向量量化技术相结合，并改进对抗损失和重建损失，实现了这一目标。我们使用单一的通用模型压缩所有领域（语音、环境声、音乐等），使其可广泛应用于所有音频的生成式建模。我们将本方法与现有的音频压缩算法进行了对比，发现我们的方法显著优于它们。我们为每个设计选择提供了详尽的消融实验，并开源了代码和训练好的模型权重。我们希望我们的工作能为下一代高保真音频建模奠定基础。
该模型由 Kamil Akesbi 贡献。 原始代码可在 此处 找到。
模型结构
Descript 音频编解码器（DAC）模型由三个不同的阶段组成：
- 编码器模型：此阶段对输入音频进行压缩，在保留关键信息的同时减小其体积。
- 残差向量量化器（RVQ）模型：与编码器协同工作，该模型对音频的潜在编码进行量化，优化压缩效果并确保高质量的重建。
- 解码器模型：此最终阶段从压缩形式重建音频，将其恢复为与原始输入高度相似的状态。
使用示例
以下是使用此模型对音频进行编码和解码的简单示例：
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
class 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) — 每个码本嵌入向量的维度。 - quantizer_dropout (
bool，可选，默认为 0) — 是否对量化器应用 dropout。 - commitment_loss_weight (
float，可选，默认值为 0.25) — VQVAE 损失函数中 commitment loss 项的权重。 - codebook_loss_weight (
float, 可选，默认为 1.0) — VQVAE 损失函数中码本损失项的权重。 - sampling_rate (
int，可选，默认为16000) — 音频文件应被数字化时的采样率，以赫兹（Hz）为单位。
这是用于存储 DacModel 配置的类。它根据指定的参数实例化 Dac 模型，并定义模型架构。使用默认值实例化配置将生成与 descript/dac_16khz 类似的配置。
配置对象继承自 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
class transformers.DacFeatureExtractor
< source >( feature_size: int = 1sampling_rate: int = 16000padding_value: float = 0.0hop_length: int = 512**kwargs )
构建一个 Dac 特征提取器。
该特征提取器继承自 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 数组、浮点值列表、numpy 数组列表或浮点值列表的列表。对于单声道音频（feature_size = 1），numpy 数组的形状必须为(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。 - max_length (
int，可选) — 返回列表的最大长度，以及可选的填充长度（见上文）。 - return_tensors (
str或 TensorType, 可选, ，默认为 'pt'）— 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：'pt'：返回 PyTorchtorch.Tensor对象。'np'：返回 Numpynp.ndarray对象。
- sampling_rate (
int, 可选) —audio输入被采样时的采样率。强烈建议在 forward 调用时传入sampling_rate，以避免静默错误。
用于对一条或多条序列进行特征化并准备输入模型的主要方法。
DacModel
class 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，形状为(batch_size, dimension, time_steps)，可选) — 输入的量化连续表示。 - audio_codes（形状为
(batch_size, num_codebooks, time_steps)的torch.Tensor，可选） — 每个码本的码本索引，表示输入的量化离散表示。如果您希望直接从音频代码进行解码，则应提供此参数（它将覆盖 quantized_representation）。 - return_dict (
bool，可选，默认为True) — 是否返回DacDecoderOutput而不是普通元组。
返回值
DacDecoderOutput 或 tuple(torch.Tensor)
DacDecoderOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（DacConfig）和输入。
- audio_values（形状为
(batch_size, input_length)的torch.Tensor，可选）— 解码后的音频值，通过 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，可选) — 要使用的量化器数量。如果为 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（形状为
(batch_size, dimension, time_steps)的torch.Tensor，可选） — 输入的量化连续表示。 - audio_codes（形状为
(batch_size, num_codebooks, time_steps)的torch.Tensor，可选）— 每个码本的码本索引（输入的量化离散表示）。 - projected_latents（形状为
(batch_size, num_codebooks * dimension, time_steps)的torch.Tensor，可选）— 投影后的潜变量（量化前输入的连续表示）。
forward
< source >( input_values: Tensorn_quantizers: int | None = Nonereturn_dict: bool | None = None ) → DacOutput or tuple(torch.Tensor)
参数
- input_values（形状为
(batch_size, 1, time_steps)的torch.Tensor）— 要编码的音频数据。 - n_quantizers (
int, 可选) — 要使用的量化器数量。如果为None，则使用所有量化器。默认值为None。 - return_dict (
bool, 可选) — 是否返回 ModelOutput 而不是普通元组。
返回值
DacOutput 或 tuple(torch.Tensor)
DacOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（DacConfig）和输入。
DacModel 的 forward 方法会重写 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
- loss (
torch.Tensor, 可选) — 来自编码器模型的损失，由承诺损失和码本损失的加权组合构成。 - audio_values（形状为
(batch_size, input_length)的torch.Tensor）— 重建的音频数据。 - quantized_representation（形状为
(batch_size, dimension, time_steps)的torch.Tensor）— 输入的量化连续表示。 - audio_codes（形状为
(batch_size, num_codebooks, time_steps)的torch.LongTensor）— 每个码本的码本索引（输入的量化离散表示）。 - projected_latents（形状为
(batch_size, num_codebooks * dimension, time_steps)的torch.Tensor）— 投影后的潜在变量（量化前输入的连续表示）。
示例：
>>> 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