Transformers documentation

Thêm các thành phần xử lý thị giác

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Thêm các thành phần xử lý thị giác

Việc thêm một mô hình thị giác đòi hỏi các thành phần xử lý ảnh hoặc video bên cạnh cách tiếp cận modular tiêu chuẩn. Các mô hình chỉ xử lý ảnh cần bộ xử lý ảnh, còn các mô hình video cần bộ xử lý video, cả hai đều có thể truy cập thông qua các điểm vào AutoImageProcessor và AutoVideoProcessor.

Đối với các bước mô hình hóa và cấu hình, hãy làm theo hướng dẫn modular trước.

Bộ xử lý hình ảnh

Tạo bộ xử lý ảnh khi mô hình tiêu thụ ảnh. Backend torchvision là mặc định và hỗ trợ tăng tốc GPU. PIL là phương án dự phòng khi torchvision không khả dụng.

Cả hai lớp image processor đều chia sẻ cùng một logic tiền xử lý nhưng có các backend khác nhau. Chữ ký constructor và các giá trị mặc định của chúng phải giống hệt nhau. AutoImageProcessor.from_pretrained() sẽ chọn backend tại thời điểm tải và chuyển sang PIL khi torchvision không khả dụng. Việc chữ ký không khớp sẽ khiến cùng một config đã lưu có hành vi khác nhau giữa các môi trường.

torchvision

Tạo image_processing_<model_name>.py với một class kế thừa từ TorchvisionBackend. Nếu processor của bạn cần các tham số tùy chỉnh ngoài [ImagesKwargs] chuẩn, hãy định nghĩa một class 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)

Xem LlavaOnevisionImageProcessor để tham khảo.

PIL

Tạo image_processing_pil_<model_name>.py với một class kế thừa từ PilBackend. Sao chép class kwargs tại đây thay vì import từ file torchvision vì nó có thể thất bại khi torchvision chưa được cài đặt. Thêm chú thích # Adapted from để hai file đồng bộ với nhau. Đối với các processor không có tham số tùy chỉnh, hãy dùng trực tiếp 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)

Xem LlavaOnevisionImageProcessorPil để tham khảo.

Thêm các phương pháp xử lý hậu kỳ

Thêm các phương pháp xử lý hậu kỳ trực tiếp vào lớp processor. Các phương pháp xử lý hậu kỳ được gọi với đầu ra của mô hình (outputs) và bất kỳ đối số bổ sung nào cần thiết cho phương pháp xử lý hậu kỳ cụ thể.

class MyModelImageProcessor(TorchvisionBackend):
    ...

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

Post-processor trả về một danh sách các đối tượng đơn giản (list[str] hoặc list[torch.Tensor]) hoặc một danh sách các đối tượng phức tạp (list[MyTaskPostProcessorOutput] hoặc list[dict]). Đầu ra của post-processor được định nghĩa trong src/transformers/image_processing_outputs.py và kế thừa từ BatchFeature.

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

Bộ xử lý video

Thêm một video processor khi mô hình sử dụng video hoặc các khung hình video được lấy mẫu.

Tạo video_processing_<model_name>.py trong thư mục model. BaseVideoProcessor kế thừa từ TorchvisionBackend và cung cấp các hành vi chung cho việc giải mã, lấy mẫu khung hình, thay đổi kích thước, thay đổi tỷ lệ, chuẩn hóa, lưu và tải.

Các thuộc tính của lớp là các giá trị tiền xử lý mặc định. Người dùng có thể ghi đè chúng khi khởi tạo hoặc khi gọi. Hãy sử dụng cùng tên với VideosKwargs khi có thể, chẳng hạn như size, crop_size, do_resize, do_sample_frames, num_frames và fps.

Định nghĩa một lớp kwargs nếu trình xử lý video của bạn cần các tham số tùy chỉnh ngoài VideosKwargs tiêu chuẩn. Đặt nó làm valid_kwargs và sử dụng nó để chú thích __init__ cho cả xác thực thời gian chạy và docstring được tạo tự động.

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)

Chỉ ghi đè sample_frames() khi mô hình yêu cầu một quy tắc lấy mẫu mà bộ lấy mẫu đều cơ sở không thể biểu diễn. Ví dụ, một số mô hình áp đặt số khung hình tối thiểu hoặc tối thiểu, hoặc lấy mẫu dựa trên các ràng buộc cụ thể của mô hình.

Nếu phương thức forward của model kỳ vọng một tên input cũ, hãy ghi đè preprocess và đổi tên key sau khi gọi implementation gốc.

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

