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. En plus des transformations, la classe VideoProcessor gère le décodage vidéo depuis des chemins locaux ou des URL (nécessite torchcodec) et l’échantillonnage des images selon des stratégies spécifiques à chaque modèle.

Le processeur vidéo étend les fonctionnalités des processeurs d’images en permettant aux modèles de langage visuels (VLM) de traiter des vidéos avec un ensemble d’arguments distinct de celui des images. Il sert de pont entre les données vidéo brutes et le modèle, garantissant que les caractéristiques d’entrée sont optimisées pour le VLM.

Les paramètres du processeur vidéo sont enregistrés dans video_preprocessor_config.json. Les points de contrôle plus anciens peuvent les stocker dans preprocessor_config.json. Consultez Enregistrer et recharger pour la registration d'un backend personnalisé lors du rechargement.

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

La prétraitement s’exécute sur l’appareil du tenseur d’entrée, ou sur le CPU pour les autres entrées. Définissez device pour déplacer les vidéos vers un autre appareil avant la prétraitement ; cela ne modifie pas le backend. Vous pouvez également compiler la prétraitement de torchvision avec torch.compile lors de l’utilisation d’un accélérateur.

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

Backends de processeur vidéo

Les processeurs de vidéo intégrés utilisent torchvision pour le redimensionnement, le rééchelonnement et la normalisation par lots. Installez PyTorch et torchvision pour les utiliser. Contrairement aux processeurs d’images, les processeurs de vidéo intégrés ne fournissent pas de backend PIL.

AutoVideoProcessor sélectionne par défaut le backend torchvision. Vous pouvez également le demander explicitement et inspecter l’attribut backend du processeur chargé.

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

L'argument backend sélectionne l'implémentation de la prétraitement, et non le décodeur vidéo. Consultez Comportement de l'échantillonnage pour le décodage et l'échantillonnage des images.

Backends personnalisés

BaseVideoProcessor fournit un prétraitement basé sur torchvision. Pour une implémentation non basée sur torchvision, vous pouvez sous-classez VideoProcessorMixin et surcharger preprocess pour retourner un BatchFeature contenant les entrées attendues par le modèle.

Enregistrez des classes personnalisées avec AutoVideoProcessor.register(), et utilisez video_processor_classes pour associer les noms de backends aux classes. L’exemple ci-dessous suppose que NewCustomVideoProcessor est défini avec le prétraitement requis par le checkpoint LLaVA-OneVision.

from transformers import LlavaOnevisionConfig

AutoVideoProcessor.register(
    LlavaOnevisionConfig,
    video_processor_classes={"custom": NewCustomVideoProcessor},
    exist_ok=True,
)
custom_processor = AutoVideoProcessor.from_pretrained(model_id, backend="custom")

Utilisez exist_ok=True car LlavaOnevisionConfig est déjà enregistré. Les entrées fournies sont fusionnées dans sa correspondance de backend, où les noms correspondants sont remplacés, et les entrées non fournies, telles que torchvision, sont conservées.

Enregistrer et recharger

save_pretrained() enregistre la configuration de prétraitement, mais pas les mappings de backend ajoutés avec AutoVideoProcessor.register(). Dans le même processus Python, rechargez le processeur enregistré avec backend="custom" :

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

Les enregistrements personnalisés s'appliquent au processus Python actuel. Dans un nouveau processus, définissez ou importez la classe personnalisée et enregistrez-la à nouveau avant le chargement.

Comportement de l'échantillonnage

Le processeur vidéo peut également échantillonner les images vidéo en utilisant la technique la mieux adaptée au modèle donné. Le comportement de l'échantillonnage est contrôlé par l'argument do_sample_frames et peut être configuré via des paramètres spécifiques au modèle tels que num_frames ou fps (la fréquence à laquelle la vidéo sera échantillonnée). Si la vidéo d'entrée est fournie sous forme de chemin local ou d'URL (str), le processeur la décodera automatiquement. Pour obtenir des métadonnées sur la vidéo décodée, telles que les indices des images échantillonnées, les dimensions d'origine, la durée et le fps, passez return_metadata=True au processeur.

