Video processor

Video Processorは、動画モデルの入力特徴量の準備と、その出力の後処理を担当するユーティリティです。リサイズ、正規化、PyTorch への変換などの変換処理を提供します。変換処理に加えて、VideoProcessor クラスは、ローカルパスまたは URL からの動画デコード（torchcodec が必要）と、モデル固有の戦略に基づくフレームサンプリングを処理します。

video processorは、画像プロセッサの機能を拡張し、Vision Large Language Models (VLMs) が画像とは異なる引数セットを使用して動画を処理できるようにします。これは生データである動画とモデルの間の橋渡し役として機能し、入力特徴量が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")

前処理は、入力テンソルのデバイス上、またはその他の入力の場合は 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")

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)

デコード済みの動画配列を渡す場合でも、モデル固有のフレームサンプリングを有効にしたい場合は、video_metadata を提供することを強く推奨します。これにより、サンプラーは元の動画の再生時間と FPS を把握できます。メタデータは VideoMetadata オブジェクトとして渡すことも、プレーンな dict として渡すこともできます。

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

class 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[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

これらのパラメータからインスタンス化されたビデオプロセッサオブジェクト。

Pythonのパラメータ辞書から~video_processing_utils.VideoProcessorBaseの型をインスタンス化します。

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 オブジェクト。

パラメータの JSON ファイルへのパスから、~video_processing_utils.VideoProcessorBase 型のビデオプロセッサをインスタンス化します。

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) — 存在する場合はキャッシュされたバージョンを上書きし、動画プロセッサのファイルを（再）ダウンロードすることを強制するかどうか。
proxies (dict[str, str]、省略可) — プロトコルまたはエンドポイントごとに使用するプロキシサーバーの辞書です。例: {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. 各リクエストでこれらのプロキシが使用されます。
token (str または bool、省略可) — リモートファイルの HTTP ベアラ認証に使用するトークンです。True の場合、または指定されていない場合は、hf auth login を実行した際に生成されたトークン（~/.huggingface に保存）が使用されます。
revision (str, 省略可, デフォルトは "main") — 使用する特定のモデルのバージョンです。huggingface.co ではモデルやその他の成果物を保存するために git ベースのシステムを使用しているため、ブランチ名、タグ名、またはコミット ID を指定できます。したがって、 revision には git で許可される任意の識別子を指定できます。

Hubでプルリクエストを作成した場合、revision="refs/pr/<pr_number>"を渡すことでテストできます。
return_unused_kwargs (bool、省略可、デフォルトは False) — False の場合、この関数は最終的な video processor オブジェクトのみを返します。True の場合、この関数は Tuple(video_processor, unused_kwargs) を返します。ここで unused_kwargs は、キーが video processor の属性でないキー/値のペアで構成される辞書です。つまり、video_processor の更新に使用されず、それ以外は無視される kwargs の部分です。
subfolder (str、任意、デフォルトは "") — huggingface.co 上のモデルリポジトリのサブフォルダ内に該当するファイルが配置されている場合、ここにフォルダ名を指定できます。
kwargs (dict[str, Any]、省略可) — kwargs 内の、キーが video processor の属性である値は、読み込まれた値の上書きに使用されます。キーが video processor の属性でないキー/値ペアの動作は、return_unused_kwargs キーワード引数によって制御されます。

~video_processing_utils.VideoProcessorBase の型を、video processor からインスタンス化します。

例:

# 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) — パラメータの辞書を取得したい事前学習済みチェックポイントの識別子です。
subfolder (str、任意、デフォルトは "") — huggingface.co 上のモデルリポジトリのサブフォルダ内に該当するファイルが配置されている場合、ここにフォルダ名を指定できます。

戻り値

tuple[Dict, Dict]

動画プロセッサオブジェクトをインスタンス化するために使用される辞書です。

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 の範囲にある、単一の動画またはバッチの動画を想定しています。ピクセル値が 0 から 1 の範囲にある動画を渡す場合は、do_rescale=False を設定してください。
do_convert_rgb (bool、kwargs、任意) — 画像を RGB に変換するかどうかを指定します。
do_resize (bool、kwargs、optional) — 画像をリサイズするかどうか。
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — モデルへの最大入力次元を記述します。
default_to_square (bool、kwargs、任意) — サイズが整数の場合、リサイズ時に正方形の画像をデフォルトとするかどうか。
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — 画像のリサイズ時に使用するリサンプリングフィルタ。PILImageResampling の列挙型のいずれかを使用できます。do_resize が True に設定されている場合のみ有効です。
do_rescale (bool、kwargs、optional) — 画像をリスケールするかどうかを指定します。
rescale_factor (float、kwargs、任意) — 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、任意) — サポートされているのは ChannelDimension.FIRST のみです。slow processors との互換性のために追加されました。
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、任意) — 処理前に動画からフレームをサンプリングするか、動画全体を処理するかどうかを指定します。
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 の場合、1 秒あたりサンプリングするターゲットフレーム数。
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]、省略可) — 初期化時に PyTorch/Numpy の Tensor 内の整数リストを変換するために、ここで tensor_type を指定できます。

register_for_auto_class

< source >

( auto_class = 'AutoVideoProcessor' )

パラメータ

auto_class (str または type、省略可能、デフォルトは "AutoVideoProcessor ") — この新しい video processor を登録するための auto class。

このクラスを指定された auto クラスに登録します。ライブラリ内のものはすでにAutoVideoProcessorにマッピングされているため、このメソッドはカスタムな video processor の場合にのみ使用してください。

この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

class 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、省略可) — 1 秒あたりにサンプリングするターゲットフレーム数。デフォルトは self.fps です。

戻り値

np.ndarray

動画フレームをサンプリングするためのインデックス。

0から総フレーム数までの範囲で、指定されたフレーム数を均等にサンプリングするデフォルトのサンプリング関数です。メタデータとともにfpsが渡された場合、fpsフレーム/秒で均等にサンプリングされます。引数num_framesとfpsは排他的です。

Update on GitHub

Transformers

Video processor

使用例

Video processor バックエンド

カスタムバックエンド

保存と再読み込み

サンプリングの動作

VideoProcessorMixin

class 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

class transformers.BaseVideoProcessor

convert_to_rgb

sample_frames