Lưu video processor cùng với checkpoint bằng cách khởi tạo nó trong script chuyển đổi và gọi save_pretrained(). Nếu ProcessorMixin bao bọc video processor, hãy gọi save_pretrained() thay thế. Không tự động tạo hoặc chỉnh sửa các tệp cấu hình tiền xử lý.

Xem Qwen3VLVideoProcessor để tham khảo.

Đăng ký các lớp

Thêm các lớp mới vào __all__ ở cuối tệp, sau đó tạo lại __init__.py bằng:

python utils/check_inits.py --fix_and_overwrite

Ánh xạ các lớp mới vào cấu hình mô hình để các lớp Auto có thể tải chúng. Tệp ánh xạ auto được tạo có một cảnh báo ở đầu. Không chỉnh sửa thủ công. Thêm hoặc cập nhật cấu hình mô hình, sau đó chạy:

python utils/check_auto.py --fix_and_overwrite

Sau khi ánh xạ được tạo, hãy kiểm tra xem loại mô hình có xuất hiện trong các ánh xạ liên quan trong src/transformers/models/auto/auto_mappings.py hay không.

Kiểm thử

Thêm các bài kiểm tra cho từng thành phần xử lý thị giác trong thư mục kiểm tra mô hình. Sử dụng các mixin kiểm tra dùng chung và cung cấp các tham số khởi tạo cụ thể cho mô hình. Các bài kiểm tra ảnh tự động phát hiện các backend của processor thông qua một tester dùng chung, trong khi các bài kiểm tra video cấu hình lớp processor và các fixture một cách tường minh.

Kiểm tra bộ xử lý ảnh

Các bài kiểm tra bộ xử lý ảnh nằm trong tests/models/<model_name>/test_image_processing_<model_name>.py. Hãy định nghĩa một tester kế thừa từ ImageProcessingTester và một lớp kiểm thử kế thừa từ ImageProcessingTestMixin và unittest.TestCase.

Trình kiểm tra xử lý ảnh định nghĩa các thuộc tính kiểm thử mặc định, chẳng hạn như các đối số khởi tạo bộ xử lý và các tham số để tạo đầu vào ngẫu nhiên cho các bài kiểm tra. Chỉ ghi đè các đối số nếu chúng cần khác với giá trị mặc định của bộ xử lý ảnh. Ví dụ, chúng ta thường kiểm thử với kích thước ảnh nhỏ hơn để giữ cho các bài kiểm tra chạy nhanh. Các lớp bộ xử lý ảnh được suy ra tự động từ IMAGE_PROCESSOR_MAPPING_NAMES.

Đặt image_processor_tester_class trên lớp kiểm thử. Mixin tạo ra self.image_processor_tester và đã bao phủ hầu hết các phương thức kiểm thử cần thiết.

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)

Thêm các bài kiểm tra tập trung cho hành vi mà mixin không thể suy luận, chẳng hạn như các quy tắc thay đổi kích thước tùy chỉnh hoặc các tham số kwargs cụ thể cho từng model.

Các mixin kiểm tra hậu xử lý có sẵn trong tests/test_image_processing_common.py và được thêm vào bên trên ImageProcessingTestMixin.

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

Các bài kiểm tra tự động xác minh rằng các mixin đúng được sử dụng cho mô hình của bạn. Các mixin cho các tác vụ mới phải được thêm vào tests/test_image_processing_common.py.

Kiểm tra bộ xử lý video

Các bài kiểm tra video processor thường nằm trong tests/models/<model_name>/test_video_processing_<model_name>.py và kế thừa từ VideoProcessingTestMixin. Hãy đặt fast_video_processing_class, định nghĩa video_processor_dict, và ghi đè input_name nếu model sử dụng một key khác với pixel_values_videos.

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}

Thêm các bài kiểm tra video tập trung cho việc lấy mẫu khung hình, xử lý metadata, đầu vào video đã giải mã, đầu vào dạng danh sách khung hình và hình dạng đầu ra. Nếu bộ xử lý của bạn đổi tên pixel_values_videos, hãy khẳng định rằng khóa đã đổi tên được trả về.

Nếu model cũng có ProcessorMixin bao bọc image hoặc video processor, hãy thêm tests/models/<model_name>/test_processing_<model_name>.py và kế thừa từ ProcessorTesterMixin. Đặt processor_class và ghi đè các class method _setup_<component>() cho các component không thể được khởi tạo mà không có đối số. Sử dụng _setup_test_attributes() để phơi bày các placeholder token được dùng bởi các processor tests chung.

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", "")

Các bước tiếp theo

Update on GitHub