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

Процессор видео

Video Processor — это утилита, отвечающая за подготовку входных признаков для видеомоделей, а также за постобработку их результатов. Она обеспечивает такие преобразования, как изменение размера, нормализация и конвертация в PyTorch. Помимо преобразований, класс VideoProcessor выполняет декодирование видео из локальных путей или URL (требуется torchcodec) и выборку кадров в соответствии со специфичными для модели стратегиями.

Видео-процессор расширяет функциональность процессоров изображений, позволяя мультимодальным языковым моделям (VLM) обрабатывать видео с набором аргументов, отличным от используемого для изображений. Он выступает связующим звеном между сырыми видеоданными и моделью, обеспечивая оптимизацию входных признаков для VLM.

Настройки видеопроцессора сохраняются в video_preprocessor_config.json. В более старых контрольных точках они могут храниться в preprocessor_config.json. См. Сохранение и перезагрузка для регистрации пользовательского бэкенда при перезагрузке.

Пример использования

Приведён пример загрузки видео-процессора для модели llava-hf/llava-onevision-qwen2-0.5b-ov-hf:

from transformers import AutoVideoProcessor

processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf")

Предобработка выполняется на устройстве входного тензора или на CPU для других типов входных данных. Укажите device, чтобы переместить видео на другое устройство перед предобработкой; это не меняет бэкенд. Также можно скомпилировать предобработку torchvision с помощью torch.compile при использовании ускорителя.

import torch
from transformers.video_utils import load_video
from transformers import AutoVideoProcessor

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

video = load_video("video.mp4")
processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf", device=device)
processor = torch.compile(processor)
processed_video = processor(video, return_tensors="pt")

Бэкенды процессора видео

Встроенные видео-процессоры используют torchvision для пакетного изменения размера, масштабирования и нормализации. Для их использования установите PyTorch и torchvision. В отличие от процессоров изображений, встроенные видео-процессоры не предоставляют бэкенд PIL.

AutoVideoProcessor по умолчанию выбирает бэкенд torchvision. Вы также можете запросить его явно и проверить атрибут backend загруженного процессора.

from transformers import AutoVideoProcessor

model_id = "llava-hf/llava-onevision-qwen2-0.5b-ov-hf"
video_processor = AutoVideoProcessor.from_pretrained(model_id, backend="torchvision")
print(video_processor.backend)
# torchvision

Аргумент backend определяет реализацию предобработки, а не декодер видео. См. Поведение при выборке для информации о декодировании и выборке кадров.

Пользовательские backends

BaseVideoProcessor обеспечивает предобработку на базе torchvision. Для реализации, не использующей torchvision, можно создать подкласс VideoProcessorMixin и переопределить preprocess так, чтобы он возвращал BatchFeature с входными данными, ожидаемыми моделью.

Регистрируйте пользовательские классы с помощью AutoVideoProcessor.register() и используйте video_processor_classes для сопоставления имён бэкендов с классами. В примере ниже предполагается, что NewCustomVideoProcessor определён с предобработкой, необходимой для чекпоинта LLaVA-OneVision.

from transformers import LlavaOnevisionConfig

AutoVideoProcessor.register(
    LlavaOnevisionConfig,
    video_processor_classes={"custom": NewCustomVideoProcessor},
    exist_ok=True,
)
custom_processor = AutoVideoProcessor.from_pretrained(model_id, backend="custom")

Используйте exist_ok=True, так как LlavaOnevisionConfig уже зарегистрирован. Переданные записи объединяются с его backend-маппингом, при этом совпадающие по имени записи заменяются, а записи, которые не были переданы, например torchvision, сохраняются.

Сохранение и загрузка

save_pretrained() сохраняет конфигурацию предобработки, а не сопоставления бэкендов, добавленные с помощью AutoVideoProcessor.register(). В том же процессе Python перезагрузите сохранённый процессор с backend="custom":

custom_processor.save_pretrained("./saved-video-processor")
custom_processor = AutoVideoProcessor.from_pretrained("./saved-video-processor", backend="custom")

Пользовательские регистрации действуют только в текущем процессе Python. В новом процессе необходимо определить или импортировать пользовательский класс и зарегистрировать его повторно перед загрузкой.

Поведение при выборке

Видео-процессор также может извлекать кадры видео, используя технику, наиболее подходящую для данной модели. Поведение выборки управляется аргументом do_sample_frames и может настраиваться с помощью параметров, специфичных для модели, таких как num_frames или fps (частота выборки кадров из видео). Если входное видео задано в виде локального пути или URL (str), процессор декодирует его автоматически. Чтобы получить метаданные о декодированном видео, такие как индексы выбранных кадров, исходные размеры, длительность и fps, передайте в процессор return_metadata=True.

  • Указание num_frames не гарантирует, что в выводе будет ровно такое количество кадров. В зависимости от модели, сэмплер может применять минимальные или максимальные ограничения по числу кадров.

  • По умолчанию используется декодер torchcodec, который необходимо установить.

