Transformers documentation
UnivNet
该模型于 2021-06-15 在 HF papers 上发表，并于 2023-11-22 贡献至 Hugging Face Transformers。
UnivNet
概述
UnivNet 模型由 Won Jang、Dan Lim、Jaesam Yoon、Bongwan Kin 和 Juntae Kim 在 UnivNet: A Neural Vocoder with Multi-Resolution Spectrogram Discriminators for High-Fidelity Waveform Generation 中提出。
UnivNet 模型是一种生成对抗网络（GAN），用于合成高保真语音波形。transformers 中共享的 UnivNet 模型是 generator，它将条件 log-mel 频谱图以及可选的噪声序列映射为语音波形（例如，一个声码器）。推理时只需要 generator。用于训练 generator 的 discriminator 并未实现。
该论文的摘要如下：
大多数神经声码器使用带限梅尔频谱来生成波形。如果将全频段频谱特征作为输入，声码器就能获得尽可能多的声学信息。然而，在一些采用全频段梅尔频谱的模型中，会出现过度平滑的问题，导致生成的频谱不够锐利。为了解决这一问题，我们提出了 UnivNet，一种能够实时合成高保真波形的神经声码器。受语音活动检测领域相关工作的启发，我们引入了一个多分辨率频谱判别器，该判别器使用基于不同参数集计算出的多个线性频谱幅度。以全频段梅尔频谱作为输入，我们期望通过添加一个以多分辨率频谱作为输入的判别器来生成高分辨率信号。在一个包含数百位说话人信息的数据集上进行评估，UnivNet 在已知和未知说话人上均取得了优于竞争模型的最优客观和主观结果。这些结果，包括文本转语音的最佳主观得分，展示了无需从头训练即可快速适应新说话人的潜力。
提示：
noise_sequence参数用于 UnivNetModel.forward()，应为标准高斯噪声（例如来自torch.randn），其形状为([batch_size], noise_length, model.config.model_in_channels)，其中noise_length应与input_features参数的长度维度（维度 1）相匹配。如果未提供该参数，系统将随机生成噪声；可以向generator参数传入一个torch.Generator，以便复现前向传播过程。（请注意，UnivNetFeatureExtractor 默认会返回生成的噪声，因此通常无需手动生成noise_sequence。）- 通过
UnivNetFeatureExtractor.batch_decode()方法，可以从 UnivNetModel 的输出中移除由 UnivNetFeatureExtractor 添加的填充，如下面的使用示例所示。 - 在每条波形的末尾填充静音，可以减少生成音频样本末尾的伪影。可以通过向 UnivNetFeatureExtractor.call() 传入
pad_end = True来实现。更多详情请参见 此 issue。
使用示例：
import torch
from datasets import Audio, load_dataset
from scipy.io.wavfile import write
from transformers import UnivNetFeatureExtractor, UnivNetModel
model_id_or_path = "dg845/univnet-dev"
model = UnivNetModel.from_pretrained(model_id_or_path, device_map="auto")
feature_extractor = UnivNetFeatureExtractor.from_pretrained(model_id_or_path)
ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
# Resample the audio to the model and feature extractor's sampling rate.
ds = ds.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
# Pad the end of the converted waveforms to reduce artifacts at the end of the output audio samples.
inputs = feature_extractor(
ds[0]["audio"]["array"], sampling_rate=ds[0]["audio"]["sampling_rate"], pad_end=True, return_tensors="pt"
)
with torch.no_grad():
audio = model(**inputs)
# Remove the extra padding at the end of the output.
audio = feature_extractor.batch_decode(**audio)[0]
# Convert to wav file
write("sample_audio.wav", feature_extractor.sampling_rate, audio)该模型由 dg845 贡献。 据我所知，目前尚无官方代码发布，但可以在 maum-ai/univnet 找到非官方实现，预训练检查点位于 此处。
UnivNetConfig
class transformers.UnivNetConfig
< 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 = Nonemodel_in_channels: int = 64model_hidden_channels: int = 32num_mel_bins: int = 100resblock_kernel_sizes: list[int] | tuple[int, ...] = (3, 3, 3)resblock_stride_sizes: list[int] | tuple[int, ...] = (8, 8, 4)resblock_dilation_sizes: list | tuple = ((1, 3, 9, 27), (1, 3, 9, 27), (1, 3, 9, 27))kernel_predictor_num_blocks: int = 3kernel_predictor_hidden_channels: int = 64kernel_predictor_conv_size: int = 3kernel_predictor_dropout: float | int = 0.0initializer_range: float = 0.01leaky_relu_slope: float = 0.2 )
参数
- model_in_channels (
int，可选，默认为 64) — UnivNet 残差网络的输入通道数。该值应与noise_sequence.shape[1]以及 UnivNetFeatureExtractor 类中使用的值相对应。 - model_hidden_channels (
int, 可选，默认为 32) — UnivNet 残差网络中每个残差块的隐藏通道数。 - num_mel_bins (
int, 可选，默认为 100) — 条件对数梅尔频谱图中的频率分箱数量。此值应与 UnivNetFeatureExtractor 类中使用的值相对应。 - resblock_kernel_sizes (
tuple[int]或list[int]，可选，默认为[3, 3, 3]) — 一个整数元组，用于定义 UnivNet 残差网络中一维卷积层的卷积核大小。resblock_kernel_sizes的长度决定了 ResNet 块的数量，并且应与resblock_stride_sizes和resblock_dilation_sizes的长度保持一致。 - resblock_stride_sizes (
tuple[int]或list[int]，可选，默认为[8, 8, 4]) — 一个整数元组，用于定义 UnivNet 残差网络中一维卷积层的步幅大小。resblock_stride_sizes的长度应与resblock_kernel_sizes和resblock_dilation_sizes的长度一致。 - resblock_dilation_sizes (
tuple[tuple[int]]或list[list[int]]，可选，默认为[[1, 3, 9, 27], [1, 3, 9, 27], [1, 3, 9, 27]]) — 一个嵌套的整数元组，用于定义 UnivNet 残差网络中膨胀一维卷积层的膨胀率。resblock_dilation_sizes的长度应与resblock_kernel_sizes和resblock_stride_sizes的长度一致。resblock_dilation_sizes中每个嵌套列表的长度定义了每个 resnet 块中的卷积层数量。 - kernel_predictor_num_blocks (
int，可选，默认为 3) — 核预测器网络中残差块的数量，该网络用于计算 UnivNet 残差网络中每个位置变量卷积层的核和偏置。 - kernel_predictor_hidden_channels (
int，可选，默认为 64) — kernel predictor 网络中每个残差块的隐藏通道数。 - kernel_predictor_conv_size (
int，可选，默认值为 3) — 核预测网络中每个一维卷积层的卷积核大小。 - kernel_predictor_dropout (
float，可选，默认值为 0.0) — 核预测器网络中每个残差块的 dropout 概率。 - initializer_range (
float，可选，默认为0.01) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。 - leaky_relu_slope (
float，可选，默认为 0.2) — Leaky ReLU 激活函数所使用的负斜率角度。
这是用于存储 UnivNetModel 配置的类。它根据指定的参数实例化 Univnet 模型，并定义模型架构。使用默认值实例化配置将得到与 dg845/univnet-dev 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
示例：
>>> from transformers import UnivNetModel, UnivNetConfig
>>> # Initializing a Tortoise TTS style configuration
>>> configuration = UnivNetConfig()
>>> # Initializing a model (with random weights) from the Tortoise TTS style configuration
>>> model = UnivNetModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configUnivNetFeatureExtractor
class transformers.UnivNetFeatureExtractor
< source >( feature_size: int = 1sampling_rate: int = 24000padding_value: float = 0.0do_normalize: bool = Falsenum_mel_bins: int = 100hop_length: int = 256win_length: int = 1024win_function: str = 'hann_window'filter_length: int | None = 1024max_length_s: int = 10fmin: float = 0.0fmax: float | None = Nonemel_floor: float = 1e-09center: bool = Falsecompression_factor: float = 1.0compression_clip_val: float = 1e-05normalize_min: float = -11.512925148010254normalize_max: float = 2.3143386840820312model_in_channels: int = 64pad_end_length: int = 10return_attention_mask = True**kwargs )
参数
- feature_size (
int，可选，默认为 1) — 提取特征的维度。 - sampling_rate (
int，可选，默认为 24000) — 音频文件应被数字化时的采样率，以赫兹 (Hz) 为单位。 - padding_value (
float，可选，默认为 0.0) — 对 UnivNetFeatureExtractor.call() 应用由padding参数定义的填充策略时，用于填充的值。该值应对应音频静音。__call__的pad_end参数也会使用此填充值。 - do_normalize (
bool，可选，默认为False) — 是否对输入执行 Tacotron 2 归一化。归一化可以显著提升某些模型的性能。 - num_mel_bins (
int, 可选，默认为 100) — 提取的频谱特征中梅尔频率分箱的数量。此值应与UnivNetModel.config.num_mel_bins相匹配。 - hop_length (
int，可选，默认为 256) — 滑动窗口之间直接的样本数。在许多论文中也被称为“shift”。请注意，这与 SpeechT5FeatureExtractor 等其他音频特征提取器不同，后者以毫秒为单位接收hop_length。 - win_length (
int，可选，默认为 1024) — 每个滑动窗口的直接样本数。请注意，这与 SpeechT5FeatureExtractor 等其他音频特征提取器不同，后者的win_length以毫秒为单位。 - win_function (
str，可选，默认为"hann_window") — 用于加窗的窗函数名称，必须可通过torch.{win_function}访问 - filter_length (
int，可选，默认为 1024) — 要使用的 FFT 分量数量。如果为None，则使用transformers.audio_utils.optimal_fft_length来确定。 - max_length_s (
int，可选，默认为 10) — 模型输入的最大长度（以秒为单位）。此参数用于填充音频。 - fmin (
float，可选，默认为 0.0) — 最小 mel 频率，单位为 Hz。 - fmax (
float, 可选) — 最大梅尔频率，单位为 Hz。如果未设置，则默认为sampling_rate / 2。 - mel_floor (
float, 可选，默认为 1e-09) — 梅尔频率银行的最低值。请注意，UnivNetFeatureExtractor 使用mel_floor的方式与 transformers.audio_utils.spectrogram() 中的方式不同。 - center (
bool，可选，默认为False) — 是否对波形进行填充，使得帧t以时间t * hop_length为中心。如果为False，则帧t将从时间t * hop_length开始。 - compression_factor (
float，可选，默认为 1.0) — 在频谱归一化过程中，用于动态范围压缩的乘性压缩因子。 - compression_clip_val (
float，可选，默认为 1e-05) — 在频谱归一化过程中应用动态范围压缩之前，对波形应用的裁剪值。 - normalize_min (
float，可选，默认值为 -11.512925148010254) — 用于 Tacotron 2 风格线性归一化的最小值。默认值为 Tacotron 2 实现中的原始值。 - normalize_max (
float，可选，默认值为 2.3143386840820312) — 用于 Tacotron 2 风格线性归一化的最大值。默认值为 Tacotron 2 原始实现中的值。 - model_in_channels (
int, 可选，默认为 64) — UnivNetModel 模型的输入通道数。此值应与UnivNetModel.config.model_in_channels相匹配。 - pad_end_length (
int，可选，默认为 10) — 如果要对每个波形的末尾进行填充，则指定要追加的样本数（以频谱图帧数计）。追加的样本数为pad_end_length * hop_length。 - return_attention_mask (
bool，可选，默认为True) — 是否让 call() 返回attention_mask。
构建 UnivNet 特征提取器。
该类使用短时傅里叶变换（STFT）从原始语音中提取对数梅尔滤波器组特征。STFT 的实现遵循 TacoTron 2 和 Hifi-GAN 的做法。
该特征提取器继承自 SequenceFeatureExtractor，其中包含了大部分主要方法。用户应参考该父类以获取有关这些方法的更多信息。
__call__
< source >( raw_speech: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]]sampling_rate: int | None = Nonepadding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonetruncation: bool = Truepad_to_multiple_of: int | None = Nonereturn_noise: bool = Truegenerator: numpy.random._generator.Generator | None = Nonepad_end: bool = Falsepad_length: int | None = Nonedo_normalize: str | None = Nonereturn_attention_mask: bool | None = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = None )
参数
- raw_speech (
np.ndarray、list[float]、list[np.ndarray]、list[list[float]]) — 需要填充的序列或序列批次。每个序列可以是 numpy 数组、浮点值列表、numpy 数组列表或浮点值列表的列表。必须是单声道音频，而非立体声，即每个时间步对应一个浮点数。 - sampling_rate (
int, 可选) —raw_speech输入所使用的采样率。强烈建议在 forward 调用时传入sampling_rate，以避免静默错误并支持自动语音识别流水线。 - padding (
bool,str或 PaddingStrategy, 可选, 默认为True) — 选择一种策略来填充输入raw_speech波形（根据模型的填充侧和填充索引），可选值如下：True或'longest'：填充至批次中最长的序列（如果仅提供单个序列，则不进行填充）。'max_length'：填充至由参数max_length指定的最大长度；若未提供该参数，则填充至模型可接受的最大输入长度。False或'do_not_pad'（默认值）：不进行填充（即可以输出包含不同长度序列的批次）。
如果
pad_end = True，则填充操作将在应用padding策略之前执行。 - max_length (
int，可选) — 返回列表的最大长度，以及可选的填充长度（见上文）。 - truncation（
bool，可选，默认为True）— 启用截断，将长度超过max_length的输入序列截断为max_length。 - pad_to_multiple_of (
int, 可选) — 如果设置，将把序列填充为所提供值的倍数。这在启用 NVIDIA 硬件（计算能力
>= 7.5，即 Volta 架构）上的 Tensor Cores 使用时尤为有用，或者在 TPU 上使用时也特别有益，因为 TPU 在序列长度为 128 的倍数时性能更佳。 - return_noise (
bool，可选，默认为True) — 是否生成并返回噪声波形，供 UnivNetModel.forward() 使用。 - generator (
numpy.random.Generator，可选，默认为None) — 用于生成噪声的可选numpy.random.Generator随机数生成器。 - pad_end (
bool，可选，默认为False) — 是否在每个波形的末尾填充静音。这有助于减少生成音频样本末尾的伪影；更多详情请参见 https://github.com/seungwonpark/melgan/issues/8。此填充将在执行padding中指定的填充策略之前进行。 - pad_length (
int，可选，默认为None) — 如果要对每个波形的末尾进行填充，则此参数表示填充在频谱图中的帧数。如果未设置，该值将默认为self.config.pad_end_length。 - do_normalize (
bool, 可选) — 是否对输入执行 Tacotron 2 归一化。归一化可以显著提升某些模型的性能。如果未设置，则默认为self.config.do_normalize。 - return_attention_mask (
bool, 可选) — 是否返回注意力掩码。如果保持默认值，将根据特定 feature_extractor 的默认设置返回注意力掩码。 - return_tensors (
str或 TensorType, 可选) — 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：'pt'：返回 PyTorchtorch.np.array对象。'np'：返回 Numpynp.ndarray对象。
用于对一条或多条序列进行特征化并准备输入模型的主要方法。
UnivNetModel
class transformers.UnivNetModel
< source >( config: UnivNetConfig )
参数
- config (UnivNetConfig) — 模型的配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
未添加任何特定头部的裸 Univnet 模型，直接输出原始隐藏状态。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( input_features: Tensornoise_sequence: typing.Optional[torch.Tensor] = Nonepadding_mask: typing.Optional[torch.Tensor] = Nonegenerator: typing.Optional[torch.Generator] = Nonereturn_dict: bool | None = None**kwargs ) → UnivNetModelOutput or tuple(torch.Tensor)
参数
- input_features (
torch.Tensor，形状为(batch_size, sequence_length, feature_dim)) — 与输入音频特征对应的张量。可以使用 UnivNetFeatureExtractor 获取音频特征。有关详细信息，请参阅 UnivNetFeatureExtractor.call()（processor_class使用 UnivNetFeatureExtractor 处理音频）。 - noise_sequence (
torch.Tensor, 可选) — 包含标准高斯噪声序列的张量。可以批量处理，形状为(batch_size, sequence_length, config.model_in_channels)，也可以不批量处理，形状为 (sequence_length, config.model_in_channels)`。如果未提供，将随机生成。 - padding_mask (
torch.BoolTensor, 可选) — 指示每个序列中哪些部分被填充的掩码。掩码值取自[0, 1]:- 1 表示未被屏蔽的 token
- 对于被屏蔽的 token，值为 0
掩码可以按批次处理，形状为
(batch_size, sequence_length)，也可以不按批次处理，形状为(sequence_length,)。 - generator (
torch.Generator, 可选) — 用于使生成过程具有确定性的 torch 生成器。 return_dict: 是否返回 ModelOutput 的子类，而不是普通的元组。 - return_dict (
bool, 可选) — 是否返回 ModelOutput 而不是普通元组。
返回值
UnivNetModelOutput 或 tuple(torch.Tensor)
UnivNetModelOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（UnivNetConfig）和输入。
UnivNetModel 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
- 波形（形状为
(batch_size, sequence_length)的torch.Tensor）— 批处理的 1D（单声道）输出音频波形。 - waveform_lengths（形状为
(batch_size,)的torch.Tensor）—waveforms中每个未填充波形的批量采样长度。
示例：
>>> from transformers import UnivNetFeatureExtractor, UnivNetModel
>>> from datasets import load_dataset, Audio
>>> model = UnivNetModel.from_pretrained("dg845/univnet-dev")
>>> feature_extractor = UnivNetFeatureExtractor.from_pretrained("dg845/univnet-dev")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> # Resample the audio to the feature extractor's sampling rate.
>>> ds = ds.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
>>> inputs = feature_extractor(
... ds[0]["audio"]["array"], sampling_rate=ds[0]["audio"]["sampling_rate"], return_tensors="pt"
... )
>>> audio = model(**inputs).waveforms
>>> list(audio.shape)
[1, 140288]