Hugging Face's logo

Transformers documentation

プロセッサ

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

プロセッサ

マルチモーダルプロセッサ

マルチモーダルモデルでは、テキスト、ビジョン、オーディオなどの複数のモダリティにまたがるデータをエンコードまたはデコードするために、それらをまとめるオブジェクトが必要です。これはプロセッサと呼ばれるオブジェクトによって処理され、トークナイザ（テキストモダリティ用）、イメージプロセッサ（ビジョン用）、フィーチャーエクストラクター（オーディオ用）などの2つ以上の処理オブジェクトをグループ化します。

これらのプロセッサーは、保存および読み込みの機能を実装している以下のベースクラスを継承しています:

class transformers.ProcessorMixin

< >

( *args**kwargs )

これは、すべてのプロセッサクラスに保存/読み込み機能を提供するために使用されるミックスインです。

__call__

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )

パラメータ

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], 任意) — 前処理対象の画像です。ピクセル値が 0 から 255 の範囲にある単一の画像またはバッチを想定しています。ピクセル値が 0 から 1 の範囲にある画像を渡す場合は、do_rescale=False を設定してください。
  • text (Union[str, list[str], list[list[str]]]、省略可) — エンコード対象のシーケンスまたはシーケンスのバッチです。各シーケンスは文字列、または文字列のリスト（事前トークン化済み文字列）であることができます。事前トークン化済みの入力を渡す場合は、バッチ入力との曖昧さを避けるために is_split_into_words=True を設定してください。
  • videos (Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]], 任意) — 前処理を行う動画です。ピクセル値が 0 から 255 の範囲にある、単一の動画またはバッチの動画を想定しています。ピクセル値が 0 から 1 の範囲にある動画を渡す場合は、do_rescale=False を設定してください。
  • audio (Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]], 任意) — 準備対象のオーディオまたはオーディオのバッチです。各オーディオは NumPy 配列または PyTorch テンソルであることができます。 NumPy 配列/PyTorch テンソルの場合、各オーディオの形状は (C, T) である必要があります。ここで C はチャネル数、T はオーディオのサンプル長です。
  • return_mm_token_type_ids (bool, kwargs) — マルチモーダルプレースホルダトークンの位置を示すマルチモーダルトークンタイプIDを返すかどうか。
  • return_text_replacement_offsets (bool, kwargs) — 各マルチモーダルプレースホルダーとその置換文字列の文字オフセットを返すかどうかを指定します。
  • return_tensors (str または TensorType, 省略可) — 設定すると、特定のフレームワークのテンソルを返します。使用可能な値は以下の通りです:
    • 'pt': PyTorchのtorch.Tensorオブジェクトを返します。
    • 'np': NumPyのnp.ndarrayオブジェクトを返します。
  • **kwargs (ProcessingKwargs、任意) — 各モダリティ（テキスト、画像、動画、音声）の追加処理オプション。モデル固有のパラメータは上記にリストされています。サポートされている引数の完全なリストについては、TypedDictクラスを参照してください。

prepare_inputs_layout

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )

処理の前に、入力を正規化して事前取得します。マルチモーダルプロセッサではテキストをリストにラップし、URLが指定されている場合はリモートの画像やオーディオを取得し、オーディオが適切にバッチ化されることを保証します。正規化された(images, text, videos, audio)のタプルを返します。

validate_inputs

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )

少なくとも1つの入力が提供されていること、および非推奨のキーワード引数が使用されていないことを検証します。それ以外の場合はValueErrorを発生させます。

プロセッサが入力引数に対して追加の検証を必要とする場合にオーバーライドします。

get_text_with_replacements

< >

( text: list[str]images_replacements: list[str] = []videos_replacements: list[str] = []audio_replacements: list[str] = [] ) → tuple[list[str], list[dict[str, Any]]]

パラメータ

  • text (list[str]) — 生の文字列のバッチ。各文字列には、マルチモーダルのプレースホルダトークンが含まれる場合があります。注意: この引数はインプレースで変更され、返されます。
  • images_replacements (list[str]、optional、デフォルトは []) — バッチ全体で画像が出現する順序に従った、各画像に対応する展開された置換文字列。self._process_images によって生成されます。
  • videos_replacements (list[str]、optional、デフォルトは []) — 各動画に対する展開された置換文字列。self._process_videos によって生成されます。
  • audio_replacements (list[str]、optional、デフォルトは []) — 各オーディオ入力に対する展開された置換文字列。self._process_audio によって生成されます。

