Transformers documentation

音频频谱图 Transformer

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

该模型于 2021-04-05 在 HF papers 上发布,并于 2022-11-21 贡献至 Hugging Face Transformers。

音频频谱图 Transformer

FlashAttention SDPA

概述

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% 的准确率。

drawing Audio Spectrogram Transformer architecture. Taken from the original paper.

该模型由 nielsr 贡献。 原始代码可在此处找到。

使用技巧

  • 在针对自己的数据集微调 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)
12764.5
21262
42182.62
840142.86

资源

一份来自 Hugging Face 官方和社区(以 🌎 标识)的资源列表,帮助你快速上手 Audio Spectrogram Transformer。

Audio Classification

如果您有兴趣提交资源以收录在此处,请随时发起 Pull Request,我们将对其进行审核!理想情况下,该资源应展示一些新内容,而不是重复现有资源。

ASTConfig

class transformers.ASTConfig

< >

( 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.config

ASTFeatureExtractor

class transformers.ASTFeatureExtractor

< >

( 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__

< >

( 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':返回 PyTorch torch.Tensor 对象。
    • 'np':返回 Numpy np.ndarray 对象。

用于对一条或多条序列进行特征化并准备输入模型的主要方法。

ASTModel

class transformers.ASTModel

< >

( config: ASTConfig )

参数

  • config (ASTConfig) — 模型的配置类,包含模型的所有参数。使用配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

未添加任何特定头部的裸 Audio Spectrogram Transformer 模型,输出原始隐藏状态。

该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。

forward

< >

( 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

< >

( config: ASTConfig )

参数

  • config (ASTConfig) — 模型的配置类,包含模型的所有参数。使用配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

带有音频分类头(在池化输出之上添加一个线性层)的 Audio Spectrogram Transformer 模型,例如用于 AudioSet、Speech Commands v2 等数据集。

该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。

forward

< >

( 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)
...
Update on GitHub