import torch
from transformers import AutoVideoProcessor

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf", device=device)
processed_video_inputs = processor(videos=["video_path.mp4"], return_metadata=True, do_sample_frames=True, return_tensors="pt")
video_metadata = processed_video_inputs["video_metadata"]

# See how many frames the original video had and what was the original FPS
print(video_metadata.total_num_frames, video_metadata.fps)

Если вы передаёте уже декодированный массив видео, но хотите включить выборку кадров, специфичную для модели, настоятельно рекомендуется указать video_metadata. Это позволяет сэмплеру знать длительность и FPS исходного видео. Метаданные можно передать в виде объекта VideoMetadata или обычного словаря.

import torch
from transformers import AutoVideoProcessor
from transformers.video_utils import VideoMetadata

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf", device=device)
decoded_video = torch.randint(0, 255, size=(100, 3, 1280, 1280)) # short video of 100 frames
video_metadata = VideoMetadata(
    total_num_frames=100,
    fps=24,
    duration=4.1, # in seconds
)
processed_video_inputs = processor(videos=[decoded_video], video_metadata=video_metadata, do_sample_frames=True, num_frames=10, return_tensors="pt")
print(processed_video_inputs.pixel_values_videos.shape)
[10, 3, 384, 384]

VideoProcessorMixin

класс transformers.VideoProcessorMixin

< >

( **kwargs: *<class 'transformers.processing_utils.VideosKwargs'> )

fetch_videos

< >

( video_url_or_urls: str | list[str] | list[list[str]]sample_indices_fn = None )

Преобразовать один URL или список URL в соответствующие объекты np.array.

Если передан один url, возвращаемое значение будет одним объектом. Если передан список, возвращается список объектов.

from_dict

< >

( video_processor_dict: dict**kwargs ) → ~video_processing_utils.VideoProcessorBase

Параметры

  • video_processor_dict (dict[str, Any]) — Словарь, который будет использован для создания объекта video processor. Такой словарь можно получить из предобученной контрольной точки, используя метод ~video_processing_utils.VideoProcessorBase.to_dict.
  • kwargs (dict[str, Any]) — Дополнительные параметры для инициализации объекта видео-процессора.

Возвращает

~video_processing_utils.VideoProcessorBase

Объект видеопроцессора, созданный из этих параметров.

Создаёт экземпляр типа ~video_processing_utils.VideoProcessorBase из словаря параметров на Python.

from_json_file

< >

( json_file: str | os.PathLike ) → A video processor of type ~video_processing_utils.VideoProcessorBase

Параметры

  • json_file (str или os.PathLike) — Путь к JSON-файлу, содержащему параметры.

Возвращает

Обработчик видео типа ~video_processing_utils.VideoProcessorBase

Объект video_processor, созданный из этого JSON-файла.

Создаёт экземпляр видеопроцессора типа ~video_processing_utils.VideoProcessorBase на основе пути к JSON-файлу с параметрами.

from_pretrained

< >

( pretrained_model_name_or_path: str | os.PathLikecache_dir: str | os.PathLike | None = Noneforce_download: bool = Falselocal_files_only: bool = Falsetoken: str | bool | None = Nonerevision: str = 'main'**kwargs )

