企业官网建设流程全解析

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

本指南聚焦 OpenMMLab 第二代视频理解工具箱 MMAction2（仓库根目录gh_mirrors/mm/mmaction2）中模型训练与测试的完整操作链路，覆盖单 GPU、多 GPU、多机（以太网 / Slurm 集群）三类常见运行环境下的tools/train.py与tools/test.py用法、全部命令行参数、环境变量语义及其底层实现。读完本文，你将能够独立撰写一条可复现的训练 / 测试命令，理解--cfg-options、--resume、--amp、--work-dir等参数在源码中的真实作用，并在多机集群环境中正确配置NNODES、NODE_RANK、PORT、MASTER_ADDR等分布式变量。

训练（Training）

MMAction2 的训练入口统一为 tools/train.py，无论单卡还是分布式训练，最终都会回归到该脚本；分布式的差异只体现在「启动方式」上（由torch.distributed.launch或srun决定）。

使用单个 GPU 进行训练

您可以使用tools/train.py在一台带有 CPU 和 GPU（可选）的单机上训练模型。脚本的完整用法如下：

python tools/train.py ${CONFIG_FILE} [ARGS]

默认情况下，MMAction2 更倾向于使用 GPU 而不是 CPU 进行训练。如果您想在 CPU 上训练模型，请清空 `CUDA_VISIBLE_DEVICES` 或将其设置为 -1 以使 GPU 对程序不可见。 ```bash CUDA_VISIBLE_DEVICES=-1 python tools/train.py ${CONFIG_FILE} [ARGS] ```

参数说明

源码视角：tools/train.py的参数合并逻辑

从 tools/train.py 的merge_args(cfg, args)函数可以看到上述参数在底层是如何落地到配置对象（mmengine.config.Config）中的：

• --no-validate：并非单纯关闭验证，而是直接将cfg.val_cfg、cfg.val_dataloader、cfg.val_evaluator三个字段置为None，即从 Runner 的构建输入中彻底移除验证环节，因此文档标注其为「不建议使用」（正常训练建议保留周期性验证以监控泛化指标）。
• --work-dir的优先级：CLI 参数 > 配置文件中已有的 work_dir > 配置文件文件名。若命令行未指定且配置中也没有work_dir，则默认取./work_dirs/<配置文件名去后缀>，例如configs/recognition/tsn/xxx.py对应./work_dirs/xxx。
• --resume：该参数使用nargs='?'+const='auto'，因此不带路径使用时等价于--resume auto。auto模式将cfg.resume=True且cfg.load_from=None，由 MMEngine Runner 自动从工作目录中的最新 checkpoint 恢复；带路径时则将cfg.load_from指向该 checkpoint。
• --amp：只有当cfg.optim_wrapper.type属于OptimWrapper/AmpOptimWrapper时才生效，会将类型改写为AmpOptimWrapper并默认设置loss_scale='dynamic'；若使用自定义优化器包装类型则会直接assert报错。
• --auto-scale-lr：将配置中的cfg.auto_scale_lr.enable置为True。以 tsn_imagenet-pretrained-r50_8xb32-1x1x3-100e_kinetics400-rgb.py 为例，其内置auto_scale_lr = dict(enable=False, base_batch_size=256)，base_batch_size表示该配置设计时的原始批次大小（8 卡 × 32 样本/卡），开启后系统会根据实际总 batch size 线性缩放学习率。
• --seed/--diff-rank-seed/--deterministic：当配置中尚无randomness字段时，三者会被打包进cfg.randomness交给 Runner 统一管理。

完成合并后，脚本会检查配置中是否存在runner_type：若不存在则通过Runner.from_cfg(cfg)构建 MMEngine 默认 Runner；否则从mmaction.registry.RUNNERS注册表构建自定义 Runner（例如 mmaction/engine/runner/multi_loop.py 中注册的MultiLoaderEpochBasedTrainLoop，用于多数据加载器训练），最后调用runner.train()。

使用多个 GPU 进行训练

MMAction2 提供了一个 shell 脚本 tools/dist_train.sh，其内部通过torch.distributed.launch来启动多个 GPU 的训练任务：

bash tools/dist_train.sh ${CONFIG} ${GPUS} [PY_ARGS]

从 dist_train.sh 源码可以看到，脚本最终执行的等价命令为：

python -m torch.distributed.launch \ --nnodes=$NNODES --node_rank=$NODE_RANK --master_addr=$MASTER_ADDR \ --nproc_per_node=$GPUS --master_port=$PORT \ tools/train.py $CONFIG --launcher pytorch ${@:3}

其中--launcher pytorch由脚本自动附加，${@:3}捕获第三个位置参数之后的所有PY_ARGS原样透传给tools/train.py。

您还可以通过环境变量来指定启动器的其他参数。例如，使用以下命令将启动器的通信端口更改为 29666：

PORT=29666 bash tools/dist_train.sh ${CONFIG} ${GPUS} [PY_ARGS]

如果您想启动多个训练作业并使用不同的 GPU，可以通过指定不同的端口和可见设备来启动它们：

