Transformers documentation

ビジョン処理コンポーネントを追加

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

ビジョン処理コンポーネントを追加

ビジョンモデルを追加するには、標準的なモジュラーアプローチに加えて、画像または動画の処理コンポーネントが必要です。画像のみを扱うモデルには画像プロセッサが必要であり、動画モデルには動画プロセッサが必要です。これらはそれぞれAutoImageProcessorおよびAutoVideoProcessorのエントリポイントからアクセスできます。

モデリングと設定の手順については、まずモジュラーガイドに従ってください。

画像プロセッサ

モデルが画像を消費する場合に、画像プロセッサを作成します。torchvisionバックエンドがデフォルトであり、GPUアクセラレーションをサポートしています。PILは、torchvisionが利用できない場合のフォールバックです。

両方の画像プロセッサクラスは同じ前処理ロジックを共有していますが、バックエンドが異なります。コンストラクタのシグネチャとデフォルト値は同一である必要があります。AutoImageProcessor.from_pretrained()は読み込み時にバックエンドを選択し、torchvision が利用できない場合は PIL にフォールバックします。シグネチャが一致しない場合、同じ保存済み設定が環境によって異なる挙動を示す原因になります。

torchvision

image_processing_<model_name>.py を作成し、TorchvisionBackend を継承するクラスを定義してください。プロセッサが標準の [ImagesKwargs] 以外のカスタムパラメータを必要とする場合は、kwargs クラスを定義してください。

from ...image_processing_backends import TorchvisionBackend
from ...image_utils import OPENAI_CLIP_MEAN, OPENAI_CLIP_STD, PILImageResampling
from ...processing_utils import ImagesKwargs, Unpack
from ...utils import auto_docstring

class MyModelImageProcessorKwargs(ImagesKwargs, total=False):
    tile_size: int  # any model-specific kwargs

@auto_docstring
class MyModelImageProcessor(TorchvisionBackend):
    resample = PILImageResampling.BICUBIC
    image_mean = OPENAI_CLIP_MEAN
    image_std = OPENAI_CLIP_STD
    size = {"shortest_edge": 224}
    do_resize = True
    do_rescale = True
    do_normalize = True
    do_convert_rgb = True

    def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]):
        super().__init__(**kwargs)

参考として、LlavaOnevisionImageProcessorを参照してください。

PIL

image_processing_pil_<model_name>.py を作成し、PilBackend を継承するクラスを定義します。torchvision がインストールされていない場合に失敗する可能性があるため、torchvision のファイルからインポートするのではなく、kwargs クラスをここに複製してください。両者が同期されるよう、# Adapted from のコメントを追加します。カスタムパラメータのないプロセッサでは、ImagesKwargs を直接使用します。

from ...image_processing_backends import PilBackend
from ...image_utils import OPENAI_CLIP_MEAN, OPENAI_CLIP_STD, PILImageResampling
from ...processing_utils import ImagesKwargs, Unpack
from ...utils import auto_docstring

# Adapted from transformers.models.my_model.image_processing_my_model.MyModelImageProcessorKwargs
class MyModelImageProcessorKwargs(ImagesKwargs, total=False):
    tile_size: int  # any model-specific kwargs

@auto_docstring
class MyModelImageProcessorPil(PilBackend):
    resample = PILImageResampling.BICUBIC
    image_mean = OPENAI_CLIP_MEAN
    image_std = OPENAI_CLIP_STD
    size = {"shortest_edge": 224}
    do_resize = True
    do_rescale = True
    do_normalize = True
    do_convert_rgb = True

    def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]):
        super().__init__(**kwargs)

参考として、LlavaOnevisionImageProcessorPilを参照してください。

後処理メソッドを追加する

後処理メソッドをプロセッサクラスに直接追加します。後処理メソッドは、モデルの出力(outputs)と、特定の後処理メソッドに必要な追加引数とともに呼び出されます。

class MyModelImageProcessor(TorchvisionBackend):
    ...

    def post_process_my_task(self, outputs, ...):
        ...

Post-processor は、単純なオブジェクトのリスト(list[str] または list[torch.Tensor])または複雑なオブジェクトのリスト(list[MyTaskPostProcessorOutput] または list[dict])を返します。Post-processor の出力は src/transformers/image_processing_outputs.py で定義され、BatchFeature を継承します。

class MyTaskPostProcessorOutput(BatchFeature):
    predictions: torch.Tensor
    scores: torch.Tensor

