Procesador de video

Un Video Processor es una utilidad encargada de preparar las características de entrada para modelos de video, así como de gestionar el posprocesamiento de sus salidas. Proporciona transformaciones como el redimensionado, la normalización y la conversión a PyTorch. Junto con las transformaciones, la clase VideoProcessor gestiona la decodificación de videos desde rutas locales o URLs (requiere torchcodec) y la muestreo de fotogramas según estrategias específicas de cada modelo.

El procesador de vídeo amplía la funcionalidad de los procesadores de imagen al permitir que los modelos de lenguaje visual (VLM) procesen vídeos con un conjunto de argumentos distinto al de las imágenes. Actúa como el puente entre los datos de vídeo crudos y el modelo, garantizando que las características de entrada estén optimizadas para el VLM.

La configuración del procesador de video se guarda en video_preprocessor_config.json. Los puntos de control antiguos pueden almacenarla en preprocessor_config.json. Consulte Guardar y recargar para el registro de backends personalizados al recargar.

Ejemplo de uso

A continuación se muestra un ejemplo de cómo cargar un procesador de video con el modelo 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")

El preprocesamiento se ejecuta en el dispositivo del tensor de entrada, o en la CPU para otras entradas. Establezca device para mover los videos a otro dispositivo antes del preprocesamiento; esto no cambia el backend. También puede compilar el preprocesamiento de torchvision con torch.compile cuando use un acelerador.

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 del procesador de video

Los procesadores de video integrados utilizan torchvision para el redimensionamiento, la reescalado y la normalización por lotes. Instale PyTorch y torchvision para usarlos. A diferencia de los procesadores de imagen, los procesadores de video integrados no ofrecen un backend de PIL.

AutoVideoProcessor selecciona el backend torchvision de forma predeterminada. También puede solicitarlo explícitamente e inspeccionar el atributo backend del procesador cargado.

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

El argumento backend selecciona la implementación de preprocesamiento, no el decodificador de video. Consulte Comportamiento de muestreo para la decodificación y el muestreo de fotogramas.

Backends personalizados

BaseVideoProcessor proporciona preprocesamiento basado en torchvision. Para una implementación que no use torchvision, puedes crear una subclase de VideoProcessorMixin y sobrescribir preprocess para devolver un BatchFeature que contenga las entradas esperadas por el modelo.

Registre clases personalizadas con AutoVideoProcessor.register() y use video_processor_classes para mapear los nombres de los backends a las clases. El siguiente ejemplo asume que NewCustomVideoProcessor está definido con el preprocesamiento requerido por el checkpoint de 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")

Use exist_ok=True porque LlavaOnevisionConfig ya está registrado. Las entradas proporcionadas se fusionan en su mapeo de backend, donde los nombres coincidentes se reemplazan, y las entradas no proporcionadas, como torchvision, se conservan.

Guardar y recargar

save_pretrained() guarda la configuración de preprocesamiento, no los mapeos de backend añadidos con AutoVideoProcessor.register(). En el mismo proceso de Python, recarga el procesador guardado con backend="custom":

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

Las registraciones personalizadas se aplican al proceso de Python actual. En un nuevo proceso, defina o importe la clase personalizada y regístrela nuevamente antes de cargarla.

Comportamiento de muestreo

El procesador de video también puede muestrear fotogramas de video utilizando la técnica más adecuada para el modelo dado. El comportamiento del muestreo se controla con el argumento do_sample_frames y se puede configurar mediante parámetros específicos del modelo, como num_frames o fps (la tasa a la que se muestreará el video). Si el video de entrada se proporciona como una ruta local o una URL (str), el procesador lo decodificará automáticamente. Para obtener metadatos sobre el video decodificado, como los índices de los fotogramas muestreados, las dimensiones originales, la duración y los fps, pase return_metadata=True al procesador.

Especificar num_frames no garantiza que la salida contenga exactamente ese número de fotogramas. Dependiendo del modelo, el muestreador puede aplicar límites mínimos o máximos de fotogramas.

El decodificador predeterminado es torchcodec, que debe estar instalado.

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

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

Convierte una sola URL o una lista de URLs en los objetos np.array correspondientes.

Si se pasa una única url, el valor devuelto será un único objeto. Si se pasa una lista, se devuelve una lista de objetos.

from_dict

< source >

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

Parámetros

video_processor_dict (dict[str, Any]) — Diccionario que se utilizará para instanciar el objeto de procesador de video. Dicho diccionario puede obtenerse de un punto de control preentrenado aprovechando el método ~video_processing_utils.VideoProcessorBase.to_dict.
kwargs (dict[str, Any]) — Parámetros adicionales para inicializar el objeto de procesador de video.

Devuelve

~video_processing_utils.VideoProcessorBase

El objeto de procesador de video instanciado a partir de esos parámetros.

Instancia un tipo de ~video_processing_utils.VideoProcessorBase a partir de un diccionario de Python de parámetros.

from_json_file

< source >

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

Parámetros

