speechbrain.lobes.models.beats 模块

该叶瓣使得预训练的BEATs能够集成：使用声学标记器进行音频预训练。

参考: https://arxiv.org/abs/2212.09058 基于Github源码: https://github.com/microsoft/unilm/tree/master/beats

你可以从以下链接下载检查点：https://github.com/microsoft/unilm/tree/master/beats

Author

Pooneh Mousavi 2024

摘要

类：

`BEATs`	BEATs: 使用声学标记器进行音频预训练。
`BEATsConfig`	BEATs模型的配置类。
`GLU_Linear`	实现了一个结合线性变换的门控线性单元（GLU）。
`GradMultiply`	一个自定义的自动梯度函数，用于在反向传播过程中缩放梯度。
`MultiheadAttention`	实现多头注意力机制，支持相对位置嵌入和基于GRU的门控相对位置嵌入等高级功能。
`SamePad`	实现了一个模块，该模块在卷积后调整张量的填充以保持其原始大小，并提供因果填充的选项。
`Swish`	实现Swish激活函数作为一个PyTorch模块。
`TransformerEncoder`	实现Transformer编码器模块。
`TransformerSentenceEncoderLayer`	实现一个单一的Transformer句子编码器层。

函数：

`gelu`	应用高斯误差线性单元（GELU）激活函数。
`gelu_accurate`	应用高斯误差线性单元（GELU）激活函数，使用精确近似。
`get_activation_fn`	返回与提供的激活名称对应的激活函数。
`init_bert_params`	初始化BERT模型中模块的权重和偏差。
`quant_noise`	封装模块并对其权重应用量化噪声，以便后续使用迭代产品量化（iPQ）进行量化。

参考

class speechbrain.lobes.models.beats.BEATs(ckp_path: str = None, freeze: bool = True, output_all_hiddens: bool = False)[source]

基础：Module

BEATs: 使用声学标记器进行音频预训练。

该类实现了BEATs模型，该模型处理音频信号以进行特征提取或下游任务。模型支持从检查点加载、应用归一化，并可选择冻结参数。

Parameters:

ckp_path (str, 可选) – 检查点文件的路径。如果为None，模型将不使用预训练权重进行初始化。你可以从以下链接下载检查点：https://github.com/microsoft/unilm/tree/master/beats
freeze (bool, 可选 (默认: False)) – 如果为True，模型参数将被冻结，模型将设置为评估模式。
output_all_hiddens (bool, 可选 (默认: False)) – 如果为True，前向函数会输出所有transformer层的隐藏状态。例如，BEATs_iter3有12个transformer层，输出形状为(13, B, T, C)，其中CNN输出的投影被添加到开头。如果为False，前向函数仅输出最后一个transformer层的隐藏状态。

Example

>>> audio = torch.randn(4, 10000)  # Batch of 4 audio signals
>>> length = torch.tensor([1.0, 0.5, 0.75, 1.0])
>>> model = BEATs()
>>> outputs = model.extract_features(audio, length)[0]
>>> outputs.shape
torch.Size([4, 24, 768])

forward_padding_mask(features: Tensor, padding_mask: Tensor) → Tensor[source]

调整给定特征的填充掩码。

Parameters:

特征 (torch.Tensor) – 经过补丁嵌入后的输入特征。
padding_mask (torch.Tensor) – 输入信号的原始填充掩码。

Returns:

调整后的填充掩码。

Return type:

torch.Tensor

preprocess(source: Tensor, fbank_mean: float = 15.41663, fbank_std: float = 6.55582) → Tensor[source]

通过提取滤波器组并应用归一化来预处理输入波形。

Parameters:

source (torch.Tensor) – 输入波形信号。
fbank_mean (float, 可选) – 滤波器组归一化的平均值（默认值：15.41663）。
fbank_std (float, 可选) – 滤波器组归一化的标准差（默认值：6.55582）。

Returns:

归一化的滤波器组。

Return type:

torch.Tensor

forward(wav: Tensor, wav_lens: Tensor | None = None, fbank_mean: float = 15.41663, fbank_std: float = 6.55582)[source]

接收一个输入波形并返回其对应的节拍编码。

Parameters:

wav (torch.Tensor) – 一批要转换为特征的音频信号。
wav_lens (torch.Tensor) – 以SpeechBrain格式给出的wav的相对长度。
fbank_mean (float, 可选) – 滤波器组归一化的平均值（默认值：15.41663）。
fbank_std (float, 可选) – 滤波器组归一化的标准差（默认值：6.55582）。

Return type:

BEATs编码特征。

