视频处理器

视频处理器是一种实用工具，负责为视频模型准备输入特征，以及处理其输出的后处理。它提供诸如调整大小、归一化和转换为 PyTorch 等转换。

视频处理器扩展了图像处理器的功能，允许视觉大型语言模型（VLM）使用与图像不同的参数集来处理视频。它充当原始视频数据和模型之间的桥梁，确保输入特征针对 VLM 进行了优化。

在添加新的 VLM 或更新现有 VLM 以启用不同的视频预处理时，保存和重新加载处理器配置会将视频相关参数存储在一个名为 video_preprocessing_config.json 的专用文件中。如果你还没有更新你的 VLM，也不用担心，处理器会尝试从一个名为 preprocessing_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 参数来指定处理应在哪个设备上进行。默认情况下，如果输入是张量，处理将在与输入相同的设备上进行，否则在 CPU 上进行。为了进一步提高速度，当使用“cuda”作为设备时，我们可以编译处理器。

import torch
from transformers.video_utils import load_video
from transformers import AutoVideoProcessor

video = load_video("video.mp4")
processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf", device="cuda")
processor = torch.compile(processor)
processed_video = processor(video, return_tensors="pt")

BaseVideoProcessor

class transformers.BaseVideoProcessor

< 来源 >

( **kwargs: typing_extensions.Unpack[transformers.processing_utils.VideosKwargs] )

参数

do_resize (bool, 可选, 默认为 self.do_resize) — 是否将视频的（高，宽）维度调整到指定的 size。可在 preprocess 方法中通过 do_resize 参数覆盖。
size (dict, 可选, 默认为 self.size) — 调整大小后输出视频的尺寸。可在 preprocess 方法中通过 size 参数覆盖。
size_divisor (int, 可选, 默认为 self.size_divisor) — 用于确保高度和宽度都可以被其整除的大小。
default_to_square (bool, 可选, 默认为 self.default_to_square) — 在调整大小时，如果 size 是一个整数，是否默认调整为正方形视频。
resample (PILImageResampling, 可选, 默认为 self.resample) — 如果调整视频大小，使用的重采样过滤器。仅在 do_resize 设置为 True 时有效。可在 preprocess 方法中通过 resample 参数覆盖。
do_center_crop (bool, 可选, 默认为 self.do_center_crop) — 是否将视频中心裁剪到指定的 crop_size。可在 preprocess 方法中通过 do_center_crop 参数覆盖。
do_pad (bool, 可选) — 是否将视频填充到批处理中视频的 (max_height, max_width)。
crop_size (dict[str, int] 可选, 默认为 self.crop_size) — 应用 center_crop 后输出视频的尺寸。可在 preprocess 方法中通过 crop_size 参数覆盖。
do_rescale (bool, 可选, 默认为 self.do_rescale) — 是否通过指定的缩放因子 rescale_factor 对视频进行缩放。可在 preprocess 方法中通过 do_rescale 参数覆盖。
rescale_factor (int 或 float, 可选, 默认为 self.rescale_factor) — 如果对视频进行缩放，使用的缩放因子。仅在 do_rescale 设置为 True 时有效。可在 preprocess 方法中通过 rescale_factor 参数覆盖。
do_normalize (bool, 可选, 默认为 self.do_normalize) — 是否对视频进行归一化。可在 preprocess 方法中通过 do_normalize 参数覆盖。可在 preprocess 方法中通过 do_normalize 参数覆盖。
image_mean (float 或 list[float], 可选, 默认为 self.image_mean) — 如果对视频进行归一化，使用的均值。这是一个浮点数或长度等于视频通道数的浮点数列表。可在 preprocess 方法中通过 image_mean 参数覆盖。可在 preprocess 方法中通过 image_mean 参数覆盖。
image_std (float 或 list[float], 可选, 默认为 self.image_std) — 如果对视频进行归一化，使用的标准差。这是一个浮点数或长度等于视频通道数的浮点数列表。可在 preprocess 方法中通过 image_std 参数覆盖。可在 preprocess 方法中通过 image_std 参数覆盖。
do_convert_rgb (bool, 可选, 默认为 self.image_std) — 是否将视频转换为 RGB。
video_metadata (VideoMetadata, 可选) — 包含视频总时长、fps 和总帧数等信息的视频元数据。
do_sample_frames (int, 可选, 默认为 self.do_sample_frames) — 是在处理前从视频中采样帧还是处理整个视频。
num_frames (int, 可选, 默认为 self.num_frames) — 当 do_sample_frames=True 时，采样的最大帧数。
fps (int, 可选, 默认为 self.fps) — 当 do_sample_frames=True 时，每秒采样的目标帧数。
return_tensors (str 或 TensorType, 可选) — 如果设置为 `pt`，返回堆叠的张量，否则返回张量列表。
data_format (ChannelDimension 或 str, 可选, 默认为 ChannelDimension.FIRST) — 输出视频的通道维度格式。可以是以下之一：
- "channels_first" 或 ChannelDimension.FIRST: 视频格式为 (num_channels, height, width)。
- "channels_last" 或 ChannelDimension.LAST: 视频格式为 (height, width, num_channels)。
- 未设置：使用输入视频的通道维度格式。
input_data_format (ChannelDimension 或 str, 可选) — 输入视频的通道维度格式。如果未设置，则从输入视频推断通道维度格式。可以是以下之一：
- "channels_first" 或 ChannelDimension.FIRST: 视频格式为 (num_channels, height, width)。
- "channels_last" 或 ChannelDimension.LAST: 视频格式为 (height, width, num_channels)。
- "none" 或 ChannelDimension.NONE: 视频格式为 (height, width)。
device (torch.device, 可选) — 处理视频的设备。如果未设置，则从输入视频推断设备。

