PaddleX 人体关键点检测模块实战指南：PP-TinyPose 模型推理与二次开发

• 人工智能
• 大模型
• 低代码
• 计算机视觉
• 深度学习
• NLP
• 模型推理服务
• RAG

人体关键点检测是计算机视觉的重要任务，通过定位人体关键点实现姿态估计、动作识别与人机交互。本文以飞桨 PaddleX 中的人体关键点检测模块（keypoint_detection）为核心，完整讲解 PP-TinyPose 系列模型的推理集成、结果解析、数据集校验、模型训练、评估与产线部署全流程，并深入剖析TopDown关键点检测方案的底层实现原理，帮助你在实际项目中快速落地人体姿态估计能力。

一、人体关键点检测任务与两种主流算法方案

人体关键点检测旨在识别图像或视频中人体的特定关键点位置。通过检测这些关键点，可以实现姿态估计、动作识别、人机交互、动画生成等多种应用，在增强现实、虚拟现实、运动捕捉等领域都有广泛的应用。

关键点检测算法主要包括Top-Down和Bottom-Up两种方案：

• Top-Down 方案：通常依赖一个目标检测算法识别出感兴趣物体的边界框，关键点检测模型的输入为经过裁剪的单个目标，输出为这个目标的关键点预测结果。该方案的准确率更高，但速度会随着对象数量的增加而变慢。
• Bottom-Up 方案：不依赖先进行目标检测，而是直接对整个图像进行关键点检测，然后对这些点进行分组或连接以形成多个姿势实例。其速度固定，不会随着物体数量的增加而变慢，但精度会更低。

PaddleX 人体关键点检测模块目前提供的是PP-TinyPose模型，采用 Top-Down 方案，是百度飞桨视觉团队自研的、针对移动端设备优化的实时关键点检测模型，可流畅地在移动端设备上执行多人姿态估计任务。

从仓库源码看，该模块的推理核心位于 inference/models/keypoint_detection/predictor.py 中的KptPredictor类，它继承自目标检测的DetPredictor，体现了 Top-Down 方案"先检测、再裁剪关键点估计"的天然依赖关系。模型清单在 modules/keypoint_detection/model_list.py 中定义：

MODELS = ["PP-TinyPose_128x96", "PP-TinyPose_256x192"]

二、支持模型列表与性能表现

PaddleX 人体关键点检测模块支持以下模型：

两个模型尺寸相同（约 4.9M），256x192 输入版本精度更高（AP 68.3），128x96 版本在 CPU 上延迟更低，适合移动端实时场景。

测试环境说明

• 性能测试环境：测试数据集为 COCO 数据集，指标为 AP(0.5:0.95)，所依赖的检测框为 ground truth 标注得到。
• 硬件配置：
  • GPU：NVIDIA Tesla T4
  • CPU：Intel Xeon Gold 6271C @ 2.60GHz
  • 其他环境：Ubuntu 20.04 / CUDA 11.8 / cuDNN 8.9 / TensorRT 8.6.1.6

推理模式说明

三、快速集成：几行代码完成关键点检测推理

❗ 在快速集成前，请先安装 PaddleX 的 wheel 包，详细请参考 PaddleX本地安装教程。

完成 wheel 包的安装后，几行代码即可完成人体关键点检测模块的推理，可以任意切换该模块下的模型，也可以将人体关键点检测模块中的模型推理集成到您的项目中。运行以下代码前，请先下载示例图片到本地。

from paddlex import create_model model = create_model(model_name="PP-TinyPose_128x96") output = model.predict("keypoint_detection_002.jpg", batch_size=1) for res in output: res.print() res.save_to_img("./output/") res.save_to_json("./output/")

运行后，得到的结果如下：

{'res': {'input_path': 'keypoint_detection_002.jpg', 'kpts': [{'keypoints': array([[175.28381 , 56.04361 , 0.6522829 ], [181.32794 , 49.64205 , 0.7338211 ], [169.46002 , 50.59111 , 0.68370765], [193.34212 , 51.919697 , 0.86765444], [164.50787 , 55.65199 , 0.8232859 ], [219.72359 , 90.2871 , 0.8812915 ], [152.90378 , 95.078064 , 0.9093066 ], [233.10957 , 149.67049 , 0.77069044], [139.55766 , 144.38327 , 0.75550145], [245.2283 , 202.4244 , 0.7065905 ], [117.837944 , 188.5641 , 0.8892116 ], [203.29543 , 200.2967 , 0.83833086], [172.00792 , 201.19939 , 0.7636936 ], [181.18797 , 273.06693 , 0.8719099 ], [185.175 , 278.47977 , 0.687819 ], [171.55069 , 362.4273 , 0.7994317 ], [201.69414 , 354.59534 , 0.67892176]], dtype=float32), 'kpt_score': 0.7831442}]}}