extract_features(wav: Tensor, wav_lens: Tensor | None = None, fbank_mean: float = 15.41663, fbank_std: float = 6.55582) → Tensor[source]

从输入波形中提取特征。

Parameters:

wav (torch.Tensor) – 一批要转换为特征的音频信号。
wav_lens (torch.Tensor) – 以SpeechBrain格式给出的wav的相对长度。
fbank_mean (float, 可选) – 滤波器组归一化的平均值（默认值：15.41663）。
fbank_std (float, 可选) – 滤波器组归一化的标准差（默认值：6.55582）。

Returns:

从BEATs模型中提取的特征。

Return type:

torch.Tensor

speechbrain.lobes.models.beats.gelu_accurate(x)[source]

应用高斯误差线性单元（GELU）激活函数，使用精确近似。

Parameters:: x (torch.Tensor) – 输入张量，将对其应用GELU激活函数。
Returns:: 应用了GELU激活的逐元素张量。
Return type:: torch.Tensor

speechbrain.lobes.models.beats.gelu(x: Tensor) → Tensor[source]

应用高斯误差线性单元（GELU）激活函数。

Parameters:: x (torch.Tensor) – 应用GELU激活的输入张量。
Returns:: 应用了GELU激活的逐元素张量。
Return type:: torch.Tensor

speechbrain.lobes.models.beats.get_activation_fn(activation: str)[source]

返回与提供的激活名称对应的激活函数。

Parameters:: activation (str) – 激活函数的名称。支持的值为： - “relu”：应用ReLU激活。 - “gelu”：应用GELU激活。 - “gelu_fast”：gelu_accurate的别名，带有弃用警告。 - “gelu_accurate”：应用精确的GELU激活。 - “tanh”：应用Tanh激活。 - “linear”：应用恒等函数。 - “glu”：应用恒等函数（GLU占位符）。
Returns:: 应用于输入张量的相应激活函数。
Return type:: Callable[[torch.Tensor], torch.Tensor]
Raises:: RuntimeError – 如果不支持指定的激活函数。

class speechbrain.lobes.models.beats.SamePad(kernel_size, causal=False)[source]

基础：Module

实现了一个模块，该模块在卷积后调整张量的填充以保持其原始大小，并提供因果填充的选项。

这对于处理卷积层中的填充特别有用，其中内核大小或因果关系会影响输出大小。

Parameters:

kernel_size (int) – 卷积核的大小。
causal (bool, 可选 (默认=False)) – 如果为True，通过从张量的末尾移除(kernel_size - 1)个元素来应用因果填充。如果为False，则移除元素以使填充居中对齐，确保输出大小与输入大小匹配。

forward(x)[source]

调整输入张量 x 的填充。

如果 self.remove > 0，该方法会沿着最后一个维度对张量进行切片，以根据 kernel_size 和 causal 设置移除多余的填充。

Parameters:: x (torch.Tensor) – 用于调整填充的输入张量。
Returns:: 调整填充后的张量。
Return type:: torch.Tensor

class speechbrain.lobes.models.beats.Swish[source]

基础：Module

实现Swish激活函数作为一个PyTorch模块。

Swish is a smooth, non-monotonic activation function defined as:: Swish(x) = x * sigmoid(x)

它经常用于深度学习中，因为它能够提高某些架构中的训练性能。

forward(x)[source]

将Swish激活函数应用于输入张量。

Parameters:: x (torch.Tensor) – 应用Swish激活函数的输入张量。
Returns:: 应用Swish激活后的输入张量。
Return type:: torch.Tensor

class speechbrain.lobes.models.beats.GLU_Linear(input_dim, output_dim, glu_type='sigmoid', bias_in_glu=True)[source]

基础：Module

实现了一个结合线性变换的门控线性单元（GLU）。

Parameters:

input_dim (int) – 输入特征的维度。
output_dim (int) – 输出特征的维度。
glu_type (str, optional (default="sigmoid")) – 用于门控的激活函数类型。支持的值为： - “sigmoid”：使用Sigmoid激活函数。 - “swish”：使用Swish激活函数。 - “relu”：使用ReLU激活函数。 - “gelu”：使用GELU激活函数。
bias_in_glu (bool, 可选 (默认=True)) – 是否在线性变换中包含偏置项。

class speechbrain.lobes.models.beats.GradMultiply(*args, **kwargs)[source]

基础：Function

一个自定义的自动梯度函数，在反向传播过程中缩放梯度。

这对于需要在不影响前向传播输出的情况下进行梯度缩放的场景非常有用。前向传播返回输入本身，而后向传播则通过指定的因子缩放梯度。

