Transformers documentation

特徴量抽出器

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.23.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

特徴量抽出器

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

FeatureExtractionMixin

class transformers.FeatureExtractionMixin

< >

( **kwargs )

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

from_pretrained

< >

( pretrained_model_name_or_path: str | os.PathLikecache_dir: str | os.PathLike | None = Noneforce_download: bool = Falselocal_files_only: bool = Falsetoken: str | bool | None = Nonerevision: str = 'main'**kwargs )

パラメータ

  • pretrained_model_name_or_path (str または os.PathLike) — 次のいずれかです:
    • 文字列、huggingface.co上のモデルリポジトリにホストされている事前学習済みfeature_extractorのmodel id
    • save_pretrained()メソッドを使用して保存されたフィーチャーエクストラクターファイルを含むディレクトリへのパス。例: ./my_model_directory/
    • 保存されたフィーチャーエクストラクターの./my_model_directory/preprocessor_config.jsonのようなファイルへのパス
  • cache_dir (str または os.PathLike、省略可) — 標準のキャッシュを使用しない場合、ダウンロードした事前学習済みモデルのフィーチャーエクストラクターをキャッシュするディレクトリのパス。
  • force_download (bool、任意、デフォルトは False) — feature extractor のファイルを(再)ダウンロードを強制し、キャッシュされたバージョンが存在する場合にそれを上書きするかどうかを指定します。
  • 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 を指定できます。したがって、 revision には git で許可される任意の識別子を指定できます。

    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 キーワード引数によって制御されます。

フィーチャーエクストラクター、例えば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

< >

( save_directory: str | os.PathLikepush_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

class transformers.SequenceFeatureExtractor

< >

( feature_size: intsampling_rate: intpadding_value: float**kwargs )

パラメータ

  • feature_size (int) — 抽出された特徴量の次元数。
  • sampling_rate (int) — オーディオファイルをデジタル化するためのサンプリングレート(ヘルツ (Hz) 単位)。
  • padding_value (float) — パディングの値やベクトルを埋めるために使用される値。

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

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 = Truemax_length: int | None = Nonetruncation: bool = Falsepad_to_multiple_of: int | None = Nonereturn_attention_mask: bool | None = Nonereturn_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]]]) — 処理済みの入力。1つの入力(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, 任意) — 返されるリストの最大長、および必要に応じてパディングの長さ(上記を参照)。
  • truncation (bool) — max_length を超える入力シーケンスを max_length に切り詰めるための切り詰め処理を有効にします。
  • pad_to_multiple_of (int, 省略可能) — 設定すると、シーケンスを指定された値の倍数にパディングします。

    これは、計算能力が>= 7.5(Volta)のNVIDIAハードウェアでTensor Coresの利用を有効にするために、また、シーケンス長が128の倍数であることで恩恵を受けるTPUにおいて、特に有用です。

  • return_attention_mask (bool, 省略可能) — attention mask を返すかどうか。デフォルトのままにすると、特定の feature_extractor のデフォルトに従って attention mask を返します。

    アテンションマスクとは?

  • return_tensors (str または TensorType, 省略可) — 設定すると、Python の整数のリストではなくテンソルを返します。指定可能な値は以下の通りです:
    • 'pt': PyTorchのtorch.Tensorオブジェクトを返します。
    • 'np': Numpy の np.ndarray オブジェクトを返します。

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

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

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

BatchFeature

class transformers.BatchFeature

< >

( data: dict[str, typing.Any] | None = Nonetensor_type: None | str | transformers.utils.generic.TensorType = Noneskip_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

< >

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

パラメータ

  • tensor_type (str または TensorType、任意) — 使用するテンソルの型です。str の場合、TensorType の列挙型のいずれかの値である必要があります。None の場合、変更は行われません。
  • skip_tensor_conversion (list[str] または set[str]、任意) — tensor_type が指定されている場合でも、テンソルに変換すべきでないキーのリストまたはセット。

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

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

へ

< >

( *args**kwargs ) → BatchFeature

パラメータ

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

戻り値

BatchFeature

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

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

ImageFeatureExtractionMixin

class transformers.ImageFeatureExtractionMixin

< >

( )

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

center_crop

< >

( imagesize ) → new_image

パラメータ

  • image (PIL.Image.Image または np.ndarray または torch.Tensor、shape が (n_channels, height, width) または (height, width, n_channels)) — リサイズする画像。
  • size (int または tuple[int, int]) — 画像をクロップするサイズ。

戻り値

new_image

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

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

convert_rgb

< >

( image )

パラメータ

  • image (PIL.Image.Image) — 変換対象の画像です。

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

expand_dims

< >

( image )

パラメータ

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

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

flip_channel_order

< >

( image )

パラメータ

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

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

normalize

< >

( imagemeanstdrescale = 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 配列への変換がトリガーされます。

rescale

< >

( image: ndarrayscale: float | int )

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

リサイズ

< >

( imagesizeresample = Nonedefault_to_square = Truemax_size = None ) → image

パラメータ

  • 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 に設定すると、最小辺のみをリサイズする機能と、任意の max_size を指定する機能を備えた torchvision.transforms.Resize と同じ動作になります。
  • max_size (int, 任意、デフォルトは None) — リサイズ後の画像の長い辺の許容される最大値です。画像が size に基づいてリサイズされた後、長い辺が max_size より大きい場合、長い辺が max_size に等しくなるように画像が再度リサイズされます。その結果、size が上書きされ、短い辺が size より短くなる可能性があります。default_to_square が False の場合のみ使用されます。

戻り値

image

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

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

rotate

< >

( imageangleresample = Noneexpand = 0center = Nonetranslate = Nonefillcolor = None ) → image

パラメータ

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

戻り値

image

回転済みのPIL.Image.Image。

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

to_numpy_array

< >

( imagerescale = Nonechannel_first = True )

パラメータ

  • image (PIL.Image.Image または np.ndarray または torch.Tensor) — NumPy 配列に変換する画像。
  • rescale (bool, 省略可) — スケーリング係数を適用するかどうか(ピクセル値を 0. から 1. の間の浮動小数点数にするため)。画像が PIL Image または整数の配列/テンソルの場合は True がデフォルト、それ以外の場合は False になります。
  • channel_first (bool、任意、デフォルトはTrue) — 画像の次元を並べ替え、チャネル次元を先頭に配置するかどうかを指定します。

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

to_pil_image

< >

( imagerescale = None )

パラメータ

  • image (PIL.Image.Image または numpy.ndarray または torch.Tensor) — PIL Image 形式に変換する画像。
  • rescale (bool, 省略可) — スケーリング係数を適用するかどうか(ピクセル値を 0 から 255 の整数にするため)。画像の型が浮動小数点型の場合は True、それ以外の場合は False がデフォルトになります。

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

Update on GitHub