ViTPose 仓库 HRFormer 姿态估计配置全解析:基于 COCO 的 Top-Down Heatmap 训练与部署

原创2026-10-14 13:26:301,635 阅读
文章标签:人工智能计算机视觉深度学习机器学习

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 条目。

登录后查看全文
ViTPose