비디오 프로세서

Video Processor는 비디오 모델의 입력 특징을 준비하고 출력의 후처리를 담당하는 유틸리티입니다. 리사이징, 정규화, PyTorch로의 변환과 같은 변환을 제공합니다. VideoProcessor 클래스는 변환과 함께 로컬 경로 또는 URL로부터의 비디오 디코딩(torchcodec 필요) 및 모델별 전략에 따른 프레임 샘플링을 처리합니다.

video processor는 이미지와 구별되는 고유한 인자 세트를 사용하여 VLM(Vision Large Language Models)이 비디오를 처리할 수 있도록 함으로써 이미지 프로세서의 기능을 확장합니다. 이는 원시 비디오 데이터와 모델 간의 가교 역할을 하며, 입력 기능이 VLM에 최적화되도록 보장합니다.

Video processor 설정은 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")

Preprocessing은 입력 텐서의 디바이스에서 실행되며, 다른 입력의 경우 CPU에서 실행됩니다. device를 설정하여 전처리 전에 비디오를 다른 디바이스로 이동할 수 있으며, 이는 백엔드를 변경하지 않습니다. 가속기를 사용하는 경우 torch.compile로 torchvision 전처리를 컴파일할 수도 있습니다.

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 백엔드

내장 비디오 프로세서에서는 배치 리사이징, 리스케일링, 정규화를 위해 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 인자는 비디오 디코더가 아니라 전처리 구현을 선택합니다. 디코딩 및 프레임 샘플링에 대해서는 샘플링 동작을 참조하세요.

사용자 지정 백엔드

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

LlavaOnevisionConfig이 이미 등록되어 있으므로 exist_ok=True를 사용합니다. 제공된 항목은 해당 백엔드 매핑에 병합되며, 이름이 일치하는 항목은 대체되고, 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 프로세스에만 적용됩니다. 새 프로세스에서는 커스텀 클래스를 정의하거나 가져온 후, 로딩 전에 다시 등록해야 합니다.

샘플링 동작

Video processor는 주어진 모델에 가장 적합한 기법을 사용하여 비디오 프레임을 샘플링할 수도 있습니다. 샘플링 동작은 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)

이미 디코딩된 비디오 배열을 전달하되 모델별 프레임 샘플링을 활성화하려면, VideoMetadata 객체나 일반 dict로 video_metadata를 제공하는 것이 강력히 권장됩니다. 이를 통해 샘플러가 원본 비디오의 길이와 FPS를 알 수 있습니다.

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

< source >

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

fetch_videos

< source >

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

단일 URL 또는 URL 목록을 해당하는 np.array 객체로 변환합니다.

단일 url이 전달되면 반환 값은 단일 객체입니다. 목록이 전달되면 객체의 목록이 반환됩니다.

from_dict

< source >

( 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 processor 객체를 초기화할 때 사용할 추가 매개변수입니다.

반환값

~video_processing_utils.VideoProcessorBase

해당 파라미터에서 인스턴스화된 비디오 프로세서 객체입니다.

~video_processing_utils.VideoProcessorBase의 유형을 매개변수의 Python 사전에서 초기화합니다.

from_json_file

< source >

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

매개변수

json_file (str 또는 os.PathLike) — 파라미터를 포함하는 JSON 파일의 경로.

반환값

~video_processing_utils.VideoProcessorBase 유형의 비디오 프로세서

해당 JSON 파일에서 인스턴스화된 video_processor 객체

~video_processing_utils.VideoProcessorBase 유형의 비디오 프로세서 인스턴스를 매개변수 JSON 파일의 경로에서 생성합니다.

from_pretrained

< source >

매개변수

pretrained_model_name_or_path (str 또는 os.PathLike) — 다음 중 하나일 수 있습니다:
- 문자열이며, huggingface.co의 모델 저장소에 호스팅된 사전 학습된 비디오의 model id입니다.
- ~video_processing_utils.VideoProcessorBase.save_pretrained 메서드를 사용하여 비디오 프로세서 파일을 저장한 디렉터리의 경로, 예: ./my_model_directory/.
- 저장된 비디오 프로세서 JSON 파일의 경로, 예: ./my_model_directory/video_preprocessor_config.json.
cache_dir (str 또는 os.PathLike, 선택 사항) — 표준 캐시를 사용하지 않을 경우, 다운로드한 사전 학습된 모델의 video processor를 캐시할 디렉터리의 경로입니다.
force_download (bool, 선택 사항, 기본값 False) — 캐시된 버전이 존재하더라도 video processor 파일을 (재)다운로드를 강제하고 캐시된 버전을 덮어쓸지 여부입니다.
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에서 허용하는 모든 식별자, 즉 브랜치 이름, 태그 이름 또는 커밋 ID가 될 수 있습니다.

~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

< source >

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

매개변수

pretrained_model_name_or_path (str 또는 os.PathLike) — 파라미터 사전(dictionary)을 가져오려는 사전 학습된 체크포인트의 식별자입니다.
subfolder (str, 선택 사항, 기본값 "") — huggingface.co의 모델 저장소에서 관련 파일이 하위 폴더에 있는 경우, 여기에 폴더 이름을 지정할 수 있습니다.

반환값

tuple[Dict, Dict]

video processor 객체를 인스턴스화하는 데 사용될 사전(들).

pretrained_model_name_or_path에서 매개변수 사전으로 해석하여, from_dict를 사용해 ~video_processing_utils.VideoProcessorBase 유형의 비디오 프로세서 인스턴스를 생성하는 데 사용합니다.

preprocess

< source >

( 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 범위로 이루어진 단일 비디오 또는 비디오 배치(batch)를 기대합니다. 픽셀 값이 0에서 1 범위로 이루어진 비디오를 전달하는 경우 do_rescale=False로 설정하십시오.
do_convert_rgb (bool, kwargs, 선택 사항) — 이미지를 RGB로 변환할지 여부입니다.
do_resize (bool, kwargs, 선택) — 이미지를 리사이즈할지 여부.
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 모델의 최대 입력 차원을 설명합니다.
default_to_square (bool, kwargs, 선택 사항) — size가 int인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부.
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — 이미지를 리사이즈할 경우 사용할 리샘플링 필터입니다. 이는 PILImageResampling enum 중 하나일 수 있습니다. do_resize가 True로 설정된 경우에만 효과가 있습니다.
do_rescale (bool, kwargs, 선택 사항) — 이미지를 다시 스케일링할지 여부입니다.
rescale_factor (float, kwargs, optional) — do_rescale이 True로 설정된 경우 이미지를 리스케일하기 위한 리스케일 팩터입니다.
do_normalize (bool, kwargs, optional) — 이미지를 정규화할지 여부.
image_mean (Union[float, list[float], tuple[float, ...]], kwargs, 선택) — 정규화에 사용할 이미지 평균입니다. do_normalize가 True로 설정된 경우에만 효과가 있습니다.
image_std (Union[float, list[float], tuple[float, ...]], kwargs, 선택) — 정규화에 사용할 이미지 표준 편차. do_normalize가 True로 설정된 경우에만 효과가 있습니다.
do_center_crop (bool, kwargs, 선택) — 이미지를 중앙으로 크롭할지 여부.
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, 선택 사항) — ChannelDimension.FIRST만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다.
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다:
- "channels_first" 또는 ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지.
- "channels_last" 또는 ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지.
- "none" 또는 ChannelDimension.NONE: (height, width) 형식의 이미지.
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — 동영상을 처리할 장치입니다. 설정되지 않은 경우, 입력 동영상에서 장치를 추론합니다.
do_sample_frames (bool, kwargs, 선택) — 처리 전에 비디오에서 프레임을 샘플링할지, 아니면 비디오 전체를 처리할지 여부를 지정합니다.
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, 선택) — 비디오 메타데이터를 반환할지 여부를 지정합니다. 비디오 메타데이터는 비디오 길이, 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], 선택 사항) — 초기화 시 PyTorch/Numpy 텐서에서 정수 목록을 변환하려면 여기에 tensor_type를 지정할 수 있습니다.