参数含义如下：

• input_path：输入的待预测图像的路径
• kpts：预测的关键点信息，一个字典列表。每个字典包含以下信息：
  • keypoints：关键点坐标信息，一个 numpy 数组，形状为[num_keypoints, 3]，其中每个关键点由[x, y, score]组成，score为该关键点的置信度
  • kpt_score：关键点整体的置信度，即关键点的平均置信度

PP-TinyPose 输出的是 COCO 17 点人体骨架，从结果中可以看到 17 行[x, y, score]坐标。可视化结果由 inference/models/keypoint_detection/result.py 中的draw_keypoints绘制，当检测到 17 个关键点时按 COCO 骨架拓扑连线，低置信度关键点（默认visual_thresh=0.1）会被跳过不绘制。

3.1create_model参数说明

create_model用于实例化人体关键点检测模型（此处以PP-TinyPose_128x96为例），具体说明如下：

其中，model_name必须指定，指定model_name后，默认使用 PaddleX 内置的模型参数，在此基础上指定model_dir时，使用用户自定义的模型。

值得深入理解的是flip参数（水平翻转测试）。在 predictor.py 中，KptPredictor定义了flip_perm左右关节交换列表（COCO 17 点中左右对称关键点的配对关系，如[1,2]、[3,4]等），推理时先将输入图像沿宽度方向翻转再次推理，再通过flip_back方法把翻转结果的各关节按flip_perm换回对称位置，并执行shift_heatmap的 1 像素偏移修正（PP-TinyPose 专属），最后与原始推理的 heatmap 取平均(output + output_flipped) * 0.5。因此开启flip会带来一次额外的翻转推理，精度更高但耗时翻倍。

3.2predict()方法参数说明

调用人体关键点检测模型的predict()方法进行推理预测，predict()方法参数有input和batch_size，具体说明如下：

底层的数据打批逻辑由 predictor.py 中的KptBatchSampler完成：它会自动处理 URL 下载、目录展开，并按batch_size切分为多个批次；与常规图像任务不同，关键点模块明确不支持 PDF 文件作为输入（PDF_SUFFIX = []）。

3.3 预测结果处理方法与属性

对预测结果进行处理，每个样本的预测结果均为对应的 Result 对象，且支持打印、保存为图片、保存为json文件的操作：

此外，也支持通过属性获取带结果的可视化图像和预测结果：

关于更多 PaddleX 的单模型推理 API 的使用方法，可以参考 PaddleX单模型Python脚本使用说明。

四、二次开发：数据校验、训练、评估与推理

如果你追求更高精度的现有模型，可以使用 PaddleX 的二次开发能力，开发更好的关键点检测模型。在使用 PaddleX 开发关键点检测模型之前，请务必安装 PaddleX 的 PaddleDetection 插件，安装过程可以参考 PaddleX本地安装教程。

4.1 数据准备

在进行模型训练前，需要准备相应任务模块的数据集。PaddleX 针对每一个模块提供了数据校验功能，只有通过数据校验的数据才可以进行模型训练。此外，PaddleX 为每一个模块都提供了 demo 数据集，你可以基于官方提供的 Demo 数据完成后续的开发。

4.1.1 Demo 数据下载

参考下面的命令将 Demo 数据集下载到指定文件夹：

cd /path/to/paddlex wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/keypoint_coco_examples.tar -P ./dataset tar -xf ./dataset/keypoint_coco_examples.tar -C ./dataset/

从数据校验源码 modules/keypoint_detection/dataset_checker/dataset_src/check_dataset.py 可以看出，关键点 Demo 数据集遵循 COCO 关键点格式：数据集根目录下必须存在annotations/instance_train.json与annotations/instance_val.json两个标注文件，图像放在images/目录下（二者缺一不可，否则校验会直接报错）。

4.1.2 数据校验

一行命令即可完成数据校验：

python main.py -c paddlex/configs/modules/keypoint_detection/PP-TinyPose_128x96.yaml \ -o Global.mode=check_dataset \ -o Global.dataset_dir=./dataset/keypoint_coco_examples

执行上述命令后，PaddleX 会对数据集进行校验，并统计数据集的基本信息，命令运行成功后会在 log 中打印出Check dataset passed !信息。校验结果文件保存在./output/check_dataset_result.json，同时相关产出会保存在当前目录的./output/check_dataset目录下，产出目录中包括可视化的示例样本图片和样本分布直方图。