CUDA_VISIBLE_DEVICES=0,1,2,3 PORT=29500 bash tools/dist_train.sh ${CONFIG} 4 [PY_ARGS] CUDA_VISIBLE_DEVICES=4,5,6,7 PORT=29501 bash tools/dist_train.sh ${CONFIG} 4 [PY_ARGS]

使用多台机器进行训练

同一网络中的多台机器

如果您使用以太网连接的多台机器启动训练作业，需要保证所有机器环境变量一致（NNODES、PORT、MASTER_ADDR），仅在NODE_RANK上区分主从。

在第一台机器上：

NNODES=2 NODE_RANK=0 PORT=$MASTER_PORT MASTER_ADDR=$MASTER_ADDR bash tools/dist_train.sh $CONFIG $GPUS

在第二台机器上：

NNODES=2 NODE_RANK=1 PORT=$MASTER_PORT MASTER_ADDR=$MASTER_ADDR bash tools/dist_train.sh $CONFIG $GPUS

需要指定以下额外的环境变量来训练或测试多台机器上的模型：

以上默认值均可在 dist_train.sh 与 dist_test.sh 的NNODES=${NNODES:-1}、PORT=${PORT:-29500}、MASTER_ADDR=${MASTER_ADDR:-"127.0.0.1"}等语句中直接印证。

通常，如果您没有高速网络（如 InfiniBand），则速度会比较慢。

使用 slurm 管理的多台机器

如果您在使用 Slurm 管理的集群上运行 MMAction2，可以使用脚本 tools/slurm_train.sh：

[ENV_VARS] bash tools/slurm_train.sh ${PARTITION} ${JOB_NAME} ${CONFIG} [PY_ARGS]

下面是该脚本的参数描述：

下面列出了可用于配置 slurm 作业的环境变量：

从 slurm_train.sh 源码可见其核心调度方式：脚本会随机生成MASTER_PORT=$((12000 + $RANDOM % 20000))以避免端口冲突，然后通过srun -p ${PARTITION} --gres=gpu:${GPUS_PER_NODE} --ntasks=${GPUS} --ntasks-per-node=${GPUS_PER_NODE} --cpus-per-task=${CPUS_PER_TASK} --kill-on-bad-exit=1 ${SRUN_ARGS} python -u tools/train.py ${CONFIG} --launcher="slurm" ${PY_ARGS}提交作业。这里--launcher="slurm"会切换到 MMAction2 的 slurm 分布式环境初始化路径；--kill-on-bad-exit=1保证任一任务异常退出时整个作业立即终止，避免集群资源空转。

测试（Testing）

测试入口为 tools/test.py，与训练共享同一套配置继承机制与分布式启动方式。

使用单个 GPU 进行测试

您可以使用tools/test.py在一台带有 CPU 和可选 GPU 的单机上测试模型：

python tools/test.py ${CONFIG_FILE} ${CHECKPOINT_FILE} [ARGS]

默认情况下，MMAction2 更倾向于使用 GPU 而不是 CPU 进行测试。如果您想在 CPU 上测试模型，请清空 `CUDA_VISIBLE_DEVICES` 或将其设置为 -1 以使 GPU 对程序不可见。 ```bash CUDA_VISIBLE_DEVICES=-1 python tools/test.py ${CONFIG_FILE} ${CHECKPOINT_FILE} [ARGS] ```

源码视角：tools/test.py的可视化与结果导出

merge_args 揭示了测试脚本两个高频参数的真实机制：

• --show/--show-dir：触发可视化时，脚本会先断言配置的default_hooks中存在VisualizationHook（即dict(type="VisualizationHook")，可参考 configs/base/default_runtime.py 中default_hooks的结构），然后将enable、show、wait_time、out_dir、interval五个字段写回cfg.default_hooks.visualization。
• --dump：要求目标文件必须以.pkl或.pickle结尾，否则直接断言报错。其实现方式是向cfg.test_evaluator追加一个DumpResults评测器（dict(type='DumpResults', out_file_path=args.dump)），评测完成后将模型的全部预测输出序列化保存，供后续离线评估复用。

此外，cfg.load_from = args.checkpoint直接将权重路径注入配置；work_dir的确定优先级与训练完全一致（CLI > 配置 > 文件名）。

使用多个 GPU 进行测试

我们提供了一个 shell 脚本 tools/dist_test.sh，使用torch.distributed.launch来启动多个 GPU 的测试任务：

bash tools/dist_test.sh ${CONFIG} ${CHECKPOINT} ${GPUS} [PY_ARGS]

您还可以通过环境变量来指定启动器的其他参数。例如，使用以下命令将启动器的通信端口更改为 29666：

PORT=29666 bash tools/dist_test.sh ${CONFIG} ${CHECKPOINT} ${GPUS} [PY_ARGS]

如果您想启动多个测试作业并使用不同的 GPU，可以通过指定不同的端口和可见设备来启动它们：

