VideoMAE 的官方 PyTorch 实现（NeurIPS 2022 Spotlight）。

VideoMAE：掩码自编码器是自监督视频预训练中数据高效的学习者
Zhan Tong (https://github.com/yztongzhan), Yibing Song (https://ybsong00.github.io/), Jue Wang (https://juewang725.github.io/), Limin Wang (http://wanglimin.github.io/)
南京大学，腾讯 AI 实验室

📰 新闻

[2023.4.18] 🎈大家可以从这个链接下载 VideoMAE 中使用的 Kinetics-400 数据集。
[2023.4.18] VideoMAE V2 的代码和预训练模型已经发布！请查看并体验这个仓库！
[2023.4.17] 我们提出了一个端到端的视频动作检测框架 EVAD。
[2023.2.28] 我们的 VideoMAE V2 被 CVPR 2023 接收！🎉
[2023.1.16] VideoMAE 中用于动作检测的代码和预训练模型已经可用！
[2022.12.27] 🎈大家可以从 InternVideo 下载提取出的 THUMOS、ActivityNet、HACS 和 FineAction 的 VideoMAE 特征。
[2022.11.20] 👀 VideoMAE 已集成到 和 ，由 @Sayak Paul 提供支持。
[2022.10.25] 👀 VideoMAE 已集成到 MMAction2，在 Kinetics-400 上的结果可以成功复现。
[2022.10.20] ViT-S 和 ViT-H 的预训练模型和脚本已经可用！
[2022.10.19] UCF101 上的预训练模型和脚本已经可用！
[2022.9.15] VideoMAE 被 NeurIPS 2022 接受为 spotlight 报告！🎉
[2022.8.8] 👀 VideoMAE 现已集成到 官方 🤗HuggingFace Transformers 中！
[2022.7.7] 我们更新了下游 AVA 2.2 基准上的新结果。详情请参阅我们的论文。
[2022.4.24] 代码和预训练模型现已可用！
[2022.3.24] 代码和预训练模型将在此发布。 欢迎关注此仓库以获取最新动态。

✨ 亮点

🔥 视频预训练中的掩码视频建模

VideoMAE 执行视频预训练中的掩码视频建模任务。我们提出了极高的掩码比例（90%-95%）和体素掩码策略，为自监督视频预训练创造了一个极具挑战性的任务。

⚡️ 一种简单、高效且强大的自监督视频预训练基线

VideoMAE 使用简单的掩码自编码器和纯 ViT 主干网络来进行视频自监督学习。由于掩码比例极高，VideoMAE 的预训练时间比对比学习方法短得多（速度提升 3.2 倍）。VideoMAE 可以作为未来自监督视频预训练研究中简单但强大的基线。

😮 高性能，无需额外数据

VideoMAE 在不同规模的视频数据集上表现良好，在 Kinetics-400 上达到 87.4%，在 Something-Something V2 上达到 75.4%，在 UCF101 上达到 91.3%，在 HMDB51 上达到 62.6%。据我们所知，VideoMAE 是首个使用原生 ViT 主干网络，在不需任何额外数据或预训练模型的情况下，在这四个热门基准上取得最先进性能的方法。

🚀 主要结果

✨ Something-Something V2

方法	需要额外数据	主干网络	分辨率	帧数 × 片段 × 裁剪	Top-1	Top-5
VideoMAE	否	ViT-S	224x224	16x2x3	66.8	90.3
VideoMAE	否	ViT-B	224x224	16x2x3	70.8	92.4
VideoMAE	否	ViT-L	224x224	16x2x3	74.3	94.6
VideoMAE	否	ViT-L	224x224	32x1x3	75.4	95.2

✨ Kinetics-400

方法	额外数据	主干网络	分辨率	帧数×片段数×裁剪次数	Top-1	Top-5
VideoMAE	无	ViT-S	224x224	16x5x3	79.0	93.8
VideoMAE	无	ViT-B	224x224	16x5x3	81.5	95.1
VideoMAE	无	ViT-L	224x224	16x5x3	85.2	96.8
VideoMAE	无	ViT-H	224x224	16x5x3	86.6	97.1
VideoMAE	无	ViT-L	320x320	32x4x3	86.1	97.3
VideoMAE	无	ViT-H	320x320	32x4x3	87.4	97.6

✨ AVA 2.2

请查看 VideoMAE-Action-Detection 中的代码和检查点。

方法	额外数据	额外标签	主干网络	帧数×采样率	mAP
VideoMAE	Kinetics-400	✗	ViT-S	16x4	22.5
VideoMAE	Kinetics-400	✓	ViT-S	16x4	28.4
VideoMAE	Kinetics-400	✗	ViT-B	16x4	26.7
VideoMAE	Kinetics-400	✓	ViT-B	16x4	31.8
VideoMAE	Kinetics-400	✗	ViT-L	16x4	34.3
VideoMAE	Kinetics-400	✓	ViT-L	16x4	37.0
VideoMAE	Kinetics-400	✗	ViT-H	16x4	36.5
VideoMAE	Kinetics-400	✓	ViT-H	16x4	39.5
VideoMAE	Kinetics-700	✗	ViT-L	16x4	36.1
VideoMAE	Kinetics-700	✓	ViT-L	16x4	39.3

✨ UCF101 & HMDB51

方法	额外数据	主干网络	UCF101	HMDB51
VideoMAE	无	ViT-B	91.3	62.6
VideoMAE	Kinetics-400	ViT-B	96.1	73.3

🔨 安装

请按照 INSTALL.md 中的说明进行操作。

➡️ 数据准备

请按照 DATASET.md 中的说明进行数据准备。

🔄 预训练

预训练说明见 PRETRAIN.md。

⤴️ 使用预训练模型进行微调

微调说明见 FINETUNE.md。

📍 模型库

我们在 MODEL_ZOO.md 中提供了预训练和微调后的模型。

👀 可视化

我们提供了用于可视化的脚本 vis.sh。用于更好可视化的 Colab 笔记本即将推出。

☎️ 联系方式

Zhan Tong：tongzhan@smail.nju.edu.cn

👍 致谢

感谢 Ziteng Gao、Lei Chen、Chongjian Ge 和 Zhiyu Zhao 的鼎力支持。
本项目基于 MAE-pytorch 和 BEiT 构建。感谢这些优秀代码库的贡献者们。

🔒 许可证

本项目的大部分内容采用 CC-BY-NC 4.0 许可证，详见 LICENSE 文件。项目中的部分内容则采用单独的许可条款：SlowFast 和 pytorch-image-models 采用 Apache 2.0 许可证。BEiT 则采用 MIT 许可证。

✏️ 引用

如果您认为本项目有所帮助，请随时点赞⭐️ 并引用我们的论文：

@inproceedings{tong2022videomae,
  title={Video{MAE}: Masked Autoencoders are Data-Efficient Learners for Self-Supervised Video Pre-Training},
  author={Zhan Tong and Yibing Song and Jue Wang and Limin Wang},
  booktitle={Advances in Neural Information Processing Systems},
  year={2022}
}

@article{videomae,
  title={VideoMAE: Masked Autoencoders are Data-Efficient Learners for Self-Supervised Video Pre-Training},
  author={Tong, Zhan and Song, Yibing and Wang, Jue and Wang, Limin},
  journal={arXiv preprint arXiv:2203.12602},
  year={2022}
}

VideoMAE 快速上手指南

VideoMAE 是一种基于掩码自编码器（Masked Autoencoders）的视频自监督预训练框架，在 NeurIPS 2022 上获得 Spotlight 展示。它通过极高的掩码比例（90%-95%）和管状掩码策略，实现了高效且强大的视频表征学习，无需额外数据即可在多个基准数据集上达到 SOTA 性能。

环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu 18.04+)
• Python: 3.7+
• GPU: 支持 CUDA 的 NVIDIA GPU (建议显存 >= 16GB 用于训练)
• CUDA: 10.2 或更高版本