校验结果文件具体内容为：

{ "done_flag": true, "check_pass": true, "attributes": { "num_classes": 1, "train_samples": 500, "train_sample_paths": [ "check_dataset/demo_img/000000560108.jpg", "check_dataset/demo_img/000000434662.jpg", "check_dataset/demo_img/000000540556.jpg", ... ], "val_samples": 100, "val_sample_paths": [ "check_dataset/demo_img/000000463730.jpg", "check_dataset/demo_img/000000085329.jpg", "check_dataset/demo_img/000000459153.jpg", ... ] }, "analysis": { "histogram": "check_dataset/histogram.png" }, "dataset_path": "keypoint_coco_examples", "show_type": "image", "dataset_type": "KeypointTopDownCocoDetDataset" }

上述校验结果中，check_pass为True表示数据集格式符合要求，其他部分指标的说明如下：

• attributes.num_classes：该数据集类别数为 1；
• attributes.train_samples：该数据集训练集样本数量为 500；
• attributes.val_samples：该数据集验证集样本数量为 100；
• attributes.train_sample_paths：该数据集训练集样本可视化图片相对路径列表；
• attributes.val_sample_paths：该数据集验证集样本可视化图片相对路径列表。

数据集校验还会对数据集中所有类别的样本数量分布情况进行分析，并绘制分布直方图（histogram.png）。从源码看，校验过程使用pycocotools解析 COCO 标注，统计每个集合的图片数量，并通过 dataset_src/utils/visualizer.py 中的draw_keypoint将标注的关键点渲染到示例图片上，输出到check_dataset/demo_img/目录供人工抽检。

4.1.3 数据集格式转换 / 数据集划分（可选）

在完成数据校验之后，可以通过修改配置文件或是追加超参数的方式对数据集的格式进行转换，也可以对数据集的训练/验证比例进行重新划分。

（1）数据集格式转换

关键点检测不支持数据格式转换。

（2）数据集划分

数据集划分的参数可以通过修改配置文件中CheckDataset下的字段进行设置，配置文件中部分参数的示例说明如下：

• CheckDataset:
  • split:
    • enable: 是否进行重新划分数据集，为True时进行数据集划分，默认为False；
    • train_percent: 如果重新划分数据集，则需要设置训练集的百分比，类型为 0-100 之间的任意整数，需要保证与val_percent的值之和为 100。

例如，你想重新划分数据集为训练集占比 90%、验证集占比 10%，则需将配置文件修改为：

...... CheckDataset: ...... split: enable: True train_percent: 90 val_percent: 10 ......

随后执行命令：

python main.py -c paddlex/configs/modules/keypoint_detection/PP-TinyPose_128x96.yaml \ -o Global.mode=check_dataset \ -o Global.dataset_dir=./dataset/keypoint_coco_examples

数据划分执行之后，原有标注文件会被在原路径下重命名为xxx.bak。

以上参数同样支持通过追加命令行参数的方式进行设置：

python main.py -c paddlex/configs/modules/keypoint_detection/PP-TinyPose_128x96.yaml \ -o Global.mode=check_dataset \ -o Global.dataset_dir=./dataset/keypoint_coco_examples \ -o CheckDataset.split.enable=True \ -o CheckDataset.split.train_percent=90 \ -o CheckDataset.split.val_percent=10

4.2 模型训练

一条命令即可完成模型的训练，以此处PP-TinyPose_128x96的训练为例：

python main.py -c paddlex/configs/modules/keypoint_detection/PP-TinyPose_128x96.yaml \ -o Global.mode=train \ -o Global.dataset_dir=./dataset/keypoint_coco_examples

需要如下几步：

• 指定模型的.yaml配置文件路径（此处为PP-TinyPose_128x96.yaml，训练其他模型时，需要指定相应的配置文件，模型和配置文件的对应关系可查阅 PaddleX模型列表（CPU/GPU））；
• 指定模式为模型训练：-o Global.mode=train；
• 指定训练数据集路径：-o Global.dataset_dir；
• 其他相关参数均可通过修改.yaml配置文件中的Global和Train下的字段来进行设置，也可以通过在命令行中追加参数来进行调整。如指定前 2 卡 GPU 训练：-o Global.device=gpu:0,1；设置训练轮次数为 10：-o Train.epochs_iters=10。更多可修改的参数及其详细解释，可以查阅模型对应任务模块的配置文件说明 PaddleX通用模型配置文件参数说明；
• 新特性：Paddle 3.0 版本支持了 CINN 神经网络编译器，在使用 GPU 设备训练时，不同模型有不同程度的训练加速效果。在 PaddleX 中训练模型时，可通过指定参数-o Train.dy2st=True开启。

