Transformers 文档
音频频谱图 Transformer
并获得增强的文档体验
开始使用
音频频谱图 Transformer
概述
音频频谱图 Transformer 模型由 Yuan Gong、Yu-An Chung、James Glass 在论文 AST: Audio Spectrogram Transformer 中提出。音频频谱图 Transformer 将 视觉 Transformer 应用于音频，通过将音频转换为图像（频谱图）来实现。该模型在音频分类任务上取得了目前最先进的结果。
论文摘要如下：
在过去十年中，卷积神经网络（CNNs）被广泛用作端到端音频分类模型的主要构建模块，旨在学习从音频频谱图到相应标签的直接映射。为了更好地捕捉长距离全局上下文，最近的趋势是在 CNN 之上添加自注意力机制，形成 CNN-注意力混合模型。然而，尚不清楚是否必须依赖 CNN，以及纯粹基于注意力的神经网络是否足以在音频分类中获得良好性能。在本文中，我们通过引入音频频谱图 Transformer（AST）来回答这个问题，这是第一个无卷积、纯粹基于注意力的音频分类模型。我们在各种音频分类基准上评估了 AST，它在 AudioSet 上取得了 0.485 mAP 的新 SOTA 结果，在 ESC-50 上取得了 95.6% 的准确率，在 Speech Commands V2 上取得了 98.1% 的准确率。
音频频谱图 Transformer 架构。摘自原始论文。 使用技巧
- 在您自己的数据集上微调音频频谱图 Transformer (AST) 时，建议注意输入归一化（确保输入均值为 0，标准差为 0.5）。ASTFeatureExtractor 负责此操作。请注意，它默认使用 AudioSet 的均值和标准差。您可以查看
ast/src/get_norm_stats.py来了解作者如何为下游数据集计算统计数据。 - 请注意，AST 需要较低的学习率（作者使用的学习率比他们在 PSLA 论文 中提出的 CNN 模型小 10 倍）并且收敛速度快，因此请为您的任务寻找合适的学习率和学习率调度器。
使用缩放点积注意力 (SDPA)
PyTorch 在 torch.nn.functional 中包含了原生的缩放点积注意力 (SDPA) 算子。此函数包含多种实现，可根据输入和所用硬件进行应用。更多信息请参见官方文档或GPU 推理页面。
当实现可用时，SDPA 默认用于 `torch>=2.1.1`，但你也可以在 `from_pretrained()` 中设置 `attn_implementation="sdpa"` 来明确请求使用 SDPA。
from transformers import ASTForAudioClassification
model = ASTForAudioClassification.from_pretrained("MIT/ast-finetuned-audioset-10-10-0.4593", attn_implementation="sdpa", torch_dtype=torch.float16)
...为了获得最佳加速效果，我们建议以半精度（例如 `torch.float16` 或 `torch.bfloat16`）加载模型。
在本地基准测试 (A100-40GB, PyTorch 2.3.0, OS Ubuntu 22.04) 中，使用 float32 和 MIT/ast-finetuned-audioset-10-10-0.4593 模型，我们在推理过程中观察到以下速度提升。
| 批次大小 | 平均推理时间（毫秒），eager 模式 | 平均推理时间（毫秒），sdpa 模型 | 加速，Sdpa / Eager (x) |
|---|---|---|---|
| 1 | 27 | 6 | 4.5 |
| 2 | 12 | 6 | 2 |
| 4 | 21 | 8 | 2.62 |
| 8 | 40 | 14 | 2.86 |
资源
Hugging Face 官方和社区（由 🌎 标志）提供的资源列表，帮助您开始使用音频频谱图 Transformer。
- 一个展示使用 AST 进行音频分类推理的 notebook 可以在这里找到。
- ASTForAudioClassification 受此示例脚本和notebook支持。
- 另请参阅：音频分类。
如果您有兴趣在此处提交资源，请随时开启 Pull Request，我们将对其进行审查！该资源最好能展示一些新内容，而不是重复现有资源。
ASTConfig
class transformers.ASTConfig
< source >( hidden_size = 768 num_hidden_layers = 12 num_attention_heads = 12 intermediate_size = 3072 hidden_act = 'gelu' hidden_dropout_prob = 0.0 attention_probs_dropout_prob = 0.0 initializer_range = 0.02 layer_norm_eps = 1e-12 patch_size = 16 qkv_bias = True frequency_stride = 10 time_stride = 10 max_length = 1024 num_mel_bins = 128 **kwargs )
参数
- hidden_size (
int, 可选, 默认为 768) — 编码器层和池化层的维度。 - num_hidden_layers (
int, 可选, 默认为 12) — Transformer 编码器中的隐藏层数量。 - num_attention_heads (
int, 可选, 默认为 12) — Transformer 编码器中每个注意力层的注意力头数量。 - intermediate_size (
int, 可选, 默认为 3072) — Transformer 编码器中“中间”（即前馈）层的维度。 - hidden_act (
strorfunction, 可选, 默认为"gelu") — 编码器和池化层中的非线性激活函数（函数或字符串）。如果为字符串，则支持"gelu"、"relu"、"selu"和"gelu_new"。 - hidden_dropout_prob (
float, 可选, 默认为 0.0) — 嵌入层、编码器和池化层中所有全连接层的丢弃概率。 - attention_probs_dropout_prob (
float, 可选, 默认为 0.0) — 注意力概率的丢弃率。 - initializer_range (
float, 可选, 默认为 0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。 - layer_norm_eps (
float, 可选, 默认为 1e-12) — 层归一化层使用的 epsilon 值。 - patch_size (
int, 可选, 默认为 16) — 每个 patch 的大小（分辨率）。 - qkv_bias (
bool, 可选, 默认为True) — 是否为查询、键和值添加偏置。 - frequency_stride (
int, 可选, 默认为 10) — 对频谱图进行 patch 化时使用的频率步长。 - time_stride (
int, 可选, 默认为 10) — 对频谱图进行 patch 化时使用的时间步长。 - max_length (
int, 可选, 默认为 1024) — 频谱图的时间维度。 - num_mel_bins (
int, 可选, 默认为 128) — 频谱图的频率维度（梅尔频率带的数量）。
这是用于存储 ASTModel 配置的配置类。它用于根据指定的参数实例化一个 AST 模型，定义模型架构。使用默认值实例化一个配置将产生与 AST MIT/ast-finetuned-audioset-10-10-0.4593 架构类似的配置。
配置对象继承自 PretrainedConfig，可用于控制模型输出。更多信息请参阅 PretrainedConfig 的文档。
示例
>>> from transformers import ASTConfig, ASTModel
>>> # Initializing a AST MIT/ast-finetuned-audioset-10-10-0.4593 style configuration
>>> configuration = ASTConfig()
>>> # Initializing a model (with random weights) from the MIT/ast-finetuned-audioset-10-10-0.4593 style configuration
>>> model = ASTModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configASTFeatureExtractor
class transformers.ASTFeatureExtractor
< source >( feature_size = 1 sampling_rate = 16000 num_mel_bins = 128 max_length = 1024 padding_value = 0.0 do_normalize = True mean = -4.2677393 std = 4.5689974 return_attention_mask = False **kwargs )
参数
- feature_size (
int, 可选, 默认为 1) — 提取特征的特征维度。 - sampling_rate (
int, 可选, 默认为 16000) — 音频文件数字化的采样率，以赫兹 (Hz) 表示。 - num_mel_bins (
int, 可选, 默认为 128) — 梅尔频率带的数量。 - max_length (
int, 可选, 默认为 1024) — 用于对提取的特征进行填充/截断的最大长度。 - do_normalize (
bool, 可选, 默认为True) — 是否使用mean和std对对数-梅尔特征进行归一化。 - mean (
float, 可选, 默认为 -4.2677393) — 用于归一化对数-梅尔特征的均值。默认使用 AudioSet 的均值。 - std (
float, 可选, 默认为 4.5689974) — 用于归一化对数-梅尔特征的标准差值。默认使用 AudioSet 的标准差。 - return_attention_mask (
bool, 可选, 默认为False) — call() 是否应返回attention_mask。
构建一个音频频谱图 Transformer (AST) 特征提取器。
该特征提取器继承自 SequenceFeatureExtractor，其中包含了大多数主要方法。用户应参考此超类以获取有关这些方法的更多信息。
如果安装了 TorchAudio，此类将使用 TorchAudio 从原始语音中提取 mel-filter bank 特征，否则使用 numpy。然后将它们填充/截断到固定长度，并使用均值和标准差进行归一化。
__call__
< source >( raw_speech: typing.Union[numpy.ndarray, list[float], list[numpy.ndarray], list[list[float]]] sampling_rate: typing.Optional[int] = None return_tensors: typing.Union[str, transformers.utils.generic.TensorType, NoneType] = None **kwargs )
参数
- raw_speech (
np.ndarray,list[float],list[np.ndarray],list[list[float]]) — 要填充的序列或序列批次。每个序列可以是 numpy 数组、浮点值列表、numpy 数组列表或浮点值列表的列表。必须是单声道音频，而不是立体声，即每个时间步只有一个浮点数。 - sampling_rate (
int, 可选) —raw_speech输入的采样率。强烈建议在前向调用时传递sampling_rate以防止静默错误。 - return_tensors (
stror TensorType, 可选) — 如果设置，将返回张量而不是 Python 整数列表。可接受的值有：'tf'：返回 TensorFlowtf.constant对象。'pt'：返回 PyTorchtorch.Tensor对象。'np'：返回 Numpynp.ndarray对象。
对一个或多个序列进行特征化并为模型准备的主方法。
ASTModel
class transformers.ASTModel
< source >( config: ASTConfig )
参数
- config (ASTConfig) — 包含模型所有参数的模型配置类。使用配置文件初始化不会加载与模型相关的权重，仅加载配置。请查看 from_pretrained() 方法来加载模型权重。
基础的音频频谱图 Transformer 模型，输出原始的隐藏状态，没有任何特定的头部。
该模型继承自 PreTrainedModel。请查看超类文档，了解库为所有模型实现的通用方法（如下载或保存、调整输入嵌入大小、修剪头部等）。
该模型也是一个 PyTorch torch.nn.Module 子类。可以像常规 PyTorch 模块一样使用它，并参考 PyTorch 文档了解所有与通用用法和行为相关的事项。
forward
< source >( input_values: typing.Optional[torch.Tensor] = None head_mask: typing.Optional[torch.Tensor] = None output_attentions: typing.Optional[bool] = None output_hidden_states: typing.Optional[bool] = None return_dict: typing.Optional[bool] = None ) → transformers.modeling_outputs.BaseModelOutputWithPooling 或 tuple(torch.FloatTensor)
参数
- input_values (形状为
(batch_size, max_length, num_mel_bins)的torch.FloatTensor) — 从原始音频波形中提取的浮点值梅尔特征。原始音频波形可以通过将.flac或.wav音频文件加载到list[float]或numpy.ndarray类型的数组中获得，例如通过 soundfile 库（pip install soundfile）。为了将数组准备成input_features，应使用 AutoFeatureExtractor 来提取梅尔特征、进行填充并转换为torch.FloatTensor类型的张量。请参阅 call() - head_mask (
torch.Tensor，形状为(num_heads,)或(num_layers, num_heads)，可选) — 用于使自注意力模块中选定的头无效的掩码。掩码值的取值范围为[0, 1]：- 1 表示该头未被掩码，
- 0 表示该头已被掩码。
- output_attentions (
bool, 可选) — 是否返回所有注意力层的注意力张量。更多详情请参阅返回张量下的attentions。 - output_hidden_states (
bool, 可选) — 是否返回所有层的隐藏状态。更多详情请参阅返回张量下的hidden_states。 - return_dict (
bool, 可选) — 是返回一个 ModelOutput 而不是一个普通的元组。
返回
transformers.modeling_outputs.BaseModelOutputWithPooling 或 tuple(torch.FloatTensor)
一个 transformers.modeling_outputs.BaseModelOutputWithPooling 或一个 torch.FloatTensor 的元组（如果传入 return_dict=False 或 config.return_dict=False），包含根据配置（ASTConfig）和输入而变化的不同元素。
-
last_hidden_state (
torch.FloatTensor, 形状为(batch_size, sequence_length, hidden_size)) — 模型最后一层输出的隐藏状态序列。 -
pooler_output (
torch.FloatTensor，形状为(batch_size, hidden_size)) — 序列中第一个词元（分类词元）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后的结果。例如，对于 BERT 族模型，这返回的是经过线性层和 tanh 激活函数处理后的分类词元。线性层的权重是在预训练期间通过下一句预测（分类）目标进行训练的。 -
hidden_states (
tuple(torch.FloatTensor), 可选, 当传入output_hidden_states=True或config.output_hidden_states=True时返回) —torch.FloatTensor的元组（如果模型有嵌入层，则一个是嵌入层的输出，另外每个层各有一个输出），形状为(batch_size, sequence_length, hidden_size)。模型在每个层输出的隐藏状态以及可选的初始嵌入输出。
-
attentions (
tuple(torch.FloatTensor), 可选, 当传入output_attentions=True或config.output_attentions=True时返回) —torch.FloatTensor的元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力 softmax 后的注意力权重，用于计算自注意力头中的加权平均值。
ASTModel 的 forward 方法，重写了 __call__ 特殊方法。
尽管前向传播的逻辑需要在此函数中定义，但之后应该调用 Module 实例而不是这个函数，因为前者会处理前后处理步骤，而后者会静默地忽略它们。
ASTForAudioClassification
class transformers.ASTForAudioClassification
< 源代码 >( config: ASTConfig )
参数
- config (ASTConfig) — 包含模型所有参数的模型配置类。使用配置文件进行初始化不会加载与模型相关的权重，只会加载配置。请查看 from_pretrained() 方法来加载模型权重。
音频频谱图 Transformer 模型，顶部带有一个音频分类头（在池化输出之上加一个线性层），例如用于像 AudioSet、Speech Commands v2 这样的数据集。
该模型继承自 PreTrainedModel。请查看超类文档，了解库为所有模型实现的通用方法（如下载或保存、调整输入嵌入大小、修剪头部等）。
该模型也是一个 PyTorch torch.nn.Module 子类。可以像常规 PyTorch 模块一样使用它，并参考 PyTorch 文档了解所有与通用用法和行为相关的事项。
forward
< 源代码 >( input_values: typing.Optional[torch.Tensor] = None head_mask: typing.Optional[torch.Tensor] = None labels: typing.Optional[torch.Tensor] = None output_attentions: typing.Optional[bool] = None output_hidden_states: typing.Optional[bool] = None return_dict: typing.Optional[bool] = None ) → transformers.modeling_outputs.SequenceClassifierOutput 或 tuple(torch.FloatTensor)
参数
- input_values (
torch.FloatTensor，形状为(batch_size, max_length, num_mel_bins)) — 从原始音频波形中提取的浮点值梅尔特征。原始音频波形可以通过将.flac或.wav音频文件加载到list[float]或numpy.ndarray类型的数组中获得，例如，通过 soundfile 库（pip install soundfile）。为了将数组准备成input_features，应使用 AutoFeatureExtractor 来提取梅尔特征、进行填充并转换为torch.FloatTensor类型的张量。请参阅 call() - head_mask (
torch.Tensor，形状为(num_heads,)或(num_layers, num_heads)，可选) — 用于使自注意力模块中选定的头无效的掩码。掩码值的取值范围为[0, 1]：- 1 表示该头未被掩码，
- 0 表示该头已被掩码。
- labels (
torch.LongTensor，形状为(batch_size,)，可选) — 用于计算音频分类/回归损失的标签。索引应在[0, ..., config.num_labels - 1]范围内。如果config.num_labels == 1，则计算回归损失（均方损失），如果config.num_labels > 1，则计算分类损失（交叉熵）。 - output_attentions (
bool, 可选) — 是否返回所有注意力层的注意力张量。更多详情请参阅返回张量下的attentions。 - output_hidden_states (
bool, 可选) — 是否返回所有层的隐藏状态。更多详情请参阅返回张量下的hidden_states。 - return_dict (
bool, 可选) — 是返回一个 ModelOutput 而不是一个普通的元组。
返回
transformers.modeling_outputs.SequenceClassifierOutput 或 tuple(torch.FloatTensor)
一个 transformers.modeling_outputs.SequenceClassifierOutput 或一个 torch.FloatTensor 的元组（如果传入 return_dict=False 或 config.return_dict=False），包含根据配置（ASTConfig）和输入而变化的不同元素。
-
loss (形状为
(1,)的torch.FloatTensor，可选，当提供labels时返回) — 分类损失（如果 config.num_labels==1，则为回归损失）。 -
logits (形状为
(batch_size, config.num_labels)的torch.FloatTensor) — 分类（如果 config.num_labels==1，则为回归）分数（SoftMax 之前）。 -
hidden_states (
tuple(torch.FloatTensor), 可选, 当传入output_hidden_states=True或config.output_hidden_states=True时返回) —torch.FloatTensor的元组（如果模型有嵌入层，则一个是嵌入层的输出，另外每个层各有一个输出），形状为(batch_size, sequence_length, hidden_size)。模型在每个层输出的隐藏状态以及可选的初始嵌入输出。
-
attentions (
tuple(torch.FloatTensor), 可选, 当传入output_attentions=True或config.output_attentions=True时返回) —torch.FloatTensor的元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力 softmax 后的注意力权重，用于计算自注意力头中的加权平均值。
ASTForAudioClassification 的 forward 方法，重写了 __call__ 特殊方法。
尽管前向传播的逻辑需要在此函数中定义，但之后应该调用 Module 实例而不是这个函数，因为前者会处理前后处理步骤，而后者会静默地忽略它们。
示例
>>> from transformers import AutoFeatureExtractor, ASTForAudioClassification
>>> from datasets import load_dataset
>>> import torch
>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_demo", "clean", split="validation")
>>> dataset = dataset.sort("id")
>>> sampling_rate = dataset.features["audio"].sampling_rate
>>> feature_extractor = AutoFeatureExtractor.from_pretrained("MIT/ast-finetuned-audioset-10-10-0.4593")
>>> model = ASTForAudioClassification.from_pretrained("MIT/ast-finetuned-audioset-10-10-0.4593")
>>> # audio file is decoded on the fly
>>> inputs = feature_extractor(dataset[0]["audio"]["array"], sampling_rate=sampling_rate, return_tensors="pt")
>>> with torch.no_grad():
... logits = model(**inputs).logits
>>> predicted_class_ids = torch.argmax(logits, dim=-1).item()
>>> predicted_label = model.config.id2label[predicted_class_ids]
>>> predicted_label
...
>>> # compute loss - target_label is e.g. "down"
>>> target_label = model.config.id2label[0]
>>> inputs["labels"] = torch.tensor([model.config.label2id[target_label]])
>>> loss = model(**inputs).loss
>>> round(loss.item(), 2)
...