static forward(ctx, x, scale)[source]

执行GradMultiply函数的前向传递。

Parameters:

ctx (torch.autograd.Function) – 上下文对象，用于存储反向计算的信息。
x (torch.Tensor) – 输入张量，将保持不变地向前传递。
scale (float) – 在反向传播过程中，梯度将被缩放的因子。

Returns:

与输入张量相同的新张量。

Return type:

torch.Tensor

static backward(ctx, grad)[source]

执行反向传播，通过存储的因子缩放梯度。

Parameters:

ctx (torch.autograd.Function) – 包含存储的缩放因子的上下文对象。
grad (torch.Tensor) – 来自后续层的梯度张量。

Returns:

缩放后的梯度张量和None（对于没有梯度的缩放输入）。

Return type:

元组[torch.Tensor, 无]

speechbrain.lobes.models.beats.quant_noise(module, p, block_size)[source]

封装模块并对其权重应用量化噪声，以便后续使用迭代产品量化（iPQ）进行量化。

这种方法在论文中有所描述： “Training with Quantization Noise for Extreme Model Compression.” 它在训练过程中引入量化噪声，以提高模型在极端权重压缩场景下的鲁棒性。

Parameters:

模块 (nn.Module) – 将应用量化噪声的模块。支持的模块包括 Linear、Embedding 和 Conv2d。
p (float) – 要应用的量化噪声量。通常是一个概率或缩放因子。
block_size (int) – 用于后续使用iPQ进行量化的块的大小。

Return type:

无

class speechbrain.lobes.models.beats.TransformerEncoder(args)[source]

基础：Module

实现Transformer编码器模块。

Parameters:: args (Namespace 或 dict) – 模型超参数和配置的集合。

forward(x, padding_mask=None, output_all_hiddens=None)[source]

通过Transformer编码器层处理输入序列。

Parameters:

x (torch.Tensor) – 输入张量的形状为 (seq_len, batch_size, embed_dim)，包含输入嵌入。
padding_mask (torch.Tensor, optional) – 一个形状为 (batch_size, seq_len) 的二进制掩码，指示哪些位置是填充的，在注意力计算中应被忽略。默认值为 None。
output_all_hiddens (bool, 可选) – 如果为True，除了最终输出外，还会返回所有编码器层的隐藏状态。默认值为 None。

Returns:

最终输出的张量形状为 (seq_len, batch_size, embed_dim)。

Return type:

元组[torch.Tensor, 列表[torch.Tensor]]

extract_features(x, padding_mask=None, output_all_hiddens=None)[source]

使用位置卷积、层归一化、dropout 和一系列 Transformer 编码器层从输入序列中提取特征。

Parameters:

x (torch.Tensor) – 输入张量，形状为 (batch_size, seq_len, embed_dim)，包含输入嵌入。
padding_mask (torch.Tensor, optional) – 一个形状为 (batch_size, seq_len) 的二进制掩码，指示哪些位置是填充的，在计算中应被忽略。默认值为 None。
output_all_hiddens (bool, optional) – 如果为True，除了最终输出外，还会收集并返回所有编码器层的隐藏状态。默认值为None。

Returns:

最终输出的张量形状为 (batch_size, seq_len, embed_dim)。

Return type:

元组[torch.Tensor, 列表[torch.Tensor]]

class speechbrain.lobes.models.beats.TransformerSentenceEncoderLayer(embedding_dim: float = 768, ffn_embedding_dim: float = 3072, num_attention_heads: float = 8, dropout: float = 0.1, attention_dropout: float = 0.1, activation_dropout: float = 0.1, activation_fn: str = 'relu', layer_norm_first: bool = False, deep_norm: bool = False, has_relative_attention_bias: bool = False, num_buckets: int = 0, max_distance: int = 0, rescale_init: bool = False, gru_rel_pos: bool = False, encoder_layers: int = 0)[source]

基础：Module

实现一个单一的Transformer句子编码器层。

Parameters:

