Transformers 4.37 中文文档（一百）（1）https://developer.aliyun.com/article/1565785
特征提取器的实用程序
原文：
huggingface.co/docs/transformers/v4.37.2/en/internal/audio_utils
此页面列出了所有可以被音频 FeatureExtractor 使用的实用函数，以便使用常见算法（如 短时傅里叶变换 或 对数梅尔频谱图）从原始音频中计算特殊特征。
大多数情况下，这些只有在研究库中音频处理器的代码时才有用。
音频转换
transformers.audio_utils.hertz_to_mel
( freq: Union mel_scale: str = 'htk' ) → export const metadata = 'undefined';float or np.ndarray
参数
freq(float或np.ndarray) — 要转换的频率，或多个频率，单位为赫兹（Hz）。mel_scale(str, 可选, 默认为"htk") — 要使用的梅尔频率刻度，"htk"、"kaldi"或"slaney"。
返回
float 或 np.ndarray
梅尔刻度上的频率。
将频率从赫兹转换为梅尔。
transformers.audio_utils.mel_to_hertz
( mels: Union mel_scale: str = 'htk' ) → export const metadata = 'undefined';float or np.ndarray
参数
mels(float或np.ndarray) — 要转换的频率，或多个频率，单位为梅尔。mel_scale(str, 可选,"htk") — 要使用的梅尔频率刻度，"htk"、"kaldi"或"slaney"。
返回
float 或 np.ndarray
赫兹频率。
将频率从梅尔转换为赫兹。
transformers.audio_utils.mel_filter_bank
( num_frequency_bins: int num_mel_filters: int min_frequency: float max_frequency: float sampling_rate: int norm: Optional = None mel_scale: str = 'htk' triangularize_in_mel_space: bool = False ) → export const metadata = 'undefined';np.ndarray of shape (num_frequency_bins, num_mel_filters)
参数
num_frequency_bins(int) — 用于计算频谱图的频率数量（应与stft中的相同）。num_mel_filters(int) — 要生成的梅尔滤波器数量。min_frequency(float) — 感兴趣的最低频率，单位为赫兹。max_frequency(float) — 感兴趣的最高频率，单位为赫兹。不应超过sampling_rate / 2。sampling_rate(int) — 音频波形的采样率。norm(str, 可选) — 如果为"slaney"，则通过梅尔带宽的宽度来除以三角形梅尔权重（面积归一化）。mel_scale(str, 可选, 默认为"htk") — 要使用的梅尔频率刻度，"htk"、"kaldi"或"slaney"。triangularize_in_mel_space(bool, 可选, 默认为False) — 如果启用此选项，则三角形滤波器将在梅尔空间而不是频率空间中应用。为了获得与计算梅尔滤波器时torchaudio相同的结果，应将此设置为true。
返回
形状为 (num_frequency_bins, num_mel_filters) 的 np.ndarray
三角形滤波器组矩阵。这是一个投影矩阵，用于从频谱图到梅尔频谱图的转换。
创建用于获取梅尔频谱图的频率箱转换矩阵。这称为 梅尔滤波器组，存在各种实现，这些实现在滤波器数量、滤波器形状、滤波器间距、滤波器带宽以及频谱变形方式上有所不同。这些特征的目标是近似人类对频率变化的非线性感知。
文献中引入了不同的梅尔滤波器组。支持以下变体：
- MFCC FB-20: 由 Davis 和 Mermelstein 于 1980 年提出，假设采样频率为 10 kHz，语音带宽为
[0, 4600]Hz。 - MFCC FB-24 HTK: 来自剑桥 HMM 工具包（HTK）（1995 年），使用 24 个滤波器的滤波器组，语音带宽为
[0, 8000]Hz。假设采样率 ≥ 16 kHz。 - MFCC FB-40: 由 Slaney 于 1998 年编写的 MATLAB 听觉工具箱，假设采样率为 16 kHz，语音带宽为
[133, 6854]Hz。此版本还包括面积归一化。 - Skowronski 和 Harris（2004）的 HFCC-E FB-29（人类因素倒谱系数），假设采样率为 12.5 kHz，语音带宽为
[0, 6250]Hz。
此代码改编自torchaudio和librosa。请注意，torchaudio 的melscale_fbanks的默认参数实现了"htk"滤波器，而 librosa 使用"slaney"实现。
transformers.audio_utils.optimal_fft_length
( window_length: int )
找到给定window_length的最佳 FFT 输入大小。此函数接受给定的窗口长度，如果不是 2 的幂，则将其四舍五入到下一个 2 的幂。
FFT 算法在输入长度为 2 的幂时运行最快，这可能比窗口或分析帧的大小更大。例如，如果窗口是 400 个样本，使用 512 个样本的 FFT 输入大小比 400 个样本的 FFT 大小更优。使用更大的 FFT 大小不会影响检测到的频率，它只是提供了更高的频率分辨率（即频率箱更小）。
transformers.audio_utils.window_function
( window_length: int name: str = 'hann' periodic: bool = True frame_length: Optional = None center: bool = True )
参数
window_length（int）- 窗口的长度（以样本为单位）。name（str，可选，默认为"hann"）- 窗口函数的名称。periodic（bool，可选，默认为True）- 窗口是否周期性或对称。frame_length（int，可选）- 分析帧的长度（以样本为单位）。如果窗口比帧长度小，请为frame_length提供一个值，以便进行零填充。center（bool，可选，默认为True）- 是否将窗口居中在 FFT 缓冲区内。仅在提供frame_length时使用。
返回一个包含指定窗口的数组。这个窗口旨在与stft一起使用。
支持以下窗口类型：
"boxcar"：一个矩形窗口"hamming"：汉明窗口"hann"：汉宁窗口"povey"：波维窗口
transformers.audio_utils.spectrogram
( waveform: ndarray window: ndarray frame_length: int hop_length: int fft_length: Optional = None power: Optional = 1.0 center: bool = True pad_mode: str = 'reflect' onesided: bool = True preemphasis: Optional = None mel_filters: Optional = None mel_floor: float = 1e-10 log_mel: Optional = None reference: float = 1.0 min_value: float = 1e-10 db_range: Optional = None remove_dc_offset: Optional = None dtype: dtype = <class 'numpy.float32'> )
参数
waveform（形状为(length,)的np.ndarray）- 输入波形。这必须是单声道的实值波形。window（形状为(frame_length,)的np.ndarray）- 要应用的窗函数，包括必要时的零填充。实际窗口长度可能比frame_length短，但我们假设数组已经被零填充。frame_length（int）- 分析帧的长度（以样本为单位）。在 librosa 中，这总是等于fft_length，但我们也允许更小的尺寸。hop_length（int）- 分析帧之间的连续跨度（以样本为单位）。fft_length（int，可选）- FFT 缓冲区的大小（以样本为单位）。这决定了频谱图将具有多少频率箱。为了获得最佳速度，这应该是 2 的幂。如果为None，则使用frame_length。power（float，可选，默认为 1.0）- 如果为 1.0，则返回幅度谱图。如果为 2.0，则返回功率谱图。如果为None，则返回复数。center（bool，可选，默认为True）- 是否填充波形，使得帧t围绕时间t * hop_length居中。如果为False，帧t将从时间t * hop_length开始。pad_mode（str，可选，默认为"reflect"）- 当center为True时使用的填充模式。可能的值为："constant"（用零填充）、"edge"（用边缘值填充）、"reflect"（用镜像值填充）。onesided（bool，可选，默认为True）- 如果为 True，则仅计算正频率并返回包含fft_length // 2 + 1个频率箱的谱图。如果为 False，还会计算负频率并返回fft_length个频率箱。preemphasis(float, optional) — 在 DFT 之前应用预加重的低通滤波器的系数。mel_filters(np.ndarray，形状为(num_freq_bins, num_mel_filters)，optional) — 梅尔滤波器组。如果提供，将应用此滤波器组以创建梅尔频谱图。mel_floor(float, optional，默认为 1e-10) — 梅尔频率组的最小值。log_mel(str, optional) — 如何将频谱图转换为对数刻度。可能的选项有：None（不转换），"log"（取自然对数）"log10"（取以 10 为底的对数），"dB"（转换为分贝）。只能在power不为None时使用。reference(float, optional，默认为 1.0) — 设置对应于 0 dB 的输入频谱图值。例如，使用np.max(spectrogram)将最响亮的部分设置为 0 dB。必须大于零。min_value(float, optional，默认为1e-10) — 在转换为分贝之前，将频谱图剪切到此最小值，以避免取log(0)。对于功率频谱图，默认值1e-10对应于-100 dB。对于振幅频谱图，值1e-5对应于-100 dB。必须大于零。db_range(float, optional) — 设置分贝中的最大动态范围。例如，如果db_range = 80，峰值和最小值之间的差异永远不会超过 80 dB。必须大于零。remove_dc_offset(bool, optional) — 从每个帧的波形中减去均值，在预加重之前应用。为了在计算梅尔滤波器时获得与torchaudio.compliance.kaldi.fbank相同的结果，应将其设置为true。dtype(np.dtype, optional，默认为np.float32) — 频谱图张量的数据类型。如果power为 None，则忽略此参数，数据类型将为np.complex64。
使用短时傅里叶变换计算一个波形的频谱图。
此函数可以创建以下类型的频谱图：
- 振幅频谱图（
power = 1.0） - 功率频谱图（
power = 2.0） - 复数值频谱图（
power = None） - 对数频谱图（使用
log_mel参数） - 梅尔频谱图（提供
mel_filters） - 对数梅尔频谱图（提供
mel_filters和log_mel）
工作原理：
- 输入波形被分割成大小为
frame_length的帧，这些帧部分重叠了frame_length个样本。
hop_length个样本。
- 每个帧都乘以窗口，并放入大小为
fft_length的缓冲区中。 - 对每个窗口帧进行 DFT。
- 结果被堆叠成一个频谱图。
我们区分以下“块”样本数据，每个样本数据可能具有不同的长度：
- 分析帧。这是将输入波形分割成的时间片段的大小。
- 窗口。每个分析帧都乘以窗口以避免频谱泄漏。
- FFT 输入缓冲区。其长度决定了频谱图中有多少频率箱。
在此实现中，假定窗口被零填充以具有与分析帧相同的大小。可以从window_function()获得填充的窗口。FFT 输入缓冲区可能比分析帧大，通常是下一个二的幂。
注意：此函数尚未针对速度进行优化。它应该与librosa.stft和torchaudio.functional.transforms.Spectrogram大部分兼容，尽管由于构建频谱图的不同方式，它更加灵活。
transformers.audio_utils.power_to_db
( spectrogram: ndarray reference: float = 1.0 min_value: float = 1e-10 db_range: Optional = None ) → export const metadata = 'undefined';np.ndarray
参数
spectrogram(np.ndarray) — 输入功率（梅尔）频谱图。请注意，功率频谱图的振幅已经平方！reference(float, optional，默认为 1.0) — 设置对应于 0 dB 的输入频谱图值。例如，使用np.max(spectrogram)将最响亮的部分设置为 0 dB。必须大于零。min_value(float, optional, 默认为1e-10) — 在转换为分贝之前，将频谱图剪切到此最小值，以避免取log(0)。默认值1e-10对应于最小值为-100 dB。必须大于零。db_range(float, optional) — 设置分贝的最大动态范围。例如，如果db_range = 80，峰值和最小值之间的差异永远不会超过 80 dB。必须大于零。
返回
np.ndarray
以分贝为单位的频谱图
将功率频谱图转换为分贝刻度。这使用基本对数属性计算10 * log10(spectrogram / reference)，以确保数值稳定性。
将对(mel)频谱图应用对数函数的动机是人类听不到响度的线性刻度。通常，要使声音的感知音量加倍，我们需要将 8 倍的能量投入其中。这意味着如果声音本来就很大，那么能量的大变化可能听起来并不那么不同。这种压缩操作使(mel)频谱图特征更接近人类实际听到的声音。
基于librosa.power_to_db的实现。
transformers.audio_utils.amplitude_to_db
( spectrogram: ndarray reference: float = 1.0 min_value: float = 1e-05 db_range: Optional = None ) → export const metadata = 'undefined';np.ndarray
参数
spectrogram(np.ndarray) — 输入振幅(mel)频谱图。reference(float, optional, 默认为 1.0) — 设置对应于 0 dB 的输入频谱图值。例如，使用np.max(spectrogram)将最响亮的部分设置为 0 dB。必须大于零。min_value(float, optional, 默认为1e-5) — 在转换为分贝之前，将频谱图剪切到此最小值，以避免取log(0)。默认值1e-5对应于最小值为-100 dB。必须大于零。db_range(float, optional) — 设置分贝的最大动态范围。例如，如果db_range = 80，峰值和最小值之间的差异永远不会超过 80 dB。必须大于零。
返回
np.ndarray
以分贝为单位的频谱图
将振幅频谱图转换为分贝刻度。这使用基本对数属性计算20 * log10(spectrogram / reference)，以确保数值稳定性。
将对(mel)频谱图应用对数函数的动机是人类听不到响度的线性刻度。通常，要使声音的感知音量加倍，我们需要将 8 倍的能量投入其中。这意味着如果声音本来就很大，那么能量的大变化可能听起来并不那么不同。这种压缩操作使(mel)频谱图特征更接近人类实际听到的声音。
通用实用程序
原始文本：
huggingface.co/docs/transformers/v4.37.2/en/internal/file_utils
此页面列出了在文件utils.py中找到的所有 Transformers 通用实用函数。
大多数情况下，这些只在研究库中的通用代码时才有用。
枚举和命名元组
class transformers.utils.ExplicitEnum
( value names = None module = None qualname = None type = None start = 1 )
具有更明确错误消息的枚举，用于缺少值。
class transformers.utils.PaddingStrategy
( value names = None module = None qualname = None type = None start = 1 )
[PreTrainedTokenizerBase.call()]中padding参数的可能值。在 IDE 中用于制表完成。
class transformers.TensorType
( value names = None module = None qualname = None type = None start = 1 )
[PreTrainedTokenizerBase.call()]中return_tensors参数的可能值。在 IDE 中用于制表完成。
特殊装饰器
transformers.add_start_docstrings
( *docstr )
transformers.utils.add_start_docstrings_to_model_forward
( *docstr )
transformers.add_end_docstrings
( *docstr )
transformers.utils.add_code_sample_docstrings
( *docstr processor_class = None checkpoint = None output_type = None config_class = None mask = '[MASK]' qa_target_start_index = 14 qa_target_end_index = 15 model_cls = None modality = None expected_output = None expected_loss = None real_checkpoint = None revision = None )
transformers.utils.replace_return_docstrings
( output_type = None config_class = None )
特殊属性
class transformers.utils.cached_property
( fget = None fset = None fdel = None doc = None )
模拟@property 但在成员变量中缓存输出的描述符。
来自 tensorflow_datasets
Python 3.8 中内置的 functools。
其他实用工具
class transformers.utils._LazyModule
( name module_file import_structure module_spec = None extra_objects = None )
模块类，展示所有对象，但仅在请求对象时执行相关导入。
时间序列工具
原始文本：
huggingface.co/docs/transformers/v4.37.2/en/internal/time_series_utils
此页面列出了所有可用于基于时间序列的模型的实用函数和类。
大多数情况下，这些只有在您研究时间序列模型的代码或者希望添加到分布输出类集合时才有用。
分布输出
class transformers.time_series_utils.NormalOutput
( dim: int = 1 )
正态分布输出类。
class transformers.time_series_utils.StudentTOutput
( dim: int = 1 )
学生 T 分布输出类。
class transformers.time_series_utils.NegativeBinomialOutput
( dim: int = 1 )
负二项分布输出类。
Transformers 4.37 中文文档（一百）（3）https://developer.aliyun.com/article/1565787
