Hugging Face's logo

Transformers documentation

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

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[str, typing.Any]**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.

    Чтобы протестировать pull request, который вы создали на Hub, вы можете передать revision="refs/pr/<pr_number>".

  • return_unused_kwargs (bool, необязательный, по умолчанию False) — Если False, функция возвращает только итоговый объект видеопроцессора. Если True, функция возвращает Tuple(video_processor, unused_kwargs), где unused_kwargs — это словарь, содержащий пары ключ/значение, ключи которых не являются атрибутами видеопроцессора, то есть та часть kwargs, которая не была использована для обновления video_processor и в остальном игнорируется.
  • subfolder (str, необязательный, по умолчанию "") — Если нужные файлы находятся в подпапке репозитория модели на huggingface.co, укажите здесь имя папки.
  • kwargs (dict[str, Any], необязательный) — Значения в kwargs для любых ключей, являющихся атрибутами видео-процессора, используются для переопределения загруженных значений. Поведение в отношении пар ключ/значение, ключи которых не являются атрибутами видео-процессора, контролируется параметром return_unused_kwargs.

Создайте экземпляр типа ~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

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