戻り値

tuple[list[str], list[dict[str, Any]]]

次のタプル:

  • すべてのプレースホルダトークンが展開された修正済みtextバッチ。
  • batch_replacement_offsets: バッチ項目ごとに1エントリあり、それぞれが以下のキーを持つ辞書のリストです:
  • “type” (str): モダリティ名 — “image”、“video”、または “audio”
  • “span” (tuple[int, int]): プレースホルダートークンの元の (start, end) 文字オフセット
  • “new_span” (tuple[int, int]): 展開後の文字列におけるプレースホルダーの (start, end) オフセット
  • “text” (str): 一致した元のプレースホルダトークン文字列
  • “replacement” (str): 置き換えられた文字列

テキスト文字列のバッチ内のマルチモーダルプレースホルダトークンを展開された表現に置き換え、変更されたテキストとオフセットメタデータを返します。

このメソッドは、マルチモーダル入力におけるテキスト側の前処理のコアステップです。バッチ内の各テキストをスキャンして特殊トークン（image、video、audio）を検出し、self.replace_image_token / self.replace_video_token / self.replace_audio_token によって事前計算された置換文字列に、出現順に置き換えます。置換は各モダリティのリストから順次消費されるため、例えば self.image_token の i 番目の出現箇所は images_replacements[i] に置き換えられます。

プレースホルダートークン付きの新しいマルチモーダルプロセッサを追加するには、入力テキストに埋め込まれ、プレースホルダーとして使用され、複数回繰り返されるのと同じトークンである正しい self.image_token を定義する必要があります。次に、インデックス i の画像に対して正しい置換文字列を返すように self.replace_image_token をオーバーライドする必要があります。サポートされている他のすべてのモダリティについても同様です。

create_mm_token_type_ids

< >

( input_ids: list ) → list[list[int]]

パラメータ

  • input_ids (list[list[int]]) — トークン ID シーケンスのバッチです。パディングされていない（可変長）場合があるため、テンソルや均一な形状の配列ではなく、通常の Python のリストのリストが期待されます。

戻り値

list[list[int]]

input_ids と同じ構造のリストで、各整数は対応するトークンのモダリティタイプ ID です。

バッチのtoken_idシーケンスに対して、トークンごとのモダリティ型IDを構築します。

各位置には、どのモダリティに属するかを示す整数が割り当てられます。0は通常のテキスト、1は画像トークン、2は動画トークン、3は音声トークンを表します。所属は、self.image_token_ids、self.video_token_ids、self.audio_token_idsとの比較によって判定されます。

apply_chat_template

< >

( conversation: list[dict[str, str]] | list[list[dict[str, str]]]chat_template: str | None = Nonetools: list[dict] | None = Nonedocuments: list[dict[str, str]] | None = Noneadd_generation_prompt: bool = Falsecontinue_final_message: bool | str = Falsereturn_assistant_tokens_mask: bool = Falsetokenize: bool = Falsereturn_tensors: str | transformers.utils.generic.TensorType | None = 'auto'return_dict: bool = Falseload_audio_from_video: bool = Falseprocessor_kwargs: dict | None = Nonesanitize_control_tokens: bool = False**kwargs )

パラメータ

  • conversation (Union[list[Dict, [str, str]], list[list[dict[str, str]]]]) — フォーマット対象の会話です。
  • chat_template (Optional[str]、省略可) — 会話を整形するために使用する Jinja テンプレートです。指定しない場合、トークナイザーのチャットテンプレートが使用されます。
  • sanitize_control_tokens (bool、デフォルトはFalse) — 会話、ツール、ドキュメント、および**kwargsとして渡されるテンプレート変数に含まれる制御トークンをプレーンテキストとしてエンコードし、ユーザー入力がそれらやmmプレースホルダーを書き込めないようにするかどうかを指定します。 トークナイザーのapply_chat_templateを参照してください。 tokenize=Trueが必要です。

トークナイザーのapply_chat_templateメソッドと同様に、このメソッドは入力された会話にJinjaテンプレートを適用し、それを単一のトークナイズ可能な文字列に変換します。

