ViTPose 仓库 HRFormer 姿态估计配置全解析:基于 COCO 的 Top-Down Heatmap 训练与部署
ViTPose 仓库 HRFormer 姿态估计配置全解析:基于 COCO 的 Top-Down Heatmap 训练与部署
本文以 ViTPose 仓库中 hrformer_coco.md 为骨架,系统讲解 HRFormer(NIPS'2021)这一高分辨率 Vision Transformer 骨干在人体姿态估计任务上的完整落地方式:包括其在 COCO val2017 上的官方指标、四套可用配置文件的逐段解读、HRFormer 源码级原理剖析,以及从训练到评估的实操命令。读完本文,你将能够独立读懂并复现基于 HRFormer 的 2D 人体姿态估计实验,并掌握在该仓库框架下替换骨干网络与调整训练细节的方法。
一、HRFormer 与 COCO:本文档涉及的算法与数据集
HRFormer(High-Resolution Vision Transformer for Dense Predict)是微软亚研院与中科院团队在 NIPS'2021 上发表的工作,其核心思路是把 HRNet 的多分支高分辨率并行结构保留下来,同时将传统卷积 Block 替换为带**局部窗口自注意力(Local-Window Self-Attention, LSA)**的 Transformer Block,从而在保持高分辨率特征表达的同时引入全局建模能力,面向分割、姿态估计等密集预测任务。
本仓库文档中给出了该算法的引用信息(hrformer_coco.md 头部):
@article{yuan2021hrformer,
title={HRFormer: High-Resolution Vision Transformer for Dense Predict},
author={Yuan, Yuhui and Fu, Rao and Huang, Lang and Lin, Weihong and Zhang, Chao and Chen, Xilin and Wang, Jingdong},
journal={Advances in Neural Information Processing Systems},
volume={34},
year={2021}
}
实验数据使用 COCO(Microsoft COCO: Common Objects in Context,ECCV'2014),其官方引用如下:
@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}
}
本文档对应的模型族在 ViTPose 仓库的 models/backbones/hrformer.py 中注册为 HRFormer 骨干,并被 TopDown 检测器与 TopdownHeatmapSimpleHead 头部组合使用。
二、官方结果指标:COCO val2017 上的性能基准
文档明确标注了评测前提:以下结果是在 COCO val2017 上、使用在 COCO val2017 上人体检测 AP 为 56.4 的检测器得到的(即 top-down 两阶段方案中检测框来自 COCO_val2017_detections_AP_H_56_person.json)。这与仓库各配置文件 data_cfg 中的 bbox_file 设置完全一致。
| Arch | Input Size | AP | AP⁵⁰ | AP⁷⁵ | AR | AR⁵⁰ | 权重文件(ckpt 文件名) |
|---|---|---|---|---|---|---|---|
| pose_hrformer_small(hrformer_small_coco_256x192.py) | 256x192 | 0.737 | 0.899 | 0.810 | 0.792 | 0.938 | hrformer_small_coco_256x192-b657896f_20220226.pth |
| pose_hrformer_small(hrformer_small_coco_384x288.py) | 384x288 | 0.755 | 0.906 | 0.822 | 0.805 | 0.941 | hrformer_small_coco_384x288-4b52b078_20220226.pth |
| pose_hrformer_base(hrformer_base_coco_256x192.py) | 256x192 | 0.753 | 0.907 | 0.821 | 0.806 | 0.943 | hrformer_base_coco_256x192-66cee214_20220226.pth |
上述数字同时被记录在 hrformer_coco.yml 的模型索引中,作为可检索、可核对的基准数据。可以观察到两个规律:
- 输入分辨率红利:same small 模型从 256x192 提升到 384x288,AP 从 0.737 涨到 0.755(+1.8 个百分点),说明高分辨率对姿态估计精度提升显著;
- 模型容量红利:在 256x192 输入下,base 相比 small 提升约 1.6 个百分点(0.737 → 0.753)。
文档还提供了配套的训练日志文件(.log.json),可用于对比训练曲线与复现过程。权重与日志的下载地址为 OpenMMLab 官方模型库,读者可在对应配置页中按文件名检索获取。
三、核心配置文件逐段解读:以 hrformer_small_coco_256x192.py 为例
hrformer_small_coco_256x192.py 是 HRFormer 在 COCO 上的最小规格训练配置,下面按逻辑分段说明。
3.1 全局运行与调度设置
_base_ = ['../../../../_base_/datasets/coco.py']
log_level = 'INFO'
load_from = None
resume_from = None
dist_params = dict(backend='nccl')
workflow = [('train', 1)]
checkpoint_config = dict(interval=5, create_symlink=False)
evaluation = dict(interval=10, metric='mAP', save_best='AP')
_base_继承 COCO 数据集的dataset_info(17 个关键点定义,见 configs/base/datasets/coco.py);checkpoint_config每 5 个 epoch 保存一次权重,evaluation每 10 个 epoch 用 mAP 指标评测一次,并将最优 AP 模型保存为 best;dist_params使用 NCCL 后端,支持多卡分布式训练。
3.2 优化器与学习率策略
optimizer = dict(
type='AdamW',
lr=5e-4,
betas=(0.9, 0.999),
weight_decay=0.01,
paramwise_cfg=dict(
custom_keys={'relative_position_bias_table': dict(decay_mult=0.)}))
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
关键细节:
- 优化器使用 AdamW,基础学习率 5e-4,权重衰减 0.01;
paramwise_cfg中把relative_position_bias_table(相对位置偏置表)的权重衰减置为 0。这是因为相对位置偏置是参数化位置编码,不应被 L2 正则约束,这也是 Transformer 训练中的常见实践;- 学习率采用 step 衰减策略,线性 warmup 500 步,warmup 比率为 0.001,在 170 和 200 epoch 处分别衰减,总训练 210 epoch;
- 四套 HRFormer 配置的学习率策略完全一致,直接复用即可。
3.3 通道配置与模型骨架
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])
norm_cfg = dict(type='SyncBN', requires_grad=True)
model = dict(
type='TopDown',
pretrained='https://download.openmmlab.com/mmpose/'
'pretrain_models/hrformer_small-09516375_20220226.pth',
backbone=dict(
type='HRFormer',
in_channels=3,
norm_cfg=norm_cfg,
extra=dict(
drop_path_rate=0.1,
with_rpe=False,
stage1=dict(
num_modules=1,
num_branches=1,
block='BOTTLENECK',
num_blocks=(2, ),
num_channels=(64, ),
num_heads=[2],
num_mlp_ratios=[4]),
stage2=dict(
num_modules=1,
num_branches=2,
block='HRFORMERBLOCK',
num_blocks=(2, 2),
num_channels=(32, 64),
num_heads=[1, 2],
mlp_ratios=[4, 4],
window_sizes=[7, 7]),
stage3=dict(
num_modules=4,
num_branches=3,
block='HRFORMERBLOCK',
num_blocks=(2, 2, 2),
num_channels=(32, 64, 128),
num_heads=[1, 2, 4],
mlp_ratios=[4, 4, 4],
window_sizes=[7, 7, 7]),
stage4=dict(
num_modules=2,
num_branches=4,
block='HRFORMERBLOCK',
num_blocks=(2, 2, 2, 2),
num_channels=(32, 64, 128, 256),
num_heads=[1, 2, 4, 8],
mlp_ratios=[4, 4, 4, 4],
window_sizes=[7, 7, 7, 7]))),
keypoint_head=dict(
type='TopdownHeatmapSimpleHead',
in_channels=32,
out_channels=channel_cfg['num_output_channels'],
num_deconv_layers=0,
extra=dict(final_conv_kernel=1, ),
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))
这段配置是理解 HRFormer 在本仓库落地的核心,需要重点掌握:
模型装配:检测器类型为 TopDown(定义见 mmpose/models/detectors/top_down.py),由 backbone(HRFormer)+ keypoint_head(TopdownHeatmapSimpleHead)构成,pretrained 指定了 ImageNet 预训练权重地址。
backbone 的 extra 结构:HRFormer 沿用 HRNet 的 4-stage 多分支架构(源码类 HRFormer(HRNet),见 mmpose/models/backbones/hrformer.py):
- stage1 仍使用传统
BOTTLENECK卷积块(1 个分支、64 通道),作为 stem; - stage2~stage4 全部换成
HRFORMERBLOCK,分支数从 2、3 递增到 4; - 每个 stage 的
num_heads(注意力头数)、mlp_ratios(FFN 扩展比)、window_sizes(LSA 窗口大小,默认为 7×7)均随分支数逐级扩大; drop_path_rate=0.1是随机深度(Stochastic Depth)的最大 drop path 比率——源码会按 stage 深度做线性插值分配(见 mmpose/models/backbones/hrformer.py);with_rpe=False表示本配置中 LSA 不启用相对位置偏置(该开关会传入WindowMSA,见 mmpose/models/backbones/hrformer.py)。
头部设计:TopdownHeatmapSimpleHead 的 in_channels=32 与 HRFormer 第一分支输出通道一致;num_deconv_layers=0 表示不做反卷积上采样,直接用 1×1 卷积(final_conv_kernel=1)从 1/4 分辨率特征图回归 17 通道热图——这是轻量化设计,也是 HRFormer 配置与经典 HRNet 配置(通常带 3 层 deconv)的显著区别。
损失函数:JointsMSELoss 配合 use_target_weight=True,对每个关键点按可见性加权计算 MSE 损失。
测试后处理:flip_test=True 开启水平翻转测试增强(将原图与翻转图的热图平均);post_process='default' 表示使用默认的坐标解码(基于最大响应位置及邻域调制);shift_heatmap=True 会在翻转融合时补偿像素偏移;modulate_kernel=11 为最大响应邻域调制核大小。
3.4 数据配置与数据管线
data_root = 'data/coco'
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=f'{data_root}/person_detection_results/'
'COCO_val2017_detections_AP_H_56_person.json',
)
image_size=[192, 256]表示输入为宽 192、高 256(W×H 顺序),对应heatmap_size=[48, 64]的 1/4 分辨率热图;use_gt_bbox=False表明评测时不使用真实标注框,而是使用检测框文件COCO_val2017_detections_AP_H_56_person.json(即文档所述 AP 56.4 的检测器输出),这保证了 top-down 流程的公平对比;soft_nms=False, nms_thr=1.0, oks_thr=0.9, vis_thr=0.2控制多人场景下的后处理阈值。
训练管线(train_pipeline)依次为:图像加载 → 随机翻转(0.5)→ 半身变换(num_joints_half_body=8, prob_half_body=0.3)→ 随机旋转缩放(rot_factor=40, scale_factor=0.5)→ 仿射变换 → 张量化和 ImageNet 归一化(mean=[0.485, 0.456, 0.406])→ 高斯热图生成(sigma=2)→ 收集样本。验证/测试管线则只保留加载、仿射、归一化与收集四个环节。数据声明中 samples_per_gpu=32、workers_per_gpu=2,验证与测试时 samples_per_gpu=64,并额外启用了 fp16 混合精度(fp16 = dict(loss_scale='dynamic'))。
四、从 small 到 base、从 256x192 到 384x288:四套配置的差异对照
仓库为该模型族提供了四套可直接运行的配置,除上述 small/256x192 外,还包括 hrformer_small_coco_384x288.py、hrformer_base_coco_256x192.py 与 hrformer_base_coco_384x288.py。它们之间的关键差异如下:
| 配置项 | small/256x192 | small/384x288 | base/256x192 | base/384x288 |
|---|---|---|---|---|
| stage2 通道 | (32, 64) | (32, 64) | (78, 156) | (78, 156) |
| stage4 通道 | (32, 64, 128, 256) | 同左 | (78, 156, 312, 624) | 同左 |
| stage2 注意力头数 | [1, 2] | [1, 2] | [2, 4] | [2, 4] |
| drop_path_rate | 0.1 | 0.1 | 0.2 | 0.3 |
| 预训练权重 | hrformer_small | 同左 | hrformer_base | 同左 |
| image_size / heatmap_size | 192x256 / 48x64 | 288x384 / 72x96 | 192x256 / 48x64 | 288x384 / 72x96 |
| 高斯 sigma(TopDownGenerateTarget) | 2 | 3 | 2 | 3 |
| modulate_kernel | 11 | 11 | 11 | 17 |
| 训练 samples_per_gpu | 32 | 32 | 32 | 8 |
| 预训练下载地址 | hrformer_small-09516375 | 同左 | hrformer_base-32815020 | 同左 |
值得注意的细节:
- base 版通道从 78 起步(而不是 small 的 32),并在 stage4 一路扩到 624 通道,相应注意力头数从 2 增至 16,因此容量显著大于 small;
- 384x288 输入下高斯 sigma 从 2 增大到 3,这是因为热图分辨率更高(72×96),需要更大的高斯核半径来生成合理的监督目标;
- base/384x288 的 drop_path_rate 最大(0.3),同时
modulate_kernel增大到 17,且训练 batch 缩小到samples_per_gpu=8(显存考量); - 四套配置的优化器、学习率策略(210 epoch、step [170,200])与 fp16 设置完全一致,便于横向对比。
五、HRFormer 骨干网络的源码级原理
5.1 类继承关系与注册
在 mmpose/models/backbones/hrformer.py 中,HRFormer 类继承自 HRNet(class HRFormer(HRNet)),通过 blocks_dict = {'BOTTLENECK': Bottleneck, 'HRFORMERBLOCK': HRFormerBlock} 实现两种 Block 的混用:第一层 stage 用卷积 Bottleneck,其余 stage 用 HRFormerBlock。整个 extra 配置与 HRNet 的 stage 定义方式一脉相承,保证了使用习惯上的平滑迁移。
5.2 HRFormerBlock:LSA + CrossFFN
HRFormerBlock 的前向逻辑(mmpose/models/backbones/hrformer.py)可概括为两个残差分支:
x = x + DropPath(LSA(LN1(x)))
x = x + DropPath(CrossFFN(LN2(x)))
- LSA(LocalWindowSelfAttention):将特征图按
window_size(默认 7×7)切成窗口,在窗口内做标准 multi-head self-attention。源码用 center-pad 处理边缘不整除的情况,并在with_rpe=True时叠加相对位置偏置(mmpose/models/backbones/hrformer.py); - CrossFFN:与常规 Transformer 的纯 MLP FFN 不同,HRFormer 的 FFN 在 1×1 升维卷积之后插入了一个 3×3 深度可分离卷积(
dw3x3),从而注入局部空间上下文,是 "high-resolution + transformer" 的关键设计(mmpose/models/backbones/hrformer.py)。
5.3 多分支融合与随机深度
HRFomerModule 继承 HRNet 的 HRModule,保留跨分支特征融合(_make_fuse_layers:低分辨率分支通过 1×1 卷积 + 双线性上采样向高分辨率分支融合,高分辨率分支通过 3×3 stride-2 卷积降采样),但受限于当前实现,HRFormerBlock 尚不支持分支内下采样(源码注释明确 "HRFormerBlock does not support down sample layer yet",见 mmpose/models/backbones/hrformer.py)。
随机深度方面,HRFormer.__init__ 会依据各 stage 深度计算线性递增的 drop path 概率列表,再逐 block 传入(mmpose/models/backbones/hrformer.py),这与配置中的 drop_path_rate 直接对应。
5.4 测试用例验证
仓库的单元测试 tests/test_backbones/test_hrformer.py 覆盖了:
HRFomerModule的多尺度/单尺度前向、单分支模块,以及num_blocks/num_channels/num_inchannels长度不匹配时的ValueError校验;HRFormer骨干整体前向:输入(1, 3, 64, 64)时输出 4 个多尺度特征((1, 32, 16, 16)至(1, 256, 2, 2)),并验证multiscale_output=False与with_rpe=False分支路径。
这些测试为配置修改提供了回归保障:任何对 extra 结构(如分支数、通道数)的改动若破坏一致性约束,都会在测试阶段被及时捕获。
六、训练、评估与部署实操
6.1 单卡/多卡训练
使用 tools/train.py 直接训练:
# 单卡训练 HRFormer-Small 256x192
python tools/train.py configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/hrformer_small_coco_256x192.py --work-dir work_dirs/hrformer_small_coco_256x192
多卡分布式训练使用仓库自带的 tools/dist_train.sh:
bash tools/dist_train.sh configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/hrformer_small_coco_256x192.py 8 --work-dir work_dirs/hrformer_small_coco_256x192
若需断点续训,可在配置中设置 resume_from 指向已有 checkpoint,或通过 --resume-from 参数指定。训练过程中每 5 个 epoch 保存一次 checkpoint,每 10 个 epoch 在 val2017 上以 mAP 评测并记录最优 AP 模型。
6.2 评估与推理
使用 tools/test.py 在验证集上复现文档中的指标:
python tools/test.py configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/hrformer_small_coco_256x192.py \
work_dirs/hrformer_small_coco_256x192/best_AP_epoch_210.pth \
--eval mAP
6.3 单图演示
配合 top-down 推理脚本可直接在单张图片上可视化关键点结果(详细用法见 demo/2d_human_pose_demo.md):
python demo/top_down_img_demo.py \
configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/hrformer_small_coco_256x192.py \
/path/to/hrformer_small_coco_256x192-b657896f_20220226.pth \
--img-root tests/data/coco/ --json-file tests/data/coco/test_coco.json \
--out-img-root vis_results
6.4 环境与数据准备
- 训练前需按 docs/zh_cn/install.md 安装 mmcv、mmpose 及相关依赖;
- COCO 数据需按 docs/zh_cn/data_preparation.md 组织为
data/coco/目录结构,并放置person_detection_results/COCO_val2017_detections_AP_H_56_person.json检测框文件(该文件即为文档中 "detector having human AP of 56.4" 所指的检测结果)。
七、小结
HRFormer 在 ViTPose 仓库中的落地遵循"HRNet 多分支高分辨率骨架 + 局部窗口自注意力 + 深度可分离 FFN"的组合范式,文档给出的三组官方基准(small/256x192、small/384x288、base/256x192)验证了其精度表现,而仓库提供的四套配置覆盖了规格(small/base)与输入分辨率(256x192/384x288)两个维度的组合,可直接复制运行。从源码层面看,HRFormer 的实现完整保留了 HRNet 的融合机制,并以内嵌 window_sizes、num_heads、mlp_ratios、drop_path_rate 等参数的方式把 Transformer 的调节自由度暴露给配置系统——读者修改这些参数即可在精度与计算量之间自由权衡。
引用本模型时,请使用上文给出的 HRFormer 与 COCO 的 bibtex 条目。