# 特徴量抽出器

Feature extractorsは、指定されたモデルに適合する形式に音声データを前処理します。生の音声信号を受け取り、モデルに入力できるテンソルに変換します。テンソルの形状はモデルによって異なりますが、Feature extractorsは使用しているモデルに基づいて、音声データを正しく前処理してくれます。また、Feature extractorsには、パディング、切り詰め、リサンプリングのためのメソッドも含まれています。

[from_pretrained()](/docs/transformers/main/ja/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`を返します。

このガイドでは、フィーチャーエクストラクターのクラスと、オーディオデータの前処理方法について説明します。

## Feature extractorクラス

Transformers のフィーチャーエクストラクターは、[FeatureExtractionMixin](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.FeatureExtractionMixin) をサブクラスとするベースクラス [SequenceFeatureExtractor](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.SequenceFeatureExtractor) を継承しています。

- [SequenceFeatureExtractor](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.SequenceFeatureExtractor) は、シーケンスの長さが揃わないことを避けるために、シーケンスを特定の長さに[pad()](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.SequenceFeatureExtractor.pad)するメソッドを提供します。
- [FeatureExtractionMixin](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.FeatureExtractionMixin) は、フィーチャーエクストラクターの読み込みと保存のために [from_pretrained()](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.FeatureExtractionMixin.from_pretrained) および [save_pretrained()](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.FeatureExtractionMixin.save_pretrained) を提供します。

フィーチャーエクストラクターを読み込む方法には2つあります。[AutoFeatureExtractor](/docs/transformers/main/ja/model_doc/auto#transformers.AutoFeatureExtractor)と、モデル固有のフィーチャーエクストラクタークラスです。

[AutoClass](./model_doc/auto) API は、指定されたモデルに対応する正しいフィーチャーエクストラクターを自動的に読み込みます。

[from_pretrained()](/docs/transformers/main/ja/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")
```

## 前処理

feature extractorは、特定の形状の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)`の形状を持つテンソルであることを期待します。

feature extractorは、使用しているオーディオモデルに応じて、適切な入力形状を生成します。

feature extractorは、音声ファイルのサンプリングレート（1秒あたりに取得する音声シグナルの値の個数）も設定します。音声データのサンプリングレートは、事前学習モデルが学習に使用したデータセットのサンプリングレートと一致する必要があります。この値は、通常、モデルカードに記載されています。

[from_pretrained()](/docs/transformers/main/ja/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 は、すべてのシーケンスが同じ長さになるように、特別な *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,)
```

### 切り詰め

モデルは、クラッシュする前に処理できるシーケンスの長さに上限があります。

Truncationは、シーケンスが最大長を超えないように余分なトークンを削除する戦略です。`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/main/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}
```