企业官网建设流程全解析

• 人工智能
• 计算机视觉
• 深度学习

导读

本文以 MMAction2 官方 FAQ 文档（docs/zh_cn/get_started/faq.md）为主线，系统梳理视频理解工具箱使用中最常遇到的四类问题：环境安装报错、数据预处理异常、训练配置细节、测试阶段的显存与归一化技巧。每一类问题均给出可直接复制的解决方案，并结合当前仓库源码（如mmaction/datasets/rawframe_dataset.py、mmaction/models/backbones/resnet3d.py、mmaction/models/heads/base.py等）说明问题产生的底层原理，帮助你既能"照方抓药"，也能"知其所以然"。

说明：FAQ 是社区持续维护的排障清单，本文尽量保留原文档中所有问题与回答，并补充实现层面的佐证。若你的问题未被覆盖，可参照仓库.github/ISSUE_TEMPLATE中的报错模板创建 Issue，并填写完整环境信息。

一、安装阶段：三大高频报错的定位与修复

1. "No module named 'mmcv.ops'" / "No module named 'mmcv._ext'"

这是 OpenMMLab 系项目最常见的安装问题，根因是mmcv 安装版本不正确（例如只装了纯 Python 版 mmcv，或 mmcv 与 PyTorch/CUDA 编译环境不匹配），导致 C++/CUDA 扩展算子（mmcv.ops、mmcv._ext）缺失。

修复步骤：

1. 先卸载环境中现有 mmcv：

   pip uninstall mmcv

2. 再参照 mmcv 官方安装说明，按你的 PyTorch 与 CUDA 版本安装对应的mmcv（注意选择带编译扩展的 wheel 或源码编译版）。

3. 之后按 docs/en/get_started/installation.md 中的安装流程依次安装 mmengine、mmaction2 及其余依赖。

2. "OSError: MoviePy Error: creation of None failed because of the following error"

此报错出现在依赖 MoviePy 的视频处理场景（例如 demo 中的可视化合成），解决方案是先安装依赖：

pip install moviepy

安装后仍需注意两个平台差异（来源于 MoviePy 官方 issue 记录）：

• Windows 用户：ImageMagick 不会被 MoviePy 自动检测到。需要手动编辑moviepy/config_defaults.py，为IMAGEMAGICK_BINARY提供magick二进制文件的绝对路径，例如：

  IMAGEMAGICK_BINARY = "C:\\Program Files\\ImageMagick_VERSION\\magick.exe"

• Linux 用户：若 MoviePy 未检测到 ImageMagick，需编辑/etc/ImageMagick-6/policy.xml，将限制文本处理的策略注释掉：

  <!-- <policy domain="path" rights="none" pattern="@*" /> -->

3. 已安装 XXCODEBASE，为何仍报 "Please install XXCODEBASE to use XXX"？

收到该错误说明 MMAction2 在运行时无法从 XXCODEBASE 中 import 某个函数或类。常见原因是依赖顺序错误：OpenMMLab 系列代码库（mmdet、mmseg、mmpose 等）通常要求先安装 mmcv 与 mmengine，再安装对应代码库。建议按照安装教程的依赖顺序重装一遍；也可以直接运行报错信息对应的 import 行，观察具体的失败原因（是找不到模块、版本不匹配，还是编译扩展缺失）。

二、数据阶段：文件路径、预处理策略与流水线配对

1. FileNotFound 错误：No such file or directory: xxx/xxx/img_00300.jpg

该问题的本质是start_index与帧文件命名偏移不一致。在 MMAction2 中：

• rawframe（原始帧）数据集默认start_index=1：源码 mmaction/datasets/rawframe_dataset.py 的文档明确说明"raw frames count from 1"，因此filename_tmpl='img_{:05}.jpg'会从img_00001.jpg开始取帧；
• 视频数据集默认start_index=0：源码 mmaction/datasets/video_dataset.py 说明"frames loaded from videos count from 0"。

如果第一帧或最后一帧报 FileNotFound，请检查数据实际从xxx_00000.jpg还是xxx_00001.jpg开始，然后在配置文件的dataset或数据处理流水线中显式调整start_index的值，使偏移与文件名匹配。