Spécifier num_frames ne garantit pas que la sortie contiendra exactement ce nombre de frames. Selon le modèle, le sampler peut imposer des limites minimales ou maximales de frames.

Le décodeur par défaut est torchcodec, qui doit être installé.

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)

If you pass an already decoded video array but still want to enable model-specific frame sampling, it is strongly recommended to provide video_metadata. This allows the sampler to know the original video’s duration and FPS. You can pass metadata as a VideoMetadata object or as a plain dict.

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

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

Convertit une URL unique ou une liste d'URL en objets np.array correspondants.

Si une seule url est passée, la valeur retournée sera un seul objet. Si une liste est passée, une liste d'objets est retournée.

from_dict

< source >

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

Paramètres

video_processor_dict (dict[str, Any]) — Dictionnaire qui sera utilisé pour instancier l'objet de traitement vidéo. Un tel dictionnaire peut être récupéré à partir d'un point de contrôle préentraîné en utilisant la méthode ~video_processing_utils.VideoProcessorBase.to_dict.
kwargs (dict[str, Any]) — Paramètres supplémentaires à partir desquels initialiser l'objet de processeur vidéo.

Retourne

~video_processing_utils.VideoProcessorBase

L'objet de processeur vidéo instancié à partir de ces paramètres.

Instancie un type de ~video_processing_utils.VideoProcessorBase à partir d'un dictionnaire Python de paramètres.

from_json_file

< source >

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

Paramètres

json_file (str ou os.PathLike) — Chemin vers le fichier JSON contenant les paramètres.

Retourne

Un processeur vidéo de type ~video_processing_utils.VideoProcessorBase

L'objet video_processor instancié à partir de ce fichier JSON.

Instancie un processeur vidéo de type ~video_processing_utils.VideoProcessorBase à partir du chemin d'accès vers un fichier JSON de paramètres.

from_pretrained

< source >

Paramètres

