Transformers 文档
视频分类
并获得增强的文档体验
开始使用
视频分类
视频分类的任务是对整个视频分配一个标签或类别。每个视频预计只有一个类别。视频分类模型以视频作为输入,并返回关于视频所属类别的预测。这些模型可用于对视频内容进行分类。视频分类的一个实际应用是动作/活动识别,这对于健身应用很有用。它对于视力受损的个体也很有帮助,尤其是在他们通勤时。
本指南将向您展示如何:
要查看与此任务兼容的所有架构和检查点,建议查阅任务页面。
在开始之前,请确保您已安装所有必要的库
pip install -q pytorchvideo transformers evaluate
你将使用 PyTorchVideo(名为 `pytorchvideo`)来处理和准备视频。
我们鼓励您登录到 Hugging Face 帐户,以便您可以将模型上传并与社区共享。当出现提示时,输入您的令牌进行登录。
>>> from huggingface_hub import notebook_login
>>> notebook_login()
加载 UCF101 数据集
首先加载 UCF-101 数据集的一个子集。这将让你有机会进行实验,并确保一切正常,然后再花更多时间在完整数据集上进行训练。
>>> from huggingface_hub import hf_hub_download
>>> hf_dataset_identifier = "sayakpaul/ucf101-subset"
>>> filename = "UCF101_subset.tar.gz"
>>> file_path = hf_hub_download(repo_id=hf_dataset_identifier, filename=filename, repo_type="dataset")
子集下载完成后,你需要解压缩归档文件
>>> import tarfile
>>> with tarfile.open(file_path) as t:
... t.extractall(".")
总的来说,数据集的组织结构如下:
UCF101_subset/
train/
BandMarching/
video_1.mp4
video_2.mp4
...
Archery
video_1.mp4
video_2.mp4
...
...
val/
BandMarching/
video_1.mp4
video_2.mp4
...
Archery
video_1.mp4
video_2.mp4
...
...
test/
BandMarching/
video_1.mp4
video_2.mp4
...
Archery
video_1.mp4
video_2.mp4
...
...
然后你可以统计视频的总数。
>>> import pathlib
>>> dataset_root_path = "UCF101_subset"
>>> dataset_root_path = pathlib.Path(dataset_root_path)
>>> video_count_train = len(list(dataset_root_path.glob("train/*/*.avi")))
>>> video_count_val = len(list(dataset_root_path.glob("val/*/*.avi")))
>>> video_count_test = len(list(dataset_root_path.glob("test/*/*.avi")))
>>> video_total = video_count_train + video_count_val + video_count_test
>>> print(f"Total videos: {video_total}")
>>> all_video_file_paths = (
... list(dataset_root_path.glob("train/*/*.avi"))
... + list(dataset_root_path.glob("val/*/*.avi"))
... + list(dataset_root_path.glob("test/*/*.avi"))
... )
>>> all_video_file_paths[:5]
(排序后
的)视频路径如下所示:
...
'UCF101_subset/train/ApplyEyeMakeup/v_ApplyEyeMakeup_g07_c04.avi',
'UCF101_subset/train/ApplyEyeMakeup/v_ApplyEyeMakeup_g07_c06.avi',
'UCF101_subset/train/ApplyEyeMakeup/v_ApplyEyeMakeup_g08_c01.avi',
'UCF101_subset/train/ApplyEyeMakeup/v_ApplyEyeMakeup_g09_c02.avi',
'UCF101_subset/train/ApplyEyeMakeup/v_ApplyEyeMakeup_g09_c06.avi'
...
你会注意到,有些视频片段属于同一个组/场景,其中组在视频文件路径中以 g
表示。例如,v_ApplyEyeMakeup_g07_c04.avi
和 v_ApplyEyeMakeup_g07_c06.avi
。
对于验证和评估拆分,您不希望有来自同一组/场景的视频剪辑,以防止数据泄露。本教程中使用的子集已将此信息考虑在内。
接下来,你将推导出数据集中存在的标签集。另外,创建两个字典,它们在模型初始化时会很有用
label2id
:将类名映射到整数。id2label
:将整数映射到类名。
>>> class_labels = sorted({str(path).split("/")[2] for path in all_video_file_paths})
>>> label2id = {label: i for i, label in enumerate(class_labels)}
>>> id2label = {i: label for label, i in label2id.items()}
>>> print(f"Unique classes: {list(label2id.keys())}.")
# Unique classes: ['ApplyEyeMakeup', 'ApplyLipstick', 'Archery', 'BabyCrawling', 'BalanceBeam', 'BandMarching', 'BaseballPitch', 'Basketball', 'BasketballDunk', 'BenchPress'].
有10个独特的类别。每个类别在训练集中有30个视频。
加载模型进行微调
从预训练检查点及其关联的图像处理器实例化一个视频分类模型。模型的编码器带有预训练参数,分类头是随机初始化的。图像处理器在编写数据集的预处理管道时会派上用场。
>>> from transformers import VideoMAEImageProcessor, VideoMAEForVideoClassification
>>> model_ckpt = "MCG-NJU/videomae-base"
>>> image_processor = VideoMAEImageProcessor.from_pretrained(model_ckpt)
>>> model = VideoMAEForVideoClassification.from_pretrained(
... model_ckpt,
... label2id=label2id,
... id2label=id2label,
... ignore_mismatched_sizes=True, # provide this in case you're planning to fine-tune an already fine-tuned checkpoint
... )
模型加载时,您可能会注意到以下警告
Some weights of the model checkpoint at MCG-NJU/videomae-base were not used when initializing VideoMAEForVideoClassification: [..., 'decoder.decoder_layers.1.attention.output.dense.bias', 'decoder.decoder_layers.2.attention.attention.key.weight']
- This IS expected if you are initializing VideoMAEForVideoClassification from the checkpoint of a model trained on another task or with another architecture (e.g. initializing a BertForSequenceClassification model from a BertForPreTraining model).
- This IS NOT expected if you are initializing VideoMAEForVideoClassification from the checkpoint of a model that you expect to be exactly identical (initializing a BertForSequenceClassification model from a BertForSequenceClassification model).
Some weights of VideoMAEForVideoClassification were not initialized from the model checkpoint at MCG-NJU/videomae-base and are newly initialized: ['classifier.bias', 'classifier.weight']
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.
警告告诉我们,我们正在丢弃一些权重(例如 classifier
层的权重和偏置),并随机初始化一些其他权重(一个新的 classifier
层的权重和偏置)。在这种情况下这是预期行为,因为我们正在添加一个新的头部,我们没有预训练权重,所以库会警告我们应该在使用此模型进行推理之前对其进行微调,这正是我们要做的。
请注意,此检查点在此任务上表现更好,因为该检查点是在具有相当领域重叠的相似下游任务上微调获得的。您可以查看此检查点,它是通过微调MCG-NJU/videomae-base-finetuned-kinetics
获得的。
准备训练数据集
为了对视频进行预处理,你将利用 PyTorchVideo 库。首先导入所需的依赖项。
>>> import pytorchvideo.data
>>> from pytorchvideo.transforms import (
... ApplyTransformToKey,
... Normalize,
... RandomShortSideScale,
... RemoveKey,
... ShortSideScale,
... UniformTemporalSubsample,
... )
>>> from torchvision.transforms import (
... Compose,
... Lambda,
... RandomCrop,
... RandomHorizontalFlip,
... Resize,
... )
对于训练数据集的转换,我们结合使用了均匀时间子采样、像素归一化、随机裁剪和随机水平翻转。对于验证和评估数据集的转换,除了随机裁剪和水平翻转外,我们保持相同的转换链。要了解这些转换的更多细节,请查看 PyTorchVideo 的官方文档。
使用与预训练模型关联的 image_processor
来获取以下信息
- 用于归一化视频帧像素的图像均值和标准差。
- 视频帧将调整到的空间分辨率。
首先定义一些常量。
>>> mean = image_processor.image_mean
>>> std = image_processor.image_std
>>> if "shortest_edge" in image_processor.size:
... height = width = image_processor.size["shortest_edge"]
>>> else:
... height = image_processor.size["height"]
... width = image_processor.size["width"]
>>> resize_to = (height, width)
>>> num_frames_to_sample = model.config.num_frames
>>> sample_rate = 4
>>> fps = 30
>>> clip_duration = num_frames_to_sample * sample_rate / fps
现在,分别定义数据集特有的转换和数据集。从训练集开始:
>>> train_transform = Compose(
... [
... ApplyTransformToKey(
... key="video",
... transform=Compose(
... [
... UniformTemporalSubsample(num_frames_to_sample),
... Lambda(lambda x: x / 255.0),
... Normalize(mean, std),
... RandomShortSideScale(min_size=256, max_size=320),
... RandomCrop(resize_to),
... RandomHorizontalFlip(p=0.5),
... ]
... ),
... ),
... ]
... )
>>> train_dataset = pytorchvideo.data.Ucf101(
... data_path=os.path.join(dataset_root_path, "train"),
... clip_sampler=pytorchvideo.data.make_clip_sampler("random", clip_duration),
... decode_audio=False,
... transform=train_transform,
... )
同样的工作流程可以应用于验证集和评估集。
>>> val_transform = Compose(
... [
... ApplyTransformToKey(
... key="video",
... transform=Compose(
... [
... UniformTemporalSubsample(num_frames_to_sample),
... Lambda(lambda x: x / 255.0),
... Normalize(mean, std),
... Resize(resize_to),
... ]
... ),
... ),
... ]
... )
>>> val_dataset = pytorchvideo.data.Ucf101(
... data_path=os.path.join(dataset_root_path, "val"),
... clip_sampler=pytorchvideo.data.make_clip_sampler("uniform", clip_duration),
... decode_audio=False,
... transform=val_transform,
... )
>>> test_dataset = pytorchvideo.data.Ucf101(
... data_path=os.path.join(dataset_root_path, "test"),
... clip_sampler=pytorchvideo.data.make_clip_sampler("uniform", clip_duration),
... decode_audio=False,
... transform=val_transform,
... )
**注意**:上述数据集管道取自PyTorchVideo官方示例。我们使用pytorchvideo.data.Ucf101()
函数,因为它专为UCF-101数据集定制。在底层,它返回一个pytorchvideo.data.labeled_video_dataset.LabeledVideoDataset
对象。LabeledVideoDataset
类是PyTorchVideo数据集中所有视频的基类。因此,如果你想使用PyTorchVideo不直接支持的自定义数据集,你可以相应地扩展LabeledVideoDataset
类。有关详细信息,请参阅data
API文档。另外,如果你的数据集遵循类似的结构(如上所示),那么使用pytorchvideo.data.Ucf101()
应该也能正常工作。
你可以访问 num_videos
参数来了解数据集中视频的数量。
>>> print(train_dataset.num_videos, val_dataset.num_videos, test_dataset.num_videos)
# (300, 30, 75)
可视化预处理视频以更好地调试
>>> import imageio
>>> import numpy as np
>>> from IPython.display import Image
>>> def unnormalize_img(img):
... """Un-normalizes the image pixels."""
... img = (img * std) + mean
... img = (img * 255).astype("uint8")
... return img.clip(0, 255)
>>> def create_gif(video_tensor, filename="sample.gif"):
... """Prepares a GIF from a video tensor.
...
... The video tensor is expected to have the following shape:
... (num_frames, num_channels, height, width).
... """
... frames = []
... for video_frame in video_tensor:
... frame_unnormalized = unnormalize_img(video_frame.permute(1, 2, 0).numpy())
... frames.append(frame_unnormalized)
... kargs = {"duration": 0.25}
... imageio.mimsave(filename, frames, "GIF", **kargs)
... return filename
>>> def display_gif(video_tensor, gif_name="sample.gif"):
... """Prepares and displays a GIF from a video tensor."""
... video_tensor = video_tensor.permute(1, 0, 2, 3)
... gif_filename = create_gif(video_tensor, gif_name)
... return Image(filename=gif_filename)
>>> sample_video = next(iter(train_dataset))
>>> video_tensor = sample_video["video"]
>>> display_gif(video_tensor)