构建一个基础视频处理器。

转换为 RGB

< 来源 >

( video: torch.Tensor ) → torch.Tensor

参数

video ("torch.Tensor") — 要转换的视频。

torch.Tensor

转换后的视频。

将视频转换为 RGB 格式。

fetch_videos

< 来源 >

( video_url_or_urls: typing.Union[str, list[str]] )

将单个或多个 URL 转换为相应的 np.array 对象。

如果传入单个 URL，返回值将是单个对象。如果传入列表，则返回一个对象列表。

from_dict

< 来源 >

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

参数

video_processor_dict (dict[str, Any]) — 将用于实例化视频处理器对象的字典。这样的字典可以从预训练的检查点中通过 ~video_processing_utils.VideoProcessorBase.to_dict 方法获取。
kwargs (dict[str, Any]) — 用于初始化视频处理器对象的附加参数。

~video_processing_utils.VideoProcessorBase

从这些参数实例化的视频处理器对象。

从一个 Python 字典参数中实例化一个 ~video_processing_utils.VideoProcessorBase 类型的对象。

from_json_file

< 来源 >

( json_file: typing.Union[str, os.PathLike] ) → 一个 ~video_processing_utils.VideoProcessorBase 类型的视频处理器

参数

json_file (str 或 os.PathLike) — 包含参数的 JSON 文件的路径。

一个 `~video_processing_utils.VideoProcessorBase` 类型的视频处理器

从该 JSON 文件实例化的 video_processor 对象。

从一个包含参数的 JSON 文件的路径实例化一个 `~video_processing_utils.VideoProcessorBase` 类型的视频处理器。

from_pretrained

< 来源 >

( pretrained_model_name_or_path: typing.Union[str, os.PathLike] cache_dir: typing.Union[str, os.PathLike, NoneType] = None force_download: bool = False local_files_only: bool = False token: typing.Union[bool, str, NoneType] = None revision: str = 'main' **kwargs )

参数

pretrained_model_name_or_path (str 或 os.PathLike) — 这可以是以下之一：
- 一个字符串，即托管在 huggingface.co 上的模型仓库中的预训练视频的 *模型 ID*。
- 一个包含使用 ~video_processing_utils.VideoProcessorBase.save_pretrained 方法保存的视频处理器文件的 *目录* 路径，例如 ./my_model_directory/。
- 一个保存的视频处理器 JSON *文件* 的路径或 URL，例如 ./my_model_directory/preprocessor_config.json。
cache_dir (str 或 os.PathLike, 可选) — 如果不应使用标准缓存，则为下载的预训练模型视频处理器应缓存到的目录路径。
force_download (bool, 可选, 默认为 False) — 是否强制（重新）下载视频处理器文件并覆盖已存在的缓存版本。
resume_download — 已弃用并忽略。所有下载现在在可能的情况下默认恢复。将在 Transformers v5 中移除。
proxies (dict[str, str], 可选) — 一个按协议或端点使用的代理服务器字典，例如 {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}。代理在每次请求时使用。
token (str 或 bool, 可选) — 用作远程文件 HTTP 持有者授权的令牌。如果为 True 或未指定，将使用运行 huggingface-cli login 时生成的令牌（存储在 ~/.huggingface 中）。
revision (str, 可选, 默认为 "main") — 要使用的特定模型版本。它可以是分支名、标签名或提交 ID，因为我们在 huggingface.co 上使用基于 git 的系统来存储模型和其他工件，所以 revision 可以是 git 允许的任何标识符。

