视频处理器

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

视频处理器扩展了图像处理器的功能，使模型能够处理视频，并针对视频提供与图像不同的一组参数。它充当原始视频数据与模型之间的桥梁，确保输入特征针对 VLM 进行了优化。

使用 from_pretrained() 从 Hugging Face Hub 或本地目录加载视频处理器的配置（图像大小、是否进行归一化和缩放等）。每个预训练模型的配置应保存在 [video_preprocessor_config.json] 文件中，但较旧的模型可能将配置保存在 preprocessor_config.json 文件中。请注意，后者不太推荐，并将在未来被移除。

当视频处理器是多模态处理器的一部分时，其配置会嵌套在 processor_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 上执行。若使用加速器作为设备，还可以编译处理器以进一步提升速度。

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

帧采样

视频处理器负责解码视频，并选取模型实际看到的帧。设置 do_sample_frames=True 以启用采样，然后通过以下两种方式之一选取帧。

num_frames 要求以均匀分布的方式从视频中提取固定数量的帧。
fps 要求以每秒帧数为单位指定速率。

传入路径或 URL，处理器会使用默认解码器 torchcodec 为您解码视频。如果 torchcodec 不可用且您使用的是较旧版本的 torchvision，则解码会回退到 torchvision。

添加 return_metadata=True 以获取采样帧索引、原始尺寸、时长和 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)

采样默认值因模型而异，对 num_frames 或 fps 的请求只是起点，而非保证。Qwen3-VL 以 fps=2 进行采样，并将结果限制在 min_frames=4 和 max_frames=768 之间，因此一秒钟的片段仍会生成 4 帧，而长视频的帧数上限远低于其实际帧数。

具有 temporal_patch_size 的模型会添加第二个约束：沿时间轴将帧分组为包含该数量帧的补丁，并重复最后一帧，直到帧数能够被整除。

如果您传入的是已解码的视频数组，但仍希望使用模型特定的采样方式，请同时提供 video_metadata。否则，采样器将无法获知原始时长或 fps，按 fps 采样时会发出警告，并假定视频是以 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

Transformers

视频处理器

使用示例

帧采样