训练模型
利用 🤗 Transformers 中的 Trainer
来训练模型。要实例化一个 Trainer
,你需要定义训练配置和评估指标。最重要的是 TrainingArguments
,它是一个包含所有配置训练属性的类。它需要一个输出文件夹名称,用于保存模型的检查点。它还有助于同步 🤗 Hub 上模型仓库中的所有信息。
大多数训练参数都是自解释的,但其中一个非常重要的是 `remove_unused_columns=False`。此参数将删除模型调用函数未使用的任何特征。默认情况下它为 `True`,因为通常删除未使用的特征列是理想的,这样可以更轻松地将输入解包到模型的调用函数中。但是,在这种情况下,你需要未使用的特征(特别是“视频”)才能创建 `pixel_values`(这是模型输入中预期的强制性键)。
>>> from transformers import TrainingArguments, Trainer
>>> model_name = model_ckpt.split("/")[-1]
>>> new_model_name = f"{model_name}-finetuned-ucf101-subset"
>>> num_epochs = 4
>>> args = TrainingArguments(
... new_model_name,
... remove_unused_columns=False,
... eval_strategy="epoch",
... save_strategy="epoch",
... learning_rate=5e-5,
... per_device_train_batch_size=batch_size,
... per_device_eval_batch_size=batch_size,
... warmup_ratio=0.1,
... logging_steps=10,
... load_best_model_at_end=True,
... metric_for_best_model="accuracy",
... push_to_hub=True,
... max_steps=(train_dataset.num_videos // batch_size) * num_epochs,
... )
由 pytorchvideo.data.Ucf101()
返回的数据集没有实现 __len__
方法。因此,在实例化 TrainingArguments
时,我们必须定义 max_steps
。
接下来,你需要定义一个函数,用于从预测中计算指标,该函数将使用你现在加载的 metric
。你唯一需要做的预处理就是获取预测 logits 的 argmax。
import evaluate
metric = evaluate.load("accuracy")
def compute_metrics(eval_pred):
predictions = np.argmax(eval_pred.predictions, axis=1)
return metric.compute(predictions=predictions, references=eval_pred.label_ids)
关于评估的说明:
在 VideoMAE 论文中,作者使用以下评估策略。他们评估模型在测试视频的几个片段上的表现,并对这些片段应用不同的裁剪,然后报告汇总分数。然而,为了简单和简洁,本教程中不考虑这一点。
此外,定义一个 collate_fn
,它将用于将示例批量处理在一起。每个批量包含 2 个键,即 pixel_values
和 labels
。
>>> def collate_fn(examples):
... # permute to (num_frames, num_channels, height, width)
... pixel_values = torch.stack(
... [example["video"].permute(1, 0, 2, 3) for example in examples]
... )
... labels = torch.tensor([example["label"] for example in examples])
... return {"pixel_values": pixel_values, "labels": labels}
然后,你只需将所有这些连同数据集一起传递给 Trainer
>>> trainer = Trainer(
... model,
... args,
... train_dataset=train_dataset,
... eval_dataset=val_dataset,
... processing_class=image_processor,
... compute_metrics=compute_metrics,
... data_collator=collate_fn,
... )
您可能想知道为什么在已经预处理数据之后,您仍然将 image_processor
作为分词器传递。这仅仅是为了确保图像处理器配置文件(存储为 JSON)也将上传到 Hub 上的仓库中。
现在通过调用 train
方法来微调我们的模型
>>> train_results = trainer.train()
训练完成后,使用 push_to_hub() 方法将您的模型分享到 Hub,以便所有人都可以使用您的模型。
>>> trainer.push_to_hub()
推理
太棒了,现在你已经微调了一个模型,你可以用它进行推理了!
加载视频进行推理
>>> sample_test_video = next(iter(test_dataset))

尝试你的微调模型进行推理最简单的方法是使用 pipeline
。实例化一个视频分类 pipeline
,将你的模型传入其中,并将你的视频传递给它。
>>> from transformers import pipeline
>>> video_cls = pipeline(model="my_awesome_video_cls_model")
>>> video_cls("https://huggingface.co/datasets/sayakpaul/ucf101-subset/resolve/main/v_BasketballDunk_g14_c06.avi")
[{'score': 0.9272987842559814, 'label': 'BasketballDunk'},
{'score': 0.017777055501937866, 'label': 'BabyCrawling'},
{'score': 0.01663011871278286, 'label': 'BalanceBeam'},
{'score': 0.009560945443809032, 'label': 'BandMarching'},
{'score': 0.0068979403004050255, 'label': 'BaseballPitch'}]
你也可以手动复制 pipeline
的结果,如果你愿意的话。
>>> def run_inference(model, video):
... # (num_frames, num_channels, height, width)
... perumuted_sample_test_video = video.permute(1, 0, 2, 3)
... inputs = {
... "pixel_values": perumuted_sample_test_video.unsqueeze(0),
... "labels": torch.tensor(
... [sample_test_video["label"]]
... ), # this can be skipped if you don't have labels available.
... }
... device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
... inputs = {k: v.to(device) for k, v in inputs.items()}
... model = model.to(device)
... # forward pass
... with torch.no_grad():
... outputs = model(**inputs)
... logits = outputs.logits
... return logits
现在,将输入传递给模型并返回 logits
>>> logits = run_inference(trained_model, sample_test_video["video"])
解码 logits
,我们得到:
>>> predicted_class_idx = logits.argmax(-1).item()
>>> print("Predicted class:", model.config.id2label[predicted_class_idx])
# Predicted class: BasketballDunk