Transformers Video — HuggingFace 视频处理器与多模态输入管线

是什么

Transformers Video 不是独立仓库，而是 HuggingFace transformers 库里围绕视频多模态模型的一组 Processor / VideoProcessor API：负责把本地路径、URL 或帧列表变成模型 forward 所需的 pixel_values、video_grid_thw 等张量。典型入口是 Qwen2VLVideoProcessor、LlavaOnevisionVideoProcessor 及 AutoVideoProcessor.from_pretrained(...)。

日常类比：如果 decord 是「从硬盘抓帧的搬运工」，Transformers Video Processor 就是厨房配菜台——按菜谱（preprocessor_config.json）决定采多少帧、缩放到多大、要不要 pad，最后端给 qwen2-vl-2024 等模型。

最小推理片段：

from transformers import Qwen2VLForConditionalGeneration, AutoProcessor

model = Qwen2VLForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2-VL-7B-Instruct", torch_dtype="auto", device_map="auto"
)
processor = AutoProcessor.from_pretrained("Qwen/Qwen2-VL-7B-Instruct")
inputs = processor(text="描述这段视频", videos="clip.mp4", return_tensors="pt")

为什么重要

不理解这层 Processor，HF 生态里的 Video-LLM 推理会卡在「张量形状不对」：

模型权重与预处理绑定：preprocessor_config.json 里的 min_pixels / max_pixels / fps 与 checkpoint 一起发布，手写 torchvision 变换会对不齐
统一 decord / pyav / torchvision 后端：video_backend 参数切换解码实现，不必每个项目 fork 一套采帧逻辑
与 accelerate / vllm Serving 衔接：训练侧 processor(...) 与部署侧 OpenAI API 共用同一套视觉 token 契约
评测框架默认依赖：lmms-eval 许多任务内部调用 HF Processor，版本漂移直接导致跑分不可比

核心要点

VideoProcessor 继承自 BaseImageProcessor 家族：图像与视频共用 resize、normalize 逻辑；视频额外处理时间维——均匀采样或按 fps 截断。
decord 与 pyav 双后端：Qwen2VLVideoProcessor 默认倾向 decord（随机 seek 快）；无 decord 时回退 pyav（FFmpeg 绑定，与 ffmpeg 能力一致）。显式指定：video_backend="decord"。
动态分辨率与 token 预算：Qwen2-VL 系按 min_pixels/max_pixels 缩放每帧，总视觉 token 随视频时长变化——不是固定 224×224×8 帧。
批处理与对话模板：apply_chat_template 把 <video> 占位符展开为视觉 token 序列；多段视频 + 文本交织时需传 messages 结构而非裸字符串。

实践案例

案例 1：指定 decord 后端处理本地 mp4

from transformers import AutoProcessor
import torch

processor = AutoProcessor.from_pretrained("Qwen/Qwen2-VL-7B-Instruct")
inputs = processor(
    text="<|video_pad|> 视频里发生了什么？",
    videos=["/data/clip.mp4"],
    return_tensors="pt",
    video_backend="decord",
)
print(inputs["pixel_values"].shape, inputs.get("video_grid_thw"))

若报 decord 缺失，pip install decord；长视频可先 ffmpeg 裁切再喂，避免 Processor 内部截断策略与预期不符。

案例 2：多帧列表而非容器文件

from PIL import Image
from transformers import AutoProcessor

frames = [Image.open(f"frames/{i:04d}.jpg") for i in range(0, 32, 4)]
processor = AutoProcessor.from_pretrained("Qwen/Qwen2-VL-2B-Instruct")
inputs = processor(
    text="按时间顺序总结",
    videos=[frames],  # 嵌套列表表示一个视频的多帧
    return_tensors="pt",
)

适合已从 decord / OpenCV 抽好帧的流水线；帧顺序由列表下标保证。

案例 3：与 lmms-eval 对齐的模型参数

pip install "transformers>=4.45" decord accelerate

