Video iş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. Dönüşümlerin yanı sıra VideoProcessor sınıfı, yerel yollardan veya URL'lerden video çözümlemesini (torchcodec gerektirir) ve modele özgü stratejilere göre kare örnekleme işlemlerini yönetir.

Video işleyici, görüntü işleyicilerin işlevselliğini, Görüntü Büyük Dil Modelleri'nin (VLM) görüntülere kıyasla farklı bir argüman setiyle videoları işleyebilmesini sağlayarak 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.

Video işlemci ayarları video_preprocessor_config.json dosyasında saklanır. Eski kontrol noktaları bunları preprocessor_config.json dosyasında saklayabilir. Yeniden yükleme sırasında özel arka uç kaydı için Kaydet ve yeniden yükle 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")

Ön işleme, girdi tensörünün cihazında veya diğer girdiler için CPU üzerinde çalışır. Videoları ön işlemeden önce başka bir cihaza taşımak için device parametresini ayarlayın; bu, arka ucu değiştirmez. Bir hızlandırıcı kullanırken torchvision ön işleme kodunu torch.compile ile derleyebilirsiniz.

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 işleyici arka uçları

Yerleşik video işleyiciler, toplu yeniden boyutlandırma, yeniden ölçekleme ve normalizasyon için torchvision kullanır. Bunları kullanmak için PyTorch ve torchvision'ı yükleyin. Görsel işleyicilerin aksine, yerleşik video işleyiciler bir PIL arka ucu sağlamaz.

AutoVideoProcessor varsayılan olarak torchvision arka ucunu seçer. Bunu açıkça da isteyebilir ve yüklenen işleyicinin backend öznitelğini inceleyebilirsiniz.

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 argümanı, video çözücüyü değil, ön işleme uygulamasını seçer. Çözümleme ve kare örneklemesi için Örnekleme davranışı bölümüne bakın.

Özel arka uçlar

BaseVideoProcessor, torchvision tabanlı ön işleme sağlar. torchvision dışı bir uygulama için VideoProcessorMixin sınıfından türetip preprocess metodunu, modelin beklediği girdileri içeren bir BatchFeature döndürecek şekilde yeniden tanımlayabilirsiniz.

Özel sınıfları AutoVideoProcessor.register() ile kaydedin ve video_processor_classes ile backend adlarını sınıflara eşleyin. Aşağıdaki örnek, NewCustomVideoProcessor'nin LLaVA-OneVision checkpoint'inin gerektirdiği ön işleme ile tanımlandığını varsayar.

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 zaten kayıtlı olduğu için exist_ok=True kullanın. Sağlanan girdiler, eşleşen adların değiştirildiği ve sağlanmayan girdilerin (örneğin torchvision) korunduğu backend eşlemesine birleştirilir.

Kaydet ve yeniden yükle

save_pretrained() ön işleme yapılandırmasını kaydeder, AutoVideoProcessor.register() ile eklenen arka uç eşlemelerini kaydetmez. Aynı Python sürecinde, kaydedilen işlemciyi backend="custom" ile yeniden yükleyin:

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

Özel kayıtlar, geçerli Python sürecine uygulanır. Yeni bir süreçte, özel sınıfı tanımlayın veya içe aktarın ve yüklemeye başlamadan önce yeniden kaydedin.

Örnekleme davranışı

Video işleyici, verilen model için en uygun tekniği kullanarak video karelerini örnekleyebilir. Örneklemleme davranışı do_sample_frames argümanı ile kontrol edilir ve num_frames veya fps (videonun örneklenme hızı) gibi modele özgü parametreler aracılığıyla yapılandırılabilir. Girdi videosu yerel bir yol veya URL (str) olarak verilirse, işleyici onu otomatik olarak çözer. Çözülen video hakkında örneklenen kare dizinleri, orijinal boyutlar, süre ve fps gibi meta verileri almak için işleyiciye return_metadata=True parametresini iletin.

num_frames parametresinin belirtilmesi, çıktının tam olarak bu sayıda kare içereceğini garanti etmez. Modelin türüne bağlı olarak örnekleyici, minimum veya maksimum kare sınırlarını uygulayabilir.

Varsayılan çözücü torchcodec'tir ve kurulu olmalıdır.

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)

