# 特征提取器

特征提取器（Feature extractor）会将音频数据预处理为特定模型所需的正确格式。它接收原始音频信号，并将其转换为可供模型使用的张量。张量的形状取决于模型，但只要你指定了所使用的模型，特征提取器就会为你正确预处理音频数据。特征提取器还包含用于填充（padding）、截断（truncation）和重采样（resampling）的方法。

调用 [from_pretrained()](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoFeatureExtractor.from_pretrained) 从 Hugging Face [Hub](https://hf.co/models) 或本地目录加载特征提取器及其预处理器配置。特征提取器和预处理器配置保存在 [preprocessor_config.json](https://hf.co/openai/whisper-tiny/blob/main/preprocessor_config.json) 文件中。

将音频信号（通常存储在 `array` 中）传入特征提取器，并将 `sampling_rate` 参数设置为预训练音频模型的采样率。音频数据的采样率必须与预训练音频模型训练时所用数据的采样率一致，这一点非常重要。

```py
from transformers import AutoFeatureExtractor

feature_extractor = AutoFeatureExtractor.from_pretrained("facebook/wav2vec2-base")
dataset = load_dataset("PolyAI/minds14", name="en-US", split="train")
processed_sample = feature_extractor(dataset[0]["audio"]["array"], sampling_rate=16000)
processed_sample
{'input_values': [array([ 9.4472744e-05,  3.0777880e-03, -2.8888427e-03, ...,
       -2.8888427e-03,  9.4472744e-05,  9.4472744e-05], dtype=float32)]}
```

特征提取器返回一个可直接供模型使用的输入 `input_values`。

本指南将带您了解特征提取器类以及如何对音频数据进行预处理。

## 特征提取器类

Transformers 中的特征提取器继承自基类 [SequenceFeatureExtractor](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor)，而该类又继承自 [FeatureExtractionMixin](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.FeatureExtractionMixin)。

- [SequenceFeatureExtractor](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor) 提供了一个 [pad()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor.pad) 方法，用于将序列填充到指定长度，以避免序列长度不一致。
- [FeatureExtractionMixin](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.FeatureExtractionMixin) 提供了 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.FeatureExtractionMixin.from_pretrained) 和 [save_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.FeatureExtractionMixin.save_pretrained) 方法，用于加载和保存特征提取器。

加载特征提取器有两种方式：[AutoFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoFeatureExtractor) 和特定于模型的特征提取器类。

[AutoClass](./model_doc/auto) API 会自动为指定模型加载正确的特征提取器。

使用 [from_pretrained()](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoFeatureExtractor.from_pretrained) 加载特征提取器。

```py
from transformers import AutoFeatureExtractor

feature_extractor = AutoFeatureExtractor.from_pretrained("openai/whisper-tiny")
```

