Transformers documentation
ビジョン処理コンポーネントを追加
ビジョン処理コンポーネントを追加
ビジョンモデルを追加するには、標準的なモジュラーアプローチに加えて、画像または動画の処理コンポーネントが必要です。画像のみを扱うモデルには画像プロセッサが必要であり、動画モデルには動画プロセッサが必要です。これらはそれぞれ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.TensorVideo 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 の関連するマッピングにモデルタイプが表示されることを確認してください。
IMAGE_PROCESSOR_MAPPING_NAMESは AutoImageProcessor 用です- AutoVideoProcessor 用の
VIDEO_PROCESSOR_MAPPING_NAMES
テスト
モデルのテストディレクトリに、ビジョン処理コンポーネントごとにテストを追加します。共有のテストミックスインを使用し、モデル固有の初期化キーワード引数（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", "")次のステップ
@auto_docstringを使用して一貫性のあるドキュメント文字列を自動生成するには、ドキュメント文字列の自動生成ガイドをお読みください。- ユーザー向けの前処理の動作については、Image processorsおよびVideo processorsのガイドを参照してください。