2. 视频预处理：固定尺寸 vs 统一短边？

FAQ 给出的建议是：相比将所有视频缩放到固定尺寸（如340x256），统一将短边缩放到相同长度（如 256px 或 320px）通常是更好的方案，因此仓库默认采用短边 256px 的预处理设置。两种方案的基准测试结果可分别在 configs/recognition/tsn 与 configs/recognition/slowonly 的配置目录中查阅。

3. 流水线项不匹配导致KeyError: 'total_frames'

这个报错是"用错了解码器"的典型症状。MMAction2 的数据流水线分两条路线：

• 视频输入：需要在流水线中动态解码视频，必须使用配对的Init + Decode组合，例如：

  • DecordInit+DecordDecode
  • OpenCVInit+OpenCVDecode
  • PyAVInit+PyAVDecode

  典型示例见 configs/recognition/tsn/tsn_imagenet-pretrained-r50_8xb32-1x1x3-100e_kinetics400-rgb.py 中train_pipeline的DecordInit/DecordDecode配对写法。

• 帧输入：图像已离线解码，应使用RawFrameDecode，示例见 configs/recognition/trn/trn_imagenet-pretrained-r50_8xb16-1x1x8-50e_sthv1-rgb.py。

为什么会对不上？从源码看，DecordInit负责初始化视频容器并写入total_frames等键（见 mmaction/datasets/transforms/loading.py），随后DecordDecode根据帧索引批量取帧（同文件 L1170-L1248）。而RawFrameDecode直接从frame_dir+filename_tmpl按路径读图（见 loading.py L1361-L1462），它本身并不计算total_frames。因此，如果把RawFrameDecode用在视频输入上，就无法预先获得total_frames，触发KeyError。反过来，若在帧数据上误用了视频解码器，也会因缺少video_reader而报错。

三、训练阶段：主干预训练、冻结阶段、memcached 与数据集切换

1. 如何只利用训练好的识别模型的主干进行预训练？

• 若要加载整个预训练模型（全网络微调），在新配置文件的load_from字段中填入预训练权重路径或 URL 即可。
• 若要仅加载主干权重，则将配置中主干（backbone）部分的pretrained值改为权重路径/URL。训练时，与模型结构不匹配的键会被自动忽略。

2. 微调时如何冻结主干的某些阶段？

参考 mmaction/models/backbones/resnet3d.py 中_freeze_stages()的实现：当frozen_stages >= 0时，它会将conv1及layer1 ~ layer{frozen_stages}置为eval()模式并设置requires_grad = False。该函数会在train()切换模式时被自动调用（见 resnet3d.py L889-L896）。

使用要点：

• 在主干配置中设置frozen_stages参数（例如frozen_stages=1冻结 conv1 与 layer1）；
• 务必在配置中设置find_unused_parameters = True，否则分布式训练/测试时，因部分参数不参与计算图而报错；
• 除 C3D 等少数模型外，几乎所有继承自ResNet/ResNet3D的主干都支持内部函数_freeze_stages()，因此可放心使用。

3. 如何在配置中启用 memcached？

在 MMAction2 中，memcached 参数通过FileClient传递：

• 视频数据集：传给DecordInit；
• 原始帧数据集：传给RawFrameDecode。

FileClient来自 mmengine 的mmaction数据加载实现（源码可见 loading.py L1407-L1408，最终由mmengine.fileio.FileClient统一管理io_backend与扩展参数）。原始帧数据集启用 memcached 的示例：

mc_cfg = dict(server_list_cfg='server_list_cfg', client_cfg='client_cfg', sys_path='sys_path') train_pipeline = [ ... dict(type='RawFrameDecode', io_backend='memcached', **mc_cfg), ... ]

其中server_list_cfg、client_cfg、sys_path需按你部署的 memcached 集群实际填写。

4. 如何设置load_from以微调模型？

configs/base/default_runtime.py 中将load_from = None设为默认值。得益于 MMAction2 配置的继承机制（详见 docs/zh_cn/user_guides/config.md），你只需在自己的配置文件中直接覆写load_from = 'path/to/checkpoint.pth'即可，无需改动基础配置。

5. 训练时如何使用RawFrameDataset？