Zaten çözümlenmiş bir video dizisi geçiriyorsanız ancak model-özel kare örneklemeyi yine de etkinleştirmek istiyorsanız, video_metadata sağlaması şiddetle önerilir. Bu, örnekleme aracının orijinal videonun süresini ve FPS değerini bilmesini sağlar. Metadata'ı bir VideoMetadata nesnesi olarak veya düz bir dict olarak geçebilirsiniz.

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

sınıf 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 )

Tek bir URL veya URL listesini ilgili np.array nesnelerine dönüştürür.

Tek bir url geçirilirse, dönüş değeri tek bir nesne olacaktır. Bir liste geçirilirse, nesnelerin listesi döndürülür.

from_dict

< source >

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

Parametreler

video_processor_dict (dict[str, Any]) — Video işlemci nesnesini örneklemek için kullanılacak sözlük. Böyle bir sözlük, ~video_processing_utils.VideoProcessorBase.to_dict metodu kullanılarak önceden eğitilmiş bir kontrol noktasından alınabilir.
kwargs (dict[str, Any]) — Video işleyici nesnesini başlatmak için kullanılacak ek parametreler.

Dönüş değeri

~video_processing_utils.VideoProcessorBase

Bu parametrelerden örneklenen video işleyici nesnesi.

Parametrelerin Python sözlüğünden ~video_processing_utils.VideoProcessorBase türünün bir örneğini oluşturur.

from_json_file

< source >

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

Parametreler

json_file (str veya os.PathLike) — Parametreleri içeren JSON dosyasının yolu.

Dönüş değeri

~video_processing_utils.VideoProcessorBase türünde bir video işleyici

O JSON dosyasından örneklenen video_processor nesnesi

Parametrelerin JSON dosyasına giden yoldan ~video_processing_utils.VideoProcessorBase türünde bir video işleyici örnekler.

from_pretrained

< source >

Parametreler