前置依赖

确保已安装以下基础库：

• PyTorch >= 1.8.1
• torchvision
• timm
• einops
• decord (用于视频读取)

国内加速建议：推荐使用清华源或阿里源安装 Python 依赖，以加快下载速度。

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package_name>

安装步骤

1. 克隆仓库

   git clone https://github.com/MCG-NJU/VideoMAE.git
   cd VideoMAE
   

2. 创建虚拟环境并安装依赖

   conda create -n videomae python=3.8 -y
   conda activate videomae
   
   # 安装 PyTorch (根据实际 CUDA 版本选择，此处以 CUDA 11.3 为例)
   pip install torch==1.10.1+cu113 torchvision==0.11.2+cu113 -f https://download.pytorch.org/whl/cu113/torch_stable.html
   
   # 安装其他依赖 (使用国内镜像加速)
   pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   

3. 编译自定义算子 (可选) 如果需要加速数据处理，可编译 decord 等库：

   pip install decord -i https://pypi.tuna.tsinghua.edu.cn/simple
   

基本使用

以下是使用预训练模型进行视频分类的最简单示例（基于 Hugging Face Transformers 集成版，无需从头训练）：

方式一：使用 Hugging Face Transformers (推荐快速测试)

from transformers import VideoMAEFeatureExtractor, VideoMAEForVideoClassification
from PIL import Image
import torch
import av

# 加载特征提取器和模型
feature_extractor = VideoMAEFeatureExtractor.from_pretrained("MCG-NJU/videomae-base-finetuned-kinetics")
model = VideoMAEForVideoClassification.from_pretrained("MCG-NJU/videomae-base-finetuned-kinetics")

# 读取视频 (使用 av 库)
def read_video_pyav(container, indices):
    frames = []
    container.seek(0)
    start_index = indices[0]
    end_index = indices[-1]
    for i, frame in enumerate(container.decode(video=0)):
        if i > end_index:
            break
        if i >= start_index and i in indices:
            frames.append(frame)
    return [frame.to_rgb().to_ndarray() for frame in frames]

# 示例：加载视频并预处理
container = av.open("test_video.mp4")
indices = range(0, 16) # 采样 16 帧
frames = read_video_pyav(container, indices)
inputs = feature_extractor(frames, return_tensors="pt")

# 推理
with torch.no_grad():
    outputs = model(**inputs)
    logits = outputs.logits

# 获取预测结果
predicted_class_idx = logits.argmax(-1).item()
print("Predicted class:", model.config.id2label[predicted_class_idx])

方式二：运行官方微调脚本 (需自备数据集)

假设已按照 DATASET.md 准备好 Kinetics-400 数据集，使用预训练权重进行微调的命令如下：

python run_class_finetuning.py \
    --model vit_base_patch16_224 \
    --finetune ./pretrain_videomae_base_1600e_kinetics400_rgb.pth \
    --data_path ./data/kinetics400/train_list.json \
    --eval_data_path ./data/kinetics400/val_list.json \
    --num_classes 400 \
    --batch_size 8 \
    --num_workers 8 \
    --opt adamw \
    --lr 5e-4 \
    --update_freq 2 \
    --epochs 30 \
    --dist_eval \
    --save_ckpt_freq 5 \
    --output_dir ./output_dir

注意：完整的数据准备、预训练及详细参数配置请参考项目根目录下的 DATASET.md, PRETRAIN.md 和 FINETUNE.md 文档。预训练模型可在 MODEL_ZOO.md 中下载。