json_file (str o os.PathLike) — Ruta al archivo JSON que contiene los parámetros.

Devuelve

Un procesador de video de tipo ~video_processing_utils.VideoProcessorBase

El objeto video_processor instanciado a partir de ese archivo JSON.

Instancia un procesador de video de tipo ~video_processing_utils.VideoProcessorBase a partir de la ruta a un archivo JSON de parámetros.

from_pretrained

< source >

Parámetros

pretrained_model_name_or_path (str o os.PathLike) — Puede ser:
- una cadena, el model id de un video preentrenado alojado en un repositorio de modelos en huggingface.co.
- una ruta a un directorio que contenga un archivo de procesador de video guardado usando el método ~video_processing_utils.VideoProcessorBase.save_pretrained, por ejemplo, ./my_model_directory/.
- una ruta a un archivo JSON de procesador de video guardado, archivo, p. ej., ./my_model_directory/video_preprocessor_config.json.
cache_dir (str o os.PathLike, opcional) — Ruta a un directorio en el que se debe almacenar en caché el procesador de video de un modelo preentrenado descargado si no se debe utilizar la caché estándar.
force_download (bool, opcional, valor predeterminado False) — Indica si se debe forzar la (re)descarga de los archivos del procesador de video y sobrescribir las versiones en caché si existen.
proxies (dict[str, str], opcional) — Un diccionario de servidores proxy a utilizar por protocolo o punto de acceso, p. ej., {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Los proxies se utilizan en cada solicitud.
token (str o bool, opcional) — El token que se usará como autorización HTTP bearer para archivos remotos. Si es True, o no se especifica, se usará el token generado al ejecutar hf auth login (almacenado en ~/.huggingface).
revision (str, opcional, valor predeterminado "main") — La versión específica del modelo que se va a utilizar. Puede ser el nombre de una rama, el nombre de una etiqueta o un id de commit, ya que utilizamos un sistema basado en git para almacenar modelos y otros artefactos en huggingface.co, por lo que revision puede ser cualquier identificador permitido por git.

Instanciar un tipo de ~video_processing_utils.VideoProcessorBase desde un procesador de video.

Ejemplos:

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

Parámetros

pretrained_model_name_or_path (str o os.PathLike) — El identificador del punto de control preentrenado del que queremos obtener el diccionario de parámetros.
subfolder (str, opcional, valor predeterminado "") — Si los archivos relevantes se encuentran en una subcarpeta del repositorio del modelo en huggingface.co, puede especificar el nombre de la carpeta aquí.

Devuelve

tuple[Dict, Dict]

El diccionario (o diccionarios) que se utilizará para instanciar el objeto de procesador de video.

A partir de pretrained_model_name_or_path, se resuelve en un diccionario de parámetros, para ser utilizado en la instanciación de un procesador de video de tipo ~video_processing_utils.VideoProcessorBase mediante from_dict.

preprocesar

< 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

Parámetros

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]]]) — Vídeo a preprocesar. Espera un único vídeo o un lote de vídeos con valores de píxeles que van de 0 a 255. Si se pasan vídeos con valores de píxeles entre 0 y 1, establece do_rescale=False.
do_convert_rgb (bool, kwargs, opcional) — Si se debe convertir la imagen a RGB.
do_resize (bool, kwargs, opcional) — Si se debe redimensionar la imagen.
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Describe las dimensiones de entrada máximas del modelo.
default_to_square (bool, kwargs, opcional) — Si se debe usar una imagen cuadrada por defecto al redimensionar, si size es un int.
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — Filtro de remuestreo a utilizar si se redimensiona la imagen. Puede ser uno de los enum PILImageResampling. Solo tiene efecto si do_resize está establecido en True.
do_rescale (bool, kwargs, opcional) — Si se debe reescalar la imagen.
rescale_factor (float, kwargs, opcional) — Factor de reescalado para reescalar la imagen si do_rescale está establecido en True.
do_normalize (bool, kwargs, opcional) — Si se debe normalizar la imagen.
image_mean (Union[float, list[float], tuple[float, ...]], kwargs, opcional) — Media de la imagen a utilizar para la normalización. Solo tiene efecto si do_normalize está establecido en True.
image_std (Union[float, list[float], tuple[float, ...]], kwargs, opcional) — Desviación estándar de la imagen a utilizar para la normalización. Solo tiene efecto si do_normalize está establecido en True.
do_center_crop (bool, kwargs, opcional) — Si se debe recortar la imagen centrada.
do_pad (bool, kwargs, opcional) — Indica si se debe aplicar relleno a la imagen. El relleno se realiza hasta el tamaño más grande del lote o hasta un tamaño cuadrado fijo por imagen. La estrategia exacta de relleno depende del modelo.
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — Tamaño de la imagen de salida tras aplicar center_crop.
data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opcional) — Solo se admite ChannelDimension.FIRST. Se añadió para garantizar la compatibilidad con los procesadores lentos.
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, opcional) — El formato de la dimensión de canales para la imagen de entrada. Si no se establece, el formato de la dimensión de canales se infiere a partir de la imagen de entrada. Puede ser uno de:
- "channels_first" o ChannelDimension.FIRST: imagen en formato (num_channels, height, width).
- "channels_last" o ChannelDimension.LAST: imagen en formato (altura, ancho, num_canales).
- "none" o ChannelDimension.NONE: imagen en formato (altura, ancho).
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — El dispositivo en el que se procesarán los videos. Si no se establece, el dispositivo se infiere a partir de los videos de entrada.
do_sample_frames (bool, kwargs, opcional) — Si se deben muestrear fotogramas del video antes de procesarlo o si se debe procesar el video completo.
video_metadata (Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — Metadatos del video que contienen información sobre la duración total, los fps y el número total de fotogramas. Se utilizarán para muestrear fotogramas del video o calcular marcas de tiempo. No pase ningún metadato a menos que intente decodificar el video manualmente antes de procesarlo
fps (Annotated[int | float | None, None], kwargs) — Fotogramas objetivo a muestrear por segundo cuando do_sample_frames=True.
num_frames (Annotated[int | None, None], kwargs) — Número máximo de fotogramas a muestrear cuando do_sample_frames=True.
return_metadata (bool, kwargs, opcional) — Si se devuelve o no la metadatos del vídeo. Los metadatos del vídeo son un objeto que contiene información sobre la duración del vídeo, los fps, el backend de decodificación, etc.
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — Devuelve tensores apilados si se establece en 'pt'; en caso contrario, devuelve una lista de tensores.

Devuelve

~image_processing_base.BatchFeature

data (dict) — Diccionario de listas/arrays/tensores devueltos por el método call (‘pixel_values’, etc.).
tensor_type (Union[None, str, TensorType], opcional) — Puede especificar un tensor_type aquí para convertir las listas de enteros en Tensors de PyTorch/Numpy durante la inicialización.

register_for_auto_class

< source >

( auto_class = 'AutoVideoProcessor' )

Parámetros

auto_class (str o type, opcional, por defecto "AutoVideoProcessor ") — La clase automática con la que registrar este nuevo procesador de video.

Registra esta clase con una clase auto dada. Esto solo debe usarse para procesadores de video personalizados, ya que los de la biblioteca ya están mapeados con AutoVideoProcessor.

Esta API es experimental y puede presentar algunos cambios incompatibles leves en las próximas versiones.

save_pretrained

< source >

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

Parámetros

save_directory (str o os.PathLike) — Directorio donde se guardará el archivo JSON del procesador de video (se creará si no existe).
push_to_hub (bool, opcional, valor predeterminado False) — Indica si se debe subir el modelo al hub de modelos de Hugging Face después de guardarlo. Puedes especificar el repositorio al que deseas subirlo con repo_id (por defecto, usará el nombre de save_directory en tu espacio de nombres).
kwargs (dict[str, Any], opcional) — Argumentos de palabra clave adicionales que se pasan al método push_to_hub().

Guarde un objeto de procesador de video en el directorio save_directory para que pueda recargarse mediante el método de clase ~video_processing_utils.VideoProcessorBase.from_pretrained.

to_dict

< source >

( ) → dict[str, Any]

Devuelve

dict[str, Any]

Diccionario de todos los atributos que componen esta instancia de procesador de video.

Serializa esta instancia en un diccionario de Python.

BaseVideoProcessor

clase transformers.BaseVideoProcessor

< source >

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

convert_to_rgb

< source >

( video: torch.Tensor ) → torch.Tensor

Parámetros

video ("torch.Tensor") — El video a convertir.

Devuelve

torch.Tensor

El video convertido.

Convierte un video al formato RGB.

sample_frames

< source >

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

Parámetros

metadata (VideoMetadata) — Metadatos del video que contienen información sobre la duración total, los fps y el número total de fotogramas.
num_frames (int, opcional) — Número máximo de fotogramas a muestrear. El valor predeterminado es self.num_frames.
fps (int o float, opcional) — Marcos objetivo a muestrear por segundo. El valor predeterminado es self.fps.

Devuelve

np.ndarray

Índices para muestrear fotogramas de video.

Función de muestreo predeterminada que muestrea uniformemente el número deseado de fotogramas entre 0 y el número total de fotogramas. Si se pasa fps junto con los metadatos, se muestrean uniformemente fps fotogramas por segundo. Los argumentos num_frames y fps son mutuamente excluyentes.

Update on GitHub

Transformers

Procesador de video

Ejemplo de uso

Backends del procesador de video

Backends personalizados

Guardar y recargar

Comportamiento de muestreo

VideoProcessorMixin

clase transformers.VideoProcessorMixin

fetch_videos

from_dict

from_json_file

from_pretrained

get_video_processor_dict

preprocesar

register_for_auto_class

save_pretrained

to_dict

BaseVideoProcessor

clase transformers.BaseVideoProcessor

convert_to_rgb

sample_frames