Video processor

モデルが動画またはサンプリングされた動画フレームを消費する場合、ビデオプロセッサを追加します。

モデルディレクトリにvideo_processing_<model_name>.pyを作成します。BaseVideoProcessorはTorchvisionBackendを継承し、デコード、フレームサンプリング、リサイズ、リスケール、正規化、保存、読み込みの共通動作を提供します。

クラス属性は、前処理のデフォルト値です。ユーザーは初期化時または呼び出し時にこれらをオーバーライドできます。size、crop_size、do_resize、do_sample_frames、num_frames、fps など、可能な限り VideosKwargs と同じ名前を使用してください。

動画プロセッサに標準の VideosKwargs 以外のカスタムパラメータが必要な場合は、kwargs クラスを定義してください。valid_kwargs に設定し、__init__ のアノテーションに使用して、実行時検証と自動生成されるドキュメント文字列の両方に反映させます。

from ...processing_utils import Unpack, VideosKwargs
from ...utils import auto_docstring
from ...video_processing_utils import BaseVideoProcessor

class MyModelVideoProcessorKwargs(VideosKwargs, total=False):
    min_frames: int
    max_frames: int

@auto_docstring
class MyModelVideoProcessor(BaseVideoProcessor):
    size = {"shortest_edge": 224}
    crop_size = {"height": 224, "width": 224}
    do_resize = True
    do_center_crop = True
    do_normalize = True
    do_sample_frames = True
    num_frames = 16
    model_input_names = ["pixel_values_videos"]
    valid_kwargs = MyModelVideoProcessorKwargs

    def __init__(self, **kwargs: Unpack[MyModelVideoProcessorKwargs]):
        super().__init__(**kwargs)

ベースの均一サンプリャーでは表現できないサンプリングルールをモデルが要求する場合のみ、sample_frames()をオーバーライドしてください。例えば、一部のモデルはフレーム数の最小値または最大値を強制したり、モデル固有の制約に基づいてサンプリングしたりします。

モデルの forward メソッドがレガシーな入力名を期待している場合は、preprocess をオーバーライドし、ベース実装を呼び出した後にキーの名前を変更してください。

class MyModelVideoProcessor(BaseVideoProcessor):
    model_input_names = ["pixel_values"]

    def preprocess(self, videos, **kwargs):
        batch = super().preprocess(videos, **kwargs)
        batch["pixel_values"] = batch.pop("pixel_values_videos")
        return batch

変換スクリプト内でインスタンス化し、save_pretrained() を呼び出すことで、チェックポイントにビデオプロセッサを保存します。ProcessorMixin がビデオプロセッサをラップしている場合は、代わりに save_pretrained() を呼び出してください。前処理設定ファイルを手動で作成したり編集したりしないでください。

参考として、Qwen3VLVideoProcessorを参照してください。

クラスを登録する

ファイルの末尾にある__all__に新しいクラスを追加し、次に以下で__init__.pyを再生成します:

python utils/check_inits.py --fix_and_overwrite

Auto クラスが新しいクラスを読み込めるように、モデル設定にマッピングします。生成されたオートマッピングファイルの上部には警告が表示されています。手動で編集しないでください。モデル設定を追加または更新してから、以下を実行します:

python utils/check_auto.py --fix_and_overwrite

マッピングが生成された後、src/transformers/models/auto/auto_mappings.py の関連するマッピングにモデルタイプが表示されることを確認してください。

テスト

モデルのテストディレクトリに、ビジョン処理コンポーネントごとにテストを追加します。共有のテストミックスインを使用し、モデル固有の初期化キーワード引数(kwargs)を指定します。画像のテストは共有のテスターを通じてプロセッサのバックエンドを自動的に検出しますが、動画のテストではプロセッサクラスとフィクスチャを明示的に設定します。

画像プロセッサのテスト

Image processor のテストは tests/models/<model_name>/test_image_processing_<model_name>.py にあります。ImageProcessingTester を継承する tester と、ImageProcessingTestMixin および unittest.TestCase を継承するテストクラスを定義してください。

画像処理のテスターは、プロセッサの初期化引数やテスト用のランダムな入力を生成するためのパラメータなど、デフォルトのテスト属性を定義します。画像プロセッサのデフォルトと異なる場合にのみ、引数をオーバーライドしてください。例えば、テストを高速に保つために、通常はより小さい画像サイズでテストを行います。画像プロセッサのクラスは、IMAGE_PROCESSOR_MAPPING_NAMESから自動的に推論されます。

