Hugging Face's logo

Transformers documentation

Процессоры

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Процессоры

Мультимодальные процессоры

Любая мультимодальная модель требует объект для кодирования или декодирования данных, объединяющий несколько модальностей (среди текста, зрения и аудио). Это обеспечивается объектами, называемыми процессорами, которые объединяют два или более объектов обработки, таких как токенизаторы (для текстовой модальности), процессоры изображений (для зрения) и извлекатели признаков (для аудио).

Эти процессоры наследуются от следующего базового класса, который реализует функциональность сохранения и загрузки:

класс transformers.ProcessorMixin

< >

( *args**kwargs )

Это миксин, используемый для предоставления функциональности сохранения/загрузки для всех классов процессоров.

__call__

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )

Параметры

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], необязательный) — Изображение для предобработки. Ожидается одно изображение или батч изображений со значениями пикселей в диапазоне от 0 до 255. Если передаются изображения со значениями пикселей в диапазоне от 0 до 1, установите do_rescale=False.
  • text (Union[str, list[str], list[list[str]]], необязательный) — Последовательность или батч последовательностей для кодирования. Каждая последовательность может быть строкой или списком строк (предварительно токенизированная строка). Если вы передаёте предварительно токенизированный вход, установите is_split_into_words=True, чтобы избежать неоднозначности с батчированными входами.
  • videos (Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]], необязательный) — Видео для предобработки. Ожидается одно видео или батч видео со значениями пикселей в диапазоне от 0 до 255. Если передаются видео со значениями пикселей в диапазоне от 0 до 1, установите do_rescale=False.
  • audio (Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]], необязательный) — Аудио или пакет аудио, подлежащий подготовке. Каждое аудио может быть массивом NumPy или тензором PyTorch. В случае массива NumPy/тензора PyTorch каждое аудио должно иметь форму (C, T), где C — количество каналов, а T — длина выборки аудио.
  • return_tensors (str или TensorType, необязательный) — Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:
    • 'pt': возвращает объекты torch.Tensor PyTorch.
    • 'np': возвращает объекты NumPy np.ndarray.
  • **kwargs (ProcessingKwargs, optional) — Дополнительные параметры обработки для каждой модальности (текст, изображения, видео, аудио). Специфичные для модели параметры перечислены выше; полный список поддерживаемых аргументов см. в классе TypedDict.

prepare_inputs_layout

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )

Нормализация и предварительная загрузка входных данных перед обработкой. Оборачивает текст в список для мультимодальных процессоров, загружает удалённые изображения и аудио, если указаны URL, и обеспечивает корректную пакетную обработку аудио. Возвращает нормализованный кортеж (images, text, videos, audio).

validate_inputs

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )

Проверяет, что передан хотя бы один входной параметр и что не используются устаревшие именованные аргументы. В противном случае вызывает ValueError.

Переопределяется, когда процессору требуется дополнительная валидация входных аргументов.

get_text_with_replacements

< >

( text: listimages_replacements: list = []videos_replacements: list = []audio_replacements: list = [] ) → tuple[list[str], list[dict[str, Any]]]

Параметры

  • text (list[str]) — Партия необработанных строк текста, каждая из которых может содержать мультимодальные плейсхолдер-токены. Обратите внимание, что список будет изменён на месте и возвращён.
  • images_replacements (list[str], optional, по умолчанию []) — Развёрнутые строки замены для каждого изображения, в порядке их появления в батче. Формируются методом self._process_images.
  • videos_replacements (list[str], optional, по умолчанию []) — Развёрнутые строки замены для каждого видео. Формируются методом self._process_videos.
  • audio_replacements (list[str], optional, по умолчанию []) — Развёрнутые строки замены для каждого аудио-входа. Формируются методом self._process_audio.

Возвращает

tuple[list[str], list[dict[str, Any]]]