从一个视频处理器实例化一个 `~video_processing_utils.VideoProcessorBase` 类型的对象。

示例

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

< 来源 >

( pretrained_model_name_or_path: typing.Union[str, os.PathLike] **kwargs ) → tuple[Dict, Dict]

参数

pretrained_model_name_or_path (str 或 os.PathLike) — 我们想要获取参数字典的预训练检查点的标识符。
subfolder (str, 可选, 默认为 "") — 如果相关文件位于 huggingface.co 上模型仓库的子文件夹内，你可以在此处指定文件夹名称。

tuple[Dict, Dict]

将用于实例化视频处理器对象的字典。

从一个 pretrained_model_name_or_path 解析出一个参数字典，用于使用 from_dict 实例化一个 ~video_processing_utils.VideoProcessorBase 类型的视频处理器。

preprocess

< 源代码 >

( videos: typing.Union[list['PIL.Image.Image'], ForwardRef('np.ndarray'), ForwardRef('torch.Tensor'), list['np.ndarray'], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list['np.ndarrray']], list[list['torch.Tensor']]] **kwargs: typing_extensions.Unpack[transformers.processing_utils.VideosKwargs] )

参数

do_resize (bool, 可选, 默认为 self.do_resize) — 是否将视频的（高、宽）维度调整为指定的 size。可在 preprocess 方法中通过 do_resize 参数覆盖此设置。
size (dict, 可选, 默认为 self.size) — 调整大小后输出视频的尺寸。可在 preprocess 方法中通过 size 参数覆盖此设置。
size_divisor (int, 可选, 默认为 self.size_divisor) — 确保高度和宽度都能被该值整除。
default_to_square (bool, 可选, 默认为 self.default_to_square) — 当 size 为整数时，在调整大小时是否默认为方形视频。
resample (PILImageResampling, 可选, 默认为 self.resample) — 调整视频大小时使用的重采样滤波器。仅当 do_resize 设置为 True 时有效。可在 preprocess 方法中通过 resample 参数覆盖此设置。
do_center_crop (bool, 可选, 默认为 self.do_center_crop) — 是否将视频中心裁剪为指定的 crop_size。可在 preprocess 方法中通过 do_center_crop 参数覆盖此设置。
do_pad (bool, 可选) — 是否将视频填充到批处理中视频的 (max_height, max_width)。
crop_size (dict[str, int] 可选, 默认为 self.crop_size) — 应用 center_crop 后输出视频的尺寸。可在 preprocess 方法中通过 crop_size 参数覆盖此设置。
do_rescale (bool, 可选, 默认为 self.do_rescale) — 是否通过指定的缩放因子 rescale_factor 对视频进行缩放。可在 preprocess 方法中通过 do_rescale 参数覆盖此设置。
rescale_factor (int 或 float, 可选, 默认为 self.rescale_factor) — 缩放视频时使用的比例因子。仅当 do_rescale 设置为 True 时有效。可在 preprocess 方法中通过 rescale_factor 参数覆盖此设置。
do_normalize (bool, 可选, 默认为 self.do_normalize) — 是否对视频进行归一化。可在 preprocess 方法中通过 do_normalize 参数覆盖此设置。
image_mean (float 或 list[float], 可选, 默认为 self.image_mean) — 归一化视频时使用的均值。这是一个浮点数或长度等于视频通道数的浮点数列表。可在 preprocess 方法中通过 image_mean 参数覆盖此设置。
image_std (float 或 list[float], 可选, 默认为 self.image_std) — 归一化视频时使用的标准差。这是一个浮点数或长度等于视频通道数的浮点数列表。可在 preprocess 方法中通过 image_std 参数覆盖此设置。
do_convert_rgb (bool, 可选, 默认为 self.image_std) — 是否将视频转换为 RGB 格式。
video_metadata (VideoMetadata, 可选) — 视频的元数据，包含总时长、帧率和总帧数等信息。
do_sample_frames (int, 可选, 默认为 self.do_sample_frames) — 是在处理前从视频中采样帧，还是处理整个视频。
num_frames (int, 可选, 默认为 self.num_frames) — 当 do_sample_frames=True 时，要采样的最大帧数。
fps (int, 可选, 默认为 self.fps) — 当 do_sample_frames=True 时，每秒采样的目标帧数。
return_tensors (str 或 TensorType, 可选) — 如果设置为 `pt`，则返回堆叠的张量，否则返回张量列表。
data_format (ChannelDimension 或 str, 可选, 默认为 ChannelDimension.FIRST) — 输出视频的通道维度格式。可以是以下之一：
- "channels_first" 或 ChannelDimension.FIRST：视频格式为 (num_channels, height, width)。
- "channels_last" 或 ChannelDimension.LAST：视频格式为 (height, width, num_channels)。
- 未设置：使用输入视频的通道维度格式。
input_data_format (ChannelDimension 或 str, 可选) — 输入视频的通道维度格式。如果未设置，则从输入视频中推断通道维度格式。可以是以下之一：
- "channels_first" 或 ChannelDimension.FIRST：视频格式为 (num_channels, height, width)。
- "channels_last" 或 ChannelDimension.LAST：视频格式为 (height, width, num_channels)。
- "none" 或 ChannelDimension.NONE：视频格式为 (height, width)。
device (torch.device, 可选) — 用于处理视频的设备。如果未设置，将从输入视频中推断设备。

