Video Processor

Video Processor adalah utilitas yang bertanggung jawab untuk menyiapkan fitur input untuk model video, serta menangani pascapemrosesan outputnya. Utilitas ini menyediakan transformasi seperti pengubahan ukuran, normalisasi, dan konversi ke PyTorch.

Video processor memperluas fungsionalitas image processor dengan memungkinkan model untuk menangani video menggunakan seperangkat argumen yang berbeda dibandingkan dengan gambar. Komponen ini berfungsi sebagai jembatan antara data video mentah dan model, memastikan bahwa fitur input dioptimalkan untuk VLM.

Gunakan from_pretrained() untuk memuat konfigurasi video processor (ukuran gambar, apakah akan menormalisasi dan menskalakan ulang, dll.) dari model video di Hub Hugging Face atau direktori lokal. Konfigurasi untuk setiap model pretrained sebaiknya disimpan dalam file [video_preprocessor_config.json], tetapi model yang lebih lama mungkin menyimpan konfigurasinya dalam file preprocessor_config.json. Perhatikan bahwa opsi kedua kurang disarankan dan akan dihapus di masa depan.

Ketika video processor merupakan bagian dari multimodal processor, konfigurasinya bersarang di processor_config.json alih-alih. Lihat Menyimpan dan memuat processor untuk detailnya.

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

Saat ini, jika menggunakan base image processor untuk video, data video diproses dengan memperlakukan setiap frame sebagai gambar individual dan menerapkan transformasi per frame. Meskipun berfungsi, pendekatan ini tidak sangat efisien. Menggunakan AutoVideoProcessor memungkinkan kita memanfaatkan fast video processors, dengan memanfaatkan pustaka torchvision. Fast processors menangani seluruh batch video sekaligus, tanpa mengiterasi setiap video atau frame. Pembaruan ini memperkenalkan akselerasi GPU dan secara signifikan meningkatkan kecepatan pemrosesan, terutama untuk tugas yang membutuhkan throughput tinggi.

Prosesor video cepat tersedia untuk semua model dan dimuat secara default saat AutoVideoProcessor diinisialisasi. Saat menggunakan prosesor video cepat, Anda juga dapat mengatur argumen device untuk menentukan perangkat tempat pemrosesan dilakukan. Secara default, pemrosesan dilakukan pada perangkat yang sama dengan input jika input berupa tensor, atau pada CPU jika tidak. Untuk peningkatan kecepatan yang lebih besar, kita dapat mengompilasi prosesornya saat menggunakan akselerator sebagai perangkat.

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

Pengambilan sampel bingkai

Video processor mem-decode video dan memilih frame yang benar-benar dilihat oleh model. Atur do_sample_frames=True untuk mengaktifkan sampling, lalu pilih frame dengan salah satu dari dua cara berikut.

• num_frames meminta jumlah tetap yang tersebar merata di seluruh video.
• fps meminta laju dalam frame per detik.

Lewati path atau URL, dan processor akan mendekode video untuk Anda dengan torchcodec, decoder bawaan. Jika torchcodec tidak tersedia dan Anda menggunakan versi torchvision yang lebih lama, proses decoding akan kembali ke torchvision.

Tambahkan return_metadata=True untuk mendapatkan kembali indeks frame yang disampelkan, dimensi asli, durasi, dan 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)

Nilai default sampling bersifat per model, dan permintaan untuk num_frames atau fps merupakan titik awal, bukan jaminan. Qwen3-VL melakukan sampling pada fps=2 dan membatasi hasilnya di antara min_frames=4 dan max_frames=768, sehingga klip berdurasi satu detik tetap menghasilkan 4 frame, sementara rekaman panjang dibatasi jauh di bawah jumlah frame aslinya.

Model dengan temporal_patch_size menambahkan kendala kedua, yaitu frame dikelompokkan menjadi patch sebanyak jumlah frame tersebut sepanjang sumbu waktu, dan frame terakhir diulang hingga jumlah frame dapat dibagi secara merata.

Jika Anda meneruskan array video yang sudah didekodekan dan tetap menginginkan sampling yang spesifik untuk model, sediakan juga video_metadata. Tanpa itu, sampler tidak mengetahui durasi asli atau fps, dan sampling berdasarkan fps akan memberikan peringatan serta mengasumsikan video direkam pada 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"
)