Processeur vidéo

Un Video Processor est un utilitaire chargé de préparer les caractéristiques d'entrée pour les modèles vidéo, ainsi que de gérer le post-traitement de leurs sorties. Il fournit des transformations telles que le redimensionnement, la normalisation et la conversion en PyTorch.

Le processeur vidéo étend les fonctionnalités des processeurs d’images en permettant aux modèles de traiter des vidéos avec un ensemble d’arguments distinct de celui utilisé pour les images. Il fait le lien entre les données vidéo brutes et le modèle, en veillant à ce que les caractéristiques d’entrée soient optimisées pour le VLM.

Utilisez from_pretrained() pour charger la configuration d'un processeur vidéo (taille de l'image, normalisation et rééchelonnement, etc.) à partir d'un modèle vidéo sur le Hub Hugging Face ou d'un répertoire local. La configuration de chaque modèle pré-entraîné doit être enregistrée dans un fichier [video_preprocessor_config.json], mais les anciens modèles peuvent avoir la configuration enregistrée dans un fichier preprocessor_config.json. Notez que cette dernière option est moins recommandée et sera supprimée à l'avenir.

Lorsqu’un processeur vidéo fait partie d’un processeur multimodal, sa configuration est imbriquée dans processor_config.json. Consultez Enregistrer et charger un processeur pour plus de détails.

Exemple d'utilisation

Voici un exemple de chargement d’un processeur vidéo avec le modèle 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")

Actuellement, si l’on utilise le processeur d’images de base pour les vidéos, les données vidéo sont traitées en considérant chaque image comme une image individuelle et en appliquant les transformations image par image. Bien que fonctionnelle, cette approche n’est pas très efficace. L’utilisation de AutoVideoProcessor permet de tirer parti des processeurs vidéo rapides, en s’appuyant sur la bibliothèque torchvision. Les processeurs rapides traitent l’ensemble du lot de vidéos d’un seul coup, sans itérer sur chaque vidéo ou chaque image. Ces mises à jour introduisent l’accélération GPU et améliorent considérablement la vitesse de traitement, en particulier pour les tâches nécessitant un débit élevé.

Des processeurs vidéo rapides sont disponibles pour tous les modèles et sont chargés par défaut lors de l’initialisation d’un AutoVideoProcessor. Lors de l’utilisation d’un processeur vidéo rapide, vous pouvez également définir l’argument device pour spécifier l’appareil sur lequel le traitement doit être effectué. Par défaut, le traitement est réalisé sur le même appareil que les entrées si celles-ci sont des tenseurs, ou sur le CPU dans le cas contraire. Pour une amélioration supplémentaire de la vitesse, il est possible de compiler le processeur lors de l’utilisation d’un accélérateur en tant qu’appareil.

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

Échantillonnage des images

Un processeur vidéo décode une vidéo et sélectionne les images que le modèle perçoit réellement. Définissez do_sample_frames=True pour activer l'échantillonnage, puis choisissez les images de l'une des deux manières suivantes.

• num_frames demande un nombre fixe réparti uniformément sur l’ensemble de la vidéo.
• fps demande un taux en images par seconde.

Transmettez un chemin ou une URL et le processeur décode la vidéo pour vous à l’aide de torchcodec, le décodeur par défaut. Si torchcodec n’est pas disponible et que vous utilisez une ancienne version de torchvision, le décodage bascule sur torchvision.

Ajoutez return_metadata=True pour récupérer les indices des images échantillonnées, les dimensions d'origine, la durée et le 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)

Les valeurs par défaut de l'échantillonnage sont propres à chaque modèle, et une demande de num_frames ou de fps constitue un point de départ plutôt qu'une garantie. Qwen3-VL effectue l'échantillonnage à fps=2 et borne le résultat entre min_frames=4 et max_frames=768, de sorte qu'un clip d'une seconde produit toujours 4 images, tandis qu'un enregistrement long est plafonné bien en dessous de son nombre réel d'images.

Les modèles disposant d'un temporal_patch_size ajoutent une seconde contrainte : les images sont regroupées en patches de cette taille le long de l'axe temporel, et la dernière image est répétée jusqu'à ce que le nombre total soit divisible sans reste.

Si vous transmettez un tableau de vidéo déjà décodé et que vous souhaitez toujours un échantillonnage spécifique au modèle, fournissez également video_metadata. Sans cela, l’échantillonneur ne connaît pas la durée d’origine ni le fps, et l’échantillonnage par fps émet un avertissement et suppose que la vidéo a été enregistrée à 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"
)