register_for_auto_class

< 源代码 >

( auto_class = 'AutoVideoProcessor' )

参数

auto_class (str 或 type, 可选, 默认为 "AutoVideoProcessor ") — 用于注册此新视频处理器的自动类。

将此类注册到给定的自动类中。这仅应用于自定义视频处理器，因为库中的处理器已经与 AutoVideoProcessor 映射。

此 API 是实验性的，在未来版本中可能会有轻微的不兼容变更。

sample_frames

< 源代码 >

( video: torch.Tensor metadata: typing.Union[transformers.video_utils.VideoMetadata, dict, NoneType] = None num_frames: typing.Optional[int] = None fps: typing.Optional[int] = None ) → torch.Tensor

参数

video (torch.Tensor) — 需要被采样的视频。
metadata (VideoMetadata, 可选) — 视频的元数据，包含总时长、帧率和总帧数等信息。
num_frames (int, 可选) — 要采样的最大帧数。默认为 self.num_frames。
fps (int, 可选) — 每秒采样的目标帧数。默认为 self.fps。

torch.Tensor

采样后的视频帧。

默认采样函数，它在 0 和总帧数之间均匀采样所需数量的帧。如果 fps 与元数据一起传递，则每秒均匀采样 fps 帧。参数 num_frames 和 fps 是互斥的。

save_pretrained

< 源代码 >

( save_directory: typing.Union[str, os.PathLike] push_to_hub: bool = False **kwargs )

参数

save_directory (str 或 os.PathLike) — 将保存视频处理器 JSON 文件的目录（如果不存在则会创建）。
push_to_hub (bool, 可选, 默认为 False) — 是否在保存模型后将其推送到 Hugging Face 模型中心。您可以使用 repo_id 指定要推送到的仓库（默认为您命名空间中 save_directory 的名称）。
kwargs (dict[str, Any], 可选) — 传递给 push_to_hub() 方法的其他关键字参数。

将视频处理器对象保存到目录 save_directory 中，以便之后可以使用 ~video_processing_utils.VideoProcessorBase.from_pretrained 类方法重新加载。

to_dict

< 源代码 >

( ) → dict[str, Any]

dict[str, Any]

构成此视频处理器实例的所有属性的字典。

将此实例序列化为 Python 字典。

< > 在 GitHub 上更新

Transformers

视频处理器

用法示例

BaseVideoProcessor

class transformers.BaseVideoProcessor

转换为 RGB

fetch_videos

from_dict

from_json_file

from_pretrained

get_video_processor_dict

preprocess

register_for_auto_class

sample_frames

save_pretrained

to_dict