CUDA_VISIBLE_DEVICES=0,1,2,3 PORT=29500 bash tools/dist_test.sh ${CONFIG} ${CHECKPOINT} 4 [PY_ARGS] CUDA_VISIBLE_DEVICES=4,5,6,7 PORT=29501 bash tools/dist_test.sh ${CONFIG} ${CHECKPOINT} 4 [PY_ARGS]

使用多台机器进行测试

同一网络中的多台机器

如果您使用以太网连接的多台机器进行测试作业，可以运行以下命令：

在第一台机器上：

NNODES=2 NODE_RANK=0 PORT=$MASTER_PORT MASTER_ADDR=$MASTER_ADDR bash tools/dist_test.sh $CONFIG $CHECKPOINT $GPUS

在第二台机器上：

NNODES=2 NODE_RANK=1 PORT=$MASTER_PORT MASTER_ADDR=$MASTER_ADDR bash tools/dist_test.sh $CONFIG $CHECKPOINT $GPUS

与单台机器上的多个 GPU 相比，您需要指定一些额外的环境变量：

通常，如果您没有高速网络（如 InfiniBand），则速度会比较慢。

使用 slurm 管理的多台机器

如果您在使用 Slurm 管理的集群上运行 MMAction2，可以使用脚本 tools/slurm_test.sh：

[ENV_VARS] bash tools/slurm_test.sh ${PARTITION} ${JOB_NAME} ${CONFIG} ${CHECKPOINT} [PY_ARGS]

下面是该脚本的参数描述：

下面列出了可用于配置 slurm 作业的环境变量：

与训练端一致，slurm_test.sh 同样通过srun提交，并自动附加--launcher="slurm"，位置参数CONFIG、CHECKPOINT分别占据第 3、第 4 个位置，${@:5}透传其余PY_ARGS。

端到端实战：以 TSN 为例串联训练与测试

文档 快速运行 给出了从数据准备到测试的完整最小闭环，这里与其衔接展示train_test.md中的命令如何落到真实项目上：

1. 准备精简版 Kinetics400 数据（解压到data/目录），并使用 tsn_imagenet-pretrained-r50_8xb32-1x1x3-100e_kinetics400-rgb.py 作为基础配置（该配置的_base_依次继承 configs/base/models/tsn_r50.py、configs/base/schedules/sgd_100e.py 与 configs/base/default_runtime.py，其中学习率调度MultiStepLR(milestones=[40, 80], gamma=0.1)、优化器SGD(lr=0.01, momentum=0.9, weight_decay=0.0001)均在schedules/sgd_100e.py中定义）。
2. 通过--cfg-options原地覆盖数据集路径与训练计划，而无需改动配置文件本身。例如：

python tools/train.py configs/recognition/tsn/tsn_imagenet-pretrained-r50_8xb32-1x1x3-100e_kinetics400-rgb.py \ --cfg-options data_root='data/kinetics400_tiny/train' \ data_root_val='data/kinetics400_tiny/val' \ train_dataloader.batch_size=4 \ train_cfg.max_epochs=10 \ --auto-scale-lr

3. 训练完成后，将tools/test.py与训练阶段产出的最优权重组合即可完成测试；若使用多卡评测，则替换为dist_test.sh：

python tools/test.py configs/recognition/tsn/tsn_imagenet-pretrained-r50_8xb32-1x1x3-100e_kinetics400-rgb.py \ work_dirs/tsn_imagenet-pretrained-r50_8xb32-1x1x3-100e_kinetics400-rgb/best_acc/top1_epoch_6.pth

关于配置字段的逐项含义、命名约定与更复杂的覆盖写法（如列表索引train_pipeline.0.type=DenseSampleFrames、列表值model.data_preprocessor.mean="[128,128,128]"），可进一步阅读学习配置文件；若要在新数据集上进行微调（修改num_classes、降低学习率、缩短训练周期并通过load_from加载预训练权重），可参考模型微调。

使用建议与注意事项

• 恢复训练优先用--resume而非--cfg-options load_from：--resume会同时置位cfg.resume并保留工作目录中的训练状态（优化器、学习率、epoch 进度等），是中断后无缝续训的推荐方式；load_from仅加载权重。
• 端口管理：默认PORT=29500在单机多卡与多机场景下都必须全局一致；同时运行多个分布式作业时，通过CUDA_VISIBLE_DEVICES隔离 GPU 并分配不同端口可避免冲突。
• 多机通信依赖：多机训练对节点间带宽敏感，文档明确指出无 InfiniBand 等高速网络时性能会明显受限。
• --cfg-options的引号规则：覆盖列表/元组值时引号必不可少，且键值对之间不允许出现空格，否则会被DictAction解析失败。
• Slurm 环境变量默认值：GPUS=8、GPUS_PER_NODE=8、CPUS_PER_TASK=5均为脚本内置默认值，可通过环境变量前缀覆盖，例如GPUS=4 GPUS_PER_NODE=4 bash tools/slurm_train.sh ...。
• 工作目录约定：./work_dirs/<配置文件名>是tools/train.py与tools/test.py的默认输出位置（训练日志、checkpoint、测试指标文件），该行为在 tools/train.py 与 tools/test.py 中完全一致。

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