Video İşleyici

Video Processor, video modelleri için giriş özelliklerini hazırlamaktan ve çıktıların son işlemlerini gerçekleştirmekten sorumlu bir yardımcıdır. Yeniden boyutlandırma, normalizasyon ve PyTorch'a dönüştürme gibi dönüşümler sağlar.

Video işleyici, görüntü işleyicilerin işlevselliğini, görüntülere kıyasla farklı bir argüman setiyle videoları işlemeye olanak tanıyarak genişletir. Ham video verisi ile model arasında bir köprü görevi görür ve girdi özelliklerinin VLM için optimize edilmesini sağlar.

Bir video modelinin Hugging Face Hub'ındaki veya yerel dizindeki yapılandırmasını (görüntü boyutu, normalize etme ve yeniden ölçeklendirme yapılıp yapılmayacağı vb.) yüklemek için from_pretrained() kullanın. Her önceden eğitilmiş modelin yapılandırması [video_preprocessor_config.json] dosyasında kaydedilmelidir ancak eski modellerde yapılandırma preprocessor_config.json dosyasında kaydedilmiş olabilir. Dikkat edin, ikincisi tercih edilmez ve gelecekte kaldırılacaktır.

Bir video işleyici, çok modlu bir işleyicinin parçası olduğunda, yapılandırması bunun yerine processor_config.json içinde iç içe yer alır. Ayrıntılar için İşleyiciyi kaydetme ve yükleme bölümüne bakın.

Kullanım Örneği

llava-hf/llava-onevision-qwen2-0.5b-ov-hf modeliyle bir video işlemciyi nasıl yükleyeceğinize dair bir örnek:

from transformers import AutoVideoProcessor

processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf")

Şu anda, videolar için temel görüntü işleyici kullanılıyorsa, video verisi her kareyi ayrı bir görüntü olarak ele alarak ve dönüşümleri kare kare uygulayarak işlenir. İşlevsel olsa da bu yaklaşım çok verimli değildir. AutoVideoProcessor kullanmak, torchvision kütüphanesinden yararlanarak hızlı video işleyicilerinden faydalanmamızı sağlar. Hızlı işleyiciler, her video veya kare üzerinde gezinmeden tüm video grubunu (batch) birden işler. Bu güncellemeler GPU hızlandırmayı devreye sokar ve özellikle yüksek veri akışı gerektiren görevlerde işleme hızını önemli ölçüde artırır.

Hızlı video işleyicileri tüm modeller için mevcuttur ve bir AutoVideoProcessor başlatıldığında varsayılan olarak yüklenir. Hızlı bir video işleyici kullanırken, işlemenin yapılacağı cihazı belirtmek için device argümanını da ayarlayabilirsiniz. Varsayılan olarak, girdiler tensörlerse işleme girdilerle aynı cihazda, aksi halde CPU üzerinde yapılır. Hızda daha fazla iyileşme için, cihaz olarak bir hızlandırıcı kullanırken işleyiciyi derleyebiliriz.

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

Kare örneklemesi

Bir video işleyici, videoyu çözer ve modelin gerçekten gördüğü kareleri seçer. Örnekleme işlemini etkinleştirmek için do_sample_frames=True değerini ayarlayın, ardından kareleri iki yoldan biriyle seçin.

• num_frames, videoda eşit aralıklarla dağıtılmış sabit bir sayı ister.
• fps, saniyede kare cinsinden bir hız ister.

Bir yol veya URL iletin; işlemci, varsayılan çözümleyici olan torchcodec ile videoyu sizin için çözer. torchcodec kullanılamıyorsa ve eski bir torchvision sürümündeyseniz, çözümleme torchvision'a geri düşer.

Örnekleme yapılmış kare indekslerini, orijinal boyutları, süresini ve fps değerini geri almak için return_metadata=True ekleyin.

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)

Örnekleme varsayılanları modele göre değişir ve num_frames veya fps için yapılan bir istek bir garanti değil, başlangıç noktasıdır. Qwen3-VL, fps=2 ile örnekler ve sonucu min_frames=4 ile max_frames=768 arasında sınırlar; bu nedenle bir saniyelik bir klip bile 4 kare üretirken, uzun bir kaydın kare sayısı gerçek kare sayısının çok altında bir değere sabitlenir.

temporal_patch_size içeren modeller, zaman ekseni boyunca karelerin bu sayıda karelik yamalar halinde gruplandığı ikinci bir kısıt ekler ve sayı tam bölünebilene kadar son kare tekrarlanır.

Zaten çözümlenmiş bir video dizisi geçirip yine de modele özgü örneklemeyi kullanmak istiyorsanız, video_metadata parametresini de sağlamanız gerekir. Bu parametre verilmediğinde, örnekleyici orijinal süreyi veya fps değerini bilemez; fps üzerinden örneklemeye çalışıldığında uyarı verir ve videonun 24 fps ile kaydedildiğini varsayar.

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