Параметры

  • pretrained_model_name_or_path (str или os.PathLike) — Это может быть:
    • строка, model id предобученного видео, размещённого в репозитории моделей на huggingface.co.
    • путь к каталогу, содержащему файл видео-процессора, сохранённый с помощью метода ~video_processing_utils.VideoProcessorBase.save_pretrained, например, ./my_model_directory/.
    • путь к сохранённому JSON-файлу видео-процессора, например, ./my_model_directory/video_preprocessor_config.json.
  • cache_dir (str or os.PathLike, необязательный) — Путь к каталогу, в котором следует кэшировать загруженный предобученный видеопроцессор модели, если стандартный кэш не используется.
  • force_download (bool, необязательный, по умолчанию False) — Указывает, следует ли принудительно (пере)загружать файлы видео-процессора и заменять кэшированные версии, если они уже существуют.
  • proxies (dict[str, str], необязательный) — Словарь прокси-серверов, используемых по протоколу или конечной точке, например, {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Прокси применяются при каждом запросе.
  • token (str или bool, необязательный) — Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Если указано True или параметр не задан, будет использован токен, сгенерированный при выполнении hf auth login (хранится в ~/.huggingface).
  • revision (str, необязательный, по умолчанию "main") — Конкретная версия модели, которую следует использовать. Это может быть имя ветки, имя тега или идентификатор коммита, поскольку для хранения моделей и других артефактов на huggingface.co используется система на базе git, поэтому revision может быть любым идентификатором, разрешённым git.

Создайте экземпляр типа ~video_processing_utils.VideoProcessorBase из видео-процессора.

Примеры:

# We can't instantiate directly the base class *VideoProcessorBase* so let's show the examples on a
# derived class: *LlavaOnevisionVideoProcessor*
video_processor = LlavaOnevisionVideoProcessor.from_pretrained(
    "llava-hf/llava-onevision-qwen2-0.5b-ov-hf"
)  # Download video_processing_config from huggingface.co and cache.
video_processor = LlavaOnevisionVideoProcessor.from_pretrained(
    "./test/saved_model/"
)  # E.g. video processor (or model) was saved using *save_pretrained('./test/saved_model/')*
video_processor = LlavaOnevisionVideoProcessor.from_pretrained("./test/saved_model/video_preprocessor_config.json")
video_processor = LlavaOnevisionVideoProcessor.from_pretrained(
    "llava-hf/llava-onevision-qwen2-0.5b-ov-hf", do_normalize=False, foo=False
)
assert video_processor.do_normalize is False
video_processor, unused_kwargs = LlavaOnevisionVideoProcessor.from_pretrained(
    "llava-hf/llava-onevision-qwen2-0.5b-ov-hf", do_normalize=False, foo=False, return_unused_kwargs=True
)
assert video_processor.do_normalize is False
assert unused_kwargs == {"foo": False}

get_video_processor_dict

< >

( pretrained_model_name_or_path: str | os.PathLike**kwargs ) → tuple[Dict, Dict]

Параметры

  • pretrained_model_name_or_path (str или os.PathLike) — Идентификатор предобученной контрольной точки, из которой мы хотим получить словарь параметров.
  • subfolder (str, необязательный, по умолчанию "") — Если нужные файлы находятся в подпапке репозитория модели на huggingface.co, укажите здесь имя папки.

Возвращает

tuple[Dict, Dict]

Словарь(и), который(е) будет использован для создания объекта видео-процессора.

По pretrained_model_name_or_path определяется словарь параметров, используемый для создания экземпляра видео-процессора типа ~video_processing_utils.VideoProcessorBase с помощью from_dict.

preprocess

< >

( videos: 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]]]**kwargs: *<class 'transformers.processing_utils.VideosKwargs'> ) → ~image_processing_base.BatchFeature