pretrained_model_name_or_path (str veya os.PathLike) — Bunlardan biri olabilir:
- bir dize, huggingface.co içindeki bir model deposunda barındırılan önceden eğitilmiş bir videonun model kimliği.
- ~video_processing_utils.VideoProcessorBase.save_pretrained yöntemi kullanılarak kaydedilmiş bir video işlemci dosyası içeren bir dizin için bir yol, örneğin ./my_model_directory/.
- kaydedilmiş bir video işlemci JSON dosyasına giden bir yol, örneğin ./my_model_directory/video_preprocessor_config.json.
cache_dir (str veya os.PathLike, isteğe bağlı) — Standart önbellek kullanılmayacaksa, indirilen önceden eğitilmiş model video işleyicisinin önbelleğe alınacağı dizinin yolu.
force_download (bool, isteğe bağlı, varsayılan False) — Video işleyici dosyalarının indirilmesini (yeniden) zorlayıp mevcut ise önbellekteki sürümleri geçersiz kılıp kılmayacağı.
proxies (dict[str, str], isteğe bağlı) — Protokole veya uç noktaya göre kullanılacak vekil sunucuların sözlüğü, örn. {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Vekiller her istekte kullanılır.
token (str veya bool, isteğe bağlı) — Uzak dosyalar için HTTP bearer yetkilendirmesi olarak kullanılacak jeton. True ise veya belirtilmezse, hf auth login çalıştırıldığında oluşturulan jeton ( ~/.huggingface içinde saklanır) kullanılır.
revision (str, isteğe bağlı, varsayılan "main") — Kullanılacak belirli model sürümü. huggingface.co üzerinde modelleri ve diğer artefaktları depolamak için git tabanlı bir sistem kullandığımız için bir dal adı, etiket adı veya commit kimliği olabilir; bu nedenle revision, git tarafından izin verilen herhangi bir tanımlayıcı olabilir.

Bir video işleyiciden ~video_processing_utils.VideoProcessorBase türünün bir örneğini oluşturun.

Örnekler:

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

Parametreler

pretrained_model_name_or_path (str veya os.PathLike) — Parametre sözlüğünü almak istediğimiz önceden eğitilmiş kontrol noktasının tanımlayıcısı.
subfolder (str, isteğe bağlı, varsayılan "") — İlgili dosyalar huggingface.co üzerindeki model deposunun bir alt klasöründe konumlanıyorsa, klasör adını burada belirleyebilirsiniz.

Dönüş değeri

tuple[Dict, Dict]

Video işleyici nesnesini örneklemek için kullanılacak sözlük(ler).

pretrained_model_name_or_path'den, from_dict kullanılarak ~video_processing_utils.VideoProcessorBase türünde bir video işleyicisi örneklemek için kullanılacak parametre sözlüğüne çözümlenir.

ön işleme

< 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

Parametreler

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]]]) — Ön işleme yapılacak video. Piksel değerleri 0 ile 255 arasında değişen tek bir video veya video grubu beklenir. Piksel değerleri 0 ile 1 arasında olan videoları geçiriyorsanız do_rescale=False olarak ayarlayın.
do_convert_rgb (bool, kwargs, opsiyonel) — Görselin RGB'ye dönüştürülüp dönüştürülmemesi.
do_resize (bool, kwargs, opsiyonel) — Görselin yeniden boyutlandırılıp boyutlandırılmayacağı.
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Modelin kabul ettiği maksimum giriş boyutlarını açıklar.
default_to_square (bool, kwargs, opsiyonel) — Boyut bir int ise, yeniden boyutlandırma sırasında varsayılan olarak kare bir görüntüye geçilip geçilmeyeceği.
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — Görsel yeniden boyutlandırılıyorsa kullanılacak yeniden örnekleme filtresi. Bu, PILImageResampling enum değerlerinden biri olabilir. Yalnızca do_resize True olarak ayarlanırsa etkilidir.
do_rescale (bool, kwargs, opsiyonel) — Görselin yeniden ölçeklendirilip ölçeklendirilmeyeceği.
rescale_factor (float, kwargs, opsiyonel) — do_rescale True olarak ayarlanırsa görüntüyü yeniden ölçeklemek için kullanılan yeniden ölçekleme faktörü.
do_normalize (bool, kwargs, opsiyonel) — Görselin normalize edilip edilmeyeceği.
image_mean (Union[float, list[float], tuple[float, ...]], kwargs, opsiyonel) — Normalizasyon için kullanılacak görüntü ortalaması. Yalnızca do_normalize True olarak ayarlanırsa etkilidir.
image_std (Union[float, list[float], tuple[float, ...]], kwargs, opsiyonel) — Normalizasyon için kullanılacak görüntü standart sapması. Yalnızca do_normalize True olarak ayarlanmışsa etkilidir.
do_center_crop (bool, kwargs, opsiyonel) — Görselin ortadan kırpılıp kırpılmayacağı.
do_pad (bool, kwargs, opsiyonel) — Görselin dolgu (padding) uygulanıp uygulanmayacağı. Dolgu, partideki en büyük boyuta veya görsel başına sabit kare bir boyuta yapılır. Kesin dolgu stratejisi modele bağlıdır.
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — center_crop uygulandıktan sonra çıktı görüntüsünün boyutu.
data_format (Union[str, ~image_utils.ChannelDimension], kwargs, isteğe bağlı) — Yalnızca ChannelDimension.FIRST desteklenir. Yavaş işleyicilerle uyumluluk için eklendi.
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, isteğe bağlı) — Girdi görüntüsü için kanal boyutu biçimi. Ayarlanmazsa, kanal boyutu biçimi girdi görüntüsünden çıkarılır. Aşağıdakilerden biri olabilir:
- "channels_first" veya ChannelDimension.FIRST: (num_channels, height, width) biçiminde görüntü.
- "channels_last" veya ChannelDimension.LAST: (yükseklik, genişlik, kanal sayısı) biçiminde görüntü.
- "none" veya ChannelDimension.NONE: (height, width) biçiminde görüntü.
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — Videoların işleneceği cihaz. Ayarlanmamışsa, cihaz girdi videolarından çıkarılır.
do_sample_frames (bool, kwargs, opsiyonel) — İşlemden önce videodan kare örneklenip örneklenmeyeceği veya videonun tamamının işleneceği.
video_metadata (Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — Toplam süre, fps ve toplam kare sayısı hakkında bilgi içeren videonun metadata'sı. Videodan kare örneklemek veya zaman damgaları hesaplamak için kullanılacaktır. Videoyu işlemden önce manuel olarak çözmeye çalışmıyorsanız herhangi bir metadata geçirmeyin
fps (Annotated[int | float | None, None], kwargs) — do_sample_frames=True olduğunda saniyede örneklenmesi hedeflenen kare sayısı.
num_frames (Annotated[int | None, None], kwargs) — do_sample_frames=True olduğunda örneklenmesi gereken maksimum kare sayısı.
return_metadata (bool, kwargs, opsiyonel) — Video metadata döndürülüp döndürülmemesi. Video metadata, video süresi, fps, çözümleme arka ucu gibi bilgileri içeren bir nesnedir.
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 'pt' olarak ayarlanırsa yığılmış tensörler döndürür, aksi takdirde tensör listesi döndürür.

Dönüş değeri

~image_processing_base.BatchFeature

data (dict) — call yönteminin döndürdüğü listeler/diziler/tensörler sözlüğü (‘pixel_values’ vb.).
tensor_type (Union[None, str, TensorType], isteğe bağlı) — Başlatma sırasında PyTorch/Numpy Tensörlerindeki tamsayı listelerini dönüştürmek için burada bir tensor_type verebilirsiniz.

register_for_auto_class

< source >

( auto_class = 'AutoVideoProcessor' )

Parametreler

auto_class (str veya type, isteğe bağlı, varsayılan "AutoVideoProcessor ") — Bu yeni video işleyicisinin kaydedileceği otomatik sınıf.

Bu sınıfı, verilen bir otomatik sınıf ile kaydedin. Bu, kütüphanedeki AutoVideoProcessor ile zaten eşlenmiş olanlar dışında yalnızca özel video işleyicileri için kullanılmalıdır.

Bu API deneyseldir ve bir sonraki sürümlerde bazı küçük kırıcı değişiklikler içerebilir.

save_pretrained

< source >

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

Parametreler

save_directory (str veya os.PathLike) — Video işleyici JSON dosyasının kaydedileceği dizin (varsa oluşturulur).
push_to_hub (bool, isteğe bağlı, varsayılan False) — Modelinizi kaydettikten sonra Hugging Face model hub'ına gönderip göndermeyeceğinizi belirtir. Göndermek istediğiniz depoyu repo_id ile belirtebilirsiniz (varsayılan olarak ad alanınızdaki save_directory adını kullanır).
kwargs (dict[str, Any], isteğe bağlı) — push_to_hub() yöntemine iletilen ek anahtar kelime argümanları.

Bir video işlemci nesnesini save_directory dizinine kaydedin; böylece ~video_processing_utils.VideoProcessorBase.from_pretrained sınıf yöntemi kullanılarak yeniden yüklenebilir.

to_dict

< source >

( ) → dict[str, Any]

Dönüş değeri

dict[str, Any]

Bu video işleyici örneğini oluşturan tüm özniteliklerin sözlüğü.

Bu örneği bir Python sözlüğüne serialize eder.

BaseVideoProcessor

sınıf transformers.BaseVideoProcessor

< source >

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

convert_to_rgb

< source >

( video: torch.Tensor ) → torch.Tensor

Parametreler

video ("torch.Tensor") — Dönüştürülecek video.

Dönüş değeri

torch.Tensor

Dönüştürülen video.

Bir videoyu RGB formatına dönüştürür.

sample_frames

< source >

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

Parametreler

metadata (VideoMetadata) — Toplam süre, fps ve toplam kare sayısı hakkında bilgi içeren videonun metadata bilgisi.
num_frames (int, isteğe bağlı) — Örneklenecek maksimum kare sayısı. Varsayılan olarak self.num_frames'tir.
fps (int veya float, isteğe bağlı) — Saniyede örneklenmesi hedeflenen kare sayısı. Varsayılan olarak self.fps değerini kullanır.

Dönüş değeri

np.ndarray

Video karelerini örneklemek için dizinler.

0 ile toplam kare sayısı arasında istenen sayıda kareyi eşit aralıklarla örnekleyen varsayılan örneklemiş fonksiyonu. fps metadata ile birlikte geçirilirse, saniyede fps kare eşit aralıklarla örneklenir. num_frames ve fps argümanları birbirini dışlar.

Update on GitHub

Transformers

Video işleyici

Kullanım Örneği

Video işleyici arka uçları

Özel arka uçlar

Kaydet ve yeniden yükle

Örnekleme davranışı

VideoProcessorMixin

sınıf transformers.VideoProcessorMixin

fetch_videos

from_dict

from_json_file

from_pretrained

get_video_processor_dict

ön işleme

register_for_auto_class

save_pretrained

to_dict

BaseVideoProcessor

sınıf transformers.BaseVideoProcessor

convert_to_rgb

sample_frames