معالج الفيديو

يُعدّ Video Processor أداة مسؤولة عن تجهيز ميزات الإدخال لنماذج الفيديو، فضلاً عن معالجة مخرجاتها بعد المعالجة. فهو يوفر تحويلات مثل تغيير الحجم، والتطبيع، والتحويل إلى PyTorch.

يمدّد مُعالج الفيديو وظائف مُعالجات الصور من خلال تمكين النماذج من التعامل مع مقاطع الفيديو باستخدام مجموعة مميزة من الحجج مقارنةً بالصور. ويعمل هذا المُعالج كجسر بين بيانات الفيديو الخام والنموذج، مما يضمن تحسين ميزات الإدخال من أجل نموذج اللغة المرئي (VLM).

استخدم from_pretrained() لتحميل إعدادات معالج الفيديو (حجم الصورة، ما إذا كان سيتم تطبيع الصور وإعادة تحجيمها، إلخ) من نموذج فيديو على Hub الخاص بـ Hugging Face أو من مجلد محلي. يجب أن يُحفظ إعداد كل نموذج مُدرَّب مسبقًا في ملف [video_preprocessor_config.json]، لكن قد تكون النماذج الأقدم قد حفظت الإعدادات في ملف preprocessor_config.json. يُشار إلى أن الخيار الثاني أقل تفضيلاً وسيتم إزالته في المستقبل.

عندما يكون معالج الفيديو جزءًا من معالج متعدد الوسائط، فإن تكوينه يكون متداخلًا في processor_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")

حاليًا، عند استخدام معالج الصور الأساسي للفيديوهات، تتم معالجة بيانات الفيديو عن طريق اعتبار كل إطار صورة مستقلة وتطبيق التحويلات إطارًا بإطار. وعلى الرغم من أن هذا النهج يعمل، إلا أنه ليس كافيًا من حيث الكفاءة. يتيح استخدام AutoVideoProcessor الاستفادة من معالجات الفيديو السريعة، بالاستعانة بمكتبة torchvision. تتعامل المعالجات السريعة مع الدفعة الكاملة من الفيديوهات دفعة واحدة، دون الحاجة إلى التكرار على كل فيديو أو إطار. تُدخل هذه التحديثات تسريعًا عبر وحدة معالجة الرسوميات (GPU) وتُحسّن سرعة المعالجة بشكل كبير، لا سيما في المهام التي تتطلب معدل إنتاجية عالٍ.

تتوفر معالجات فيديو سريعة لجميع النماذج، وتُحمَّل افتراضيًا عند تهيئة AutoVideoProcessor. عند استخدام معالج فيديو سريع، يمكنك أيضًا تعيين معامل device لتحديد الجهاز الذي يجب أن تتم عليه عملية المعالجة. افتراضيًا، تتم المعالجة على نفس الجهاز الذي توجد عليه المدخلات إذا كانت متجهات (tensors)، وإلا فتتم على المعالج المركزي (CPU). للحصول على تحسين أكبر في السرعة، يمكننا تجميع (compile) المعالج عند استخدام مُسرِّع (accelerator) كجهاز.

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

عينة الإطار

يعمل معالج الفيديو على فك ترميز الفيديو واختيار الإطارات التي يراها النموذج فعليًا. اضبط do_sample_frames=True لتفعيل أخذ العينات، ثم اختر الإطارات بأحد طريقتين.

• num_frames يطلب عدداً ثابتاً موزعاً بالتساوي عبر الفيديو.
• يتطلب fps تحديد المعدل بإطار في الثانية.

مرّر مسارًا أو عنوان URL، وسيعمل المعالج على فك ترميز الفيديو نيابةً عنك باستخدام torchcodec، وهو مُفكك الترميز الافتراضي. إذا لم يكن torchcodec متاحًا وكنت تستخدم إصدارًا أقدم من torchvision، فإن فك الترميز سيتحول إلى الاعتماد على torchvision.

أضف return_metadata=True للحصول على فهارس الإطارات المُستخرجة، والأبعاد الأصلية، والمدة، ومعدل الإطارات في الثانية.

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)

تختلف قيم العينة الافتراضية من نموذج إلى آخر، وطلب num_frames أو fps يُعد نقطة انطلاق وليس ضمانًا. فعندما يعيّن Qwen3-VL قيمة fps=2، فإنه يقيّد النتيجة بين min_frames=4 وmax_frames=768، مما يعني أن مقطعًا مدته ثانية واحدة ينتج عنه 4 إطارات، بينما يُحَدّ التسجيل الطويل بكثير دون عدده الفعلي للإطارات.

تضيف النماذج التي تحتوي على temporal_patch_size قيدًا ثانيًا يتمثل في تجميع الإطارات في رقعات تحتوي على هذا العدد من الإطارات على محور الزمن، مع تكرار الإطار الأخير حتى يصبح العدد قابلاً للقسمة بالتساوي.

إذا مررت مصفوفة فيديو مفكوكة الترميز مسبقًا وما زلت ترغب في أخذ عينات محدد للنموذج، فقدم video_metadata أيضًا. بدونه، لن يعرف مُعَيِّن العينات المدة الأصلية أو معدل الإطارات في الثانية، وعند أخذ العينات حسب fps سيصدر تحذيرًا ويفترض أن الفيديو سُجّل بمعدل 24 إطارًا في الثانية.

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