テストクラスにimage_processor_tester_classを設定します。ミックスインはself.image_processor_testerを作成し、必要なテストメソッドの大部分をすでにカバーしています。

import unittest

from transformers.testing_utils import require_torch, require_vision
from ...test_image_processing_common import ImageProcessingTestMixin, ImageProcessingTester


class MyModelImageProcessingTester(ImageProcessingTester):
    def __init__(self, **kwargs):
        # Random test inputs kwargs
        kwargs.setdefault("batch_size", 2)          # default: 7     
        kwargs.setdefault("num_channels", 4)        # default: 3
        kwargs.setdefault("min_resolution", 20)     # default: 30
        kwargs.setdefault("max_resolution", 100)    # default: 400

        # Image processor init kwargs
        kwargs.setdefault("size", {"shortest_edge": 20})
        kwargs.setdefault("crop_size", {"height": 18, "width": 18})

        super().__init__(**kwargs)


@require_torch
@require_vision
class MyModelImageProcessingTest(ImageProcessingTestMixin, unittest.TestCase):
    image_processor_tester_class = MyModelImageProcessingTester

    def test_inherits_from_mixin(self):
        # Always iterate over all image processing classes
        for image_processing_class in self.image_processing_classes.values():
            # self.image_processor_dict contains the default processor init kwargs
            # including overrides from the tester.
            image_processor = image_processing_class(**self.image_processor_dict)
            self.assertIsInstance(image_processor, ImageProcessingMixin)

ミックスインが推論できない動作、例えばカスタムのリサイズルールやモデル固有のkwargsなどについては、焦点を絞ったテストを追加してください。

後処理のテストミックスインはtests/test_image_processing_common.pyに用意されており、ImageProcessingTestMixinの上に追加されます。

class MyModelImageProcessingTest(ImageProcessingTestMixin, MyTaskPostProcessTestMixin, unittest.TestCase):
    image_processor_tester_class = MyModelImageProcessingTester

テストは、モデルに正しいミックスインが使用されていることを自動的に検証します。新しいタスク用のミックスインは、tests/test_image_processing_common.py に追加する必要があります。

Video processor tests

Video processor のテストは通常、tests/models/<model_name>/test_video_processing_<model_name>.py に配置され、VideoProcessingTestMixin を継承します。fast_video_processing_class を設定し、video_processor_dict を定義してください。モデルが pixel_values_videos 以外のキーを使用する場合は、input_name をオーバーライドしてください。

from transformers.testing_utils import require_torch, require_vision
from transformers.utils import is_torchvision_available
from ...test_video_processing_common import VideoProcessingTestMixin

@require_torch
@require_vision
class MyModelVideoProcessingTest(VideoProcessingTestMixin, unittest.TestCase):
    fast_video_processing_class = MyModelVideoProcessor if is_torchvision_available() else None
    input_name = "pixel_values_videos"

    @property
    def video_processor_dict(self):
        return {"size": {"shortest_edge": 224}, "num_frames": 16}

フレームサンプリング、メタデータ処理、デコード済み動画入力、フレームリスト入力、および出力形状に焦点を当てた動画テストを追加します。プロセッサがpixel_values_videosをリネームする場合は、リネームされたキーが返されることをアサートしてください。

モデルが画像または動画プロセッサをラップする ProcessorMixin も持っている場合は、tests/models/<model_name>/test_processing_<model_name>.py を追加し、ProcessorTesterMixin を継承します。processor_class を設定し、引数なしでは構築できないコンポーネントについては、_setup_<component>() クラスメソッドをオーバーライドします。共通のプロセッサテストで使用されるプレースホルダトークンを公開するには、_setup_test_attributes() を使用します。

from ...test_processing_common import ProcessorTesterMixin

class MyModelProcessorTest(ProcessorTesterMixin, unittest.TestCase):
    processor_class = MyModelProcessor

    @classmethod
    def _setup_image_processor(cls):
        return cls._get_component_class_from_processor("image_processor")(size={"shortest_edge": 224})

    @classmethod
    def _setup_video_processor(cls):
        return cls._get_component_class_from_processor("video_processor")(num_frames=2)

    @classmethod
    def _setup_test_attributes(cls, processor):
        cls.image_token = getattr(processor, "image_token", "")
        cls.video_token = getattr(processor, "video_token", "")

次のステップ

Update on GitHub