入力には、各メッセージのコンテンツがテキストと、任意の画像または動画の入力からなるリストである、以下の形式が期待されます。return_dict=True の場合、画像、動画、URL、またはローカルパスを指定することもでき、それらは pixel_values を形成するために使用されます。指定しない場合、フォーマットされたテキストのみ、または任意でトークン化されたテキストのみが返されます。

conversation = [ { “role”: “user”, “content”: [ {“type”: “image”, “url”: “https://www.ilankelman.org/stopsigns/australia.jpg”}, {“type”: “text”, “text”: “Please describe this image in detail.”}, ], }, ]

kwargs の処理

Processor の __call__ メソッドは、モダリティごとに整理されたキーワード引数を受け取ります。以下の TypedDict クラスは、各モダリティで利用可能なキーワード引数を定義しています。モデル固有の Processor は、これらのクラスをサブクラス化して、フィールドを追加または上書きできます。

クラス transformers.ProcessingKwargs

< >

( )

プロセッサへのkwargsの受け渡しを行うためのベースクラス。

モデルがベースクラスに存在しない特定のkwargsを持っていたり、既存のキーにデフォルト値を設定していたりする場合は、このモデルが入力の処理に必要とする追加の型付きキーを提供するために、ProcessingKwargsを継承した独自のModelProcessorKwargsクラスを持つ必要があります。

型ヒントが正しく行われるようにするには、新しいキーは次のように定義する必要があります。

class ModelProcessorKwargs(ProcessingKwargs, total=False):
    my_kwarg: float

class ModelProcessor(ProcessorMixin):
    valid_processor_kwargs = ModelProcessorKwargs

    @auto_docstring
    def __call__(self, images: ImageInput | None = None, ..., **kwargs: Unpack[ModelProcessorKwargs]):
        my_kwarg = kwargs.get("my_kwarg")

クラス transformers.TextKwargs

< >

( )

パラメータ

  • add_special_tokens (bool, 省略可) — シーケンスをエンコードする際に、特殊トークンを追加するかどうかを指定します。
  • padding (bool、str または PaddingStrategy、省略可) — パディングの有効化と制御を行います。
  • truncation (bool、strまたはTruncationStrategy、省略可) — 切り詰めを有効にし、切り詰めを制御します。
  • max_length (int, 省略可) — 切り詰め/パディングのパラメータのいずれかによって使用される最大長を制御します。
  • stride (int, 省略可) — 設定した場合、オーバーフローしたトークンには、切り詰められたシーケンスの末尾の一部のトークンが含まれます。
  • is_split_into_words (bool, 省略可) — 入力がすでに事前トークン化済みかどうかを示します。
  • pad_to_multiple_of (int, 省略可) — 設定した場合、シーケンスを指定された値の倍数にパディングします。
  • return_token_type_ids (bool、省略可) — トークンタイプIDを返すかどうかを指定します。
  • return_attention_mask (bool, 省略可) — attention mask を返すかどうか。
  • return_overflowing_tokens (bool、省略可) — 溢れ出したトークンシーケンスを返すかどうかを指定します。
  • return_special_tokens_mask (bool, 省略可) — 特殊トークンのマスク情報を返すかどうか。
  • return_offsets_mapping (bool, 省略可) — 各トークンについて(char_start, char_end)を返すかどうか。
  • return_length (bool, 省略可) — エンコードされた入力の長さを返すかどうかを指定します。
  • verbose (bool、省略可) — より多くの情報や警告を出力するかどうかを指定します。
  • padding_side (str, 任意) — パディングを適用する側です。
  • return_mm_token_type_ids (bool, 省略可能) — 非推奨です。ProcessingKwargs.return_mm_token_type_ids を使用してください。 mm プレースホルダー トークンの位置を示すマルチモーダル トークン タイプ ID を返すかどうか。
  • return_text_replacement_offsets (bool, 省略可能) — 非推奨です。ProcessingKwargs.return_text_replacement_offsets を使用してください。 各 mm プレースホルダーとその置換文字列の文字オフセットを返すかどうかを指定します。
  • sanitize_control_tokens (bool, 省略可) — mark_control_tokens によってマークされたテキストかどうかを示します。マークされた制御トークンはプレーンテキストとしてエンコードされ、mm プレースホルダーとして展開されません。apply_chat_template(..., sanitize_control_tokens=True) によって設定されます。
  • return_tensors (str または TensorType, 省略可) — 設定すると、特定のフレームワークのテンソルを返します。使用可能な値は以下の通りです:
    • 'pt': PyTorchのtorch.Tensorオブジェクトを返します。
    • 'np': NumPyのnp.ndarrayオブジェクトを返します。

テキスト処理用のキーワード引数です。詳細なドキュメントについては、tokenization_utils_base のメソッドおよび関連する docstring をご確認ください。

class transformers.ImagesKwargs

< >

( )

パラメータ

  • do_convert_rgb (bool) — 画像をRGB形式に変換するかどうかを指定します。
  • do_resize (bool、省略可) — 画像をリサイズするかどうかを指定します。
  • size (dict[str, int]、省略可) — サポートされているサイズ辞書のいずれかを使用してリサイズします。ピクセル面積の範囲は、{"min_pixels": int, "max_pixels": int} を使用します。
  • default_to_square (bool、任意、デフォルトは self.default_to_square) — size が int の場合、リサイズ時に正方形をデフォルトとするかどうか。
  • crop_size (dict[str, int], 任意) — 中央クロップを適用する際の、希望する出力サイズ。
  • resample (PILImageResampling, 任意) — 画像をリサイズする際に使用するリサンプリングフィルタ。
  • do_rescale (bool, 省略可) — 指定されたスケーリング係数 rescale_factor によって画像をリスケールするかどうか。
  • rescale_factor (int または float、省略可) — 画像をリスケールする場合に使用するスケール係数。
  • do_normalize (bool, 省略可) — 画像を正規化するかどうかを指定します。
  • image_mean (float または list[float] or tuple[float, float, float]、省略可) — 画像を正規化する場合に使用する平均値。
  • image_std (float or list[float] or tuple[float, float, float], optional) — 画像を正規化する場合に使用する標準偏差。
  • do_pad (bool, 省略可) — バッチ内の画像をパディングするかどうかを指定します。
  • pad_size (dict[str, int]、任意) — 画像をパディングするサイズ {"height": int, "width" int}。
  • do_center_crop (bool, 任意) — 画像を中央クロップするかどうかを指定します。
  • data_format (ChannelDimension または str、省略可) — 出力画像のチャネル次元の形式です。
  • input_data_format (ChannelDimension または str、省略可) — 入力画像のチャネル次元の形式です。
  • device (Union[str, torch.Tensor]、省略可) — 処理に使用するデバイス（例: “cpu”、“cuda”）。torchvision バックエンドでのみ関連します。
  • return_tensors (str または TensorType, 省略可) — 設定すると、特定のフレームワークのテンソルを返します。使用可能な値は以下の通りです:
    • 'pt': PyTorchのtorch.Tensorオブジェクトを返します。
    • 'np': NumPyのnp.ndarrayオブジェクトを返します。
  • disable_grouping (bool、省略可) — 画像を形状ごとにグループ化して処理するかどうかを指定します。torchvision バックエンドでのみ関連します。
  • image_seq_length (int, 任意) — 入力内の各画像に使用される画像トークンの数です。 後方互換性のために追加されましたが、将来のモデルではプロセッサの属性として設定されるべきです。

画像処理用のキーワード引数です。詳細なドキュメントについては、該当するImageProcessorクラスのメソッドとdocstringを確認してください。

クラス transformers.VideosKwargs

< >

( )

パラメータ

  • do_convert_rgb (bool) — 動画をRGB形式に変換するかどうかを指定します。
  • do_resize (bool) — 動画をリサイズするかどうか。
  • size (dict[str, int]、任意) — 入力の短い辺をsize["shortest_edge"]にリサイズします。
  • default_to_square (bool、任意、デフォルトは self.default_to_square) — size が int の場合、リサイズ時に正方形をデフォルトとするかどうか。
  • resample (PILImageResampling、省略可) — 動画をリサイズする場合に使用するリサンプリングフィルタ。
  • do_rescale (bool, 省略可) — 指定されたスケーリング係数 rescale_factor によって動画をリスケールするかどうかを指定します。
  • rescale_factor (int または float、省略可) — 動画をリサイズする場合に使用するスケール係数。
  • do_normalize (bool、省略可) — 動画を正規化するかどうかを指定します。
  • image_mean (float または list[float] or tuple[float, float, float]、省略可) — 動画を正規化する場合に使用する平均値。
  • image_std (float or list[float] or tuple[float, float, float], optional) — 動画を正規化する場合に使用する標準偏差。
  • do_center_crop (bool、任意) — 動画を中央クロップするかどうかを指定します。
  • do_pad (bool, 省略可) — バッチ内の画像をパディングするかどうかを指定します。
  • do_sample_frames (bool, 省略可) — 処理前に動画からフレームをサンプリングするか、動画全体を処理するかを指定します。
  • video_metadata (Union[VideoMetadata, dict], 省略可) — 総再生時間、fps、総フレーム数などの情報が含まれる、動画のメタデータ。
  • num_frames (int, 任意) — do_sample_frames=True の場合、サンプリングするフレーム数の最大値。
  • fps (int または float、省略可) — do_sample_frames=True の場合、1 秒あたりサンプリングするターゲットフレーム数。
  • crop_size (dict[str, int], 任意) — 中央クロップを適用する際の、希望する出力サイズ。
  • data_format (ChannelDimension または str、省略可) — 出力動画のチャネル次元の形式です。
  • input_data_format (ChannelDimension または str、省略可) — 入力動画のチャネル次元の形式です。
  • device (Union[str, torch.Tensor], 省略可) — 処理に使用するデバイス（例: “cpu”、“cuda”）。高速な画像処理の場合のみ関連します。
  • return_metadata (bool, 省略可) — 動画メタデータを返すかどうかを指定します。
  • return_tensors (str または TensorType, 省略可) — 設定すると、特定のフレームワークのテンソルを返します。使用可能な値は以下の通りです:
    • 'pt': PyTorchのtorch.Tensorオブジェクトを返します。
    • 'np': NumPyのnp.ndarrayオブジェクトを返します。

動画処理用のキーワード引数。

class transformers.AudioKwargs

< >

( )

パラメータ

  • sampling_rate (int, 任意) — raw_speech 入力がサンプリングされたレート。
  • raw_speech (np.ndarray、list[float]、list[np.ndarray]、list[list[float]]) — パディング対象のシーケンスまたはシーケンスのバッチです。各シーケンスは、NumPy 配列、浮動小数点数の値のリスト、NumPy 配列のリスト、または浮動小数点数の値のリストのリストであることができます。モノラル音声（ステレオではなく、タイムステップごとに単一の浮動小数点数）である必要があります。
  • padding (bool, str または PaddingStrategy, 省略可) — 返されるシーケンスのパディング戦略を、モデルのパディング側とパディングインデックスに基づいて、以下のいずれかから選択します:
    • Trueまたは'longest': バッチ内の最長のシーケンスの長さにパディングします（単一のシーケンスのみが提供された場合は、パディングを行いません）。
    • 'max_length': 引数 max_length で指定された最大長、またはその引数が指定されていない場合はモデルが受け入れ可能な最大入力長までパディングします。
    • False または 'do_not_pad'
  • max_length (int, 任意) — 返されるリストの最大長、および必要に応じてパディングの長さ（上記を参照）。
  • truncation (bool、任意) — 入力シーケンスが max_length を超える場合、max_length に切り詰めるための切り詰め処理を有効にします。
  • pad_to_multiple_of (int, 省略可) — 設定した場合、シーケンスを指定された値の倍数にパディングします。
  • return_attention_mask (bool, オプション) — call() が attention_mask を返すかどうかを指定します。
  • device (str または torch.device、省略可) — 音声特徴量を計算するデバイス（例: “cpu”、“cuda”）です。torch を用いて特徴量を計算する特徴量抽出器の場合にのみ関連します。
  • return_tensors (str または TensorType, 省略可) — 設定すると、特定のフレームワークのテンソルを返します。使用可能な値は以下の通りです:
    • 'pt': PyTorchのtorch.Tensorオブジェクトを返します。
    • 'np': NumPyのnp.ndarrayオブジェクトを返します。
  • load_audio_backend (str, 省略可) — apply_chat_template 内の URL/パスで参照されるオーディオのデコード/リサンプリングに、load_audio() が使用するバックエンドです。"auto"、"torchcodec"、"soundfile"、"torchaudio" のいずれかです（"librosa" は "soundfile" の非推奨エイリアスです）。

音声処理用のキーワード引数。

Update on GitHub

←パイプライン エクスポート→