Video Processor

Video Processor는 비디오 모델의 입력 특징을 준비하고 출력의 후처리(포스트 프로세싱)를 담당하는 유틸리티입니다. 리사이즈, 정규화, PyTorch로의 변환과 같은 변환 작업을 제공합니다.

video processor는 이미지 프로세서의 기능을 확장하여, 이미지와 구별되는 고유한 인자 세트를 통해 모델이 비디오를 처리할 수 있도록 합니다. 이는 원시 비디오 데이터와 모델 간의 다리 역할을 하며, 입력 기능이 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")

현재 비디오에 base image processor를 사용하는 경우, 각 프레임을 개별 이미지로 취급하여 프레임별로 변환을 적용하는 방식으로 비디오 데이터를 처리합니다. 이 방식은 동작은 하지만 효율성이 높지 않습니다. AutoVideoProcessor를 사용하면 고속 비디오 프로세서의 이점을 활용할 수 있으며, 이는 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")

프레임 샘플링

Video processor는 비디오를 디코딩하여 모델이 실제로 인식하는 프레임을 선택합니다. do_sample_frames=True를 설정하여 샘플링을 활성화한 후, 두 가지 방법 중 하나로 프레임을 선택합니다.

• num_frames은 비디오 전체에 걸쳐 균일하게 분포된 고정된 프레임 수를 요청합니다.
• fps는 초당 프레임 단위의 속도를 요구합니다.

경로 또는 URL을 전달하면 프로세서가 기본 디코더인 torchcodec로 비디오를 디코딩합니다. torchcodec이 사용 불가능하고 구버전의 torchvision을 사용하는 경우, 디코딩은 torchvision으로 대체됩니다.

샘플링된 프레임 인덱스, 원래 차원, 길이, fps를 반환받으려면 return_metadata=True를 추가하세요.

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 사이로 제한합니다. 따라서 1초 클립도 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"
)