PySlowFast 从零上手指南：训练、恢复与测试视频理解模型-开发者社区

人工智能
计算机视觉
深度学习
预训练

【免费下载链接】SlowFast

PySlowFast: video understanding codebase from FAIR for reproducing state-of-the-art video models.

项目地址：https://gitcode.com/gh_mirrors/sl/SlowFast

PySlowFast 是 FAIR 开源的视频理解代码库，围绕统一的tools/run_net.py入口与 YAML 配置体系，把“训练、恢复训练、测试”三类任务收敛到同一条命令链路上。本文以 GETTING_STARTED.md 为主线，结合仓库源码与真实配置文件，完整讲解 PySlowFast 的标准训练流程、断点恢复（PyTorch/Caffe2 两种 checkpoint 类型）、纯测试模式以及多视角测试原理，读完即可用一条命令启动属于你的第一个视频分类任务。

启动任务前的前置条件

在运行任何训练或测试任务之前，需要先完成两件事：

安装 PySlowFast 及其依赖（PyTorch、fvcore、torchvision 等），安装步骤详见 INSTALL.md。
按照要求的格式准备数据集。不同的数据集（Kinetics、AVA、Charades、SSv2 等）需要不同的目录结构与标注格式，具体格式要求参见 slowfast/datasets/DATASET.md。

PySlowFast 的入口脚本是 tools/run_net.py。它在main()中按以下顺序解析并执行任务：

若cfg.TRAIN.ENABLE为真，则调用train()执行训练；
若cfg.TEST.ENABLE为真，则调用test()执行多片段测试；
若启用了 TensorBoard 可视化，则执行visualize()；
若cfg.DEMO.ENABLE为真，则执行demo()。

也就是说，训练与测试是否执行，完全由配置中的开关控制，你不需要切换不同的脚本。

配置的加载与覆盖机制：YAML 与命令行参数的优先级

所有任务都以一份 YAML 配置文件为核心。PySlowFast 基于 fvcore 的CfgNode构建了完整的默认配置体系，全部键的默认值定义在 slowfast/config/defaults.py，其中get_cfg()会返回一份默认配置的克隆。

命令行参数的解析与合并逻辑位于 slowfast/utils/parser.py 的load_config()中，其合并顺序决定了最终生效的配置值：

先通过cfg.merge_from_file(path_to_config)加载 YAML 文件中的配置；
再通过cfg.merge_from_list(args.opts)用命令行--opts（即KEY VALUE对）覆盖文件中的值；
最后继承--shard_id、--num_shards等命令行参数到cfg.NUM_SHARDS、cfg.SHARD_ID。

因此，命令行参数拥有最高优先级，可以临时覆盖配置文件中的任意键，而不必修改 YAML。此外，run_net.py会调用 slowfast/config/defaults.py 中的assert_and_infer_cfg()做合法性校验，例如：

TRAIN.BATCH_SIZE必须能被NUM_GPUS整除（assert cfg.NUM_GPUS == 0 or cfg.TRAIN.BATCH_SIZE % cfg.NUM_GPUS == 0）；
TRAIN.CHECKPOINT_TYPE与TEST.CHECKPOINT_TYPE只能是pytorch或caffe2；
若SOLVER.BASE_LR_SCALE_NUM_SHARDS为真，学习率会自动按NUM_SHARDS缩放。

从头训练一个标准模型

GETTING_STARTED 以C2D 8x8 ResNet-50为例，演示了如何在 Kinetics 数据集上从头训练一个标准模型。对应的配置文件是 configs/Kinetics/C2D_8x8_R50.yaml，其中已经完整定义了模型结构（MODEL.ARCH: c2d、MODEL.MODEL_NAME: ResNet、RESNET.DEPTH: 50）、数据采样（DATA.NUM_FRAMES: 8、DATA.SAMPLING_RATE: 8）、优化器（SOLVER.BASE_LR: 0.1、LR_POLICY: cosine、MAX_EPOCH: 196）等。

启动训练的命令如下：

python tools/run_net.py \ --cfg configs/Kinetics/C2D_8x8_R50.yaml \ DATA.PATH_TO_DATA_DIR path_to_your_dataset \ NUM_GPUS 2 \ TRAIN.BATCH_SIZE 16

命令中各个参数的含义与来源：

参数	作用	默认值/说明
`--cfg`	指定 YAML 配置文件路径	在 parser.py 中默认值为`configs/Kinetics/SLOWFAST_4x16_R50.yaml`，可传入多个配置文件
`DATA.PATH_TO_DATA_DIR`	指向数据目录（含 train/val 列表文件）	默认值为空字符串，见 defaults.py
`NUM_GPUS`	训练使用的 GPU 数量	默认 1；大于 1 时`launch_job`会通过`torch.multiprocessing.spawn`启动多进程分布式训练，见 slowfast/utils/misc.py
`TRAIN.BATCH_SIZE`	总 mini-batch 大小	默认 64；必须能被`NUM_GPUS`整除
`DATA_LOADER.NUM_WORKERS`	每个训练进程的数据加载 worker 数	默认 8
`TRAIN.CHECKPOINT_PERIOD`	每多少个 epoch 保存一次 checkpoint	默认 10（C2D 配置中为 1）
`TRAIN.EVAL_PERIOD`	每多少个 epoch 在验证集上评估一次	默认 10
`TRAIN.AUTO_RESUME`	是否自动从输出目录中的最新 checkpoint 恢复	默认 True
`OUTPUT_DIR`	输出目录（checkpoint 保存在其`checkpoints/`子目录下）	默认`.`