训练过程中会自动保存模型权重文件，默认为output，如需指定保存路径，可通过配置文件中-o Global.output字段进行设置。PaddleX 对使用者屏蔽了动态图权重和静态图权重的概念：在模型训练的过程中会同时产出动态图和静态图的权重，在模型推理时默认选择静态图权重推理。

在完成模型训练后，所有产出保存在指定的输出目录（默认为./output/）下，通常有以下产出：

• train_result.json：训练结果记录文件，记录了训练任务是否正常完成，以及产出的权重指标、相关文件路径等；
• train.log：训练日志文件，记录了训练过程中的模型指标变化、loss 变化等；
• config.yaml：训练配置文件，记录了本次训练的超参数的配置；
• .pdparams、.pdopt、.pdiparams、.json：模型权重相关文件，包括网络参数、优化器、静态图网络参数、静态图网络结构等。

【注意】：Paddle 3.0.0 对于静态图网络结构信息的存储格式，由 protobuf（原.pdmodel后缀文件）升级为 json（现.json后缀文件），以兼容 PIR 体系，并获得更好的灵活性与扩展性。

训练配置详解（结合源码）

模块级配置文件 paddlex/configs/modules/keypoint_detection/PP-TinyPose_128x96.yaml 是二次开发的入口，其中Global、Train、Evaluate、Predict、Export各字段含义如下：

• Global：model（模型名）、mode（运行模式：check_dataset/train/evaluate/predict）、dataset_dir（数据集路径）、device（训练设备，默认gpu:0,1,2,3）、output（输出目录，默认output）；
• Train：num_classes（类别数，人体关键点为 1）、epochs_iters（训练轮数，默认 50）、batch_size（批大小，默认 16）、learning_rate（学习率，默认 0.001）、pretrain_weight_path（预训练权重）、warmup_steps（预热步数，默认 100）、resume_path（断点续训路径）、log_interval（日志间隔，默认 10）、eval_interval（评估间隔，默认 1）；
• Evaluate：weight_path（评估权重路径）、log_interval；
• Predict：batch_size、model_dir（推理模型目录）、input（预测输入，默认即为演示图片 URL）、kernel_option.run_mode（推理后端，默认paddle）；
• Export：weight_path（待导出权重路径）。

底层训练由 modules/keypoint_detection/trainer.py 中的KeypointTrainer完成，它继承自目标检测的DetTrainer，并将数据集以KeypointTopDownCocoDataset形式接入。真正的网络与训练超参定义在 PaddleDetection 插件配置 paddlex/repo_apis/PaddleDetection_api/configs/PP-TinyPose_128x96.yaml 中，从中可以看到：

• 网络架构为TopDownHRNet，backbone 为LiteHRNet（wider_naive结构，width=40），检测 17 个关节点（num_joints: 17），loss 采用KeyPointMSELoss；
• 热图尺寸为hmsize: [24, 32]，对应 128x96 输入缩放到 1/4 分辨率；
• 训练阶段的数据增强包含RandomFlipHalfBodyTransform（半身随机翻转，flip_pairs与推理时flip_perm保持一致）、AugmentationbyInformantionDropping（随机遮挡）、TopDownAffine（基于检测框的仿射裁剪）以及ToHeatmapsTopDown_DARK（DARK 格式热图标签，sigma: 1）；
• use_dark: true表示训练与推理均采用 DARK 关键点定位策略。

4.3 模型评估

在完成模型训练后，可以对指定的模型权重文件在验证集上进行评估，验证模型精度。使用 PaddleX 进行模型评估，一条命令即可完成：

python main.py -c paddlex/configs/modules/keypoint_detection/PP-TinyPose_128x96.yaml \ -o Global.mode=evaluate \ -o Global.dataset_dir=./dataset/keypoint_coco_examples

与模型训练类似，需要如下几步：

• 指定模型的.yaml配置文件路径（此处为PP-TinyPose_128x96.yaml）；
• 指定模式为模型评估：-o Global.mode=evaluate；
• 指定验证数据集路径：-o Global.dataset_dir。

其他相关参数均可通过修改.yaml配置文件中的Global和Evaluate下的字段来进行设置，详细请参考 PaddleX通用模型配置文件参数说明。