Кортеж из:

  • Измененная text-партия, в которой все плейсхолдер-токены развернуты.
  • batch_replacement_offsets: по одному элементу на каждый элемент батча, каждый из которых является списком словарей с ключами:
  • “type” (str): название модальности — “image”, “video” или “audio”
  • “span” (tuple[int, int]): исходные смещения символов (start, end) для плейсхолдер-токена
  • “new_span” (tuple[int, int]): смещения (start, end) плейсхолдера в расширенной строке
  • “text” (str): исходная строка-заполнитель, которая была найдена
  • “replacement” (str): строка, которой он был заменён

Замените мультимодальные плейсхолдер-токены в батче текстовых строк на их развёрнутые представления и верните изменённые тексты вместе с метаданными смещений.

Этот метод является основным этапом предобработки текстовой части для мультимодальных входных данных. Он просматривает каждый текст в батче в поисках специальных токенов (изображение, видео, аудио) и последовательно заменяет их на заранее вычисленные строки замены, полученные с помощью self.replace_image_token / self.replace_video_token / self.replace_audio_token. Замены извлекаются из списка каждой модальности последовательно, поэтому i-е вхождение, например, self.image_token заменяется на images_replacements[i].

Чтобы добавить новый мультимодальный процессор с токенами-заполнителями, необходимо определить корректное значение self.image_token, которое является тем же токеном, что и встроенный в входной текст, а также используется в качестве заполнителя и повторяется многократно. Затем нужно переопределить self.replace_image_token, чтобы возвращать правильную строку замены для изображения с индексом i. То же самое относится ко всем другим поддерживаемым модальностям.

create_mm_token_type_ids

< >

( input_ids: list ) → list[list[int]]

Параметры

  • input_ids (list[list[int]]) — Пакет последовательностей идентификаторов токенов. Может быть без выравнивания (переменной длины), поэтому ожидается обычный список списков Python, а не тензор или массив с одинаковой формой.

Возвращает

list[list[int]]

Список той же структуры, что и input_ids, где каждое целое число — это идентификатор типа модальности для соответствующего токена.

Создайте идентификаторы типа модальности для каждого токена в батче последовательностей token_id.

Каждой позиции присваивается целое число, указывающее, к какой модальности она относится: 0 — для обычного текста, 1 — для токенов изображения, 2 — для токенов видео и 3 — для токенов аудио. Принадлежность определяется путём сравнения с self.image_token_ids, self.video_token_ids и self.audio_token_ids.

apply_chat_template

< >

( conversation: list[dict[str, str]] | list[list[dict[str, str]]]chat_template: str | None = Nonetools: list[dict] | None = Nonedocuments: list[dict[str, str]] | None = Noneadd_generation_prompt: bool = Falsecontinue_final_message: bool | str = Falsereturn_assistant_tokens_mask: bool = Falsetokenize: bool = Falsereturn_tensors: str | transformers.utils.generic.TensorType | None = 'auto'return_dict: bool = Falseload_audio_from_video: bool = Falseprocessor_kwargs: dict | None = None**kwargs )

Параметры

  • conversation (Union[list[Dict, [str, str]], list[list[dict[str, str]]]]) — Диалог, который нужно отформатировать.
  • chat_template (Optional[str], необязательный) — Шаблон Jinja, используемый для форматирования диалога. Если не указан, используется шаблон чата токенизатора.

Аналогично методу apply_chat_template в токенизаторах, данный метод применяет шаблон Jinja к входным диалогам, чтобы преобразовать их в единую строку, готовую к токенизации.

Ожидается, что входные данные будут иметь следующий формат, где содержимое каждого сообщения представляет собой список, состоящий из текста и, при необходимости, изображений или видео. Также можно указать изображение, видео, URL или локальный путь, которые будут использованы для формирования pixel_values, если return_dict=True. Если эти данные не указаны, будет возвращён только отформатированный текст, а при необходимости — и токенизированный текст.