关于数据集路径，有两种等价的做法：

方式一（命令行传递，临时生效）：如上例所示，每次启动时追加DATA.PATH_TO_DATA_DIR path_to_your_dataset。

方式二（写入 YAML，永久生效）：直接在配置文件中加入：

DATA: PATH_TO_DATA_DIR: path_to_your_dataset

之后启动命令时便无需每次再传该参数。

训练循环做了什么

从 tools/train_net.py 的train()可以看到完整训练主循环（train_net.py）：

初始化分布式环境并设置随机种子（cfg.RNG_SEED）；
构建模型build_model(cfg)，若cfg.LOG_MODEL_INFO为真，还会通过 slowfast/utils/misc.py 的log_model_info()输出参数量、FLOPs、显存占用与 nvidia-smi 信息；
构造优化器（默认 SGD，见SOLVER.OPTIMIZING_METHOD）与 GradScaler（仅当TRAIN.MIXED_PRECISION启用时生效）；
按需加载 checkpoint（详见下文“恢复训练”）；
构建 train/val 数据加载器与统计仪表（TrainMeter/ValMeter）；
进入 epoch 循环，每个 epoch 内逐 iteration 前向、计算损失、反向更新；若BN.USE_PRECISE_STATS为真，还会在 checkpoint/eval 周期用cfg.BN.NUM_BATCHES_PRECISE个 batch 重算精确 BN 统计；
按is_checkpoint_epoch/is_eval_epoch保存 checkpoint（格式为checkpoint_epoch_{epoch:05d}.pyth，见 slowfast/utils/checkpoint.py）或在验证集上评估。

本地快速调试配置

如果只想在本机快速跑通流程、验证代码是否正确（而非追求训练效果），GETTING_STARTED 推荐把数据加载和显存占用降到最低：

DATA_LOADER.NUM_WORKERS 0 \ NUM_GPUS 2 \ TRAIN.BATCH_SIZE 16 \

即：

DATA_LOADER.NUM_WORKERS 0：关闭多进程数据加载，避免 worker 进程带来的调试干扰，也降低内存占用；
NUM_GPUS 2、TRAIN.BATCH_SIZE 16：在 2 张 GPU 上以较小的 batch 快速迭代，适合在本地机器上做冒烟测试。

从已有 Checkpoint 恢复训练

PySlowFast 支持两种来源的 checkpoint：PyTorch 训练出的权重与Caffe2 格式的权重（例如官方发布的 Caffe2 预训练模型）。恢复方式同样既可以在命令行中追加，也可以写入 YAML。

恢复 PyTorch Checkpoint

TRAIN.CHECKPOINT_FILE_PATH path_to_your_PyTorch_checkpoint

对应的默认值与语义见 defaults.py：

TRAIN.CHECKPOINT_FILE_PATH：默认""，指定要加载的初始权重路径；
TRAIN.CHECKPOINT_TYPE：默认"pytorch"；
TRAIN.CHECKPOINT_INFLATE：默认False，是否执行权重膨胀；
TRAIN.CHECKPOINT_EPOCH_RESET：默认False，加载时是否重置 epoch 计数；
TRAIN.CHECKPOINT_CLEAR_NAME_PATTERN：默认空元组，加载时按给定模式清除层名前缀（用于结构微调场景）。

在 train_net.py 中，只要TRAIN.CHECKPOINT_FILE_PATH非空，就会调用 slowfast/utils/checkpoint.py 的load_checkpoint()：从 CPU 加载权重以避免 GPU 显存尖峰，然后按名称与形状匹配pre_train_dict与当前模型状态字典，strict=False加载，并打印 "Network weights not loaded" 等日志供排查。若 checkpoint 中包含epoch与optimizer_state，还会顺带恢复 epoch 计数与优化器状态，从而无缝续训。

恢复 Caffe2 Checkpoint

如果 checkpoint 是 Caffe2 训练产出的，需要额外指定 checkpoint 类型：

TRAIN.CHECKPOINT_FILE_PATH path_to_your_Caffe2_checkpoint \ TRAIN.CHECKPOINT_TYPE caffe2

此时load_checkpoint()走convert_from_caffe2=True分支（checkpoint.py）：

以pickle（encoding="latin1"）读取 Caffe2 的blobs；
通过 slowfast/utils/c2_model_loading.py 中的get_name_convert_func()将 Caffe2 层名转换为 PyTorch 命名；
自动处理维度差异：例如将线性层参数 reshape 成卷积参数、将 Caffe2 的普通 BN 统计映射到 Sub-BN（c2_normal_to_sub_bn）；
最终以strict=False加载，并打印所有未转换/未匹配的层名。

权重膨胀（Checkpoint Inflation）

