# 视频处理器

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

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

使用 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/video_processor#transformers.VideoProcessorMixin.from_pretrained) 从 Hugging Face [Hub](https://hf.co) 或本地目录加载视频处理器的配置（图像大小、是否进行归一化和缩放等）。每个预训练模型的配置应保存在 [video_preprocessor_config.json] 文件中，但较旧的模型可能将配置保存在 [preprocessor_config.json](https://huggingface.co/llava-hf/llava-onevision-qwen2-0.5b-ov-hf/blob/main/preprocessor_config.json) 文件中。请注意，后者不太推荐，并将在未来被移除。

当视频处理器是多模态处理器的一部分时，其配置会嵌套在 `processor_config.json` 中。有关详细信息，请参阅 [保存和加载处理器](./processors#save-and-load-a-processor)。

## 使用示例

以下是使用 [`llava-hf/llava-onevision-qwen2-0.5b-ov-hf`](https://huggingface.co/llava-hf/llava-onevision-qwen2-0.5b-ov-hf) 模型加载视频处理器的示例：

```python
from transformers import AutoVideoProcessor

processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf")
```

目前，如果针对视频使用基础图像处理器，它会通过逐帧处理视频数据来工作，即将每一帧视为独立的图像并逐帧应用变换。虽然这种方式可以正常运行，但效率并不高。使用 `AutoVideoProcessor` 可以让我们利用 **快速视频处理器**，借助 [torchvision](https://pytorch.org/vision/stable/index.html) 库。快速处理器会一次性处理整个视频批次，而无需遍历每个视频或每一帧。这些更新引入了 GPU 加速，并显著提升了处理速度，尤其适用于需要高吞吐量的任务。

所有模型均可使用快速视频处理器，并在初始化 `AutoVideoProcessor` 时默认加载。使用快速视频处理器时，还可以设置 `device` 参数以指定执行处理的设备。默认情况下，如果输入是张量，则处理在与输入相同的设备上执行；否则在 CPU 上执行。若使用加速器作为设备，还可以编译处理器以进一步提升速度。

```python
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](https://meta-pytorch.org/torchcodec/stable/index.html) 为您解码视频。如果 torchcodec 不可用且您使用的是较旧版本的 torchvision，则解码会回退到 torchvision。

添加 `return_metadata=True` 以获取采样帧索引、原始尺寸、时长和 fps。

```python
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 录制的。

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

