Pemroses video

Video Processor adalah utilitas yang bertanggung jawab untuk menyiapkan fitur input untuk model video, serta menangani pascapemrosesan output mereka. Utilitas ini menyediakan transformasi seperti pengubahan ukuran, normalisasi, dan konversi ke PyTorch. Bersama dengan transformasi, kelas VideoProcessor menangani dekoding video dari path lokal atau URL (memerlukan torchcodec) dan pengambilan sampel frame sesuai dengan strategi yang spesifik untuk model.

Video processor memperluas fungsionalitas image processor dengan memungkinkan Vision Large Language Models (VLMs) untuk menangani video dengan set argumen yang berbeda dibandingkan gambar. Komponen ini berfungsi sebagai jembatan antara data video mentah dan model, memastikan bahwa fitur input dioptimalkan untuk VLM.

Pengaturan video processor disimpan di video_preprocessor_config.json. Checkpoint yang lebih lama mungkin menyimpannya di preprocessor_config.json. Lihat Save and reload untuk pendaftaran backend kustom saat memuat ulang.

Contoh Penggunaan

Berikut adalah contoh cara memuat video processor dengan model 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 dijalankan pada perangkat tensor input, atau pada CPU untuk input lainnya. Atur device untuk memindahkan video ke perangkat lain sebelum preprocessing; ini tidak mengubah backend. Anda juga dapat mengompilasi preprocessing torchvision dengan torch.compile saat menggunakan akselerator.

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

Backend prosesor video

Pemroses video bawaan menggunakan torchvision untuk pengubahan ukuran, penskalaan ulang, dan normalisasi secara batch. Instal PyTorch dan torchvision untuk menggunakannya. Berbeda dengan pemroses gambar, pemroses video bawaan tidak menyediakan backend PIL.

AutoVideoProcessor memilih backend torchvision secara default. Anda juga dapat memintanya secara eksplisit dan memeriksa atribut backend dari processor yang dimuat.

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

Argumen backend memilih implementasi pra-pemrosesan, bukan decoder video. Lihat Perilaku sampling untuk decoding dan sampling frame.

Backend kustom

BaseVideoProcessor menyediakan pra-pemrosesan berbasis torchvision. Untuk implementasi non-torchvision, Anda dapat membuat subkelas dari VideoProcessorMixin dan menimpa preprocess untuk mengembalikan BatchFeature yang berisi input yang diharapkan oleh model.

Daftarkan kelas kustom dengan AutoVideoProcessor.register(), dan gunakan video_processor_classes untuk memetakan nama backend ke kelas. Contoh di bawah ini mengasumsikan NewCustomVideoProcessor telah didefinisikan dengan pra-pemrosesan yang diperlukan oleh checkpoint 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")

Gunakan exist_ok=True karena LlavaOnevisionConfig sudah terdaftar. Entri yang diberikan akan digabungkan ke dalam pemetaan backend-nya, di mana nama yang cocok akan diganti, dan entri yang tidak diberikan, seperti torchvision, akan dipertahankan.

Simpan dan muat ulang

save_pretrained() menyimpan konfigurasi pra-pemrosesan, bukan pemetaan backend yang ditambahkan dengan AutoVideoProcessor.register(). Dalam proses Python yang sama, muat ulang prosesor yang disimpan dengan backend="custom":

custom_processor.save_pretrained("./saved-video-processor")
custom_processor = AutoVideoProcessor.from_pretrained("./saved-video-processor", backend="custom")

Registrasi kustom berlaku untuk proses Python saat ini. Pada proses baru, definisikan atau impor kelas kustom tersebut dan daftarkan ulang sebelum memuat.

Perilaku sampling

Video processor juga dapat mengambil sampel frame video menggunakan teknik yang paling sesuai untuk model tertentu. Perilaku pengambilan sampel dikendalikan dengan argumen do_sample_frames dan dapat dikonfigurasi melalui parameter spesifik model seperti num_frames atau fps (laju di mana video akan diambil sampelnya). Jika video input diberikan sebagai path lokal atau URL (str), processor akan mendekodekannya secara otomatis. Untuk memperoleh metadata tentang video yang telah didekodekan, seperti indeks frame yang diambil sampelnya, dimensi asli, durasi, dan fps, berikan return_metadata=True ke processor.