MMAction2 1.x 的大多数配置默认使用VideoDataset（对文件存储更友好）。若数据以原始帧形式存放，需要修改两处：

（1）dataset 相关：将train_dataloader/val_dataloader/test_dataloader中的dataset由

dataset=dict( type=VideoDataset, data_prefix=dict(video=xxx), ...)

改为

dataset=dict( type=RawFrameDataset, data_prefix=dict(img=xxx), filename_tmpl='{:05}.jpg', ...)

注意：filename_tmpl必须与实际帧命名匹配（默认模板为img_{:05}.jpg，见 rawframe_dataset.py L89）；此外RawFrameDataset默认start_index=1（rawframe_dataset.py L93），若帧从 0 开始计数请同步调整。

（2）transform 相关：在train_pipeline/val_pipeline/test_pipeline中：

• 删除dict(type='DecordInit', **file_client_args)；
• 将dict(type='DecordDecode')改为dict(type='RawFrameDecode', **file_client_args)；
• 确保配置文件中定义了file_client_args = dict(io_backend='disk')。

典型可参考仓库内使用RawFrameDecode的配置文件，如 configs/recognition/trn/trn_imagenet-pretrained-r50_8xb16-1x1x8-50e_sthv1-rgb.py。更多自定义数据集细节见 docs/zh_cn/user_guides/prepare_dataset.md 与 docs/zh_cn/advanced_guides/customize_dataset.md。

四、测试阶段：得分归一化与大模型显存优化

1. 如何让预测得分在 softmax 后归一化到 [0, 1]？

在配置文件中将model.cls_head.average_clips设置为'prob'。

从源码看，该字段支持'score'、'prob'与None三种取值（mmaction/models/heads/base.py L210-L226）：

• 'prob'：先对每个 clip 的得分做softmax，再对多个 clip 取平均（结果天然落在 [0, 1]）；
• 'score'：直接对多个 clip 的原始得分取平均；
• None：不做平均，直接返回各 clip 得分。

仓库多处配置默认即使用'prob'，例如 mmaction/configs/base/models/slowonly_r50.py。

2. 模型过大、GPU 显存装不下一个测试样本怎么办？

默认情况下，3D 模型测试采用10 clips × 3 crops = 30 个视图。对超大模型而言，即使 batch 只有 1 个样本，30 个视图同时前向也会撑爆显存。

解决办法：在配置文件的model['test_cfg']中设置max_testing_views = n，使前向过程每次只处理 n 个视图。从 mmaction/models/recognizers/recognizer3d.py 的实现可以看到，识别器在测试模式下会把总视图数按max_testing_views切块分批送入 backbone/neck，最后将各批特征拼接（torch.cat），得到的结果与整批前向完全一致，从而在不改变推理结果的前提下大幅降低峰值显存。

使用前提（源码中的断言）：

• max_testing_views必须是整数；
• 仅与batch_size == 1兼容（num_segs == total_views）；
• 在 recognizer2d 中，max_testing_views还必须是num_segments的倍数（见 mmaction/models/recognizers/recognizer2d.py）。

五、FAQ 之外的延伸：安装与运行环境速查

FAQ 中多次涉及环境依赖问题，这里补充仓库内可核对的安装依据：

• 完整安装步骤见 docs/zh_cn/get_started/installation.md，其中明确了 mmcv、mmengine 与 MMAction2 的安装顺序与版本匹配要求；
• 依赖声明集中在 requirements.txt 与 requirements/mminstall.txt，可据此核对decord、moviepy、opencv-python等第三方库是否齐全；
• 若需在分布式或多卡环境下训练，参考 tools/dist_train.sh 与 tools/dist_test.sh 的用法。

结语

本文沿 FAQ 的四大板块（安装、数据、训练、测试）逐条给出了可落地的解决方案，并借源码确认了start_index默认值、_freeze_stages()冻结逻辑、FileClient的 memcached 通道、average_clips的三种聚合方式以及max_testing_views的分块推理原理。遇到类似报错时，建议先对照对应小节定位问题环节，再结合报错信息与配置逐项排查。若问题仍无法解决，请携带完整环境信息按 Issue 模板反馈，社区 FAQ 也会持续补充高频问题。

• 人工智能
• 计算机视觉
• 深度学习