Параметры

  • 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.
  • do_convert_rgb (bool, kwargs, optional) — Следует ли преобразовать изображение в RGB.
  • do_resize (bool, kwargs, optional) — Указывает, нужно ли изменить размер изображения.
  • size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Описывает максимальные размеры входных данных для модели.
  • default_to_square (bool, kwargs, optional) — Определяет, следует ли по умолчанию использовать квадратное изображение при изменении размера, если size является целым числом.
  • resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — Фильтр ресемплинга, используемый при изменении размера изображения. Может быть одним из значений перечисления PILImageResampling. Влияет только в том случае, если do_resize установлено в True.
  • do_rescale (bool, kwargs, optional) — Нужно ли перемасштабировать изображение.
  • rescale_factor (float, kwargs, optional) — Коэффициент масштабирования, применяемый к изображению, если do_rescale установлен в True.
  • do_normalize (bool, kwargs, optional) — Нужно ли нормализовать изображение.
  • image_mean (Union[float, list[float], tuple[float, ...]], kwargs, optional) — Среднее значение изображения, используемое для нормализации. Влияет только в том случае, если do_normalize установлено в True.
  • image_std (Union[float, list[float], tuple[float, ...]], kwargs, optional) — Стандартное отклонение изображения, используемое для нормализации. Влияет только в том случае, если do_normalize установлено в True.
  • do_center_crop (bool, kwargs, optional) — Выполнять ли центрированную обрезку изображения.
  • do_pad (bool, kwargs, optional) — Определяет, нужно ли выравнивать изображение. Выравнивание выполняется либо до максимального размера в батче, либо до фиксированного квадратного размера для каждого изображения. Точная стратегия выравнивания зависит от модели.
  • crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Размер выходного изображения после применения center_crop.
  • data_format (Union[str, ~image_utils.ChannelDimension], kwargs, optional) — Поддерживается только ChannelDimension.FIRST. Добавлено для совместимости с медленными процессорами.
  • input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, необязательный) — Формат размерности каналов для входного изображения. Если не задан, формат размерности каналов выводится из входного изображения. Может быть одним из:
    • "channels_first" или ChannelDimension.FIRST: изображение в формате (num_channels, height, width).
    • "channels_last" или ChannelDimension.LAST: изображение в формате (высота, ширина, число каналов).
    • "none" или ChannelDimension.NONE: изображение в формате (height, width).
  • device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — Устройство, на котором будут обрабатываться видео. Если не задано, устройство определяется на основе входных видео.
  • do_sample_frames (bool, kwargs, optional) — Следует ли извлекать кадры из видео перед обработкой или обрабатывать видео целиком.
  • video_metadata (Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — Метаданные видео, содержащие информацию о общей длительности, fps и общем количестве кадров. Будут использоваться для выборки кадров из видео или вычисления временных меток. Не передавайте метаданные, если не пытаетесь декодировать видео вручную перед обработкой
  • fps (Annotated[int | float | None, None], kwargs) — Целевое количество кадров для выборки в секунду при do_sample_frames=True.
  • num_frames (Annotated[int | None, None], kwargs) — Максимальное количество кадров для выборки при do_sample_frames=True.
  • return_metadata (bool, kwargs, optional) — Указывает, следует ли возвращать метаданные видео. Метаданные видео — это объект, содержащий информацию о длительности видео, частоте кадров (fps), используемом бэкенде декодирования и т. д.
  • return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Возвращает стопку тензоров, если установлено значение 'pt', иначе возвращает список тензоров.

Возвращает

~image_processing_base.BatchFeature

  • data (dict) — Словарь списков/массивов/тензоров, возвращаемый методом call (‘pixel_values’ и т. д.).
  • tensor_type (Union[None, str, TensorType], необязательный) — Здесь можно указать tensor_type, чтобы при инициализации преобразовать списки целых чисел в тензоры PyTorch/Numpy.

register_for_auto_class

< >

( auto_class = 'AutoVideoProcessor' )

Параметры

  • auto_class (str или type, необязательный, по умолчанию "AutoVideoProcessor ") — Класс auto, с которым будет зарегистрирован этот новый видео-процессор.

Зарегистрируйте этот класс с указанным автоклассом. Это следует использовать только для пользовательских видеообработчиков, так как те, что входят в библиотеку, уже сопоставлены с AutoVideoProcessor.

Этот API является экспериментальным и может содержать некоторые незначительные изменения, нарушающие обратную совместимость, в следующих версиях.

save_pretrained

< >

( save_directory: str | os.PathLikepush_to_hub: bool = False**kwargs )

Параметры

  • save_directory (str или os.PathLike) — Каталог, в котором будет сохранён JSON-файл видеопроцессора (будет создан, если не существует).
  • push_to_hub (bool, необязательный, по умолчанию False) — Указывает, следует ли после сохранения отправить вашу модель в Hugging Face model hub. С помощью repo_id можно указать репозиторий, в который нужно отправить модель (по умолчанию используется имя save_directory в вашем пространстве имён).
  • kwargs (dict[str, Any], необязательный) — Дополнительные именованные аргументы, передаваемые в метод push_to_hub().

Сохраните объект видеопроцессора в каталог save_directory, чтобы его можно было загрузить с помощью метода класса ~video_processing_utils.VideoProcessorBase.from_pretrained.

to_dict

< >

( ) → dict[str, Any]

Возвращает

dict[str, Any]

Словарь всех атрибутов, из которых состоит этот экземпляр видео-процессора.

Сериализует этот экземпляр в словарь Python.

BaseVideoProcessor

класс transformers.BaseVideoProcessor

< >

( **kwargs: *<class 'transformers.processing_utils.VideosKwargs'> )

convert_to_rgb

< >

( video: torch.Tensor ) → torch.Tensor

Параметры

  • video ("torch.Tensor") — Видео, которое нужно преобразовать.

Возвращает

torch.Tensor

Преобразованное видео.

Преобразует видео в формат RGB.

sample_frames

< >

( metadata: VideoMetadatanum_frames: int | None = Nonefps: int | float | None = None**kwargs ) → np.ndarray

Параметры

  • metadata (VideoMetadata) — Метаданные видео, содержащие информацию о общей длительности, частоте кадров (fps) и общем количестве кадров.
  • num_frames (int, необязательный) — Максимальное количество кадров для выборки. По умолчанию self.num_frames.
  • fps (int или float, необязательный) — Целевое количество кадров для выборки в секунду. По умолчанию self.fps.

Возвращает

np.ndarray

Индексы для выборки кадров видео.

Функция выборки по умолчанию, которая равномерно выбирает требуемое количество кадров в диапазоне от 0 до общего числа кадров. Если вместе с метаданными передан параметр fps, то равномерно выбирается fps кадров в секунду. Аргументы num_frames и fps взаимоисключающие.

Update on GitHub

←Обработчик изображений Ядра→