Menentukan num_frames tidak menjamin bahwa output akan berisi tepat jumlah frame tersebut. Tergantung pada model, sampler dapat menerapkan batas minimum atau maksimum frame.

Decoder default adalah torchcodec, yang harus diinstal.

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)

If you pass an already decoded video array but still want to enable model-specific frame sampling, it is strongly recommended to provide video_metadata. This allows the sampler to know the original video’s duration and FPS. You can pass metadata as a VideoMetadata object or as a plain 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

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

Mengonversi satu atau daftar url menjadi objek np.array yang sesuai.

Jika satu url diberikan, nilai yang dikembalikan akan berupa satu objek. Jika sebuah daftar diberikan, sebuah daftar objek akan dikembalikan.

from_dict

< source >

( video_processor_dict: dict**kwargs ) → ~video_processing_utils.VideoProcessorBase

Parameter

video_processor_dict (dict[str, Any]) — Kamus yang akan digunakan untuk menginstansiasi objek video processor. Kamus semacam itu dapat diperoleh dari checkpoint pretrained dengan memanfaatkan metode ~video_processing_utils.VideoProcessorBase.to_dict.
kwargs (dict[str, Any]) — Parameter tambahan untuk menginisialisasi objek video processor.

Mengembalikan

~video_processing_utils.VideoProcessorBase

Objek video processor yang diinstansiasi dari parameter tersebut.

Membuat instans dari tipe ~video_processing_utils.VideoProcessorBase dari kamus Python berisi parameter.

from_json_file

< source >

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

Parameter

json_file (str atau os.PathLike) — Path ke file JSON yang berisi parameter.

Mengembalikan

Pemroses video bertipe ~video_processing_utils.VideoProcessorBase

objek video_processor yang diinstansiasi dari file JSON tersebut.

Membuat instans video processor bertipe ~video_processing_utils.VideoProcessorBase dari path ke file JSON berisi parameter.

from_pretrained

< source >

Parameter

