ViTPose 仓库实战:ShuffleNetV1 轻量骨干下的 COCO 人体姿态估计(Top-Down Heatmap)
ViTPose 仓库实战:ShuffleNetV1 轻量骨干下的 COCO 人体姿态估计(Top-Down Heatmap)
导读
本文围绕 ViTPose 仓库中 configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/ 目录下的 ShuffleNetV1 系列配置展开,系统讲解如何在 COCO 数据集上以 Top-Down Heatmap 范式、用轻量级网络 ShuffleNetV1 完成人体关键点估计。通过本文,读者可以掌握该系列配置的完整结构与每一项参数含义、ShuffleNetV1 骨干的底层实现原理(通道混洗、分组卷积、宽度因子),以及从训练、测试到单图推理的完整实战命令。
一、方案背景:轻量骨干 + Top-Down Heatmap
人体姿态估计的主流框架分为两类:自顶向下(Top-Down)与自底向上(Bottom-Up)。本配置属于前者:先用目标检测器从图像中裁剪出单人区域,再对每个裁剪区域回归 17 个关键点的热图(heatmap),最后通过后处理从热图中解析出关键点坐标。
在 关联文档 中,该方案选用的是 ShuffleNetV1 骨干网络(CVPR'2018,论文《ShuffleNet: An Extremely Efficient Convolutional Neural Network for Mobile Devices》),其核心卖点是用分组卷积(grouped convolution)与通道混洗(channel shuffle)在极低计算量下保持精度,非常适合移动端与实时推理场景。配合 COCO 数据集(ECCV'2014,Microsoft COCO: Common Objects in Context),模型输出 17 个 COCO 人体关键点(鼻、眼、耳、肩、肘、腕、髋、膝、踝等)。
对应的两个正式配置文件为:
- shufflenetv1_coco_256x192.py:输入分辨率 256×192,精度优先于速度的平衡点;
- shufflenetv1_coco_384x288.py:输入分辨率 384×288,精度更高但计算量更大。
二、COCO val2017 实验结果
关联文档给出的评测条件为:使用在 COCO val2017 上人体检测 AP 为 56.4 的检测器(对应 data/coco/person_detection_results/COCO_val2017_detections_AP_H_56_person.json 检测框文件)。
| Arch | Input Size | AP | AP50 | AP75 | AR | AR50 |
|---|---|---|---|---|---|---|
| pose_shufflenetv1 | 256x192 | 0.585 | 0.845 | 0.650 | 0.651 | 0.894 |
| pose_shufflenetv1 | 384x288 | 0.622 | 0.859 | 0.685 | 0.684 | 0.901 |
从表格可以清晰看到两个规律:
- 输入分辨率直接决定精度:384×288 相比 256×192,AP 从 0.585 提升到 0.622(+3.7 个百分点),AP75 提升约 3.5 个百分点;
- 高分辨率下 AR 与 AP 同步提升:AR 从 0.651 提升到 0.684,说明更大输入分辨率有助于召回更精细的关键点定位。
两个配置对应的预训练权重与训练日志可依据文档中的 ckpt / log 链接获取,文件命名分别为 shufflenetv1_coco_256x192-353bc02c_20200727.pth 与 shufflenetv1_coco_384x288-b2930b24_20200804.pth。
引用信息
关联文档中同时给出了两篇论文的 BibTeX,供学术引用:
@inproceedings{zhang2018shufflenet,
title={Shufflenet: An extremely efficient convolutional neural network for mobile devices},
author={Zhang, Xiangyu and Zhou, Xinyu and Lin, Mengxiao and Sun, Jian},
booktitle={Proceedings of the IEEE conference on computer vision and pattern recognition},
pages={6848--6856},
year={2018}
}
@inproceedings{lin2014microsoft,
title={Microsoft coco: Common objects in context},
author={Lin, Tsung-Yi and Maire, Michael and Belongie, Serge and Hays, James and Perona, Pietro and Ramanan, Deva and Doll{\'a}r, Piotr and Zitnick, C Lawrence},
booktitle={European conference on computer vision},
pages={740--755},
year={2014},
organization={Springer}
}
三、配置结构逐层拆解
两个配置文件结构完全一致,仅输入分辨率、热图尺寸与高斯 σ 不同。下面以 256×192 配置为例逐段解读(差异点会单独标注)。
3.1 基配置继承与评测策略
_base_ = [
'../../../../_base_/default_runtime.py',
'../../../../_base_/datasets/coco.py'
]
evaluation = dict(interval=10, metric='mAP', save_best='AP')
- default_runtime.py 定义了通用运行时:每 10 个 epoch 保存一次 checkpoint(
checkpoint_config = dict(interval=10))、每 50 次迭代输出一次日志、日志级别 INFO、分布式后端 nccl、训练工作流[('train', 1)],并默认关闭 OpenCV 多线程、以fork方式启动多进程以加速训练; - datasets/coco.py 定义了 COCO 数据集的完整元信息:17 个关键点的名称与左右交换关系(如
left_eye↔right_eye)、骨架连接(skeleton_info)、各关节损失权重joint_weights(肘/膝 1.2、腕/踝 1.5)以及 OKS 评估所需的sigmas; evaluation:每 10 个 epoch 用 mAP 指标评测一次,并依据AP保存最优模型。
3.2 优化器与学习率策略
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,不做梯度裁剪;
- 学习率采用 step 策略:前 500 次迭代线性 warmup(起始比例为 0.001),在第 170 与第 200 个 epoch 分别衰减;
- 总训练轮数为 210 个 epoch。
3.3 通道配置 channel_cfg
channel_cfg = dict(
num_output_channels=17,
dataset_joints=17,
dataset_channel=[[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]],
inference_channel=[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16])
由于 COCO 的 17 个关键点在此配置中全部参与训练与推理,dataset_channel 与 inference_channel 均为 0–16 的全集映射。若只训练 COCO 关键点子集(例如 14 点模型),则需要在此处重新定义映射关系。
3.4 模型定义
model = dict(
type='TopDown',
pretrained='mmcls://shufflenet_v1',
backbone=dict(type='ShuffleNetV1', groups=3),
keypoint_head=dict(
type='TopdownHeatmapSimpleHead',
in_channels=960,
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':注册于 mmpose/models/detectors/top_down.py 的 Top-Down 检测器,负责将 backbone → head 串联,并实现forward_train与forward_test;pretrained='mmcls://shufflenet_v1':从 mmcls 模型库加载 ImageNet 预训练权重;backbone=dict(type='ShuffleNetV1', groups=3):骨干采用 3 组分组卷积的 ShuffleNetV1,最终 stage 输出 960 通道(与 head 的in_channels=960严格对应);keypoint_head:TopdownHeatmapSimpleHead(见 topdown_heatmap_simple_head.py),由 3 层反卷积(默认num_deconv_filters=(256,256,256)、kernel 4×4)+ 1×1 卷积构成,输出 17 通道热图;loss_keypoint:JointsMSELoss均方误差损失,配合use_target_weight=True使用各关节权重;test_cfg:开启翻转测试融合(flip_test=True),采用默认后处理,shift_heatmap=True在推理时对齐热图偏移,modulate_kernel=11控制 OKS 调制的核大小。
3.5 数据配置 data_cfg
256×192 配置:
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',
)
384×288 配置中该段仅有两处差异:image_size=[288, 384]、heatmap_size=[72, 96]。要点解读:
- 热图尺寸为输入尺寸的 1/4(192/4=48,256/4=64),由 head 中的 3 层 stride=2 反卷积实现 8 倍上采样,再经 1×1 卷积输出热图;
use_gt_bbox=False表示训练/评测不使用 GT 框,而是从bbox_file读取预检测的人体框(COCO 检测 AP 为 56.4 的检测器结果);soft_nms=False、nms_thr=1.0:关闭软 NMS;oks_thr=0.9:OKS 匹配阈值;vis_thr=0.2:关键点可见性阈值。
3.6 训练/验证数据流水线
训练流水线(train_pipeline):
train_pipeline = [
dict(type='LoadImageFromFile'),
dict(type='TopDownRandomFlip', flip_prob=0.5),
dict(type='TopDownHalfBodyTransform', num_joints_half_body=8, prob_half_body=0.3),
dict(type='TopDownGetRandomScaleRotation', rot_factor=40, scale_factor=0.5),
dict(type='TopDownAffine'),
dict(type='ToTensor'),
dict(type='NormalizeTensor',
mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
dict(type='TopDownGenerateTarget', sigma=2), # 384x288 配置为 sigma=3
dict(type='Collect',
keys=['img', 'target', 'target_weight'],
meta_keys=['image_file', 'joints_3d', 'joints_3d_visible', 'center', 'scale',
'rotation', 'bbox_score', 'flip_pairs']),
]
各变换含义:
TopDownRandomFlip:以 0.5 概率水平翻转,实现左右关键点交换的数据增强;TopDownHalfBodyTransform:以 0.3 概率只保留包含 ≥8 个关键点的半身区域,增强遮挡鲁棒性;TopDownGetRandomScaleRotation:随机旋转 ±40°、缩放 ±50%;TopDownAffine:将裁剪框仿射变换到image_size;NormalizeTensor:ImageNet 均值/方差归一化;TopDownGenerateTarget:以 σ=2(384×288 配置为 σ=3)生成高斯热图标签。σ 随分辨率增大,是因为 384×288 的热图尺寸更大(72×96),需要匹配的分布更宽。
验证/测试流水线仅包含 LoadImageFromFile → TopDownAffine → ToTensor → NormalizeTensor → Collect,不含任何随机增强。
3.7 数据集与 DataLoader
data_root = 'data/coco'
data = dict(
samples_per_gpu=64,
workers_per_gpu=2,
val_dataloader=dict(samples_per_gpu=32),
test_dataloader=dict(samples_per_gpu=32),
train=dict(
type='TopDownCocoDataset',
ann_file=f'{data_root}/annotations/person_keypoints_train2017.json',
img_prefix=f'{data_root}/train2017/',
data_cfg=data_cfg, pipeline=train_pipeline,
dataset_info={{_base_.dataset_info}}),
val=dict(...person_keypoints_val2017.json...),
test=dict(...person_keypoints_val2017.json...),
)
- 每 GPU 训练批大小 64、2 个 worker;验证/测试批大小 32;
- 训练集使用
person_keypoints_train2017.json,验证与测试均使用person_keypoints_val2017.json; {{_base_.dataset_info}}引用基配置中 COCO 的完整元信息。
四、源码纵深:ShuffleNetV1 骨干是如何工作的
4.1 ShuffleUnit 的三种算子
ShuffleNetV1 的构建单元 ShuffleUnit 位于 mmpose/models/backbones/shufflenet_v1.py,包含三个核心算子:
g_conv_1x1_compress:1×1 分组压缩卷积,输出通道为out_channels // 4;depthwise_conv3x3_bn:3×3 深度可分离卷积(groups=bottleneck_channels),实现逐通道空间特征提取;g_conv_1x1_expand:1×1 分组扩展卷积,恢复通道数。
channel_shuffle 位于两个 1×1 分组卷积之间,其作用是把不同分组的信息打散重排,从而避免"分组卷积导致组间信息不流通"的缺陷——这正是 ShuffleNet 名称的由来。
4.2 combine 模式与分组配置
- 每个 stage 的第一个 ShuffleUnit 使用
combine='concat'(stride=2 下采样 + 平均池化 + 通道拼接),后续单元使用combine='add'(恒等残差相加); groups控制 1×1 分组卷积的分组数。从 shufflenet_v1.py 源码可见各分组对应的输出通道表:
| groups | stage 输出通道 (240/480/960 体系) |
|---|---|
| 1 | 144, 288, 576 |
| 2 | 200, 400, 800 |
| 3 | 240, 480, 960 |
| 4 | 272, 544, 1088 |
| 8 | 384, 768, 1536 |
本配置使用 groups=3,因此第三 stage 输出 960 通道,与 head 的 in_channels=960 对应。widen_factor 宽度因子可整体缩放通道数(经 make_divisible 保证 8 的倍数),本配置保持默认 1.0。
4.3 单元测试验证
tests/test_backbones/test_shufflenet_v1.py 对骨干进行了多维验证:
groups=3时,输入 224×224 图像,三 stage 输出张量形状依次为(1, 240, 28, 28)、(1, 480, 14, 14)、(1, 960, 7, 7)——确认了通道数随分组数变化的映射关系;- 测试覆盖了
groups=1/2/3/4/8、out_indices组合、frozen_stages冻结策略、GroupNorm 替换(norm_cfg=dict(type='GN', ...))以及 checkpoint 训练(with_cp=True)等场景; - 测试还验证了默认
out_indices=(2,)只输出最后一个 stage 特征,与姿态估计场景中"仅取单尺度特征输入 head"的用法一致。
4.4 与 head 的衔接链路
Top-Down 检测器 top_down.py 中的 forward_train 执行 backbone(img) → keypoint_head(output) → get_loss/get_accuracy 的标准链路;forward_test 则在 flip_test=True 时对原图与水平翻转图各推理一次,再融合两个热图(flip_back 逻辑位于 mmpose/core/post_processing/post_transforms.py),最终通过默认后处理与 modulate_kernel=11 的 OKS 调制提取关键点坐标。
五、实战命令
5.1 训练
使用 tools/train.py 启动训练:
python tools/train.py configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/shufflenetv1_coco_256x192.py --work-dir work_dirs/shufflenetv1_coco_256x192
常用参数:
--work-dir:日志与 checkpoint 保存目录;--resume-from:从指定 checkpoint 恢复训练;--no-validate:训练期间跳过验证;--gpu-id:指定单卡训练 GPU。
多卡分布式训练使用 tools/dist_train.sh:
bash tools/dist_train.sh configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/shufflenetv1_coco_256x192.py 8
5.2 测试与评测
使用 tools/test.py:
python tools/test.py \
configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/shufflenetv1_coco_256x192.py \
/path/to/shufflenetv1_coco_256x192-353bc02c_20200727.pth \
--eval mAP
--eval mAP:COCO 数据集使用 mAP 指标评测(与配置中metric='mAP'一致);--fuse-conv-bn:融合 Conv 与 BN 层,可小幅提升推理速度(对应 tools/test.py 中的fuse_conv_bn逻辑);--out:输出结果文件;--gpu-id指定推理 GPU。
5.3 单图推理演示
python demo/top_down_img_demo.py \
configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/shufflenetv1_coco_256x192.py \
/path/to/shufflenetv1_coco_256x192-353bc02c_20200727.pth \
--img-root /path/to/images --json-file /path/to/annotations/person_keypoints_val2017.json \
--out-img-root vis_results
演示脚本接受 pose_config(配置文件路径)与 pose_checkpoint(权重路径)两个位置参数,并从 --img-root、--json-file 或 --show 等选项确定输入来源与可视化方式。
六、调参与扩展建议
- 精度优先:将输入分辨率提升到 384×288(对应 shufflenetv1_coco_384x288.py),AP 可提升约 3.7 个百分点,同时需将
TopDownGenerateTarget的sigma调整为 3,以匹配更大的热图尺寸; - 速度优先:若需进一步压缩计算量,可尝试
backbone=dict(type='ShuffleNetV1', groups=2)或 1,并同步将 head 的in_channels改为 800/576(对应 stage 输出通道),同时配合--fuse-conv-bn加速推理; - 数据增强:
rot_factor、scale_factor、prob_half_body均可按遮挡场景强度调整;flip_prob控制翻转增强概率; - 评测口径:论文表格结果依赖检测 AP 为 56.4 的人体检测框(
COCO_val2017_detections_AP_H_56_person.json),更换检测器会直接影响最终 AP,复现时需保持该文件与评测条件一致。
结语
ShuffleNetV1 系列配置是 ViTPose 仓库中"轻量骨干 × Top-Down Heatmap"路线的典型代表:输入分辨率 256×192 即可在 COCO val2017 上取得 0.585 AP,384×288 可进一步提升至 0.622 AP。通过配置文件逐段拆解、骨干源码原理分析与实测命令,读者既能开箱复现官方结果,也能依据 groups、widen_factor、输入分辨率等自由度自由裁剪模型,为移动端与边缘设备上的实时姿态估计提供可靠的工程起点。