Transformers documentation
音频频谱图 Transformer
该模型于 2021-04-05 在 HF papers 上发布,并于 2022-11-21 贡献至 Hugging Face Transformers。
音频频谱图 Transformer
概述
Audio Spectrogram Transformer 模型由 Yuan Gong、Yu-An Chung 和 James Glass 在 AST: Audio Spectrogram Transformer 中提出。 Audio Spectrogram Transformer 将 Vision Transformer 应用于音频,其方法是将音频转换为图像(频谱图)。该模型在音频分类任务上取得了最先进的结果。
该论文的摘要如下:
在过去十年中,卷积神经网络(CNN)被广泛用作端到端音频分类模型的主要构建模块,其目标是从音频频谱图到相应标签学习直接映射。为了更好地捕获长距离全局上下文,近期的趋势是在 CNN 之上添加自注意力机制,从而形成 CNN-注意力混合模型。然而,尚不清楚对 CNN 的依赖是否必要,以及纯基于注意力的神经网络是否足以在音频分类中取得良好的性能。在本文中,我们通过引入 Audio Spectrogram Transformer (AST) 来回答这个问题,这是首个用于音频分类的无卷积、纯基于注意力的模型。我们在各种音频分类基准上评估了 AST,并取得了新的最先进结果:在 AudioSet 上达到 0.485 mAP,在 ESC-50 上达到 95.6% 的准确率,在 Speech Commands V2 上达到 98.1% 的准确率。
Audio Spectrogram Transformer architecture. Taken from the original paper. 使用技巧
- 在针对自己的数据集微调 Audio Spectrogram Transformer (AST) 时,建议自行处理输入归一化(以确保输入的均值为 0,标准差为 0.5)。ASTFeatureExtractor 会处理此步骤。请注意,它默认使用 AudioSet 的均值和标准差。您可以查看
ast/src/get_norm_stats.py来了解作者如何为下游数据集计算这些统计量。 - 请注意,AST 需要较低的学习率(作者使用的学习率比其在 PSLA 论文 中提出的 CNN 模型小 10 倍),并且收敛速度很快,因此请为您的任务搜索合适的学习率和学习率调度器。
使用缩放点积注意力(SDPA)
PyTorch 在 torch.nn.functional 中包含了原生的缩放点积注意力(SDPA)算子。该函数涵盖了多种实现方式,可根据输入和所用硬件进行应用。有关更多信息,请参阅官方文档或GPU 推理页面。
当存在可用实现时,torch>=2.1.1 默认使用 SDPA,但您也可以在 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", device_map="auto")
...为了获得最佳加速效果,我们建议以半精度(例如 torch.float16 或 torch.bfloat16)加载模型。
在本地基准测试(A100-40GB、PyTorch 2.3.0、操作系统 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 官方和社区(以 🌎 标识)的资源列表,帮助你快速上手 Audio Spectrogram Transformer。
- 此处提供了一个演示如何使用 AST 进行音频分类推理的笔记本。
- ASTForAudioClassification 受此 notebook 支持。
- 另请参阅:音频分类。
如果您有兴趣提交资源以收录在此处,请随时发起 Pull Request,我们将对其进行审核!理想情况下,该资源应展示一些新内容,而不是重复现有资源。
ASTConfig
class transformers.ASTConfig
< 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 = Nonehidden_size: int = 768num_hidden_layers: int = 12num_attention_heads: int = 12intermediate_size: int = 3072hidden_act: str = 'gelu'hidden_dropout_prob: float | int = 0.0attention_probs_dropout_prob: float | int = 0.0initializer_range: float = 0.02layer_norm_eps: float = 1e-12patch_size: int | list[int] | tuple[int, int] = 16qkv_bias: bool = Truefrequency_stride: int = 10time_stride: int = 10max_length: int = 1024num_mel_bins: int = 128 )
参数
- hidden_size (
int,可选,默认为768) — 隐藏表示的维度。 - num_hidden_layers (
int, 可选, 默认为12) — Transformer 解码器中的隐藏层数量。 - num_attention_heads (
int,可选,默认为12) — Transformer 解码器中每个注意力层的注意力头数量。 - intermediate_size (
int,可选,默认为3072) — MLP 表示的维度。 - hidden_act (
str,可选,默认为gelu) — 解码器中的非线性激活函数(函数或字符串)。例如,"gelu"、"relu"、"silu"等。 - hidden_dropout_prob (
Union[float, int],可选,默认为0.0) — 嵌入层、编码器和池化层中所有全连接层的 dropout 概率。 - attention_probs_dropout_prob (
Union[float, int],可选,默认为0.0) — 注意力概率的 dropout 比率。 - initializer_range (
float,可选,默认为0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。 - layer_norm_eps (
float,可选,默认为1e-12) — 层归一化层所使用的 epsilon 值。 - patch_size (
Union[int, list[int], tuple[int, int]],可选,默认为16) — 每个 patch 的大小(分辨率)。 - qkv_bias (
bool,可选,默认为True) — 是否向查询、键和值添加偏置。 - frequency_stride (
int,可选,默认为 10) — 在对频谱图进行分块(patchify)时使用的频率步长。 - time_stride (
int,可选,默认为 10) — 在对频谱图进行分块(patchify)时使用的时序步长。 - max_length (
int,可选,默认为 1024) — 频谱图的时间维度。 - num_mel_bins (
int, 可选,默认为128) — 每个输入帧使用的 mel 特征数量。应与AutoFeatureExtractor类中使用的值相对应。
这是用于存储 Audio Spectrogram Transformer 模型配置的类。它根据指定的参数实例化 Audio Spectrogram Transformer 模型,并定义模型架构。使用默认值实例化配置将得到与 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 = 1sampling_rate = 16000num_mel_bins = 128max_length = 1024padding_value = 0.0do_normalize = Truemean = -4.2677393std = 4.5689974return_attention_mask = False**kwargs )
参数
- feature_size (
int,可选,默认为 1) — 提取特征的维度。 - sampling_rate (
int,可选,默认为 16000) — 音频文件应被数字化时的采样率,以赫兹 (Hz) 为单位。 - num_mel_bins (
int,可选,默认为 128) — Mel 频率带的数量。 - max_length (
int,可选,默认为 1024) — 提取特征进行填充/截断的最大长度。 - do_normalize (
bool,可选,默认为True) — 是否使用mean和std对 log-Mel 特征进行归一化。 - mean (
float, 可选,默认值为 -4.2677393) — 用于归一化 log-Mel 特征的均值。默认使用 AudioSet 的均值。 - std (
float,可选,默认值为 4.5689974) — 用于归一化 log-Mel 特征的标准差值。默认使用 AudioSet 的标准差。 - return_attention_mask (
bool,可选,默认为False) — 是否让 call() 返回attention_mask。
构建一个 Audio Spectrogram Transformer (AST) 特征提取器。
该特征提取器继承自 SequenceFeatureExtractor,其中包含了大部分主要方法。用户应参考该父类以获取有关这些方法的更多信息。
如果已安装 TorchAudio,此类将使用 TorchAudio 从原始语音中提取 mel 滤波器组特征,否则使用 numpy;随后将其填充或截断至固定长度,并使用均值和标准差进行归一化。
__call__
< source >( raw_speech: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]]sampling_rate: int | None = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = None**kwargs )
参数
- raw_speech (
np.ndarray、list[float]、list[np.ndarray]、list[list[float]]) — 需要填充的序列或序列批次。每个序列可以是 numpy 数组、浮点值列表、numpy 数组列表或浮点值列表的列表。必须是单声道音频,而非立体声,即每个时间步对应一个浮点数。 - sampling_rate (
int, 可选) —raw_speech输入所使用的采样率。强烈建议在 forward 调用时传入sampling_rate,以避免静默错误。 - return_tensors (
str或 TensorType, 可选) — 如果设置,将返回张量而不是 Python 整数列表。可接受的值为:'pt':返回 PyTorchtorch.Tensor对象。'np':返回 Numpynp.ndarray对象。
用于对一条或多条序列进行特征化并准备输入模型的主要方法。
ASTModel
class transformers.ASTModel
< source >( config: ASTConfig )
参数
- config (ASTConfig) — 模型的配置类,包含模型的所有参数。使用配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
未添加任何特定头部的裸 Audio Spectrogram Transformer 模型,输出原始隐藏状态。
该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。
forward
< source >( input_values: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
参数
- input_values (
torch.Tensor,形状为(batch_size, max_length, num_mel_bins)) — 从原始音频波形中提取的浮点型 mel 特征。原始音频波形可通过将.flac或.wav音频文件加载为list[float]、numpy.ndarray或torch.Tensor类型的数组获得,例如 使用 torchcodec 库(pip install torchcodec)或 soundfile 库(pip install soundfile)。 要将该数组处理为input_features,应使用 AutoFeatureExtractor 来提取 mel 特征、进行填充并转换为torch.Tensor类型的张量。 参见 call() - attention_mask (
torch.Tensor形状为(batch_size, sequence_length), ,可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自[0, 1]:- 1 表示未被屏蔽的 token,
- 对于被掩码的 token,值为 0。
返回值
BaseModelOutputWithPooling 或 tuple(torch.Tensor)
一个 BaseModelOutputWithPooling 或 torch.Tensor 元组(如果传入了 return_dict=False 或 config.return_dict=False),其包含的元素取决于配置(ASTConfig)和输入。
ASTModel 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义,但之后应调用
Module实例,而不是直接调用此函数,因为前者会负责执行预处理和后处理步骤,而后者则会静默地忽略这些步骤。
last_hidden_state(形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor)— 模型最后一层输出的隐藏状态序列。pooler_output (
torch.Tensor,形状为(batch_size, hidden_size)) — 序列中第一个 token(分类 token)的最后一层隐藏状态,经过用于辅助预训练任务的层进一步处理后得到。例如,对于 BERT 系列模型,这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测(分类)目标进行训练。hidden_states (
tuple(torch.Tensor),可选,当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组(如果模型具有嵌入层,则包含嵌入层的输出,以及每一层的输出),形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态,以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor),可选,当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组(每层一个),形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重,即经过注意力 softmax 之后的权重,用于在自注意力头中计算加权平均值。
ASTForAudioClassification
class transformers.ASTForAudioClassification
< source >( config: ASTConfig )
参数
- config (ASTConfig) — 模型的配置类,包含模型的所有参数。使用配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
带有音频分类头(在池化输出之上添加一个线性层)的 Audio Spectrogram Transformer 模型,例如用于 AudioSet、Speech Commands v2 等数据集。
该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。
forward
< source >( input_values: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → SequenceClassifierOutput or tuple(torch.Tensor)
参数
- input_values (
torch.Tensor,形状为(batch_size, max_length, num_mel_bins)) — 从原始音频波形中提取的浮点型 mel 特征。原始音频波形可通过将.flac或.wav音频文件加载为list[float]、numpy.ndarray或torch.Tensor类型的数组获得,例如 使用 torchcodec 库(pip install torchcodec)或 soundfile 库(pip install soundfile)。 要将该数组处理为input_features,应使用 AutoFeatureExtractor 来提取 mel 特征、进行填充并转换为torch.Tensor类型的张量。 参见 call() - labels(形状为
(batch_size,)的torch.LongTensor,可选) — 用于计算音频分类/回归损失的标签。索引应在[0, ..., config.num_labels - 1]范围内。如果config.num_labels == 1,则计算回归损失(均方损失);如果config.num_labels > 1,则计算分类损失(交叉熵)。 - attention_mask (
torch.Tensor形状为(batch_size, sequence_length), ,可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自[0, 1]:- 1 表示未被屏蔽的 token,
- 对于被掩码的 token,值为 0。
返回值
SequenceClassifierOutput 或 tuple(torch.Tensor)
一个 SequenceClassifierOutput 或 torch.Tensor 元组(如果传入了 return_dict=False 或 config.return_dict=False),其包含的元素取决于配置(ASTConfig)和输入。
ASTForAudioClassification 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义,但之后应调用
Module实例,而不是直接调用此函数,因为前者会负责执行预处理和后处理步骤,而后者则会静默地忽略这些步骤。
loss (
torch.Tensor,形状为(1,),可选,当提供labels时返回) — 分类损失(如果 config.num_labels==1,则为回归损失)。logits(形状为
(batch_size, config.num_labels)的torch.Tensor)— 分类(或当 config.num_labels==1 时为回归)得分(SoftMax 之前)。hidden_states (
tuple(torch.Tensor),可选,当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组(如果模型具有嵌入层,则包含嵌入层的输出,以及每一层的输出),形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态,以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor),可选,当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组(每层一个),形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重,即经过注意力 softmax 之后的权重,用于在自注意力头中计算加权平均值。
示例:
>>> 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)
...