pretrained_model_name_or_path (str atau os.PathLike) — Ini bisa berupa:
- sebuah string, model id dari video pretrained yang dihosting di dalam repo model di huggingface.co.
- path ke direktori yang berisi file video processor yang disimpan menggunakan metode ~video_processing_utils.VideoProcessorBase.save_pretrained, misalnya ./my_model_directory/.
- path ke file JSON video processor yang disimpan file, misalnya ./my_model_directory/video_preprocessor_config.json.
cache_dir (str atau os.PathLike, opsional) — Path ke direktori tempat video processor model pretrained yang diunduh harus di-cache jika cache standar tidak digunakan.
force_download (bool, opsional, default False) — Apakah akan memaksa (mengunduh ulang) file video processor dan menimpa versi yang sudah di-cache jika ada.
proxies (dict[str, str], opsional) — Kamus server proxy untuk digunakan berdasarkan protokol atau endpoint, misalnya {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Proxy digunakan pada setiap permintaan.
token (str atau bool, opsional) — Token yang digunakan sebagai otorisasi bearer HTTP untuk file jarak jauh. Jika True, atau tidak ditentukan, akan menggunakan token yang dihasilkan saat menjalankan hf auth login (disimpan di ~/.huggingface).
revision (str, opsional, default "main") — Versi model spesifik yang akan digunakan. Bisa berupa nama branch, nama tag, atau commit id, karena kami menggunakan sistem berbasis git untuk menyimpan model dan artefak lainnya di huggingface.co, sehingga revision dapat berupa identifikasi apa pun yang diizinkan oleh git.

Instansiasi tipe ~video_processing_utils.VideoProcessorBase dari sebuah video processor.

Contoh:

# 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]

Parameter

pretrained_model_name_or_path (str atau os.PathLike) — Identitas checkpoint terlatih sebelumnya yang dari mana kita ingin mengambil kamus parameter.
subfolder (str, opsional, defaultnya "") — Jika file yang relevan berada di dalam subfolder dari repo model di huggingface.co, Anda dapat menentukan nama folder di sini.

Mengembalikan

tuple[Dict, Dict]

Kamus yang akan digunakan untuk menginstansiasi objek pemroses video.

Dari pretrained_model_name_or_path, selesaikan menjadi kamus parameter, untuk digunakan dalam menginstansiasi pemroses video bertipe ~video_processing_utils.VideoProcessorBase menggunakan from_dict.

praproses

< 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

Parameter

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]]]) — Video yang akan dipreprocess. Mengharapkan satu video atau batch video dengan nilai piksel berkisar dari 0 hingga 255. Jika mengirimkan video dengan nilai piksel antara 0 dan 1, atur do_rescale=False.
do_convert_rgb (bool, kwargs, opsional) — Apakah akan mengonversi gambar ke RGB.
do_resize (bool, kwargs, opsional) — Apakah akan mengubah ukuran gambar.
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Menggambarkan dimensi input maksimum untuk model.
default_to_square (bool, kwargs, opsional) — Apakah akan menggunakan gambar persegi sebagai default saat mengubah ukuran, jika size berupa int.
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — Filter resampling yang digunakan jika mengubah ukuran gambar. Ini dapat berupa salah satu enum PILImageResampling. Hanya berpengaruh jika do_resize diatur ke True.
do_rescale (bool, kwargs, opsional) — Apakah akan melakukan penskalaan ulang pada gambar.
rescale_factor (float, kwargs, opsional) — Faktor rescale untuk menskalakan ulang gambar jika do_rescale diatur ke True.
do_normalize (bool, kwargs, opsional) — Apakah akan menormalisasi gambar.
image_mean (Union[float, list[float], tuple[float, ...]], kwargs, opsional) — Rata-rata gambar yang digunakan untuk normalisasi. Hanya berpengaruh jika do_normalize diatur ke True.
image_std (Union[float, list[float], tuple[float, ...]], kwargs, opsional) — Standar deviasi gambar yang digunakan untuk normalisasi. Hanya berpengaruh jika do_normalize diatur ke True.
do_center_crop (bool, kwargs, opsional) — Apakah akan melakukan center crop pada gambar.
do_pad (bool, kwargs, opsional) — Apakah akan melakukan padding pada gambar. Padding dilakukan ke ukuran terbesar dalam batch atau ke ukuran persegi tetap per gambar. Strategi padding yang tepat bergantung pada model.
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Ukuran gambar keluaran setelah menerapkan center_crop.
data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opsional) — Hanya ChannelDimension.FIRST yang didukung. Ditambahkan untuk kompatibilitas dengan prosesor lambat.
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opsional) — Format dimensi channel untuk gambar input. Jika tidak diset, format dimensi channel akan disimpulkan dari gambar input. Bisa berupa salah satu dari:
- "channels_first" atau ChannelDimension.FIRST: gambar dalam format (num_channels, height, width).
- "channels_last" atau ChannelDimension.LAST: gambar dalam format (height, width, num_channels).
- "none" atau ChannelDimension.NONE: gambar dalam format (height, width).
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — Perangkat untuk memproses video. Jika tidak disetel, perangkat akan disimpulkan dari video input.
do_sample_frames (bool, kwargs, opsional) — Apakah akan mengambil sampel frame dari video sebelum diproses atau memproses seluruh video.
video_metadata (Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — Metadata dari video yang berisi informasi tentang durasi total, fps, dan jumlah total frame. Metadata ini akan digunakan untuk mengambil sampel frame dari video atau menghitung timestamp. Jangan kirimkan metadata apa pun kecuali Anda mencoba mendekode video secara manual sebelum diproses
fps (Annotated[int | float | None, None], kwargs) — Target frame yang akan disampel per detik ketika do_sample_frames=True.
num_frames (Annotated[int | None, None], kwargs) — Jumlah maksimum frame yang akan disampelkan saat do_sample_frames=True.
return_metadata (bool, kwargs, opsional) — Apakah akan mengembalikan metadata video atau tidak. Metadata video adalah objek yang berisi informasi tentang durasi video, fps, backend decoding, dll.
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Mengembalikan tensor bertumpuk jika diset ke 'pt', selain itu mengembalikan daftar tensor.

Mengembalikan

~image_processing_base.BatchFeature

data (dict) — Kamus berisi daftar/array/tensor yang dikembalikan oleh metode call (‘pixel_values’, dll.).
tensor_type (Union[None, str, TensorType], opsional) — Anda dapat memberikan tensor_type di sini untuk mengonversi daftar bilangan bulat menjadi Tensor PyTorch/Numpy saat inisialisasi.

register_for_auto_class

< source >

( auto_class = 'AutoVideoProcessor' )

Parameter

auto_class (str atau type, opsional, defaultnya "AutoVideoProcessor ") — Kelas otomatis untuk mendaftarkan pemroses video baru ini.

Daftarkan kelas ini dengan kelas auto yang diberikan. Ini hanya harus digunakan untuk pemroses video kustom karena yang ada di pustaka sudah dipetakan dengan AutoVideoProcessor.

API ini bersifat eksperimental dan mungkin memiliki beberapa perubahan pemecah (breaking changes) kecil di rilis berikutnya.

save_pretrained

< source >

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

Parameter

save_directory (str atau os.PathLike) — Direktori tempat file JSON video processor akan disimpan (akan dibuat jika belum ada).
push_to_hub (bool, opsional, default False) — Apakah model Anda akan didorong ke Hugging Face model hub setelah disimpan. Anda dapat menentukan repository yang ingin Anda tuju dengan repo_id (defaultnya adalah nama save_directory di namespace Anda).
kwargs (dict[str, Any], opsional) — Argumen kata kunci tambahan yang diteruskan ke metode push_to_hub().

Simpan objek video processor ke direktori save_directory agar dapat dimuat ulang menggunakan metode kelas ~video_processing_utils.VideoProcessorBase.from_pretrained.

to_dict

< source >

( ) → dict[str, Any]

Mengembalikan

dict[str, Any]

Kamus dari semua atribut yang membentuk instance video processor ini.

Menserialisasi instance ini ke dalam kamus Python.

BaseVideoProcessor

kelas transformers.BaseVideoProcessor

< source >

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

convert_to_rgb

< source >

( video: torch.Tensor ) → torch.Tensor

Parameter

video ("torch.Tensor") — Video yang akan dikonversi.

Mengembalikan

torch.Tensor

Video yang telah dikonversi.

Mengonversi video ke format RGB.

sample_frames

< source >

( metadata: VideoMetadatanum_frames: int | None = Nonefps: int | float | None = None**kwargs ) → np.ndarray

Parameter

metadata (VideoMetadata) — Metadata dari video yang berisi informasi tentang durasi total, fps, dan jumlah total frame.
num_frames (int, opsional) — Jumlah maksimum frame yang akan disampel. Bawaan adalah self.num_frames.
fps (int atau float, opsional) — Target frame yang akan disampel per detik. Defaultnya adalah self.fps.

Mengembalikan

np.ndarray

Indeks untuk mengambil sampel bingkai video.

Fungsi sampling default yang mengambil sampel sejumlah frame yang diinginkan secara seragam antara 0 dan total jumlah frame. Jika fps diteruskan bersama metadata, fps frame per detik diambil sampelnya secara seragam. Argumen num_frames dan fps saling eksklusif.

Update on GitHub

Transformers

Pemroses video

Contoh Penggunaan

Backend prosesor video

Backend kustom

Simpan dan muat ulang

Perilaku sampling

VideoProcessorMixin

kelas transformers.VideoProcessorMixin

fetch_videos

from_dict

from_json_file

from_pretrained

get_video_processor_dict

praproses

register_for_auto_class

save_pretrained

to_dict

BaseVideoProcessor

kelas transformers.BaseVideoProcessor

convert_to_rgb

sample_frames