# ビジョン処理コンポーネントを追加 ビジョンモデルを追加するには、標準的な[モジュラー](./modular_transformers)アプローチに加えて、画像または動画の処理コンポーネントが必要です。画像のみを扱うモデルには画像プロセッサが必要であり、動画モデルには動画プロセッサが必要です。これらはそれぞれ[AutoImageProcessor](/docs/transformers/main/ja/model_doc/auto#transformers.AutoImageProcessor)および[AutoVideoProcessor](/docs/transformers/main/ja/model_doc/auto#transformers.AutoVideoProcessor)のエントリポイントからアクセスできます。 > [!NOTE] > モデリングと設定の手順については、まず[モジュラー](./modular_transformers)ガイドに従ってください。 ## 画像プロセッサ モデルが画像を処理する場合に、画像プロセッサを作成します。デフォルトのバックエンドは[torchvision](https://docs.pytorch.org/vision/stable/index.html)で、GPUアクセラレーションに対応しています。[PIL](https://pillow.readthedocs.io/en/stable/index.html)は、torchvisionが利用できない場合のフォールバックです。 両方の image processor クラスは同じ前処理ロジックを共有していますが、バックエンドが異なります。コンストラクタのシグネチャとデフォルト値は同一である必要があります。[AutoImageProcessor.from_pretrained()](/docs/transformers/main/ja/model_doc/auto#transformers.AutoImageProcessor.from_pretrained) は読み込み時にバックエンドを選択し、torchvision が利用できない場合は PIL にフォールバックします。シグネチャが一致しない場合、同じ保存済み設定でも環境によって動作が異なってしまいます。 ### torchvision `image_processing_.py` を作成し、[TorchvisionBackend](/docs/transformers/main/ja/main_classes/image_processor#transformers.TorchvisionBackend) を継承するクラスを定義してください。プロセッサが標準の [ImagesKwargs] 以外のカスタムパラメータを必要とする場合は、kwargs クラスを定義してください。 ```py 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) ``` > [!TIP] > 参考として、[LlavaOnevisionImageProcessor](/docs/transformers/main/ja/model_doc/llava_onevision#transformers.LlavaOnevisionImageProcessor)を参照してください。 ### PIL `image_processing_pil_.py` を作成し、[PilBackend](/docs/transformers/main/ja/main_classes/image_processor#transformers.PilBackend) を継承するクラスを定義します。torchvision がインストールされていない場合に失敗する可能性があるため、torchvision のファイルからインポートするのではなく、ここで kwargs クラスを複製します。両者が同期するように、`# Adapted from` のコメントを追加します。カスタムパラメータのないプロセッサーでは、[ImagesKwargs](/docs/transformers/main/ja/main_classes/processors#transformers.ImagesKwargs) を直接使用します。 ```py 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) ``` > [!TIP] > 参考として、[LlavaOnevisionImageProcessorPil](/docs/transformers/main/ja/model_doc/llava_onevision#transformers.LlavaOnevisionImageProcessorPil)を参照してください。 ### 後処理メソッドを追加する 後処理メソッドをプロセッサクラスに直接追加します。後処理メソッドは、モデルの出力（`outputs`）と、特定の後処理メソッドに必要な追加引数とともに呼び出されます。 ```py 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](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.BatchFeature) を継承します。 ```py class MyTaskPostProcessorOutput(BatchFeature): predictions: torch.Tensor scores: torch.Tensor ``` ## Video processor モデルが動画またはサンプリングされた動画フレームを消費する場合、ビデオプロセッサを追加します。 モデルディレクトリに`video_processing_.py`を作成します。[BaseVideoProcessor](/docs/transformers/main/ja/main_classes/video_processor#transformers.BaseVideoProcessor)は[TorchvisionBackend](/docs/transformers/main/ja/main_classes/image_processor#transformers.TorchvisionBackend)を継承し、デコード、フレームサンプリング、リサイズ、リスケール、正規化、保存、読み込みの共通動作を提供します。 クラス属性は、前処理のデフォルト値です。ユーザーは初期化時または呼び出し時にこれらをオーバーライドできます。`size`、`crop_size`、`do_resize`、`do_sample_frames`、`num_frames`、`fps` など、可能な限り [VideosKwargs](/docs/transformers/main/ja/main_classes/processors#transformers.VideosKwargs) と同じ名前を使用してください。 動画プロセッサに標準の [VideosKwargs](/docs/transformers/main/ja/main_classes/processors#transformers.VideosKwargs) 以外のカスタムパラメータが必要な場合は、kwargs クラスを定義してください。`valid_kwargs` に設定し、`__init__` のアノテーションに使用して、実行時検証と自動生成されるドキュメント文字列の両方に反映させます。 ```py 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()](/docs/transformers/main/ja/main_classes/video_processor#transformers.BaseVideoProcessor.sample_frames) をオーバーライドしてください。例えば、一部のモデルはフレーム数の最小値や最大値を強制したり、モデル固有の制約に基づいてサンプリングしたりします。 モデルの forward メソッドがレガシーな入力名を期待している場合は、`preprocess` をオーバーライドし、ベース実装を呼び出した後にキーの名前を変更してください。 ```py 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()](/docs/transformers/main/ja/main_classes/video_processor#transformers.VideoProcessorMixin.save_pretrained) を呼び出すことで、チェックポイントにビデオプロセッサを保存します。[ProcessorMixin](/docs/transformers/main/ja/main_classes/processors#transformers.ProcessorMixin) がビデオプロセッサをラップしている場合は、代わりに [save_pretrained()](/docs/transformers/main/ja/model_doc/wav2vec2#transformers.Wav2Vec2Processor.save_pretrained) を呼び出してください。前処理設定ファイルを手動で作成したり編集したりしないでください。 > [!TIP] > 参考として、[Qwen3VLVideoProcessor](/docs/transformers/main/ja/model_doc/qwen3_vl#transformers.Qwen3VLVideoProcessor)を参照してください。 ## クラスを登録する ファイルの末尾にある`__all__`に新しいクラスを追加し、次に以下で`__init__.py`を再生成します: ```bash python utils/check_inits.py --fix_and_overwrite ``` `Auto` クラスが新しいクラスを読み込めるように、モデル設定にマッピングします。生成されたオートマッピングファイルの上部には警告が表示されています。手動で編集しないでください。モデル設定を追加または更新してから、以下を実行します: ```bash python utils/check_auto.py --fix_and_overwrite ``` マッピングが生成された後、`src/transformers/models/auto/auto_mappings.py` の関連するマッピングにモデルタイプが表示されることを確認してください。 - `IMAGE_PROCESSOR_MAPPING_NAMES` は [AutoImageProcessor](/docs/transformers/main/ja/model_doc/auto#transformers.AutoImageProcessor) 用です - [AutoVideoProcessor](/docs/transformers/main/ja/model_doc/auto#transformers.AutoVideoProcessor) 用の `VIDEO_PROCESSOR_MAPPING_NAMES` ## テスト モデルのテストディレクトリに、ビジョン処理コンポーネントごとにテストを追加します。共有のテストミックスインを使用し、モデル固有の初期化キーワード引数（kwargs）を指定します。画像のテストは共有のテスターを通じてプロセッサのバックエンドを自動的に検出しますが、動画のテストではプロセッサクラスとフィクスチャを明示的に設定します。 ### 画像プロセッサのテスト Image processor のテストは `tests/models//test_image_processing_.py` にあります。`ImageProcessingTester` を継承する tester と、`ImageProcessingTestMixin` および `unittest.TestCase` を継承するテストクラスを定義してください。 画像処理のテスターは、プロセッサの初期化引数やテスト用のランダムな入力を生成するためのパラメータなど、デフォルトのテスト属性を定義します。画像プロセッサのデフォルトと異なる場合にのみ、引数をオーバーライドしてください。例えば、テストを高速に保つために、通常はより小さい画像サイズでテストを行います。画像プロセッサのクラスは、`IMAGE_PROCESSOR_MAPPING_NAMES`から自動的に推論されます。 テストクラスに`image_processor_tester_class`を設定します。ミックスインは`self.image_processor_tester`を作成し、必要なテストメソッドの大部分をすでにカバーしています。 ```py 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`の上に追加されます。 ```py class MyModelImageProcessingTest(ImageProcessingTestMixin, MyTaskPostProcessTestMixin, unittest.TestCase): image_processor_tester_class = MyModelImageProcessingTester ``` テストは、モデルに正しいミックスインが使用されていることを自動的に検証します。新しいタスク用のミックスインは、`tests/test_image_processing_common.py` に追加する必要があります。 ### Video processor tests Video processor のテストは通常、`tests/models//test_video_processing_.py` に配置され、`VideoProcessingTestMixin` を継承します。`fast_video_processing_class` を設定し、`video_processor_dict` を定義してください。モデルが `pixel_values_videos` 以外のキーを使用する場合は、`input_name` をオーバーライドしてください。 ```py 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](/docs/transformers/main/ja/main_classes/processors#transformers.ProcessorMixin) も持っている場合は、`tests/models//test_processing_.py` を追加し、`ProcessorTesterMixin` を継承します。`processor_class` を設定し、引数なしでは構築できないコンポーネントについては、`_setup_()` クラスメソッドをオーバーライドします。共通のプロセッサテストで使用されるプレースホルダトークンを公開するには、`_setup_test_attributes()` を使用します。 ```py 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", "") ``` ## 次のステップ - `@auto_docstring` を使用して一貫性のあるドキュメント文字列を自動生成するには、[ドキュメント文字列の自動生成](./auto_docstring)ガイドをお読みください。 - ユーザー向けの前処理の動作については、[Image processors](./image_processors)および[Video processors](./video_processors)のガイドを参照してください。