每个预训练音频模型都有一个特定的特征提取器，用于正确地对音频数据进行处理。加载特征提取器时，它会从 [preprocessor_config.json](https://hf.co/openai/whisper-tiny/blob/main/preprocessor_config.json) 中获取特征提取器的配置（特征大小、块长度等）。

特征提取器可以直接从其模型特定的类中加载。

```py
from transformers import WhisperFeatureExtractor

feature_extractor = WhisperFeatureExtractor.from_pretrained("openai/whisper-tiny")
```

## 预处理

特征提取器期望输入为特定形状的 PyTorch 张量。具体的输入形状可能因所使用的特定音频模型而异。

例如，[Whisper](./model_doc/whisper) 要求 `input_features` 是一个形状为 `(batch_size, feature_size, sequence_length)` 的张量，而 [Wav2Vec2](https://hf.co/docs/transformers/model_doc/wav2vec2) 要求 `input_values` 是一个形状为 `(batch_size, sequence_length)` 的张量。

特征提取器会为您所使用的任何音频模型生成正确的输入形状。

特征提取器还会设置音频文件的采样率（即每秒采集的音频信号值数量）。您的音频数据的采样率必须与预训练模型所训练的数据集的采样率相匹配。该值通常在模型卡片中给出。

使用 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.FeatureExtractionMixin.from_pretrained) 加载数据集和特征提取器。

```py
from datasets import load_dataset, Audio
from transformers import AutoFeatureExtractor

dataset = load_dataset("PolyAI/minds14", name="en-US", split="train")
feature_extractor = AutoFeatureExtractor.from_pretrained("facebook/wav2vec2-base")
```

查看数据集中的第一个示例，并访问包含`array`（原始音频信号）的`audio`列。

```py
dataset[0]["audio"]["array"]
array([ 0.        ,  0.00024414, -0.00024414, ..., -0.00024414,
        0.        ,  0.        ])
```

特征提取器会将 `array` 预处理为给定音频模型所需的输入格式。请使用 `sampling_rate` 参数设置合适的采样率。

```py
processed_dataset = feature_extractor(dataset[0]["audio"]["array"], sampling_rate=16000)
processed_dataset
{'input_values': [array([ 9.4472744e-05,  3.0777880e-03, -2.8888427e-03, ...,
       -2.8888427e-03,  9.4472744e-05,  9.4472744e-05], dtype=float32)]}
```

### 填充

音频序列长度不一致是一个问题，因为 Transformers 要求所有序列具有相同的长度才能进行批处理。长度不等的序列无法进行批处理。

```py
dataset[0]["audio"]["array"].shape
(86699,)

dataset[1]["audio"]["array"].shape
(53248,)
```

填充操作会添加一个特殊的 *padding token*，以确保所有序列具有相同的长度。特征提取器会向 `array` 中添加 `0`（解释为静音）来进行填充。设置 `padding=True` 可将序列填充至批次中最长序列的长度。

```py
def preprocess_function(examples):
    audio_arrays = [x["array"] for x in examples["audio"]]
    inputs = feature_extractor(
        audio_arrays,
        sampling_rate=16000,
        padding=True,
    )
    return inputs

processed_dataset = preprocess_function(dataset[:5])
processed_dataset["input_values"][0].shape
(86699,)

processed_dataset["input_values"][1].shape
(86699,)
```

### 截断

模型只能处理一定长度以内的序列，否则就会崩溃。

截断是一种用于移除序列中多余 token 的策略，以确保其不超过最大长度。设置 `truncation=True` 可将序列截断至 `max_length` 参数指定的长度。

```py
def preprocess_function(examples):
    audio_arrays = [x["array"] for x in examples["audio"]]
    inputs = feature_extractor(
        audio_arrays,
        sampling_rate=16000,
        max_length=50000,
        truncation=True,
    )
    return inputs

processed_dataset = preprocess_function(dataset[:5])
processed_dataset["input_values"][0].shape
(50000,)

processed_dataset["input_values"][1].shape
(50000,)
```

### 重采样

[Datasets](https://hf.co/docs/datasets/index) 库还可以对音频数据进行重采样，以匹配音频模型所需的采样率。该方法在加载音频数据时即时进行重采样，这比对整个数据集进行原地重采样可能更快。

您一直在处理的音频数据集的采样率为 8kHz，而预训练模型期望的采样率为 16kHz。

```py
dataset[0]["audio"]
{'path': '/root/.cache/huggingface/datasets/downloads/extracted/f507fdca7f475d961f5bb7093bcc9d544f16f8cab8608e772a2ed4fbeb4d6f50/en-US~JOINT_ACCOUNT/602ba55abb1e6d0fbce92065.wav',
 'array': array([ 0.        ,  0.00024414, -0.00024414, ..., -0.00024414,
         0.        ,  0.        ]),
 'sampling_rate': 8000}
```

对 `audio` 列调用 [cast_column](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset.cast_column)，将采样率上采样至 16kHz。

```py
dataset = dataset.cast_column("audio", Audio(sampling_rate=16000))
```

加载数据集样本时，它现在会被重采样为 16kHz。

```py
dataset[0]["audio"]
{'path': '/root/.cache/huggingface/datasets/downloads/extracted/f507fdca7f475d961f5bb7093bcc9d544f16f8cab8608e772a2ed4fbeb4d6f50/en-US~JOINT_ACCOUNT/602ba55abb1e6d0fbce92065.wav',
 'array': array([ 1.70562416e-05,  2.18727451e-04,  2.28099874e-04, ...,
         3.43842403e-05, -5.96364771e-06, -1.76846661e-05]),
 'sampling_rate': 16000}
```

