# 特徴量抽出器

フィーチャーエクストラクターは、オーディオモデルの入力フィーチャーの準備を担当します。これには、シーケンスからのフィーチャー抽出（Log-Mel Spectrogram フィーチャーを生成するためにオーディオファイルを前処理することなど）や、NumPy および PyTorch テンソルへの変換が含まれます。

## FeatureExtractionMixin[[transformers.FeatureExtractionMixin]]

#### transformers.FeatureExtractionMixin[[transformers.FeatureExtractionMixin]]

```python
transformers.FeatureExtractionMixin(**kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_utils.py#L266)

これは、シーケンシャルおよびオーディオのフィーチャーエクストラクターに対して保存/読み込み機能を提供するために使用されるフィーチャー抽出ミックスインです。

#### from_pretrained[[transformers.FeatureExtractionMixin.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | os.PathLike, cache_dir: str | os.PathLike | None = None, force_download: bool = False, local_files_only: bool = False, token: str | bool | None = None, revision: str = 'main', **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_utils.py#L286)

**パラメータ:**

pretrained_model_name_or_path (`str` または `os.PathLike`) : 以下のいずれかです:  - huggingface.co のモデルリポジトリにホストされている事前学習済み feature_extractor の *model id* を示す文字列。 - [save_pretrained()](/docs/transformers/v5.23.0/ja/main_classes/feature_extractor#transformers.FeatureExtractionMixin.save_pretrained) メソッドを使用して feature extractor ファイルを保存した *ディレクトリ* へのパス。例: `./my_model_directory/`。 - 保存された feature extractor の JSON *ファイル* へのパス。例: `./my_model_directory/preprocessor_config.json`。

cache_dir (`str` または `os.PathLike`、*省略可能*) : 標準のキャッシュを使用しない場合、ダウンロードした事前学習済みモデルの feature extractor をキャッシュするディレクトリのパス。

force_download (`bool`、*任意*、デフォルトは`False`) : 特徴量抽出器のファイルを（再）ダウンロードを強制し、キャッシュされたバージョンが存在する場合に上書きするかどうか。

proxies (`dict[str, str]`, *省略可*) : プロトコルまたはエンドポイントごとに使用するプロキシサーバーの辞書。例: `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}.` 各リクエストでこれらのプロキシが使用されます。

token (`str` または `bool`、*省略可*) : リモートファイルの HTTP ベアラ認証に使用するトークン。`True` の場合、または指定されていない場合は、`hf auth login` を実行した際に生成されたトークン（`~/.huggingface` に保存）が使用されます。

revision (`str`、*任意*、デフォルトは`"main"`) : 使用する特定のモデルバージョンです。huggingface.co ではモデルやその他の成果物を保存するために git ベースのシステムを使用しているため、ブランチ名、タグ名、コミット ID など、git で許可されている任意の識別子を`revision`に指定できます。     Hub で作成したプルリクエストをテストするには、`revision="refs/pr/<pr_number>"`を渡すことができます。

return_unused_kwargs (`bool`、*任意*、デフォルトは`False`) : `False`の場合、この関数は最終的なfeature extractorオブジェクトのみを返します。`True`の場合、この関数は`Tuple(feature_extractor, unused_kwargs)`を返します。ここで、*unused_kwargs*は、キーがfeature extractorの属性でないキー/値のペアで構成される辞書です。つまり、`feature_extractor`の更新に使用されず、それ以外は無視される`kwargs`の部分です。

kwargs (`dict[str, Any]`、*省略可*) : kwargs 内の、feature extractor の属性であるキーの値は、読み込まれた値の上書きに使用されます。キーが feature extractor の属性で*ない*キー/値ペアの挙動は、`return_unused_kwargs` キーワード引数によって制御されます。

**戻り値:**

型が[FeatureExtractionMixin](/docs/transformers/v5.23.0/ja/main_classes/feature_extractor#transformers.FeatureExtractionMixin)のフィーチャーエクストラクター。

フィーチャーエクストラクター、*例えば*[SequenceFeatureExtractor](/docs/transformers/v5.23.0/ja/main_classes/feature_extractor#transformers.SequenceFeatureExtractor)の派生クラスなどから、[FeatureExtractionMixin](/docs/transformers/v5.23.0/ja/main_classes/feature_extractor#transformers.FeatureExtractionMixin)の型をインスタンス化します。

例:

```python
# We can't instantiate directly the base class *FeatureExtractionMixin* nor *SequenceFeatureExtractor* so let's show the examples on a
# derived class: *Wav2Vec2FeatureExtractor*
feature_extractor = Wav2Vec2FeatureExtractor.from_pretrained(
    "facebook/wav2vec2-base-960h"
)  # Download feature_extraction_config from huggingface.co and cache.
feature_extractor = Wav2Vec2FeatureExtractor.from_pretrained(
    "./test/saved_model/"
)  # E.g. feature_extractor (or model) was saved using *save_pretrained('./test/saved_model/')*
feature_extractor = Wav2Vec2FeatureExtractor.from_pretrained("./test/saved_model/preprocessor_config.json")
feature_extractor = Wav2Vec2FeatureExtractor.from_pretrained(
    "facebook/wav2vec2-base-960h", return_attention_mask=False, foo=False
)
assert feature_extractor.return_attention_mask is False
feature_extractor, unused_kwargs = Wav2Vec2FeatureExtractor.from_pretrained(
    "facebook/wav2vec2-base-960h", return_attention_mask=False, foo=False, return_unused_kwargs=True
)
assert feature_extractor.return_attention_mask is False
assert unused_kwargs == {"foo": False}
```

#### save_pretrained[[transformers.FeatureExtractionMixin.save_pretrained]]

```python
save_pretrained(save_directory: str | os.PathLike, push_to_hub: bool = False, **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_utils.py#L390)

**パラメータ:**

save_directory (`str` または `os.PathLike`) : 特徴量抽出器の JSON ファイルを保存するディレクトリ（存在しない場合は作成されます）。

push_to_hub (`bool`、*任意*、デフォルトは`False`) : モデルを保存した後、Hugging Face モデルハブにプッシュするかどうかを指定します。プッシュ先のリポジトリは`repo_id`で指定できます（指定しない場合、`save_directory`の名前があなたのネームスペース内でデフォルトとして使用されます）。

kwargs (`dict[str, Any]`、*省略可*) : [push_to_hub()](/docs/transformers/v5.23.0/ja/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) メソッドに渡される追加のキーワード引数。

`save_directory` に [from_pretrained()](/docs/transformers/v5.23.0/ja/main_classes/feature_extractor#transformers.FeatureExtractionMixin.from_pretrained) クラスメソッドで再読み込みできるように、feature_extractor オブジェクトを保存します。

## SequenceFeatureExtractor[[transformers.SequenceFeatureExtractor]]

#### transformers.SequenceFeatureExtractor[[transformers.SequenceFeatureExtractor]]

```python
transformers.SequenceFeatureExtractor(feature_size: int, sampling_rate: int, padding_value: float, **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_sequence_utils.py#L28)

**パラメータ:**

feature_size (`int`) : 抽出された特徴量の次元数。

sampling_rate (`int`) : 音声ファイルをデジタル化するためのサンプリングレート（ヘルツ（Hz）で表します）。

padding_value (`float`) : パディングの値/ベクトルに埋めるために使用される値。

これは音声認識向けの一般的な特徴抽出クラスです。

#### pad[[transformers.SequenceFeatureExtractor.pad]]

```python
pad(processed_features: transformers.feature_extraction_utils.BatchFeature | list[transformers.feature_extraction_utils.BatchFeature] | dict[str, transformers.feature_extraction_utils.BatchFeature] | dict[str, list[transformers.feature_extraction_utils.BatchFeature]] | list[dict[str, transformers.feature_extraction_utils.BatchFeature]], padding: bool | str | transformers.utils.generic.PaddingStrategy = True, max_length: int | None = None, truncation: bool = False, pad_to_multiple_of: int | None = None, return_attention_mask: bool | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_sequence_utils.py#L51)

**パラメータ:**

processed_features ([BatchFeature](/docs/transformers/v5.23.0/ja/main_classes/feature_extractor#transformers.BatchFeature)、[BatchFeature](/docs/transformers/v5.23.0/ja/main_classes/feature_extractor#transformers.BatchFeature) のリスト、`dict[str, list[float]]`、`dict[str, list[list[float]]` または `list[dict[str, list[float]]]`) : 処理済みの入力です。単一の入力（[BatchFeature](/docs/transformers/v5.23.0/ja/main_classes/feature_extractor#transformers.BatchFeature) または `dict[str, list[float]]`）を表すことも、入力値/ベクトルのバッチ（[BatchFeature](/docs/transformers/v5.23.0/ja/main_classes/feature_extractor#transformers.BatchFeature) のリスト、*dict[str, list[list[float]]]* または *list[dict[str, list[float]]]*）を表すこともできるため、前処理時だけでなく、PyTorch の Dataloader の collate 関数としても使用できます。 `list[float]` の代わりにテンソル（numpy 配列や PyTorch テンソル）を持つ場合があり、戻り値の型については上記の注記を参照してください。

padding (`bool`、`str`または[PaddingStrategy](/docs/transformers/v5.23.0/ja/internal/file_utils#transformers.utils.PaddingStrategy)、*省略可能*、デフォルトは`True`) : 返されるシーケンスのパディング戦略を選択します（モデルのパディング側とパディングインデックスに従います）。選択肢は以下の通りです。 - `True`または`'longest'`: バッチ内の最も長いシーケンスまでパディングします（単一のシーケンスのみが提供された場合は、パディングを行いません）。 - `'max_length'`: 引数`max_length`で指定された最大長までパディングします。この引数が指定されていない場合は、モデルが受け入れ可能な最大入力長までパディングします。 - `False`または`'do_not_pad'`（デフォルト）: パディングを行いません（つまり、長さが異なるシーケンスのバッチを出力できます）。

max_length (`int`, *optional*) : 返されるリストの最大長、および必要に応じてパディング長（上記を参照）。

truncation (`bool`) : `max_length` を超える入力シーケンスを `max_length` に切り詰めるための切り詰め処理を有効にします。

pad_to_multiple_of (`int`, *optional*) : 設定されている場合、シーケンスを指定された値の倍数にパディングします。これは、計算能力が `>= 7.5` (Volta) の NVIDIA ハードウェアで Tensor Cores を使用可能にするため、またはシーケンス長が 128 の倍数であることで性能が向上する TPU で特に有用です。

return_attention_mask (`bool`、*任意*) : attention mask を返すかどうか。デフォルトのままにすると、特定の feature_extractor のデフォルトに従って attention mask を返します。 [attention mask とは?](../glossary#attention-mask)

return_tensors (`str` または [TensorType](/docs/transformers/v5.23.0/ja/internal/file_utils#transformers.TensorType)、*optional*) : 設定されている場合、Python の整数のリストではなくテンソルを返します。指定可能な値は以下の通りです。 - `'pt'`: PyTorch の `torch.Tensor` オブジェクトを返します。 - `'np'`: Numpy の `np.ndarray` オブジェクトを返します。

入力値/入力ベクトル、または入力値/入力ベクトルのバッチを、事前定義された長さまたはバッチ内の最大シーケンス長までパディングします。

パディング側（左/右）のパディング値は、フィーチャーエクストラクターレベルで定義されます（`self.padding_side`、`self.padding_value`）。

`processed_features` に渡されたものが numpy 配列の辞書または PyTorch テンソルの場合、`return_tensors` で別のテンソル型を指定しない限り、結果も同じ型になります。ただし、PyTorch テンソルの場合は、テンソルが保持していた特定のデバイス情報が失われます。

## BatchFeature[[transformers.BatchFeature]]

#### transformers.BatchFeature[[transformers.BatchFeature]]

```python
transformers.BatchFeature(data: dict[str, typing.Any] | None = None, tensor_type: None | str | transformers.utils.generic.TensorType = None, skip_tensor_conversion: list[str] | set[str] | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_utils.py#L58)

**パラメータ:**

data (`dict`, *任意*) : __call__/pad メソッドによって返されるリスト/配列/テンソルの辞書（'input_values'、'attention_mask' など）。

tensor_type (`Union[None, str, TensorType]`、*任意*) : ここで tensor_type を指定すると、初期化時に PyTorch/Numpy の Tensor 内の整数リストを変換できます。

skip_tensor_conversion (`list[str]` または `set[str]`、*任意*) : `tensor_type` が指定されている場合でも、テンソルに変換すべきでないキーのリストまたはセット。

[pad()](/docs/transformers/v5.23.0/ja/main_classes/feature_extractor#transformers.SequenceFeatureExtractor.pad) およびフィーチャーエクストラクター固有の `__call__` メソッドの出力を保持します。

このクラスはPythonの辞書から派生しており、辞書として使用できます。

#### convert_to_tensors[[transformers.BatchFeature.convert_to_tensors]]

```python
convert_to_tensors(tensor_type: str | transformers.utils.generic.TensorType | None = None, skip_tensor_conversion: list[str] | set[str] | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_utils.py#L158)

**パラメータ:**

tensor_type (`str` または [TensorType](/docs/transformers/v5.23.0/ja/internal/file_utils#transformers.TensorType)、*optional*) : 使用するテンソルの型です。`str` の場合、列挙型 [TensorType](/docs/transformers/v5.23.0/ja/internal/file_utils#transformers.TensorType) の値のいずれかである必要があります。`None` の場合、変更は行われません。

skip_tensor_conversion (`list[str]` または `set[str]`、*任意*) : `tensor_type` が指定されている場合でも、テンソルに変換すべきでないキーのリストまたはセット。

内部のコンテンツをテンソルに変換します。

注: 配列のような構造を持たない値(文字列、辞書、文字列のリストなど)は自動的にスキップされ、テンソルに変換されません。ラガード配列(長さが異なる配列のリスト)については変換が試みられますが、変換中にエラーが発生する可能性があります。

#### へ[[transformers.BatchFeature.to]]

```python
to(*args, **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_utils.py#L215)

**パラメータ:**

args (`Tuple`) : テンソルの `to(...)` 関数に渡されます。

kwargs (`Dict`、*任意*) : テンソルの `to(...)` 関数に渡されます。非同期データ転送を有効にするには、`kwargs` に `non_blocking` フラグを設定します（デフォルトは `False`）。

**戻り値:** [BatchFeature](/docs/transformers/v5.23.0/ja/main_classes/feature_extractor#transformers.BatchFeature)

変更後の同じインスタンス。

`v.to(*args, **kwargs)` を呼び出して、すべての値をデバイスに送信します（PyTorch のみ）。これにより、異なる `dtypes` へのキャストや、`BatchFeature` を別の `device` へ送信することがサポートされるべきです。

## ImageFeatureExtractionMixin[[transformers.ImageFeatureExtractionMixin]]

#### transformers.ImageFeatureExtractionMixin[[transformers.ImageFeatureExtractionMixin]]

```python
transformers.ImageFeatureExtractionMixin()
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L649)

画像特徴の準備に使用するユーティリティを含むミックスインです。

#### center_crop[[transformers.ImageFeatureExtractionMixin.center_crop]]

```python
center_crop(image, size)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L883)

**パラメータ:**

image (`PIL.Image.Image` または `np.ndarray` または (n_channels, height, width) または (height, width, n_channels) の形状の `torch.Tensor`) : リサイズする画像。

size (`int` または `tuple[int, int]`) : 画像をクロップするサイズ。

**戻り値:** `new_image`

形状が (n_channels, height, width) の、中央クロップされた `PIL.Image.Image` または `np.ndarray` または `torch.Tensor`。

`image` を中心クロップにより指定サイズに切り出します。画像が指定サイズにクロップできないほど小さい場合は、パディングが適用されます（そのため、返される結果は要求されたサイズになります）。

#### convert_rgb[[transformers.ImageFeatureExtractionMixin.convert_rgb]]

```python
convert_rgb(image)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L691)

**パラメータ:**

image (`PIL.Image.Image`) : 変換対象の画像。

`PIL.Image.Image`をRGB形式に変換します。

#### expand_dims[[transformers.ImageFeatureExtractionMixin.expand_dims]]

```python
expand_dims(image)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L744)

**パラメータ:**

image (`PIL.Image.Image` または `np.ndarray` または `torch.Tensor`) : 拡大する画像。

2次元の`image`を3次元に拡張します。

#### flip_channel_order[[transformers.ImageFeatureExtractionMixin.flip_channel_order]]

```python
flip_channel_order(image)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L958)

**パラメータ:**

image (`PIL.Image.Image` または `np.ndarray` または `torch.Tensor`) : 色チャネルを反転する画像。`np.ndarray` または `torch.Tensor` の場合、チャネル次元が先頭である必要があります。

`image`のチャネル順序をRGBからBGRへ、またはその逆に変換します。なお、`image`がPIL Imageである場合、NumPy配列への変換がトリガーされます。

#### normalize[[transformers.ImageFeatureExtractionMixin.normalize]]

```python
normalize(image, mean, std, rescale = False)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L764)

**パラメータ:**

image (`PIL.Image.Image` または `np.ndarray` または `torch.Tensor`) : 正規化対象の画像。

mean (`list[float]` または `np.ndarray` または `torch.Tensor`) : 正規化に使用する平均値（チャネルごと）。

std (`list[float]` または `np.ndarray` または `torch.Tensor`) : 正規化に使用する標準偏差（チャンネルごと）。

rescale (`bool`、*任意*、デフォルトは `False`) : 画像を 0 から 1 の間にリスケールするかどうか。PIL 画像が提供されている場合、スケーリングは自動的に実行されます。

`image` を `mean` と `std` で正規化します。なお、`image` が PIL Image の場合、NumPy 配列への変換がトリガーされます。

#### リスケール[[transformers.ImageFeatureExtractionMixin.rescale]]

```python
rescale(image: ndarray, scale: float | int)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L705)

numpyの画像をスケール量でリスケールします

#### resize[[transformers.ImageFeatureExtractionMixin.resize]]

```python
resize(image, size, resample = None, default_to_square = True, max_size = None)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L816)

**パラメータ:**

image (`PIL.Image.Image` または `np.ndarray` または `torch.Tensor`) : リサイズする画像。

size (`int` または `tuple[int, int]`) : 画像のリサイズに使用するサイズ。`size` が (h, w) のようなシーケンスの場合、出力サイズはこれに一致させられます。 `size` が int かつ `default_to_square` が `True` の場合、画像は (size, size) にリサイズされます。 `size` が int かつ `default_to_square` が `False` の場合、画像の短い辺がこの数値に一致させられます。つまり、height > width の場合、画像は (size * height / width, size) にリスケールされます。

resample (`int`, *任意*, デフォルトは `PILImageResampling.BILINEAR`) : リサンプリングに使用するフィルタ。

default_to_square (`bool`, *任意*, デフォルトは `True`) : `size` が単一の int の場合の変換方法です。`True` に設定すると、`size` は正方形 (`size`,`size`) に変換されます。`False` に設定すると、[`torchvision.transforms.Resize`](https://pytorch.org/vision/stable/transforms.html#torchvision.transforms.Resize) を再現し、最小辺のみのリサイズおよび任意の `max_size` の指定に対応します。

max_size (`int`、*任意*、デフォルトは`None`) : リサイズ後の画像の長い辺の許容される最大値です。画像が`size`に従ってリサイズされた後、長い辺が`max_size`を超えている場合、長い辺が`max_size`に等しくなるように画像が再度リサイズされます。その結果、`size`が上書きされる可能性があります。つまり、短い辺が`size`より短くなる場合があります。`default_to_square`が`False`の場合にのみ使用されます。

**戻り値:** `image`

リサイズされた`PIL.Image.Image`。

`image`をリサイズします。入力をPIL.Imageに変換することを強制します。

#### 回転[[transformers.ImageFeatureExtractionMixin.rotate]]

```python
rotate(image, angle, resample = None, expand = 0, center = None, translate = None, fillcolor = None)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L975)

**パラメータ:**

image (`PIL.Image.Image` または `np.ndarray` または `torch.Tensor`) : 回転させる画像。`np.ndarray` または `torch.Tensor` の場合、回転処理の前に `PIL.Image.Image` に変換されます。

**戻り値:** `image`

回転済みの`PIL.Image.Image`。

`image`の回転コピーを返します。このメソッドは、`image`のコピーを、中心を基準として指定された角度だけ反時計回りに回転させて返します。

#### to_numpy_array[[transformers.ImageFeatureExtractionMixin.to_numpy_array]]

```python
to_numpy_array(image, rescale = None, channel_first = True)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L712)

**パラメータ:**

image (`PIL.Image.Image` または `np.ndarray` または `torch.Tensor`) : NumPy 配列に変換する画像。

rescale (`bool`, *optional*) : スケーリング係数を適用するかどうか（ピクセル値を0.から1.の間のfloatにするため）。画像がPIL Imageまたは整数の配列/テンソルの場合はデフォルトで`True`、それ以外の場合は`False`になります。

channel_first (`bool`, *任意*, デフォルトは `True`) : 画像の次元を並べ替えて、チャネル次元を先頭に配置するかどうか。

`image`をNumPy配列に変換します。必要に応じて、スケールを再調整し、チャネル次元を最初の次元に配置します。

#### to_pil_image[[transformers.ImageFeatureExtractionMixin.to_pil_image]]

```python
to_pil_image(image, rescale = None)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L661)

**パラメータ:**

image (`PIL.Image.Image` または `numpy.ndarray` または `torch.Tensor`) : PIL Image 形式に変換する画像。

rescale (`bool`, *optional*) : スケーリング係数を適用するかどうか（ピクセル値を 0 から 255 の整数にするため）。画像の型が浮動小数点型の場合は `True`、それ以外の場合は `False` がデフォルトになります。

`image`をPIL Imageに変換します。必要に応じて、リスケールし、チャネル次元を最後の軸に戻します。

