Transformers documentation

Video Processor

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Video Processor

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.

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

Use from_pretrained() para cargar la configuración de un procesador de video (tamaño de imagen, si normalizar y reescalar, etc.) desde un modelo de video en el Hub de Hugging Face o desde un directorio local. La configuración de cada modelo preentrenado debe guardarse en un archivo [video_preprocessor_config.json], pero los modelos más antiguos podrían tener la configuración guardada en un archivo preprocessor_config.json. Tenga en cuenta que este último es menos recomendable y se eliminará en el futuro.

Cuando un procesador de vídeo forma parte de un procesador multimodal, su configuración se anida en processor_config.json. Consulte Guardar y cargar un procesador para obtener más detalles.

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

Actualmente, si se utiliza el procesador de imágenes base para videos, los datos de video se procesan tratando cada fotograma como una imagen individual y aplicando transformaciones fotograma a fotograma. Aunque es funcional, este enfoque no es muy eficiente. El uso de AutoVideoProcessor permite aprovechar los procesadores de video rápidos, haciendo uso de la biblioteca torchvision. Los procesadores rápidos manejan el lote completo de videos de una sola vez, sin iterar sobre cada video o fotograma. Estas actualizaciones introducen aceleración por GPU y mejoran significativamente la velocidad de procesamiento, especialmente para tareas que requieren un alto rendimiento.

Los procesadores de video rápidos están disponibles para todos los modelos y se cargan de forma predeterminada al inicializar un AutoVideoProcessor. Al usar un procesador de video rápido, también se puede establecer el argumento device para especificar el dispositivo en el que se debe realizar el procesamiento. De forma predeterminada, el procesamiento se realiza en el mismo dispositivo que las entradas si estas son tensores, o en la CPU en caso contrario. Para una mejora aún mayor de la velocidad, se puede compilar el procesador cuando se utiliza un acelerador como dispositivo.

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

Muestreo de fotogramas

Un procesador de vídeo decodifica el vídeo y selecciona los fotogramas que el modelo realmente ve. Establece do_sample_frames=True para activar el muestreo y, a continuación, selecciona los fotogramas de una de las dos formas siguientes.

  • num_frames solicita una cantidad fija distribuida de manera uniforme a lo largo del video.
  • fps solicita una tasa en fotogramas por segundo.

Pasa una ruta o una URL y el procesador decodificará el video por ti con torchcodec, el decodificador predeterminado. Si torchcodec no está disponible y estás usando una versión antigua de torchvision, la decodificación se realiza con torchvision.

Añade return_metadata=True para obtener los índices de los fotogramas muestreados, las dimensiones originales, la duración y los 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)

Los valores predeterminados de muestreo son específicos de cada modelo, y una solicitud de num_frames o fps es un punto de partida, no una garantía. Qwen3-VL muestrea a fps=2 y limita el resultado entre min_frames=4 y max_frames=768, por lo que un clip de un segundo sigue generando 4 fotogramas y una grabación larga se limita a un valor muy inferior a su número real de fotogramas.

Los modelos con un temporal_patch_size añaden una segunda restricción: los fotogramas se agrupan en parches de ese número de fotogramas a lo largo del eje temporal, y el último fotograma se repite hasta que la cantidad sea divisible exactamente.

Si pasas un array de video ya decodificado y aun así quieres muestreo específico del modelo, proporciona también video_metadata. Sin él, el muestreador no conoce la duración original ni el fps, y el muestreo por fps emite una advertencia y asume que el video fue grabado a 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"
)
Update on GitHub