ViTPose 实战指南:基于 ShuffleNetV2 骨干的 COCO 人体姿态估计(Top-Down Heatmap 方案)
ViTPose 实战指南:基于 ShuffleNetV2 骨干的 COCO 人体姿态估计(Top-Down Heatmap 方案)
本文以 ViTPose 仓库(基于 OpenMMLab MMPose 框架)中 COCO 人体姿态估计任务的 ShuffleNetV2 配置文件为核心,系统讲解其模型结构、训练配置、数据增广流水线、评测流程与复现命令,并结合仓库源码逐层剖析 ShuffleNetV2 骨干、热图头与损失函数的实现细节。读完本文,你将能够理解 256x192 与 384x288 两套配置的完整参数含义,并掌握在 COCO 数据集上从零训练、测试与迁移该轻量级姿态估计模型的具体方法。
一、配置文档与官方结果速览
本文对应的原始文档为 shufflenetv2_coco.md,属于仓库 configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/ 目录下的 Backbone 模型卡片。该文档引用了两个核心工作:
- ShuffleNetV2(ECCV'2018):
Shufflenet v2: Practical guidelines for efficient cnn architecture design,提出以"直接度量(memory access cost)"为指导的轻量级 CNN 设计准则,是本文骨干网络的理论出处; - COCO 数据集(ECCV'2014):
Microsoft coco: Common objects in context,用于人体关键点检测任务,本配置在其 val2017 上评测。
同一目录下还配套存放了两套可运行配置与一份模型索引:
| 配置文件 | 输入尺寸 | 输出热图尺寸 |
|---|---|---|
| shufflenetv2_coco_256x192.py | 256x192 | 64x48 |
| shufflenetv2_coco_384x288.py | 384x288 | 96x72 |
文档记录的评测结果(COCO val2017,使用人体检测器 AP 为 56.4 的检测框):
| 架构 | 输入尺寸 | AP | AP50 | AP75 | AR | AR50 |
|---|---|---|---|---|---|---|
| pose_shufflenetv2 | 256x192 | 0.599 | 0.854 | 0.663 | 0.664 | 0.899 |
| pose_shufflenetv2 | 384x288 | 0.636 | 0.865 | 0.705 | 0.697 | 0.909 |
对应的模型索引文件 shufflenetv2_coco.yml 记录了这两套模型(topdown_heatmap_shufflenetv2_coco_256x192 与 topdown_heatmap_shufflenetv2_coco_384x288)的完整指标、任务类型(Body 2D Keypoint)与训练数据(COCO),并登记了官方权重文件名(如 shufflenetv2_coco_256x192-0aba71c7_20200921.pth),可用于下载后复现评测。可以看出,将输入分辨率从 256x192 提升到 384x288 后,AP 从 0.599 提升至 0.636(+3.7),代价是约 2.25 倍的计算量。
二、从配置看整体模型架构
两套 COCO 配置的模型定义几乎一致,仅输入尺寸、热图尺寸与高斯 sigma 不同。以 shufflenetv2_coco_256x192.py 为例:
# model settings
model = dict(
type='TopDown',
pretrained='mmcls://shufflenet_v2',
backbone=dict(type='ShuffleNetV2', widen_factor=1.0),
keypoint_head=dict(
type='TopdownHeatmapSimpleHead',
in_channels=1024,
out_channels=channel_cfg['num_output_channels'],
loss_keypoint=dict(type='JointsMSELoss', use_target_weight=True)),
train_cfg=dict(),
test_cfg=dict(
flip_test=True,
post_process='default',
shift_heatmap=True,
modulate_kernel=11))
各部分职责如下:
type='TopDown':采用自顶向下(top-down)检测范式,即先由检测器给出人体框,再对每个框内的人体单独回归关键点。对应检测器实现位于 mmpose/models/detectors/top_down.py,其forward_train依次执行backbone -> neck(可选) -> keypoint_head,并通过keypoint_head.get_loss()计算热图损失、get_accuracy()统计 PCK 精度(见 top_down.py);pretrained='mmcls://shufflenet_v2':从 mmcls 模型库加载在 ImageNet 上预训练的 ShuffleNetV2 权重,作为骨干初始化;backbone=dict(type='ShuffleNetV2', widen_factor=1.0):骨干网络使用宽度因子 1.0 的标准 ShuffleNetV2;keypoint_head:使用TopdownHeatmapSimpleHead,输入 1024 通道(ShuffleNetV2 最后一层输出),输出 17 个通道(COCO 的 17 个关键点);loss_keypoint:使用JointsMSELoss并开启use_target_weight(按关键点可见性加权);test_cfg:开启水平翻转测试(flip_test=True,原始热图与翻转热图取平均)、默认后处理post_process='default'、翻转热图平移对齐shift_heatmap=True、坐标解码时的调制卷积核modulate_kernel=11。
channel_cfg 定义了 COCO 数据集的通道映射:num_output_channels=17、dataset_joints=17,dataset_channel 与 inference_channel 均为 <a href="https://link.gitcode.com/i/b0c9e83c8262eb03ab0e83b4def1fd32" target="_blank">0..16],即训练通道与推理通道一一对应(见 [shufflenetv2_coco_256x192.py)。17 个关键点的具体语义(nose、left_eye、right_eye……right_ankle)与左右互换关系(flip_pairs)定义在基础数据集配置 configs/base/datasets/coco.py 中,该文件同时提供了 joint_weights(肘、腕等关键点权重更高)与 sigmas(用于 OKS 评估的关键点标准差)。
三、ShuffleNetV2 骨干网络源码解析
骨干实现位于 mmpose/models/backbones/shufflenet_v2.py,核心设计遵循 ShuffleNetV2 论文的四条轻量化准则(输入输出同通道、分组数不宜过多、碎片化最小化、逐元素运算不可忽略)。
3.1 InvertedResidual 基础块
InvertedResidual 类(shufflenet_v2.py)是网络的基本构建单元:
- stride=1:输入在通道维一分为二(
x.chunk(2, dim=1)),一半直接恒等传递,另一半经过1x1 Conv -> 3x3 深度可分离卷积 -> 1x1 Conv,最后与恒等分支拼接并执行channel_shuffle(out, 2); - stride>1:两条分支均参与计算,第一条分支为
3x3 深度卷积 + 1x1 Conv,第二条分支为1x1 -> 3x3 分组卷积 -> 1x1,两分支输出拼接后同样经过通道混洗; with_cp=True时使用 torch 的 checkpoint 机制,以少量训练速度为代价显著节省显存。
仓库配套的单测 tests/test_backbones/test_shufflenet_v2.py 验证了:stride=1 时 in_channels 必须等于 out_channels // 2 * 2;InvertedResidual(24, 48, stride=2) 前向输出形状为 (1, 48, 28, 28),即空间分辨率减半、通道数翻倍。
3.2 网络主干与宽度因子
ShuffleNetV2 主干(shufflenet_v2.py)由 conv1(3x3, stride=2) -> maxpool -> 3 个 stage -> 1x1 Conv 构成,各 stage 的块数为 [4, 8, 4]。宽度因子 widen_factor 决定各层通道数:
| widen_factor | 各 stage 通道数 | 输出通道 |
|---|---|---|
| 0.5 | [48, 96, 192] | 1024 |
| 1.0 | [116, 232, 464] | 1024 |
| 1.5 | [176, 352, 704] | 1024 |
| 2.0 | [244, 488, 976] | 2048 |
本配置使用 widen_factor=1.0,因此 keypoint_head 的 in_channels=1024 与骨干输出严格对应。测试代码 tests/test_backbones/test_shufflenet_v2.py 验证了 widen_factor=1.0 时各 stage 输出特征图为 (1,116,28,28)、(1,232,14,14)、(1,464,7,7);同时校验了 widen_factor 仅允许取 0.5/1.0/1.5/2.0,frozen_stages 需在 [-1, 4) 范围,out_indices 需在 [0, 4) 范围。
此外骨干还支持 frozen_stages(冻结前若干 stage 的参数,常用于迁移学习)、norm_eval(训练时保持 BN 的 running stats 不更新)与 with_cp 等参数,均可通过 --cfg-options 在命令行覆盖。
四、简易热图头与 MSE 损失
4.1 TopdownHeatmapSimpleHead
热图头实现位于 mmpose/models/heads/topdown_heatmap_simple_head.py,其结构为"3 层反卷积(deconv)+ 1x1 卷积":
- 默认
num_deconv_layers=3、num_deconv_filters=(256,256,256)、num_deconv_kernels=(4,4,4),每层反卷积 stride=2、output_padding=1(见_make_deconv_layer,topdown_heatmap_simple_head.py),将 1024 通道的骨干特征逐步上采样 8 倍并降至 256 通道; final_layer为 1x1 卷积,将 256 通道映射为out_channels=17的关键点热图(每个通道对应一个关键点的高斯响应);- 推理阶段
inference_model(topdown_heatmap_simple_head.py)会对翻转热图执行flip_back并用shift_heatmap做 1 像素平移对齐,从而修正翻转引起的特征错位,这与配置中test_cfg的两个开关一一对应; - 训练时
get_loss输出heatmap_loss,get_accuracy通过pose_pck_accuracy计算acc_pose。
4.2 JointsMSELoss
损失函数实现在 mmpose/models/losses/mse_loss.py。JointsMSELoss 将预测热图与真值热图按关节展开,逐关节计算 MSE:
if self.use_target_weight:
loss += self.criterion(heatmap_pred * target_weight[:, idx],
heatmap_gt * target_weight[:, idx])
当 use_target_weight=True 时,每个关节的损失按 target_weight 加权——不可见关键点权重为 0,不参与梯度回传;最后损失除以关节数取平均。该文件还提供了 CombinedTargetMSELoss(分类+回归联合目标)与 JointsOHKMMSELoss(在线困难关键点挖掘)等变体,可供替换实验。
五、数据配置与增广流水线
5.1 data_cfg:框来源与后处理阈值
以 shufflenetv2_coco_256x192.py 为例:
data_cfg = dict(
image_size=[192, 256],
heatmap_size=[48, 64],
num_output_channels=channel_cfg['num_output_channels'],
num_joints=channel_cfg['dataset_joints'],
dataset_channel=channel_cfg['dataset_channel'],
inference_channel=channel_cfg['inference_channel'],
soft_nms=False,
nms_thr=1.0,
oks_thr=0.9,
vis_thr=0.2,
use_gt_bbox=False,
det_bbox_thr=0.0,
bbox_file='data/coco/person_detection_results/'
'COCO_val2017_detections_AP_H_56_person.json',
)
image_size=[192, 256](W, H):输入图像裁剪尺寸;heatmap_size=[48, 64]:输出热图尺寸,恰为输入尺寸的 1/4(配合骨干的 4 次下采样与热图头的 3 次反卷积 2 倍上采样,最终分辨率比例为 1/4×8=2,即输入 256 高对应 64 热图高);use_gt_bbox=False:评估时不使用 GT 框,而是从bbox_file指定的检测结果文件(人体检测器 AP 为 56.4 的预生成检测框)读取候选框;det_bbox_thr=0.0表示不按检测分数过滤;soft_nms=False、nms_thr=1.0、oks_thr=0.9:评测时使用普通 OKS-NMS,阈值 0.9;vis_thr=0.2用于关键点分数重打分(rescoring)。这些参数在数据集类 mmpose/datasets/datasets/top_down/topdown_coco_dataset.py 中被逐一读取并生效。
5.2 train_pipeline:训练增广
训练流水线包含以下变换(见 shufflenetv2_coco_256x192.py):
| 变换 | 参数 | 作用 |
|---|---|---|
LoadImageFromFile |
- | 加载图像 |
TopDownRandomFlip |
flip_prob=0.5 | 随机水平翻转 |
TopDownHalfBodyTransform |
num_joints_half_body=8, prob_half_body=0.3 | 以 30% 概率按半身 8 个关键点裁剪,加强遮挡鲁棒性 |
TopDownGetRandomScaleRotation |
rot_factor=40, scale_factor=0.5 | 随机旋转 ±40°、缩放 ±0.5 倍 |
TopDownAffine |
- | 仿射变换到固定尺寸 |
ToTensor + NormalizeTensor |
mean=[0.485,0.456,0.406], std=[0.229,0.224,0.225] | 张量化并做 ImageNet 归一化 |
TopDownGenerateTarget |
sigma=2 | 生成高斯热图标签 |
Collect |
keys/meta_keys | 收集样本字段 |
注意:256x192 配置的 TopDownGenerateTarget 使用 sigma=2,而 384x288 配置使用 sigma=3(见 shufflenetv2_coco_384x288.py)。高斯半径随热图尺寸增大而适当放宽,以保证标签与模型分辨率匹配。
5.3 val/test_pipeline:评测流水线
验证与测试流水线(shufflenetv2_coco_256x192.py)不含随机增广,仅包含 LoadImageFromFile -> TopDownAffine -> ToTensor -> NormalizeTensor -> Collect,且 test_pipeline = val_pipeline。train/val/test 三部分数据集均为 TopDownCocoDataset,指向 COCO 官方标注文件(train2017 / val2017 的 person_keypoints_*.json)。
六、优化器、学习率与运行配置
两套 COCO 配置的优化策略完全一致(shufflenetv2_coco_256x192.py):
evaluation = dict(interval=10, metric='mAP', save_best='AP')
optimizer = dict(type='Adam', lr=5e-4)
optimizer_config = dict(grad_clip=None)
lr_config = dict(
policy='step',
warmup='linear',
warmup_iters=500,
warmup_ratio=0.001,
step=[170, 200])
total_epochs = 210
- 优化器:Adam,初始学习率 5e-4,不裁剪梯度;
- 学习率策略:前 500 次迭代线性预热(warmup_ratio=0.001),之后在 epoch 170 与 200 处以 0.1 倍阶梯衰减;
- 总训练轮数:210 epochs;
- 评测:每 10 个 epoch 在 val2017 上评测一次 mAP,并以 AP 为准则保存最优模型。
基础运行配置继承自 configs/base/default_runtime.py:每 10 个 epoch 存一次 checkpoint、每 50 次迭代打印一次日志、禁用 OpenCV 多线程、数据加载使用 fork 方式启动多进程以加速训练。数据加载配置方面,samples_per_gpu=64、workers_per_gpu=2,验证/测试 dataloader 的 samples_per_gpu=32。
七、数据集加载与 COCO 评测流程
TopDownCocoDataset(mmpose/datasets/datasets/top_down/topdown_coco_dataset.py)继承自 Kpt2dSviewRgbImgTopDownDataset,其关键逻辑:
_get_db()依据test_mode与use_gt_bbox决定加载路径:训练或使用 GT 框时读取 COCO 关键点标注(_load_coco_keypoint_annotations),否则读取检测结果文件(_load_coco_person_detection_results,topdown_coco_dataset.py);- 评测阶段
evaluate()依次执行:按关键点可见性与vis_thr重打分 → OKS-NMS(oks_nms或soft_oks_nms)→ 写出result_keypoints.json→ 调用COCOeval计算 AP/AR 指标(topdown_coco_dataset.py),输出 AP、AP@0.5、AP@0.75、AP(M)、AP(L)、AR、AR@0.5、AR@0.75 等 10 项统计量。这与本文第一节结果表所列指标一一对应。
八、训练与测试复现命令
基于 docs/en/getting_started.md 中记载的通用流程,针对本配置的实操命令如下(需先按仓库说明安装依赖、准备 COCO 数据与检测结果文件):
单卡训练:
python tools/train.py configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/shufflenetv2_coco_256x192.py \
--work-dir work_dirs/shufflenetv2_coco_256x192
多卡分布式训练:
./tools/dist_train.sh configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/shufflenetv2_coco_256x192.py 8
多卡场景下建议按线性缩放规则调整学习率(--autoscale-lr 可按 GPU 数自动缩放),或用 --cfg-options optimizer.lr=... 手动覆盖。
单卡测试(需先下载官方权重,文件名见 shufflenetv2_coco.yml):
python tools/test.py configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/shufflenetv2_coco_256x192.py \
${CHECKPOINT_FILE} --eval mAP --out results.pkl
多卡测试:
./tools/dist_test.sh configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/shufflenetv2_coco_256x192.py \
${CHECKPOINT_FILE} 8 --eval mAP
tools/test.py 的入口逻辑(tools/test.py)会依次完成:加载配置(并设置 cfg.model.pretrained = None、test_mode = True)、构建测试数据集与 dataloader、加载 checkpoint(可选 --fuse-conv-bn 融合卷积与 BN 以小幅提速)、执行单/多卡前向,最后调用 dataset.evaluate 输出 COCO 关键点 mAP。--cfg-options 可覆盖任意配置项,例如切换分辨率配置中的 sigma 或调整 flip_test。
九、输入分辨率权衡与跨数据集迁移
对比两套配置可得到明确的工程结论:
- 256x192(sigma=2):AP 0.599,适合资源受限的边缘设备或实时场景;
- 384x288(sigma=3):AP 0.636,精度提升约 3.7 个百分点,适合对精度更敏感的场景。
ShuffleNetV2 作为轻量骨干本身计算量远小于 ResNet-50 等常用骨架,配合较小输入分辨率即可达到可部署的推理速度,这也正是该配置在姿态估计领域常被选作轻量基线的原因。
同一骨干还可迁移到其他数据集。仓库提供了 MPII 上的对应配置 shufflenetv2_mpii_256x256.py:其 channel_cfg 改为 16 个关键点、use_gt_bbox=True(MPII 使用 GT 框评估)、评测指标改为 PCKh,数据增广流水线与优化策略保持一致。对比可见,迁移到新数据集只需调整通道配置、数据路径与评测指标三处,模型主体无需改动。
十、总结
ShuffleNetV2 在 ViTPose 仓库中承担轻量级自顶向下姿态估计骨干的角色,其 COCO 配置完整覆盖了"检测框输入 → 轻量骨干特征提取 → 反卷积热图头 → 高斯热图 MSE 回归 → OKS 评估"的标准链路。理解本文所剖析的 模型配置、骨干源码、热图头源码 与数据集实现,即可在此基础上自由调整分辨率、宽度因子、增广策略与优化参数,复现官方结果并进一步实验。