Video Processor

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

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

Используйте from_pretrained() для загрузки конфигурации видео-процессора (размер изображения, параметры нормализации и масштабирования и т. д.) из видео-модели на Hugging Face Hub или из локального каталога. Конфигурация каждой предобученной модели должна сохраняться в файле [video_preprocessor_config.json], однако в более старых моделях конфигурация может храниться в файле preprocessor_config.json. Обратите внимание, что второй вариант менее предпочтителен и будет удалён в будущем.

Если видеопроцессор является частью мультимодального процессора, его конфигурация вложенным образом хранится в processor_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")

В настоящее время, если используется базовый image processor для видео, он обрабатывает видеоданные, рассматривая каждый кадр как отдельное изображение и применяя трансформации по кадрам. Хотя этот подход работает, он не отличается высокой эффективностью. Использование AutoVideoProcessor позволяет воспользоваться быстрыми video processors, опираясь на библиотеку torchvision. Быстрые процессоры обрабатывают всю партию видео сразу, без итерации по каждому видео или кадру. Эти обновления обеспечивают ускорение на GPU и значительно повышают скорость обработки, особенно для задач, требующих высокой пропускной способности.

Быстрые видео-процессоры доступны для всех моделей и загружаются по умолчанию при инициализации AutoVideoProcessor. При использовании быстрого видео-процессора можно также задать аргумент device, чтобы указать устройство, на котором должна выполняться обработка. По умолчанию обработка выполняется на том же устройстве, что и входные данные, если они являются тензорами, иначе — на CPU. Для дальнейшего ускорения можно скомпилировать процессор при использовании ускорителя в качестве устройства.

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

Выборка кадров

Видео-процессор декодирует видео и выбирает кадры, которые модель действительно видит. Установите do_sample_frames=True, чтобы включить выборку, а затем выберите кадры одним из двух способов.

• num_frames запрашивает фиксированное количество кадров, распределённых равномерно по всему видео.
• fps запрашивает частоту в кадрах в секунду.

Передайте путь или URL, и процессор декодирует видео с помощью torchcodec — декодера по умолчанию. Если torchcodec недоступен, а вы используете более старую версию torchvision, декодирование выполняется средствами torchvision.

Добавьте return_metadata=True, чтобы получить обратно индексы выбранных кадров, исходные размеры, длительность и fps.

from transformers import AutoVideoProcessor

processor = AutoVideoProcessor.from_pretrained("Qwen/Qwen3-VL-4B-Instruct")
inputs = processor(videos=["video.mp4"], do_sample_frames=True, fps=1, return_metadata=True, return_tensors="pt")

print(inputs.pixel_values_videos.shape, inputs.video_grid_thw)
print(inputs["video_metadata"][0].total_num_frames)

Значения по умолчанию для выборки зависят от модели, а запрос num_frames или fps служит лишь отправной точкой, а не гарантией. Qwen3-VL выполняет выборку с fps=2 и ограничивает результат диапазоном от min_frames=4 до max_frames=768, поэтому даже односекундный клип даст 4 кадра, а длинная запись будет обрезана значительно ниже своего фактического количества кадров.

Модели с параметром temporal_patch_size добавляют второе ограничение: кадры группируются в патчи, содержащие такое количество кадров вдоль временной оси, а последний кадр дублируется, пока общее количество не станет кратным размеру патча.

Если вы передаёте уже декодированный массив видео, но по-прежнему хотите использовать специфичную для модели выборку, также укажите video_metadata. Без него сэмплер не знает исходную длительность или fps, и выборка по fps выдаёт предупреждение, предполагая, что видео было записано с частотой 24 fps.

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

processor = AutoVideoProcessor.from_pretrained("Qwen/Qwen3-VL-4B-Instruct")
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)

inputs = processor(
    videos=[video], video_metadata=[video_metadata], do_sample_frames=True, num_frames=16, return_tensors="pt"
)