pretrained_model_name_or_path (str ou os.PathLike) — Cela peut être soit :
- une chaîne de caractères, l'identifiant du modèle d'une vidéo préentraînée hébergée dans un dépôt de modèles sur huggingface.co.
- un chemin vers un dossier contenant un fichier de processeur vidéo enregistré à l’aide de la méthode ~video_processing_utils.VideoProcessorBase.save_pretrained, par exemple ./my_model_directory/.
- a path to a saved video processor JSON file, e.g., ./my_model_directory/video_preprocessor_config.json.
cache_dir (str ou os.PathLike, facultatif) — Chemin vers un répertoire dans lequel le processeur de vidéo de modèle pré-entraîné téléchargé doit être mis en cache si le cache standard ne doit pas être utilisé.
force_download (bool, facultatif, par défaut False) — Indique s'il faut forcer le (re)téléchargement des fichiers du processeur de vidéo et remplacer les versions en cache si elles existent.
proxies (dict[str, str], facultatif) — Un dictionnaire de serveurs proxy à utiliser par protocole ou point de terminaison, par exemple {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Les proxys sont utilisés pour chaque requête.
token (str ou bool, facultatif) — Le jeton à utiliser comme autorisation bearer HTTP pour les fichiers distants. Si True, ou non spécifié, utilisera le jeton généré lors de l’exécution de hf auth login (stocké dans ~/.huggingface).
revision (str, facultatif, par défaut "main") — La version spécifique du modèle à utiliser. Il peut s’agir du nom d’une branche, du nom d’une étiquette ou d’un identifiant de commit, car nous utilisons un système basé sur git pour stocker les modèles et autres artefacts sur huggingface.co, de sorte que revision peut être n’importe quel identifiant autorisé par git.

Instanciez un type de ~video_processing_utils.VideoProcessorBase à partir d'un processeur vidéo.

Exemples :

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

Paramètres

pretrained_model_name_or_path (str ou os.PathLike) — L'identifiant du point de contrôle pré-entraîné à partir duquel nous voulons obtenir le dictionnaire des paramètres.
subfolder (str, facultatif, par défaut "") — Si les fichiers pertinents se trouvent dans un sous-dossier du dépôt de modèle sur huggingface.co, vous pouvez spécifier le nom du dossier ici.

Retourne

tuple[Dict, Dict]

Le(s) dictionnaire(s) qui sera(ont) utilisé(s) pour instancier l'objet de processeur de vidéo.

À partir de pretrained_model_name_or_path, résout en un dictionnaire de paramètres, à utiliser pour instancier un processeur vidéo de type ~video_processing_utils.VideoProcessorBase à l’aide de from_dict.

prétraiter

< 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

Paramètres

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]]]) — Vidéo à prétraiter. S’attend à une vidéo unique ou à un lot de vidéos dont les valeurs de pixels vont de 0 à 255. Si vous passez des vidéos dont les valeurs de pixels sont comprises entre 0 et 1, définissez do_rescale=False.
do_convert_rgb (bool, kwargs, facultatif) — Indique s'il faut convertir l'image en RGB.
do_resize (bool, kwargs, facultatif) — Indique s'il faut redimensionner l'image.
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Définit les dimensions maximales des entrées du modèle.
default_to_square (bool, kwargs, facultatif) — Indique s'il faut par défaut redimensionner l'image en carré si la taille est un entier.
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — Filtre de rééchantillonnage à utiliser lors du redimensionnement de l’image. Il peut s’agir de l’une des valeurs de l’enum PILImageResampling. N’a un effet que si do_resize est défini sur True.
do_rescale (bool, kwargs, facultatif) — Indique s'il faut rééchelonner l'image.
rescale_factor (float, kwargs, facultatif) — Facteur de remise à l'échelle à appliquer à l'image si do_rescale est défini sur True.
do_normalize (bool, kwargs, facultatif) — Indique s'il faut normaliser l'image.
image_mean (Union[float, list[float], tuple[float, ...]], kwargs, facultatif) — Moyenne de l'image à utiliser pour la normalisation. N'a un effet que si do_normalize est défini sur True.
image_std (Union[float, list[float], tuple[float, ...]], kwargs, facultatif) — Écart-type de l'image à utiliser pour la normalisation. N'a un effet que si do_normalize est défini sur True.
do_center_crop (bool, kwargs, facultatif) — Indique s'il faut effectuer un recadrage centré de l'image.
do_pad (bool, kwargs, facultatif) — Indique s'il faut effectuer un bourrage (padding) de l'image. Le bourrage est effectué soit jusqu'à la plus grande taille du lot, soit jusqu'à une taille carrée fixe par image. La stratégie de bourrage exacte dépend du modèle.
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Taille de l'image de sortie après application de center_crop.
data_format (Union[str, ~image_utils.ChannelDimension], kwargs, facultatif) — Seul ChannelDimension.FIRST est pris en charge. Ajouté pour la compatibilité avec les processeurs lents.
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, facultatif) — Le format de la dimension des canaux pour l'image d'entrée. Si non défini, le format de la dimension des canaux est déduit de l'image d'entrée. Peut être l'un des éléments suivants :
- "channels_first" ou ChannelDimension.FIRST : image au format (num_channels, height, width).
- "channels_last" ou ChannelDimension.LAST : image au format (hauteur, largeur, nombre de canaux).
- "none" ou ChannelDimension.NONE : image au format (hauteur, largeur).
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — L’appareil sur lequel traiter les vidéos. Si non défini, l’appareil est déduit des vidéos d’entrée.
do_sample_frames (bool, kwargs, facultatif) — Indique s'il faut échantillonner des images de la vidéo avant le traitement ou traiter la vidéo entière.
video_metadata (Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — Métadonnées de la vidéo contenant des informations sur la durée totale, le fps et le nombre total d’images. Elles seront utilisées pour échantillonner des images de la vidéo ou calculer des horodatages. Ne passez aucune métadonnée à moins de chercher à décoder la vidéo manuellement avant le traitement
fps (Annotated[int | float | None, None], kwargs) — Nombre de cibles d'images à échantillonner par seconde lorsque do_sample_frames=True.
num_frames (Annotated[int | None, None], kwargs) — Nombre maximal de frames à échantillonner lorsque do_sample_frames=True.
return_metadata (bool, kwargs, facultatif) — Indique s'il faut renvoyer les métadonnées de la vidéo ou non. Les métadonnées vidéo sont un objet contenant des informations sur la durée de la vidéo, le fps, le backend de décodage, etc.
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Retourne des tenseurs empilés si défini sur 'pt', sinon retourne une liste de tenseurs.

Retourne

~image_processing_base.BatchFeature

data (dict) — Dictionnaire de listes/tableaux/tenseurs renvoyé par la méthode call (« pixel_values », etc.).
tensor_type (Union[None, str, TensorType], facultatif) — Vous pouvez spécifier un tensor_type ici pour convertir les listes d'entiers en tenseurs PyTorch/Numpy lors de l'initialisation.

register_for_auto_class

< source >

( auto_class = 'AutoVideoProcessor' )

Paramètres

auto_class (str ou type, facultatif, par défaut "AutoVideoProcessor ") — La classe automatique avec laquelle enregistrer ce nouveau processeur vidéo.

Enregistrez cette classe avec une classe auto donnée. Cette opération ne doit être utilisée que pour les processeurs de vidéo personnalisés, car ceux de la bibliothèque sont déjà associés à AutoVideoProcessor.

Cette API est expérimentale et peut comporter quelques modifications cassantes dans les prochaines versions.

save_pretrained

< source >

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

Paramètres

save_directory (str ou os.PathLike) — Répertoire où le fichier JSON du processeur vidéo sera enregistré (il sera créé s'il n'existe pas).
push_to_hub (bool, facultatif, par défaut False) — Indique s'il faut ou non pousser votre modèle sur le hub de modèles Hugging Face après l'avoir enregistré. Vous pouvez spécifier le dépôt auquel vous souhaitez pousser avec repo_id (par défaut, il s'agit du nom de save_directory dans votre espace de noms).
kwargs (dict[str, Any], facultatif) — Arguments supplémentaires passés à la méthode push_to_hub().

Enregistrer un objet de processeur vidéo dans le répertoire save_directory afin qu’il puisse être rechargé à l’aide de la méthode de classe ~video_processing_utils.VideoProcessorBase.from_pretrained.

to_dict

< source >

( ) → dict[str, Any]

Retourne

dict[str, Any]

Dictionnaire de tous les attributs qui composent cette instance de processeur vidéo.

Sérialise cette instance en dictionnaire Python.

BaseVideoProcessor

classe transformers.BaseVideoProcessor

< source >

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

convert_to_rgb

< source >

( video: torch.Tensor ) → torch.Tensor

Paramètres

video ("torch.Tensor") — La vidéo à convertir.

Retourne

torch.Tensor

La vidéo convertie.

Convertit une vidéo au format RGB.

sample_frames

< source >

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

Paramètres

metadata (VideoMetadata) — Métadonnées de la vidéo contenant des informations sur la durée totale, le fps et le nombre total d’images.
num_frames (int, facultatif) — Nombre maximal de frames à échantillonner. Valeur par défaut : self.num_frames.
fps (int ou float, facultatif) — Nombre de cibles d'images à échantillonner par seconde. La valeur par défaut est self.fps.

Retourne

np.ndarray

Indices pour échantillonner les images vidéo.

Fonction d'échantillonnage par défaut qui échantillonne uniformément le nombre de frames souhaité entre 0 et le nombre total de frames. Si fps est transmis avec les métadonnées, fps frames par seconde sont échantillonnées uniformément. Les arguments num_frames et fps sont mutuellement exclusifs.

Update on GitHub

Transformers

Processeur vidéo

Exemple d'utilisation

Backends de processeur vidéo

Backends personnalisés

Enregistrer et recharger

Comportement de l'échantillonnage

VideoProcessorMixin

classe transformers.VideoProcessorMixin

fetch_videos

from_dict

from_json_file

from_pretrained

get_video_processor_dict

prétraiter

register_for_auto_class

save_pretrained

to_dict

BaseVideoProcessor

classe transformers.BaseVideoProcessor

convert_to_rgb

sample_frames