在模型评估时，需要指定模型权重文件路径，每个配置文件中都内置了默认的权重保存路径（output/best_model/best_model.pdparams），如需要改变，只需要通过追加命令行参数的形式进行设置即可，如-o Evaluate.weight_path=./output/best_model/best_model/model.pdparams。

在完成模型评估后，会产出evaluate_result.json，其记录了评估任务是否正常完成以及模型的评估指标（包含 AP）。从 modules/keypoint_detection/evaluator.py 的源码看，评估器KeypointEvaluator使用KeypointTopDownCocoDataset与KeyPointTopDownCOCOEval指标（即 COCO 关键点 AP 评估协议），并通过update_config将训练时的数据字段与评估权重注入底层配置。

4.4 模型推理

在完成模型的训练和评估后，即可使用训练好的模型权重进行推理预测。在 PaddleX 中实现模型推理预测可以通过两种方式：命令行和 wheel 包。

4.4.1 命令行推理

通过命令行的方式进行推理预测，只需如下一条命令。运行以下代码前，请先下载示例图片到本地。

python main.py -c paddlex/configs/modules/keypoint_detection/PP-TinyPose_128x96.yaml \ -o Global.mode=predict \ -o Predict.model_dir="./output/best_model/inference" \ -o Predict.input="keypoint_detection_002.jpg"

与模型训练和评估类似，需要如下几步：

• 指定模型的.yaml配置文件路径（此处为PP-TinyPose_128x96.yaml）；
• 指定模式为模型推理预测：-o Global.mode=predict；
• 指定模型权重路径：-o Predict.model_dir="./output/best_model/inference"；
• 指定输入数据路径：-o Predict.input="..."。

其他相关参数均可通过修改.yaml配置文件中的Global和Predict下的字段来进行设置，详细请参考 PaddleX通用模型配置文件参数说明。

4.4.2 模型集成

模型可以直接集成到 PaddleX 产线中，也可以直接集成到您自己的项目中。

1. 产线集成

人体关键点检测模块可以集成的 PaddleX 产线有人体关键点检测产线，只需要替换模型路径即可完成相关产线的人体关键点检测模块的模型更新。在产线集成中，你可以使用高性能部署和服务化部署来部署得到的模型。

产线配置示例见 paddlex/configs/pipelines/human_keypoint_detection.yaml：该产线由两个子模块串联构成——ObjectDetection子模块使用PP-YOLOE-S_human先做人检测（这也是 Top-Down 方案中的"检测器"环节），随后KeypointDetection子模块使用PP-TinyPose_128x96对每个人体框做关键点估计，并支持flip与use_udp等推理选项。

2. 模块集成

你产出的权重可以直接集成到人体关键点检测模块中，参考快速集成的 Python 示例代码，只需要将模型替换为你训练得到的模型路径即可：

from paddlex import create_model model = create_model(model_name="PP-TinyPose_128x96", model_dir="/path/to/your/model/inference") output = model.predict("your_image.jpg", batch_size=1)

五、关键点推理链路源码透视

为了帮助你更深入理解 PaddleX 关键点检测的完整推理链路，这里梳理 inference/models/keypoint_detection/ 目录下的三个核心文件的职责：

1. 预处理（TopDownAffine）：在 processors.py 中，TopDownAffine根据人体框的中心点center与尺度scale，通过仿射变换（warpAffine）将检测框区域裁剪并缩放到模型输入尺寸（如 128x96）。当use_udp=True时，使用get_warp_matrix计算无偏变换矩阵（UDP，CVPR 2020 论文方法），可进一步提升关键点定位精度。
2. 模型推理与水平翻转融合：在 predictor.py 中完成，模型输出的是每个关节点对应的 heatmap 热图（形状[batch, num_joints, H, W]），flip模式下会融合翻转推理结果。
3. 后处理（KptPostProcess）：在 processors.py 中，KptPostProcess首先从热图中取最大值位置得到粗关键点坐标（get_max_preds），然后默认启用 DARK 后处理（use_dark=True）：对热图做高斯模糊后取对数，再通过泰勒展开（dark_parse中的 Hessian 矩阵求极值偏移）得到亚像素级精确坐标，最后用transform_preds把坐标从模型空间映射回原图，得到最终的[x, y, score]结果与平均置信度kpt_score。

这一"仿射裁剪 → 热图回归 → DARK 亚像素精化 → 反变换回原图"的链路，正是 PP-TinyPose 在移动端也能保持较高定位精度的关键所在，也是理解后续对模型进行量化、裁剪等移动端优化的基础。

• 人工智能
• 大模型
• 低代码
• 计算机视觉
• 深度学习
• NLP
• 模型推理服务
• RAG