若需要用2D 预训练权重初始化 3D 视频模型（例如用 ImageNet 预训练的 ResNet 初始化 C2D/I3D/SlowFast 的 3D 卷积），记得开启膨胀开关：

TRAIN.CHECKPOINT_INFLATE True

膨胀的具体实现是 checkpoint.py 中的inflate_weight()：对于形状为 4D（2D 卷积权重）而目标为 5D（3D 卷积权重）的参数，在时间维度上unsqueeze(2).repeat(1, 1, T, 1, 1) / T，即把 2D 卷积核沿时间轴复制并取平均，得到 3D 卷积核。这正是 I3D 论文中经典的“膨胀初始化”做法。

执行模型测试

PySlowFast 用TRAIN.ENABLE与TEST.ENABLE两个开关共同决定当前任务执行训练还是测试。若只想做纯测试，将TRAIN.ENABLE置为False，并通过TEST.CHECKPOINT_FILE_PATH指定待测模型权重：

python tools/run_net.py \ --cfg configs/Kinetics/C2D_8x8_R50.yaml \ DATA.PATH_TO_DATA_DIR path_to_your_dataset \ TEST.CHECKPOINT_FILE_PATH path_to_your_checkpoint \ TRAIN.ENABLE False

测试相关的关键配置（defaults.py）：

参数	默认值	含义
`TEST.ENABLE`	True	是否执行测试
`TEST.DATASET`	kinetics	测试数据集
`TEST.BATCH_SIZE`	8	测试 mini-batch 大小（同样需能被`NUM_GPUS`整除）
`TEST.CHECKPOINT_FILE_PATH`	`""`	待测 checkpoint 路径
`TEST.CHECKPOINT_TYPE`	pytorch	可选`pytorch`或`caffe2`
`TEST.NUM_ENSEMBLE_VIEWS`	10	沿时间轴均匀采样的 clip 数量，用于多片段集成
`TEST.NUM_SPATIAL_CROPS`	3	每个 clip 的空间裁剪数（左/中/右 3 crops）
`TEST.SAVE_RESULTS_PATH`	`""`	非空时把预测结果与标签 pickle 到`OUTPUT_DIR`下

多视角测试的工作原理

测试逻辑位于 tools/test_net.py 的perform_test()（test_net.py）。其注释明确描述了多视角测试的流程：

沿时间轴均匀采样TEST.NUM_ENSEMBLE_VIEWS（默认 10）个 clip；
对每个 clip 再取TEST.NUM_SPATIAL_CROPS（默认 3）个空间裁剪；
将全部N × 3个视角的 softmax 分数取平均，得到视频级预测；
与 ground-truth 标签比较，统计并输出最终 Top-1/Top-5 精度。

TestMeter会按NUM_ENSEMBLE_VIEWS × NUM_SPATIAL_CROPS组织预测，并断言num_videos % (views × crops) == 0（test_net.py）。另外，run_net.py中有一个特殊逻辑：当TEST.NUM_ENSEMBLE_VIEWS == -1时，会自动依次用[1, 3, 5, 7, 10]五组 clip 数分别测试并对比（见 run_net.py），方便研究者观察集成视图数量对精度的影响。

测试时 checkpoint 的加载优先级由 checkpoint.py 的load_test_checkpoint()决定：优先TEST.CHECKPOINT_FILE_PATH；若为空则尝试从OUTPUT_DIR中读取最新 checkpoint；再退而求其次使用TRAIN.CHECKPOINT_FILE_PATH；若均无，则随机初始化（仅限调试）。

Run 命令速记

GETTING_STARTED 末尾给出了恢复预训练模型进行测试的最简命令形式：

python tools/run_net.py --cfg path/to/<pretrained_model_config_file>.yaml

注意该命令成立的前提是：配置文件中已写好DATA.PATH_TO_DATA_DIR与TEST.CHECKPOINT_FILE_PATH，并且TRAIN.ENABLE已关闭。实际使用时请参照上文把这两个参数补齐（命令行或 YAML 均可）。

结语与进一步探索

至此，你已经掌握了 PySlowFast 的三条核心操作路径：

训练：python tools/run_net.py --cfg <config.yaml> DATA.PATH_TO_DATA_DIR <data> NUM_GPUS <n> TRAIN.BATCH_SIZE <b>；
恢复：用TRAIN.CHECKPOINT_FILE_PATH+（Caffe2 时）TRAIN.CHECKPOINT_TYPE caffe2，必要时加TRAIN.CHECKPOINT_INFLATE True；
测试：TRAIN.ENABLE False+TEST.CHECKPOINT_FILE_PATH <ckpt>。

所有配置项都可以通过命令行--opts临时覆盖，也可以在 YAML 中固化；全部默认值可在 slowfast/config/defaults.py 中查阅。仓库还提供了覆盖多种任务的现成配置（configs 目录下包含 Kinetics、AVA、Charades、SSv2、ImageNet 以及对比学习/掩码自监督等子目录）、官方预训练基线（MODEL_ZOO.md）以及可视化与 Demo 工具（VISUALIZATION_TOOLS.md），可作为后续深入实践的直接入口。