embedding_dim (float, 可选 (默认=768)) – 输入嵌入的维度。
ffn_embedding_dim (float, 可选 (默认=3072)) – 前馈网络隐藏层的维度。
num_attention_heads (float, 可选 (默认=8)) – 自注意力机制中的注意力头数量。
dropout (float, 可选 (默认=0.1)) – 应用于前馈网络和注意力层输出的丢弃率。
attention_dropout (float, 可选 (默认=0.1)) – 在注意力机制中应用的dropout率。
activation_dropout (float, 可选 (默认=0.1)) – 在前馈网络中激活函数后应用的丢弃率。
activation_fn (str, 可选 (默认="relu")) – 在前馈网络中使用的激活函数。支持的数值包括“relu”和“gelu”。
layer_norm_first (bool, 可选 (默认=False)) – 如果为True，则在注意力和前馈层之前应用层归一化；否则，在之后应用。
deep_norm (bool, 可选 (默认=False)) – 如果为True，则对残差连接使用深度归一化缩放。
has_relative_attention_bias (bool, 可选 (默认=False)) – 如果为True，则在注意力机制中包含相对位置偏差。
num_buckets (int, 可选 (默认=0)) – 用于相对注意力偏置的桶的数量（如果启用）。
max_distance (int, 可选 (默认=0)) – 相对注意力偏差的最大距离（如果启用）。
rescale_init (bool, 可选 (默认=False)) – 如果为True，则重新调整参数初始化以提高稳定性。
gru_rel_pos (bool, 可选 (默认=False)) – 如果为True，则采用GRU风格的相对位置编码。
encoder_layers (int, 可选 (默认=0)) – Transformer中的编码器层数。

forward(x: Tensor, self_attn_mask: Tensor = None, self_attn_padding_mask: Tensor = None, need_weights: bool = False, pos_bias=None)[source]

通过Transformer句子编码器层处理输入张量。

Parameters:

x (torch.Tensor) – 输入张量的形状为 (seq_len, batch_size, embed_dim)。
self_attn_mask (torch.Tensor, optional) – 用于自注意力机制的掩码，通常用于因果或填充掩码。默认值为 None。
self_attn_padding_mask (torch.Tensor, optional) – 形状为 (batch_size, seq_len) 的填充掩码，指示在注意力计算中应忽略哪些标记。默认值为 None。
need_weights (bool, 可选 (默认=False)) – 是否返回注意力权重。如果 True，则输出中包含注意力权重。
pos_bias (可选) – 如果适用，相对注意力的位置偏差。默认值为 None。

Returns:

x (torch.Tensor): 输出张量的形状为 (seq_len, batch_size, embed_dim)

在应用编码器层之后。

Return type:

元组[torch.Tensor, torch.Tensor, 可选]

class speechbrain.lobes.models.beats.MultiheadAttention(embed_dim, num_heads, kdim=None, vdim=None, dropout=0.0, bias=True, add_bias_kv=False, add_zero_attn=False, self_attention=False, encoder_decoder_attention=False, q_noise=0.0, qn_block_size=8, has_relative_attention_bias=False, num_buckets=32, max_distance=128, gru_rel_pos=False, rescale_init=False)[source]

基础：Module

实现了多头注意力机制，支持相对位置嵌入和基于GRU的门控相对位置嵌入等高级功能。

Parameters:

embed_dim (int) – 输入嵌入的总维度数。
num_heads (int) – 注意力头的数量。
kdim (int, 可选) – 键嵌入的维度。默认为 embed_dim。
vdim (int, 可选) – 值嵌入的维度。默认为 embed_dim。
dropout (float, 可选) – 注意力权重的丢弃概率。默认为 0.0。
bias (bool, 可选) – 是否在投影中包含偏置项。默认为 True。
add_bias_kv (bool, optional) – 是否包含键和值投影的偏置。默认为 False。
add_zero_attn (bool, 可选) – 是否包含零注意力向量。默认为 False。
self_attention (bool, 可选) – 该层是否用于自注意力机制。默认为 False。
encoder_decoder_attention (bool, 可选) – 该层是否用于编码器-解码器注意力。默认为 False。
q_noise (float, 可选) – 量化的噪声水平。默认为0.0。
qn_block_size (int, 可选) – 量化的块大小。默认为8。
has_relative_attention_bias (bool, 可选) – 是否使用相对位置嵌入。默认为 False。
num_buckets (int, 可选) – 相对位置嵌入的桶数。默认为32。
max_distance (int, 可选) – 相对位置嵌入的最大距离。默认为128。
gru_rel_pos (bool, 可选) – 是否使用门控相对位置嵌入。默认为 False。
rescale_init (bool, 可选) – 是否重新缩放权重的初始化。默认为 False。

reset_parameters()[source]: 初始化投影层和相对位置嵌入的权重。

compute_bias(query_length: int, key_length: int) → Tensor[source]

计算注意力分数的相对位置偏差。

Parameters:

query_length (int) – 查询序列的长度。
key_length (int) – 键序列的长度。

Returns:

一个形状为(num_heads, query_length, key_length)的张量，包含每个注意力头的相对位置偏置值。

Return type:

torch.Tensor

forward(query: Tensor, key: Tensor | None, value: Tensor | None, key_padding_mask: Tensor | None = None, incremental_state: Dict[str, Dict[str, Tensor | None]] | None = None, need_weights: bool = True, static_kv: bool = False, attn_mask: Tensor | None = None, before_softmax: bool = False, need_head_weights: bool = False, position_bias: Tensor | None = None) → Tuple[Tensor, Tensor | None, Tensor | None][source]

支持相对位置嵌入、缓存和可选dropout的多头注意力前向传播。

此方法实现了多头注意力的核心功能，包括相对位置偏差、增量解码以及支持各种掩码选项等可选特性。

Parameters:

query (torch.Tensor) – 查询张量的形状为 (target_length, batch_size, embed_dim)。
key (torch.Tensor, optional) – 形状为 (source_length, batch_size, embed_dim) 的键张量。默认为 None。
value (torch.Tensor, optional) – 形状为 (source_length, batch_size, embed_dim) 的值张量。默认为 None。
key_padding_mask (torch.Tensor, optional) – 用于排除填充键的掩码，形状为 (batch_size, source_length)，其中填充元素由1表示。默认为 None。
incremental_state (dict, 可选) – 存储用于增量解码的缓存键和值张量。默认为 None。
need_weights (bool, 可选) – 如果为True，返回注意力权重。默认为 True。
static_kv (bool, 可选) – 如果为True，键和值张量在增量解码时保持静态。默认为 False。
attn_mask (torch.Tensor, optional) – 注意力掩码，用于防止某些位置参与注意力计算，通常用于因果注意力。形状：(target_length, source_length)。默认为 None。
before_softmax (bool, 可选) – 如果为True，返回softmax之前的原始注意力分数。默认为 False。
need_head_weights (bool, 可选) – 如果为True，返回每个头的注意力权重。意味着 need_weights=True。默认为 False。
position_bias (torch.Tensor, optional) – 预计算的位置偏置张量。如果 None，则在正向传播期间计算。

Returns:

attn (torch.Tensor) – 形状为 (target_length, batch_size, embed_dim) 的注意力输出。
attn_weights (torch.Tensor, optional) – 形状为 (batch_size, num_heads, target_length, source_length) 的注意力权重，如果 need_head_weights=False，则在头部之间平均。
position_bias (torch.Tensor, optional) – 计算或传递的相对位置偏差，形状为 (num_heads, target_length, source_length)。

apply_bias(k, v, bsz, attn_mask=None, key_padding_mask=None)[source]

将bias_k和bias_v应用于键和值张量，相应地更新注意力掩码和键填充掩码。

Parameters:

k (torch.Tensor) – 键张量。
v (torch.Tensor) – 值张量。
bsz (int) – 批量大小。
attn_mask (torch.Tensor) – 注意力掩码
key_padding_mask (torch.Tensor) – 键填充掩码。

Returns:

Tuple[torch.Tensor, torch.Tensor, Optional[torch.Tensor], Optional[torch.Tensor]] – 注意力掩码和键填充掩码。

Return type:

更新了键，值，

apply_sparse_mask(attn_weights, tgt_len: int, src_len: int, bsz: int)[source]

将稀疏掩码应用于注意力权重。

Parameters:

attn_weights (torch.Tensor) – 注意力权重张量，形状为 (batch_size * num_heads, tgt_len, src_len)。
tgt_len (int) – 目标序列的长度。
src_len (int) – 源序列的长度。
bsz (int) – 批次大小。

Returns:

（可能经过修改的）注意力权重张量。默认情况下，这与输入张量相同。

Return type:

torch.Tensor

speechbrain.lobes.models.beats.init_bert_params(module: Module) → None[source]

初始化BERT模型中模块的权重和偏置。

Parameters:: 模块 (nn.Module) – 要初始化的模块。可以是 nn.Linear, nn.Embedding, 或 MultiheadAttention 之一。

class speechbrain.lobes.models.beats.BEATsConfig(cfg=None)[source]

基础类：object

BEATs模型的配置类。

此类定义了BEATs模型的配置。它提供了一个默认配置，可以通过update方法使用自定义设置进行更新。

Parameters:: cfg (dict, 可选) – 包含自定义配置值的字典。如果提供，它将覆盖默认设置。

update(cfg: dict)[source]

使用给定配置字典中的键值对更新实例的属性。

Parameters:: cfg (dict) – 一个包含用于更新实例的配置值的字典。