ViTPose 仓库实战:VGG16-BN 主干在 COCO 人体姿态估计(Top-Down Heatmap)中的配置解析与源码剖析
ViTPose 仓库实战:VGG16-BN 主干在 COCO 人体姿态估计(Top-Down Heatmap)中的配置解析与源码剖析
本篇技术指南以 ViTPose 仓库中 COCO 人体关键点检测的 VGG 模型卡片 vgg_coco.md 及其对应训练配置 vgg16_bn_coco_256x192.py 为主体,深入讲解如何基于 VGG16-BN 主干构建经典的 Top-Down 热图式姿态估计模型。读完本文,你将掌握该模型在 COCO 数据集上的完整配置含义、VGG 主干在姿态估计场景下的源码实现、训练评估与单图推理的完整操作流程,并了解如何在此基础上替换主干或调整训练策略。
一、模型背景与基准结果
该模型卡片同时引用了两个工作:
- VGG(ICLR'2015):Karen Simonyan 与 Andrew Zisserman 提出的深度卷积网络,核心结论是使用小尺寸(3x3)卷积核并将网络加深到 16~19 层,可以显著提升大规模图像识别精度。仓库中以
BACKBONE标记声明该工作为本文所述模型的主干来源,对应文献为simonyan2014very。 - COCO(ECCV'2014):Microsoft COCO 数据集,用于人体关键点检测的标注包含 17 个关键点,对应文献为
lin2014microsoft,以DATASET标记声明其为训练与评估数据集。
模型卡片给出了在 COCO val2017 上的评估结果,评估前提是"detector having human AP of 56.4 on COCO val2017 dataset",即测试阶段使用一个人体检测器(人体 AP 为 56.4)先框出人体,再对每个人体框做关键点估计:
| Arch | Input Size | AP | AP50 | AP75 | AR | AR50 | ckpt | log |
|---|---|---|---|---|---|---|---|---|
| vgg | 256x192 | 0.698 | 0.890 | 0.768 | 0.754 | 0.929 | [ckpt] | [log] |
上表中的 ckpt 与 log 指模型权重文件与训练日志,其下载地址与精确指标同样记录在模型注册表 vgg_coco.yml 中(Weights 字段),该文件同时登记了模型在 Body 2D Keypoint 任务上的完整元数据,是批量查询与复现实验的入口。模型名称在注册表中为 topdown_heatmap_vgg16_bn_coco_256x192。
值得说明的是,该模型卡片采用的是经典的"主干 + 简单热图预测头"范式(即 Simple Baseline,参考 Bin Xiao 等人的工作),与仓库中 ViTPose 系列使用 Transformer 主干的路线形成对照,适合作为消融实验与精度基准。
二、训练配置文件逐段解析
训练配置位于 vgg16_bn_coco_256x192.py,它通过 _base_ 机制继承公共配置,自身只声明与 VGG+COCO 相关的差异部分。
2.1 基类继承
_base_ = [
'../../../../_base_/default_runtime.py',
'../../../../_base_/datasets/coco.py'
]
- default_runtime.py 提供公共运行时设置:每 10 个 epoch 保存一次 checkpoint(
checkpoint_config = dict(interval=10))、每 50 次迭代打印一次日志、log_level = 'INFO'、分布式后端nccl、单卡工作流workflow = [('train', 1)],并禁用 OpenCV 多线程(opencv_num_threads = 0)、将多进程启动方式设为fork以加速训练。 - datasets/coco.py 提供 COCO 数据集的
dataset_info:完整定义了 17 个关键点的名称、颜色、swap配对关系(如left_eye↔right_eye,用于水平翻转测试时的热图还原)、19 条骨架连接skeleton_info、按关节点位的重要性设定的joint_weights(腕部 1.5、肘膝 1.2 等)以及用于 OKS 指标计算的sigmas列表。这些信息会被TopDownCocoDataset(见 topdown_coco_dataset.py)解析为ann_info并在数据管线与评估中反复使用。
2.2 模型结构定义
model = dict(
type='TopDown',
pretrained='mmcls://vgg16_bn',
backbone=dict(type='VGG', depth=16, norm_cfg=dict(type='BN')),
keypoint_head=dict(
type='TopdownHeatmapSimpleHead',
in_channels=512,
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.py。其前向过程为:backbone(img)提取特征 →(可选的neck)→keypoint_head(output)输出热图,训练时调用get_loss/get_accuracy,测试时调用inference_model与decode。pretrained='mmcls://vgg16_bn'表示通过 mmcls 模型库加载 ImageNet 预训练权重;由于主干带 BN,预训练模型即为 VGG16-BN 版本。backbone=dict(type='VGG', depth=16, norm_cfg=dict(type='BN')):选用深度 16 的 VGG,并为每个卷积层后追加 BatchNorm。keypoint_head使用TopdownHeatmapSimpleHead(实现见 topdown_heatmap_simple_head.py):in_channels=512对应 VGG 最后一个池化层前的 512 通道特征,out_channels=17对应 COCO 的 17 个关键点。test_cfg中的flip_test=True开启水平翻转测试(将原图与翻转图的预测热图按flip_pairs对折叠加),shift_heatmap=True在翻转后对热图做 1 像素偏移修正,post_process='default'与modulate_kernel=11控制热图后处理(在极大值周围做调制以更精确地回归坐标)。
2.3 通道与数据配置
channel_cfg = dict(
num_output_channels=17,
dataset_joints=17,
dataset_channel=[[0,...,16]],
inference_channel=[0,...,16])
dataset_channel 与 inference_channel 均为全量 17 个通道,表示数据集标注通道与推理输出通道一一对应,无需做通道映射。data_cfg 进一步声明:
data_cfg = dict(
image_size=[192, 256],
heatmap_size=[48, 64],
num_output_channels=17,
num_joints=17,
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]:输入图像缩放到宽 192、高 256;heatmap_size=[48, 64]:输出热图为输入的 1/4 分辨率。这也是模型卡片中Input Size: 256x192的由来(约定写法为"高 x 宽")。- 测试阶段
use_gt_bbox=False,即不直接使用 GT 框,而是读取bbox_file中由外部检测器(人体 AP 56.4)生成的检测框结果,与模型卡片的评估说明完全对应。 soft_nms=False、nms_thr=1.0、oks_thr=0.9、vis_thr=0.2控制多人场景下关键点分组与过滤策略。
2.4 训练数据增强管线
训练管线(train_pipeline)顺序执行:
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°、随机缩放 ±50%。TopDownAffine:依据中心点、尺度与旋转角生成仿射变换并裁剪出输入图像。ToTensor+NormalizeTensor:使用 ImageNet 统计量mean=[0.485, 0.456, 0.406]、std=[0.229, 0.224, 0.225]归一化。TopDownGenerateTarget(sigma=2):按 MSRA 方式生成高斯热图标签(实现见 top_down_transform.py 的TopDownGenerateTarget,默认encoding='MSRA'、target_type='GaussianHeatmap'、3-sigma 截断),并输出target_weight标记每个关键点是否可见。Collect:收集img、target、target_weight及image_file、joints_3d、center、scale、rotation、bbox_score、flip_pairs等元信息。
验证与测试管线(val_pipeline/test_pipeline)则只做 LoadImageFromFile → TopDownAffine → ToTensor → NormalizeTensor → Collect,不做随机增强。
2.5 优化器与学习率策略
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(初始比例 0.001),在第 170 与 200 个 epoch 分别衰减一次,共训练 210 个 epoch。
- 验证相关设置
evaluation = dict(interval=10, metric='mAP', save_best='AP'):每 10 个 epoch 在验证集上计算 mAP,并按AP指标保存最优模型。
2.6 数据加载与数据集定义
data_root = 'data/coco',训练/验证/测试分别使用:
- 训练:
person_keypoints_train2017.json+train2017/图像目录; - 验证/测试:
person_keypoints_val2017.json+val2017/图像目录。
三者均为 TopDownCocoDataset 类型,dataset_info={{_base_.dataset_info}} 引用基类中 COCO 的完整关节定义。数据加载器设置:训练 samples_per_gpu=64、workers_per_gpu=2,验证/测试 samples_per_gpu=32。
三、VGG 主干源码实现剖析
VGG 主干实现位于 mmpose/models/backbones/vgg.py,通过 @BACKBONES.register_module() 注册,可供所有需要 type='VGG' 的配置直接引用。
3.1 网络结构表
arch_settings = {
11: (1, 1, 2, 2, 2),
13: (2, 2, 2, 2, 2),
16: (2, 2, 3, 3, 3),
19: (2, 2, 4, 4, 4)
}
每个元组对应 5 个 stage 中每个 stage 的卷积层数。VGG16 即 (2, 2, 3, 3, 3),与标准 VGG16 一致。构造时每个 stage 由若干 make_vgg_layer 组成:
def make_vgg_layer(in_channels, out_channels, num_blocks, ...):
for _ in range(num_blocks):
layer = ConvModule(
kernel_size=3, dilation=dilation, padding=dilation, ...)
layers.append(nn.MaxPool2d(kernel_size=2, stride=2, ...))
即每个 stage 内堆叠若干个 3x3 卷积(ConvModule 支持附加 norm 与激活,配置中 norm_cfg=dict(type='BN') 即为每个卷积追加 BN),stage 末尾接 2x2 步长 2 的最大池化。通道数按 out_channels = 64 * 2**i if i < 4 else 512 递增,即 64 → 128 → 256 → 512 → 512。
3.2 前向与输出
def forward(self, x):
outs = []
...
for i in range(len(self.stage_blocks)):
for j in range(*self.range_sub_modules[i]):
x = vgg_layersj
if i in self.out_indices:
outs.append(x)
...
out_indices 默认为 (4, )(分类场景为 (5, )),即默认输出最后一个 stage 经池化前的特征图。在姿态估计配置中,该特征图即 (N, 512, H/16, W/16) 的特征,随后送入预测头。若指定多个 out_indices,则返回特征元组(out_indices 超出 num_stages 会触发断言)。
3.3 权重初始化与冻结
init_weights:无预训练权重时,对nn.Conv2d使用 kaiming 初始化,对 BatchNorm 使用常数 1 初始化,对全连接层使用标准差 0.01 的正态初始化;配置中因指定pretrained='mmcls://vgg16_bn',会优先加载预训练权重。frozen_stages:可冻结前若干个 stage 的参数(默认 -1 表示不冻结),用于迁移学习场景。norm_eval:置 True 时 BN 层在训练中保持 eval 模式,冻结 running stats。
四、关键点预测头与损失函数
4.1 TopdownHeatmapSimpleHead
该预测头在 topdown_heatmap_simple_head.py 中实现,结构为"若干反卷积层 + 1x1 卷积":
- 默认
num_deconv_layers=3、num_deconv_filters=(256, 256, 256)、num_deconv_kernels=(4, 4, 4),即 3 层步长 2 的转置卷积把 1/16 分辨率的特征逐步上采样回 1/2 分辨率(每层后接 BN 与 ReLU); final_layer为 1x1 卷积,把 256 通道映射为out_channels=17的 17 张关键点热图;- 推理时若传入
flip_pairs,调用flip_back融合翻转热图,并在shift_heatmap=True时对翻转后的热图做 1 像素平移以修正对齐误差(参考实现 post_transforms.py 中的flip_back与transform_preds)。
4.2 JointsMSELoss 加权 MSE 损失
配置中 loss_keypoint=dict(type='JointsMSELoss', use_target_weight=True),实现位于 mse_loss.py。该损失将预测与 GT 热图逐关节计算 MSE,并用 target_weight(可见性掩码)对每个关节的损失加权后求平均:
if self.use_target_weight:
loss += self.criterion(heatmap_pred * target_weight[:, idx],
heatmap_gt * target_weight[:, idx])
return loss / num_joints * self.loss_weight
use_target_weight=True 意味着被遮挡或缺失的关键点不参与损失计算,这是姿态估计训练的常见做法。同文件中还提供了 CombinedTargetMSELoss(UDP 无偏编码)与 JointsOHKMMSELoss(在线难例挖掘,topk 默认 8)等替代损失。
五、模型训练与评估
5.1 单卡/多卡训练
训练入口为 tools/train.py,单卡训练命令:
python tools/train.py configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/vgg16_bn_coco_256x192.py --work-dir work_dirs/vgg16_bn_coco_256x192
多卡分布式训练使用 tools/dist_train.sh:
bash tools/dist_train.sh configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/vgg16_bn_coco_256x192.py 8
其中第二个参数为 GPU 数量,脚本内部通过 torch.distributed.launch --nproc_per_node=$GPUS 启动,--launcher pytorch 指定分布式启动方式。训练过程中的常用命令行参数包括:--resume-from(从断点恢复)、--no-validate(跳过验证)、--seed/--deterministic(固定随机种子)、--cfg-options(运行时覆盖配置,例如 --cfg-options model.backbone.depth=19 可无缝切换 VGG19)、--autoscale-lr(按 GPU 数量线性缩放学习率)。
5.2 指标评估
配置中 metric='mAP' 表明评估采用 COCO 风格的平均精度(AP/AP50/AP75 与 AR/AR50),其底层实现可追溯至 top_down_eval.py 中的 pose_pck_accuracy、keypoint_pck_accuracy、keypoint_auc 与距离计算 _calc_distances。测试脚本为 tools/test.py,支持 --metrics mAP 等参数。
六、单图推理与可视化
模型卡片的配置同样可以直接用于离线推理。仓库提供 demo/top_down_img_demo.py,核心调用链为 init_pose_model → inference_top_down_pose_model → vis_pose_result(API 定义见 mmpose/apis/inference.py)。
典型用法(需准备包含人体框标注的 JSON 文件,格式与 COCO 注解一致):
python demo/top_down_img_demo.py \
configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/vgg16_bn_coco_256x192.py \
<checkpoint.pth> \
--img-root <图像目录> \
--json-file <包含人体框的json> \
--out-img-root <输出目录> \
--kpt-thr 0.3
常用参数说明:
| 参数 | 默认值 | 作用 |
|---|---|---|
--img-root |
'' |
图像根目录 |
--json-file |
'' |
包含人体检测框的 JSON(xywh 格式) |
--show |
False |
是否弹出窗口显示结果 |
--out-img-root |
'' |
可视化结果输出目录 |
--device |
cuda:0 |
推理设备 |
--kpt-thr |
0.3 |
关键点置信度阈值(低于该值的点不绘制) |
--radius / --thickness |
4 / 1 |
关键点半径与骨架线粗细 |
推理时,_box2cs 会将检测框(xywh)编码为 (center, scale) 并放大 1.25 倍,再经仿射变换裁剪为 256x192 输入;模型的 17 张输出热图通过 get_max_preds 等后处理还原为原图坐标。
七、主干正确性的测试保障
仓库在 tests/test_backbones/test_vgg.py 中为 VGG 主干提供了完整的单元测试,可用于验证理解与排查问题:
- 参数合法性校验:
VGG(18)抛出KeyError(depth 仅支持 11/13/16/19);num_stages=0或6抛出AssertionError(要求 1 ≤ num_stages ≤ 5);dilations长度与num_stages不一致时抛AssertionError。 - 前向输出形状:VGG11 输入
(1, 3, 224, 224)时,5 个 stage 的输出特征图依次为(1, 64, 112, 112)、(1, 128, 56, 56)、(1, 256, 28, 28)、(1, 512, 14, 14)、(1, 512, 7, 7);VGG16 默认输出为(1, 512, 7, 7)。 - BN 版本:
norm_cfg=dict(type='BN')的 VGG11BN 前向输出形状与普通版一致,验证了make_vgg_layer中 norm 追加的正确性。
从源码结构看,这也解释了姿态估计配置中 in_channels=512 的来源——VGG16 最后一个 stage 的通道数为 512,预测头的反卷积层会将分辨率逐步还原到热图尺寸。
八、扩展与调参思路
基于本文所述配置,可以在不改动整体框架的前提下做多种实验:
- 切换主干深度:将
backbone的depth改为 19 即得 VGG19-BN,配合--cfg-options model.backbone.depth=19可快速对比; - 输入分辨率:将
image_size调整为[288, 384]、heatmap_size调整为[72, 96],通常可获得更高精度但推理变慢; - 数据增强与编码:在
train_pipeline中引入TopDownGenerateTarget的unbiased_encoding=True(UDP 无偏编码),或在loss_keypoint中替换为CombinedTargetMSELoss、JointsOHKMMSELoss; - 训练策略:修改
lr_config的step与total_epochs以适配不同数据规模;使用frozen_stages冻结浅层进行迁移学习; - 模型复用:将
backbone替换为仓库中其他已注册主干(如 ResNet、HRNet、ViT 系列),预测头的in_channels需同步调整,具体可参考同目录下 resnet_coco.md、hrnet_coco.md 等模型卡片进行横向对比。
总而言之,vgg_coco.md 这张模型卡片虽然篇幅精炼,但串联起了 ViTPose 仓库中"配置继承 → 主干实现 → 预测头/损失 → 训练评估 → 推理可视化"的完整链路。以 VGG16-BN 为代表的经典 CNN 主干,与仓库中 ViTPose 系列 Transformer 主干互为参照,是理解姿态估计模型库架构与开展消融实验的理想起点。