Transformers documentation
Мультимодальные процессоры
Мультимодальные процессоры
Процессор объединяет токенизатор с одним или несколькими процессорами модальностей, такими как процессор изображений, процессор видео или извлекатель признаков. Он предоставляет единый метод __call__, который направляет каждый входной объект в соответствующий компонент и объединяет результаты в один словарь.
Некоторые мультимодальные модели чередуют текст с изображениями, видео или аудио. Для таких моделей ProcessorMixin может заменить плейсхолдерные токены, такие как <image>, <video> и <audio>, на паттерн токенов, ожидаемый моделью.
Добавление нового процессора
Определите класс процессора, создав src/transformers/models/<model>/processing_<my_model_name>.py и унаследовав его от ProcessorMixin. Убедитесь, что вы определили объект TypedDict со значениями по умолчанию и назначили его как cls.valid_processor_kwargs
from ...processing_utils import ProcessorMixin
class MyModelProcessor(ProcessorMixin):
def __init__(self, image_processor, tokenizer, chat_template=None, **kwargs):
self.image_token = tokenizer.image_token
self.image_token_id = tokenizer.image_token_id
super().__init__(
image_processor=image_processor,
tokenizer=tokenizer,
chat_template=chat_template,
**kwargs,
)При необходимости реализуйте replace_<modality>_token. Метод принимает полный словарь вывода из подпроцессора и индекс текущего входа, а возвращает расширенную строку замены для этого входа. Строка замены — это то, что модель ожидает в входной последовательности.
Если модель вообще не использует повторение плейсхолдеров (не определён image_token), переопределять этот метод не нужно. Оставьте self.image_token не установленным, и базовый класс полностью пропустит замену.
def replace_image_token(self, image_inputs: dict, image_idx: int) -> str:
num_crops = image_inputs["num_crops"][image_idx]
return f"{self.boi_token}{self.image_token * self.num_image_tokens * num_crops}{self.eoi_token}"При необходимости переопределите методы prepare_inputs_layout и validate_inputs. Это требуется, если модели нужна определенная структура входных данных перед началом обработки, например, перестановка изображений в виде вложенного списка, или если необходимо выполнить специфичную для модели валидацию в дополнение к общим проверкам.
def prepare_inputs_layout(self, images=None, text=None, videos=None, audio=None, **kwargs):
# Call `super()` to apply common preparation steps first
images, text, videos, audio = super().prepare_inputs_layout(images, text, videos, audio)
if images is not None:
images = make_nested_list_of_images(images)
return images, text, videos, audio
def validate_inputs(self, images=None, text=None, videos=None, audio=None, **kwargs):
super().validate_inputs(images=images, text=text, **kwargs)
if text is not None and images is not None:
n_tokens = [s.count(self.image_token) for s in text]
n_images = [len(img_list) for img_list in images]
if n_tokens != n_images:
raise ValueError(
f"Number of {self.image_token} tokens in text {n_tokens} does not match "
f"number of images {n_images}."
)См. Gemma4Processor и Qwen2VLProcessor для справки.
Добавление пользовательских аргументов
Существует три способа добавить пользовательские аргументы в процессор:
| Куда добавить | Использование | Значение по умолчанию | Настраивается во время выполнения | Пример |
|---|---|---|---|---|
__init__ | Настройки, сохранённые в конфигурации (свойства модели) | Обычно имеет значение по умолчанию | Нет | image_seq_length в Gemma3Processor |
__call__ | Входы, известные только во время выполнения | По умолчанию или None | Да | images, labels, suffix и т. д. |
Пользовательский класс MyModelProcessingKwargs | Настройки, которые можно настроить во время выполнения | Установить как атрибут класса процессора | Да | use_image_id в MiniCPMV4_7Processor |
Аргументы времени выполнения, для которых может быть задано значение по умолчанию, должны быть добавлены в пользовательский MyModelProcessingKwargs и передаваться как часть **kwargs в __call__. Значения по умолчанию для этих параметров можно задать как атрибуты класса процессора. Значения по умолчанию для процессоров, специфичных для модальности, например токенизатора или процессора изображений, можно определить аналогичным образом. Обычно в этом нет необходимости, так как для процессоров, специфичных для модальности, значения по умолчанию уже определены в их соответствующих классах. Используйте этот вариант только в том случае, если процессор должен переопределить настройку процессора, специфичного для модальности. Разумеется, аргументы, переданные во время выполнения в __call__, всегда имеют более высокий приоритет, чем любые значения по умолчанию.
from ...processing_utils import ProcessingKwargs, ProcessorMixin, Unpack
class MyModelProcessorKwargs(ProcessingKwargs, total=False):
"""
use_image_id (`bool`, defaults to `False`):
Whether to prepend an image-id tag (``<image_id>N</image_id>``) before
each image placeholder.
"""
use_image_id: bool
class MyModelProcessor(ProcessorMixin):
valid_processor_kwargs = MyModelProcessorKwargs
use_image_id = False
text_kwargs = {"padding": True} # default passed to tokenizer
def __init__(self, image_processor=None, tokenizer=None, chat_template=None, image_seq_length: int = 256, **kwargs):
super().__init__(image_processor, tokenizer, chat_template=chat_template, **kwargs)
self.image_seq_length = image_seq_length
@auto_docstring
def __call__(
self,
images: ImageInput | None = None,
text: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None,
suffix: str | None = None,
**kwargs: Unpack[MyModelProcessorKwargs],
):
images, text, videos, audio = self.prepare_inputs_layout(images=images, text=text, **kwargs)
self.validate_inputs(images=images, text=text, **kwargs)
merged_kwargs = self._merge_kwargs(tokenizer_init_kwargs=self.tokenizer.init_kwargs, **kwargs)
merged_kwargs["use_image_id"] # is `False` as default from class attribute is added by _merge_kwargs
merged_kwargs["text_kwargs"]["padding"] # is `True`Тестирование
Все мультимодальные процессоры должны иметь тестовый класс, наследующий от ProcessorTesterMixin. Этот миксин предоставляет стандартный набор тестов, охватывающий токенизацию, обработку изображений, батчинг и кодирование с последующим декодированием.
# tests/models/my_model_name/test_processor_<my_model_name>.py
from transformers.testing_utils import require_vision
from transformers.utils import is_vision_available
from ...test_processing_common import ProcessorTesterMixin
if is_vision_available():
from transformers import MyModelProcessor
@require_vision
class MyModelProcessorTest(ProcessorTesterMixin, unittest.TestCase):
processor_class = MyModelProcessor
def get_processor(self):
return MyModelProcessor.from_pretrained("hf-internal-testing/my-model-test")