transformers/main/ja/main_classes/feature_extractor.md

特徴量抽出器

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

FeatureExtractionMixin[[transformers.FeatureExtractionMixin]]

transformers.FeatureExtractionMixin[[transformers.FeatureExtractionMixin]]

transformers.FeatureExtractionMixin(**kwargs)

ソース

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

from_pretrained[[transformers.FeatureExtractionMixin.from_pretrained]]

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)

ソース

パラメータ:

pretrained_model_name_or_path (str または os.PathLike) : 以下のいずれかです: - huggingface.co のモデルリポジトリにホストされている事前学習済み feature_extractor の model id を示す文字列。 - 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のフィーチャーエクストラクター。

フィーチャーエクストラクター、例えばSequenceFeatureExtractorの派生クラスなどから、FeatureExtractionMixinの型をインスタンス化します。

例:

# 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]]

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

ソース

パラメータ:

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

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

kwargs (dict[str, Any]、省略可) : push_to_hub() メソッドに渡される追加のキーワード引数。

save_directory に from_pretrained() クラスメソッドで再読み込みできるように、feature_extractor オブジェクトを保存します。

SequenceFeatureExtractor[[transformers.SequenceFeatureExtractor]]

transformers.SequenceFeatureExtractor[[transformers.SequenceFeatureExtractor]]

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

ソース

パラメータ:

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

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

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

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

pad[[transformers.SequenceFeatureExtractor.pad]]

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)

ソース

パラメータ:

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

padding (bool、strまたは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 とは?

return_tensors (str または 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]]

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)

ソース

パラメータ:

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() およびフィーチャーエクストラクター固有の __call__ メソッドの出力を保持します。

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

convert_to_tensors[[transformers.BatchFeature.convert_to_tensors]]

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

ソース

パラメータ:

tensor_type (str または TensorType、optional) : 使用するテンソルの型です。str の場合、列挙型 TensorType の値のいずれかである必要があります。None の場合、変更は行われません。

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

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

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

へ[[transformers.BatchFeature.to]]

to(*args, **kwargs)

ソース

パラメータ:

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

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

戻り値: BatchFeature

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

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

ImageFeatureExtractionMixin[[transformers.ImageFeatureExtractionMixin]]

transformers.ImageFeatureExtractionMixin[[transformers.ImageFeatureExtractionMixin]]

transformers.ImageFeatureExtractionMixin()

ソース

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

center_crop[[transformers.ImageFeatureExtractionMixin.center_crop]]

center_crop(image, size)

ソース

パラメータ:

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]]

convert_rgb(image)

ソース

パラメータ:

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

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

expand_dims[[transformers.ImageFeatureExtractionMixin.expand_dims]]

expand_dims(image)

ソース

パラメータ:

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

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

flip_channel_order[[transformers.ImageFeatureExtractionMixin.flip_channel_order]]

flip_channel_order(image)

ソース

パラメータ:

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

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

normalize[[transformers.ImageFeatureExtractionMixin.normalize]]

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

ソース

パラメータ:

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]]

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

ソース

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

resize[[transformers.ImageFeatureExtractionMixin.resize]]

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

ソース

パラメータ:

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 を再現し、最小辺のみのリサイズおよび任意の 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]]

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

ソース

パラメータ:

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]]

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

ソース

パラメータ:

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]]

to_pil_image(image, rescale = None)

ソース

パラメータ:

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

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

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