python -m lmms_eval \
  --model qwen2_vl \
  --model_args pretrained=Qwen/Qwen2-VL-7B-Instruct,device_map=auto \
  --tasks mvbench \
  --batch_size 1 \
  --output_path ./qwen2vl_mvbench.json

lmms-eval 内部实例化 HF Processor；升级 transformers 后若分数突变，先 diff preprocessor_config.json 而非怀疑模型权重。

踩过的坑

transformers 版本与模型不匹配：Qwen2-VL 需较新 transformers；用旧版会缺 Qwen2VLVideoProcessor 类或参数名变更。
decord 未装却默认走 decord：静默回退 pyav 时性能骤降；训练前 python -c "import decord" 自检。
BGR/RGB 已由 Processor 处理：勿在 Processor 前用 OpenCV 读帧再重复转换，通道会乱。
video_grid_thw 与 RoPE 绑定：Qwen2-VL 的 M-RoPE 依赖 grid 元数据；手写 pixel tensor 不带 video_grid_thw 会 forward 报错。
超长视频默认截断：Processor 按 fps 和 max_frames 裁剪；评测长片需显式调参或预切片，否则与论文设置不一致。

适用 vs 不适用场景

适用：

HuggingFace 生态内跑 qwen2-vl-2024 等 Video-LLM
需要与官方 preprocessor_config.json 严格对齐的复现
快速原型：几行 processor(...) 完成视频 QA
和 accelerate 做多卡 device_map 推理

不适用：

自定义采帧策略且不愿 fork Processor（直接用 decord + 自写 Dataset）
生产高并发 serving（用 vllm 多模态 API）
非 HF 权重格式（videollama2 等独立仓库自有预处理）
极致训练 I/O 优化（C++ VideoLoader 级定制）

历史小故事（可跳过）

2023：LLaVA 系先在 transformers 中以「多图」形式接入，视频被视为帧列表
2024：Qwen2-VL 推动专用 *VideoProcessor 与动态分辨率进主线
2024 末：video_backend 参数标准化，decord/pyav 可配置
2025：更多 OneVision / 交织模型共用 AutoProcessor，视频与图像 API 收敛

学到什么

Processor 是 checkpoint 的一部分：改预处理等于改模型输入分布
视频在 HF 里通常是「帧列表 + 时间元数据」
decord 是训练友好默认，pyav 是兜底
动态分辨率模型不能用固定 reshape 思维
lmms-eval 分数问题先查 transformers 版本与 Processor 配置

关联

qwen2-vl-2024 —— 主要消费方模型
decord —— 推荐视频解码后端
ffmpeg —— pyav 底层；预处理裁切
accelerate —— device_map 推理
pytorch —— 张量与训练框架
lmms-eval —— 统一评测入口
videollama2 —— 非 HF Processor 路线的对照
video-llava-2024 —— 另一套预处理范式
llava-next —— OneVision Processor 扩展
vllm —— 部署侧多模态 serving
gradio —— 常包装 HF Processor 做 demo
tempcompass-2024 —— 时序探针评测依赖一致预处理

反向链接

decord —— Decord — Video-LLM 数据管线的高效视频解码库
ffmpeg —— FFmpeg — 多媒体转码与封装瑞士军刀
llava-next —— LLaVA-NeXT — 图像/视频/交织统一多模态主线仓库
lmms-eval —— LMMs-Eval — 多模态大模型统一评测框架
pytorch —— PyTorch — 深度学习主流框架
qwen2-vl-2024 —— Qwen2-VL — 动态分辨率 + M-RoPE，工业级视频理解的里程碑
tempcompass-2024 —— TempCompass — 专门拆穿 Video LLM 有没有真懂时间
video-llava-2024 —— Video-LLaVA — 投影之前先对齐，图像和视频共用一个 LLM
videollama2 —— VideoLLaMA2 — 阿里达摩院音视频 Video-LLM 可运行实现
vllm —— vLLM — 高吞吐 LLM 推理引擎