register_for_auto_class

< source >

( auto_class = 'AutoVideoProcessor' )

매개변수

auto_class (str 또는 type, 선택 사항, 기본값 "AutoVideoProcessor ") — 이 새로운 video processor를 등록할 auto class입니다.

이 클래스를 주어진 auto 클래스에 등록합니다. 라이브러리에 포함된 비디오 프로세서는 이미 AutoVideoProcessor에 매핑되어 있으므로, 이 메서드는 커스텀 비디오 프로세서에만 사용해야 합니다.

이 API는 실험적이며 다음 릴리스에서 일부 경미한 호환성 변경 사항이 있을 수 있습니다.

save_pretrained

< source >

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

매개변수

save_directory (str 또는 os.PathLike) — 비디오 프로세서 JSON 파일이 저장될 디렉터리(존재하지 않으면 생성됨).
push_to_hub (bool, 선택 사항, 기본값 False) — 모델을 저장한 후 Hugging Face 모델 허브에 푸시할지 여부입니다. repo_id를 사용하여 푸시할 저장소를 지정할 수 있으며, 지정하지 않으면 네임스페이스 내 save_directory의 이름이 기본값으로 사용됩니다.
kwargs (dict[str, Any], 선택) — push_to_hub() 메서드에 함께 전달되는 추가 키워드 인자입니다.

save_directory 디렉토리에 비디오 프로세서 객체를 저장하여 ~video_processing_utils.VideoProcessorBase.from_pretrained 클래스 메서드를 사용해 다시 로드할 수 있도록 합니다.

to_dict

< source >

( ) → dict[str, Any]

반환값

dict[str, Any]

이 video processor 인스턴스를 구성하는 모든 속성의 사전입니다.

이 인스턴스를 Python 딕셔너리로 직렬화합니다.

BaseVideoProcessor

클래스 transformers.BaseVideoProcessor

< source >

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

convert_to_rgb

< source >

( video: torch.Tensor ) → torch.Tensor

매개변수

video ("torch.Tensor") — 변환할 비디오입니다.

반환값

torch.Tensor

변환된 비디오.

비디오를 RGB 형식으로 변환합니다.

sample_frames

< source >

( 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

video 프레임에서 샘플링할 인덱스.

0과 총 프레임 수 사이에서 원하는 프레임 수를 균등하게 샘플링하는 기본 샘플링 함수입니다. fps가 메타데이터와 함께 전달되면, fps 프레임/초가 균등하게 샘플링됩니다. num_frames와 fps 인수는 상호 배타적입니다.

Update on GitHub

Transformers

비디오 프로세서

사용 예시

Video processor 백엔드

사용자 지정 백엔드

저장 및 다시 로드

샘플링 동작

VideoProcessorMixin

클래스 transformers.VideoProcessorMixin

fetch_videos

from_dict

from_json_file

from_pretrained

get_video_processor_dict

preprocess

register_for_auto_class

save_pretrained

to_dict

BaseVideoProcessor

클래스 transformers.BaseVideoProcessor

convert_to_rgb

sample_frames