conversation = [ { “role”: “user”, “content”: [ {“type”: “image”, “url”: “https://www.ilankelman.org/stopsigns/australia.jpg”}, {“type”: “text”, “text”: “Please describe this image in detail.”}, ], }, ]

Обработка kwargs

Методы __call__ класса Processor принимают именованные аргументы, сгруппированные по модальности. Ниже приведены классы TypedDict, определяющие доступные именованные аргументы для каждой модальности. Процессоры, специфичные для конкретной модели, могут наследоваться от этих классов, чтобы добавлять или переопределять поля.

класс transformers.ProcessingKwargs

< >

( )

Базовый класс для передачи аргументов kwargs в процессоры. Если у модели есть специфические аргументы kwargs, отсутствующие в базовом классе, или значения по умолчанию для существующих ключей, она должна иметь собственный класс ModelProcessorKwargs, наследующийся от ProcessingKwargs, чтобы обеспечить: 1) Дополнительные типизированные ключи, необходимые этой модели для обработки входных данных. 2) Значения по умолчанию для существующих ключей в атрибуте _defaults. Новые ключи должны быть определены следующим образом, чтобы обеспечить корректную типизацию.

# adding a new image kwarg for this model
class ModelImagesKwargs(ImagesKwargs, total=False):
    new_image_kwarg: Optional[bool]

class ModelProcessorKwargs(ProcessingKwargs, total=False):
    images_kwargs: ModelImagesKwargs
    _defaults = {
        "images_kwargs: {
            "new_image_kwarg": False,
        }
        "text_kwargs": {
            "padding": "max_length",
        },
    }

Для совместимости с Python 3.8, при наследовании от этого класса и переопределении одного из kwargs,

вам необходимо вручную обновить словарь annotations. Это можно сделать следующим образом:

class CustomProcessorKwargs(ProcessingKwargs, total=False):
    images_kwargs: CustomImagesKwargs

CustomProcessorKwargs.__annotations__["images_kwargs"] = CustomImagesKwargs  # python 3.8 compatibility

класс transformers.TextKwargs

< >

( )

Параметры

  • add_special_tokens (bool, необязательный) — Указывает, следует ли добавлять специальные токены при кодировании последовательностей.
  • padding (bool, str или PaddingStrategy, необязательный) — Включает и управляет выравниванием.
  • truncation (bool, str или TruncationStrategy, необязательный) — Включает и управляет усечением.
  • max_length (int, необязательный) — Определяет максимальную длину, используемую одним из параметров усечения/дополнения.
  • stride (int, необязательный) — Если задано, переполненные токены будут содержать некоторые токены из конца усечённой последовательности.
  • is_split_into_words (bool, необязательный) — Указывает, является ли вход уже предварительно токенизированным.
  • pad_to_multiple_of (int, необязательный) — Если задано, последовательность будет дополнена до кратного указанного значения.
  • return_token_type_ids (bool, необязательный) — Возвращать ли идентификаторы типов токенов.
  • return_attention_mask (bool, необязательный) — Возвращать ли маску внимания.
  • return_overflowing_tokens (bool, необязательный) — Возвращать ли последовательности токенов, выходящие за пределы длины.
  • return_special_tokens_mask (bool, необязательный) — Возвращать ли информацию о маске специальных токенов.
  • return_offsets_mapping (bool, необязательный) — Возвращать или нет (char_start, char_end) для каждого токена.
  • return_length (bool, необязательный) — Указывает, следует ли возвращать длины закодированных входных данных.
  • verbose (bool, необязательный) — Определяет, выводить ли дополнительную информацию и предупреждения.
  • padding_side (str, необязательный) — Сторона, на которую будет применена отсечка.
  • return_mm_token_type_ids (bool, необязательный) — Указывает, следует ли возвращать идентификаторы типов мультимодальных токенов, обозначающие позиции плейсхолдерных токенов.
  • return_text_replacement_offsets (bool, необязательный) — Возвращать ли смещения символов для каждого mm-плейсхолдера и его замены.
  • return_tensors (str или TensorType, необязательный) — Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:
    • 'pt': возвращает объекты torch.Tensor PyTorch.
    • 'np': возвращает объекты NumPy np.ndarray.

Параметры-ключевые слова для обработки текста. Для расширенной документации обратитесь к методам и документационным строкам, связанным с tokenization_utils_base.

класс transformers.ImagesKwargs

< >

( )

Параметры

  • do_convert_rgb (bool) — Указывает, следует ли преобразовать изображение в формат RGB.
  • do_resize (bool, необязательный) — Указывает, нужно ли изменять размер изображения.
  • size (dict[str, int], необязательный) — Изменение размера с использованием одного из поддерживаемых словарей размеров. Ограничения по площади в пикселях задаются через {"min_pixels": int, "max_pixels": int}.
  • default_to_square (bool, необязательный, по умолчанию self.default_to_square) — Определяет, следует ли по умолчанию использовать квадратную форму при изменении размера, если size задано как целое число.
  • crop_size (dict[str, int], необязательный) — Требуемый размер выходных данных при применении центрированного кадрирования.
  • resample (PILImageResampling, необязательный) — Фильтр ресемплинга, используемый при изменении размера изображения.
  • do_rescale (bool, необязательный) — Указывает, следует ли масштабировать изображение с использованием заданного коэффициента rescale_factor.
  • rescale_factor (int или float, необязательный) — Коэффициент масштабирования, используемый при изменении размера изображения.
  • do_normalize (bool, необязательный) — Указывает, следует ли нормализовать изображение.
  • image_mean (float или list[float] or tuple[float, float, float], необязательный) — Среднее значение, используемое при нормализации изображения.
  • image_std (float or list[float] or tuple[float, float, float], optional) — Стандартное отклонение, используемое при нормализации изображения.
  • do_pad (bool, необязательный) — Указывает, нужно ли выравнивать изображения в батче.
  • pad_size (dict[str, int], необязательный) — Размер {"height": int, "width" int}, до которого следует дополнить изображения.
  • do_center_crop (bool, необязательный) — Выполнять ли центрированное обрезание изображения.
  • data_format (ChannelDimension или str, необязательный) — Формат размерности каналов для выходного изображения.
  • input_data_format (ChannelDimension или str, необязательный) — Формат размерности каналов для входного изображения.
  • device (Union[str, torch.Tensor], необязательный) — Устройство, используемое для обработки (например, “cpu”, “cuda”); актуально только для torchvision backend.
  • return_tensors (str или TensorType, необязательный) — Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:
    • 'pt': возвращает объекты torch.Tensor PyTorch.
    • 'np': возвращает объекты NumPy np.ndarray.
  • disable_grouping (bool, необязательный) — Определяет, нужно ли группировать изображения по форме при обработке. Параметр актуален только для бэкенда torchvision.
  • image_seq_length (int, необязательный) — Количество токенов изображения, используемых для каждого изображения во входных данных. Добавлено для обратной совместимости, но в будущих моделях это значение следует задавать как атрибут процессора.

Параметры по ключевым словам для обработки изображений. Для расширенной документации обратитесь к методам и строкам документации соответствующего класса ImageProcessor.

класс transformers.VideosKwargs

< >

( )

Параметры

  • do_convert_rgb (bool) — Указывает, следует ли конвертировать видео в формат RGB.
  • do_resize (bool) — Указывает, нужно ли изменять размер видео.
  • size (dict[str, int], необязательный) — Масштабирует более короткую сторону входных данных до size["shortest_edge"].
  • default_to_square (bool, необязательный, по умолчанию self.default_to_square) — Определяет, следует ли по умолчанию использовать квадратную форму при изменении размера, если size задано как целое число.
  • resample (PILImageResampling, необязательный) — Фильтр ресемплинга, используемый при изменении размера видео.
  • do_rescale (bool, необязательный) — Указывает, следует ли масштабировать видео с использованием заданного коэффициента rescale_factor.
  • rescale_factor (int или float, необязательный) — Коэффициент масштабирования, используемый при изменении размера видео.
  • do_normalize (bool, необязательный) — Указывает, следует ли нормализовать видео.
  • image_mean (float or list[float] or tuple[float, float, float], optional) — Среднее значение, используемое при нормализации видео.
  • image_std (float или list[float] or tuple[float, float, float], необязательный) — Стандартное отклонение, используемое при нормализации видео.
  • do_center_crop (bool, необязательный) — Указывает, нужно ли выполнять центрированное обрезание видео.
  • do_pad (bool, необязательный) — Указывает, нужно ли выравнивать изображения в батче.
  • do_sample_frames (bool, необязательный) — Следует ли извлекать кадры из видео перед обработкой или обрабатывать видео целиком.
  • video_metadata (Union[VideoMetadata, dict], необязательный) — Метаданные видео, содержащие информацию о общей длительности, частоте кадров (fps) и общем количестве кадров.
  • num_frames (int, необязательный) — Максимальное количество кадров для выборки при do_sample_frames=True.
  • fps (int или float, необязательный) — Целевое количество кадров для выборки в секунду при do_sample_frames=True.
  • crop_size (dict[str, int], необязательный) — Требуемый размер выходных данных при применении центрированного кадрирования.
  • data_format (ChannelDimension или str, необязательный) — Формат размерности каналов для выходного видео.
  • input_data_format (ChannelDimension или str, необязательный) — Формат размерности каналов для входного видео.
  • device (Union[str, torch.Tensor], необязательный) — Устройство, используемое для обработки (например, “cpu”, “cuda”); актуально только для быстрого обработки изображений.
  • return_metadata (bool, необязательный) — Возвращать метаданные видео или нет.
  • return_tensors (str или TensorType, необязательный) — Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:
    • 'pt': возвращает объекты torch.Tensor PyTorch.
    • 'np': возвращает объекты NumPy np.ndarray.

Параметры по имени для обработки видео.

класс transformers.AudioKwargs

< >

( )

Параметры

  • sampling_rate (int, необязательный) — Частота дискретизации, с которой вход raw_speech был оцифрован.
  • raw_speech (np.ndarray, list[float], list[np.ndarray], list[list[float]]) — Последовательность или батч последовательностей, для которых требуется выравнивание. Каждая последовательность может быть массивом numpy, списком значений float, списком массивов numpy или списком списков значений float. Аудио должно быть моноканальным, а не стерео, то есть одно значение float на каждый момент времени.
  • padding (bool, str или PaddingStrategy, , необязательный) — Выберите стратегию выравнивания возвращаемых последовательностей (с учётом стороны выравнивания и индекса выравнивания модели) из следующих:
    • True или 'longest': дополнить до самой длинной последовательности в батче (или не дополнять, если предоставлена только одна последовательность).
    • 'max_length': Дополнить до максимальной длины, указанной аргументом max_length, или до максимально допустимой длины входных данных для модели, если этот аргумент не указан.
    • False или 'do_not_pad'
  • max_length (int, необязательный) — Максимальная длина возвращаемого списка и, при необходимости, длина отступов (см. выше).
  • truncation (bool, необязательный) — Включает усечение, чтобы сократить входные последовательности длиннее max_length до max_length.
  • pad_to_multiple_of (int, необязательный) — Если задано, последовательность будет дополнена до кратного указанного значения.
  • return_attention_mask (bool, необязательный) — Указывает, должен ли call() возвращать attention_mask.
  • device (str или torch.device, необязательный) — Устройство, на котором вычисляются аудиопризнаки (например, “cpu”, “cuda”); актуально только для экстракторов признаков, которые вычисляют их с помощью torch.
  • return_tensors (str или TensorType, необязательный) — Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:
    • 'pt': возвращает объекты torch.Tensor PyTorch.
    • 'np': возвращает объекты NumPy np.ndarray.
  • load_audio_backend (str, optional) — Бэкенд, используемый load_audio() для декодирования/ресемплирования аудио, указанного по URL/пути в apply_chat_template. Одно из значений: "auto", "torchcodec", "librosa", "torchaudio".

Параметры-ключевые слова для обработки аудио.

Update on GitHub

←Пайплайны Экспортеры→