# 人体关键点检测产线使用教程 ## 1. 人体关键点检测产线介绍 人体关键点检测旨在通过识别和定位人体的特定关节和部位，来实现对人体姿态和动作的分析。该任务不仅需要在图像中检测出人体，还需要精确获取人体的关键点位置，如肩膀、肘部、膝盖等，从而进行姿态估计和行为识别。人体关键点检测广泛应用于运动分析、健康监测、动画制作和人机交互等场景。 PaddleX 的人体关键点检测产线是一个 Top-Down 方案，由行人检测和关键点检测两个模块组成，针对移动端设备优化，可精确流畅地在移动端设备上执行多人姿态估计任务。本产线同时提供了灵活的服务化部署方式，支持在多种硬件上使用多种编程语言调用。不仅如此，本产线也提供了二次开发的能力，您可以基于本产线在您自己的数据集上训练调优，训练后的模型也可以无缝集成。 人体关键点检测产线中包含了行人检测模块和人体关键点检测模块，有若干模型可供选择，您可以根据下边的 benchmark 数据来选择使用的模型。如您更考虑模型精度，请选择精度较高的模型，如您更考虑模型推理速度，请选择推理速度较快的模型，如您更考虑模型存储大小，请选择存储大小较小的模型。 > 推理耗时仅包含模型推理耗时，不包含前后处理耗时。
👉模型列表详情 行人检测模块：
模型 mAP(0.5:0.95) mAP(0.5) GPU推理耗时（ms）
[常规模式 / 高性能模式]		 CPU推理耗时（ms）
[常规模式 / 高性能模式]		 模型存储大小（MB） 介绍
PP-YOLOE-L_human 48.0 81.9 30.59 / 26.64 180.05 / 112.70 196.02 基于PP-YOLOE的行人检测模型
PP-YOLOE-S_human 42.5 77.9 10.26 / 6.66 54.01 / 23.48 28.79
人体关键点检测模块：
模型 方案 输入尺寸 AP(0.5:0.95) GPU推理耗时（ms）
[常规模式 / 高性能模式]		 CPU推理耗时（ms）
[常规模式 / 高性能模式]		 模型存储大小（MB） 介绍
PP-TinyPose_128x96 Top-Down 128*96 58.4 24.22 / 4.34 - / 6.19 4.9 PP-TinyPose 是百度飞桨视觉团队自研的针对移动端设备优化的实时关键点检测模型，可流畅地在移动端设备上执行多人姿态估计任务
PP-TinyPose_256x192 Top-Down 256*192 68.3 21.73 / 3.59 - / 10.18 4.9
测试环境说明:
模式 GPU配置 CPU配置 加速技术组合
常规模式 FP32精度 / 无TRT加速 FP32精度 / 8线程 PaddleInference
高性能模式 选择先验精度类型和加速策略的最优组合 FP32精度 / 8线程 选择先验最优后端（Paddle/OpenVINO/TRT等）
## 2. 快速开始 PaddleX 所提供的预训练的模型产线均可以快速体验效果，你可以在本地使用 Python 体验通用图像识别产线的效果。 ### 2.1 在线体验 暂不支持在线体验。 ### 2.2 本地体验 > ❗ 在本地使用人体关键点检测产线前，请确保您已经按照[PaddleX安装教程](../../../installation/installation.md)完成了PaddleX的wheel包安装。如果您希望选择性安装依赖，请参考安装教程中的相关说明。该产线对应的依赖分组为 `cv`。 #### 2.2.1 命令行方式体验 一行命令即可快速体验人体关键点检测产线效果，使用 [测试文件](https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/keypoint_detection_001.jpg)，并将 `--input` 替换为本地路径，进行预测 ```bash paddlex --pipeline human_keypoint_detection \ --input keypoint_detection_001.jpg \ --det_threshold 0.5 \ --save_path ./output/ \ --device gpu:0 ``` 相关参数和运行结果说明可以参考[2.2.2 Python脚本方式集成](#222-python脚本方式集成)中的参数说明和结果解释。支持同时指定多个设备以进行并行推理，详情请参考 [产线并行推理](../../instructions/parallel_inference.md#指定多个推理设备)。 可视化结果保存至`save_path`，如下所示： #### 2.2.2 Python脚本方式集成 通过上述命令行方式可快速体验查看效果，在项目中往往需要代码集成，您可以通过如下几行代码完成产线的快速推理： ```python from paddlex import create_pipeline pipeline = create_pipeline(pipeline="human_keypoint_detection") output = pipeline.predict("keypoint_detection_001.jpg", det_threshold=0.5) for res in output: res.print() res.save_to_img("./output/") res.save_to_json("./output/") ``` 在上述 Python 脚本中，执行了如下几个步骤： （1）调用 `create_pipeline` 实例化产线对象：具体参数说明如下：
参数 参数说明 参数类型 默认值
pipeline 产线名称或是产线配置文件路径。如为产线名称，则必须为 PaddleX 所支持的产线。 str None
config 产线具体的配置信息（如果和pipeline同时设置，优先级高于pipeline，且要求产线名和pipeline一致）。 dict[str, Any] None
device 产线推理设备。支持指定GPU具体卡号，如“gpu:0”，其他硬件具体卡号，如“npu:0”，CPU如“cpu”。支持同时指定多个设备以进行并行推理，详情请参考产线并行推理文档。 str gpu:0
use_hpip 是否启用高性能推理插件。如果为 None，则使用配置文件或 config 中的配置。 bool | None 无 None
hpi_config 高性能推理配置 dict | None 无 None
（2）调用人体关键点检测产线对象的 `predict()` 方法进行推理预测。该方法将返回一个 `generator`。以下是 `predict()` 方法的参数及其说明：
参数 参数说明 参数类型 可选项 默认值
input 待预测数据，支持多种输入类型，必需参数 Python Var|str|list
  • Python Var：如 numpy.ndarray 表示的图像数据
  • str：如图像文件的本地路径：/root/data/img.jpg；如URL链接，如图像文件的网络URL：示例；如本地目录，该目录下需包含待预测图像，如本地路径：/root/data/
  • List：列表元素需为上述类型数据，如[numpy.ndarray, numpy.ndarray]，[\"/root/data/img1.jpg\", \"/root/data/img2.jpg\"]，[\"/root/data1\", \"/root/data2\"]
 无
threshold 人体检测模型阈值 float|None
  • float：如0.5， 表示过滤掉所有阈值小于0.5的目标框；
  • None：如果设置为None, 将默认使用产线初始化的该参数值，初始化为0.5；
 None
（3）对预测结果进行处理，每个样本的预测结果均为对应的Result对象，且支持打印、保存为图片、保存为`json`文件的操作:
方法 方法说明 参数 参数类型 参数说明 默认值
print() 打印结果到终端 format_json bool 是否对输出内容进行使用 JSON 缩进格式化 True
indent int 指定缩进级别，以美化输出的 JSON 数据，使其更具可读性，仅当 format_json 为 True 时有效 4
ensure_ascii bool 控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时，所有非 ASCII 字符将被转义；False 则保留原始字符，仅当format_json为True时有效 False
save_to_json() 将结果保存为json格式的文件 save_path str 保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致 无
indent int 指定缩进级别，以美化输出的 JSON 数据，使其更具可读性，仅当 format_json 为 True 时有效 4
ensure_ascii bool 控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时，所有非 ASCII 字符将被转义；False 则保留原始字符，仅当format_json为True时有效 False
save_to_img() 将结果保存为图像格式的文件 save_path str 保存的文件路径，支持目录或文件路径 无
- 输出结果参数含义如下： - `input_path`：表示输入图像的路径 - `boxes`：检测到人体信息，一个字典列表，每个字典包含以下信息： - `coordinate`：人体目标框坐标，格式为[xmin, ymin, xmax, ymax] - `det_score`：人体目标框置信度 - `keypoints`：关键点坐标信息，一个numpy数组，形状为[num_keypoints, 3]，其中每个关键点由[x, y, score]组成，score为该关键点的置信度 - `kpt_score`：关键点整体的置信度，即关键点的平均置信度 - 调用`save_to_json()` 方法会将上述内容保存到指定的`save_path`中，如果指定为目录，则保存的路径为`save_path/{your_img_basename}_res.json`，如果指定为文件，则直接保存到该文件中。由于json文件不支持保存numpy数组，因此会将其中的`numpy.array`类型转换为列表形式。 - 调用`save_to_img()` 方法会将可视化结果保存到指定的`save_path`中，如果指定为目录，则保存的路径为`save_path/{your_img_basename}_res.{your_img_extension}`，如果指定为文件，则直接保存到该文件中。(产线通常包含较多结果图片，不建议直接指定为具体的文件路径，否则多张图会被覆盖，仅保留最后一张图) * 此外，也支持通过属性获取带结果的可视化图像和预测结果，具体如下：
属性 属性说明
json 获取预测的 json 格式的结果
img 获取格式为 dict 的可视化图像
- `json` 属性获取的预测结果为dict类型的数据，相关内容与调用 `save_to_json()` 方法保存的内容一致。 - `img` 属性返回的预测结果是一个字典类型的数据。键为 `res` ，对应的值是一个用于可视化人体关键点检测结果的 `Image.Image` 对象。 上述Python脚本集成方式默认使用 PaddleX 官方配置文件中的参数设置，若您需要自定义配置文件，可先执行如下命令获取官方配置文件，并保存在 `my_path` 中： ```bash paddlex --get_pipeline_config human_keypoint_detection --save_path ./my_path ``` 若您获取了配置文件，即可对人体关键点检测产线各项配置进行自定义。只需要修改 `create_pipeline` 方法中的 `pipeline` 参数值为自定义产线配置文件路径即可。 例如，若您的自定义配置文件保存在 `./my_path/human_keypoint_detection.yaml` ，则只需执行： ```python from paddlex import create_pipeline pipeline = create_pipeline(pipeline="./my_path/human_keypoint_detection.yaml") output = pipeline.predict("keypoint_detection_001.jpg") for res in output: res.print() res.save_to_img("./output/") res.save_to_json("./output/") ``` ## 3. 开发集成/部署 如果人体关键点检测产线可以达到您对产线推理速度和精度的要求，您可以直接进行开发集成/部署。 若您需要将通用图像识别产线直接应用在您的Python项目中，可以参考 [2.2.2 Python脚本方式](#222-python脚本方式集成)中的示例代码。 此外，PaddleX 也提供了其他三种部署方式，详细说明如下： 🚀 高性能推理：在实际生产环境中，许多应用对部署策略的性能指标（尤其是响应速度）有着较严苛的标准，以确保系统的高效运行与用户体验的流畅性。为此，PaddleX 提供高性能推理插件，旨在对模型推理及前后处理进行深度性能优化，实现端到端流程的显著提速，详细的高性能推理流程请参考[PaddleX高性能推理指南](../../../pipeline_deploy/high_performance_inference.md)。 ☁️ 服务化部署：服务化部署是实际生产环境中常见的一种部署形式。通过将推理功能封装为服务，客户端可以通过网络请求来访问这些服务，以获取推理结果。PaddleX 支持多种产线服务化部署方案，详细的产线服务化部署流程请参考[PaddleX服务化部署指南](../../../pipeline_deploy/serving.md)。 以下是基础服务化部署的API参考与多语言服务调用示例：
API参考

对于服务提供的主要操作：

名称 类型 含义
logId string 请求的UUID。
errorCode integer 错误码。固定为0。
errorMsg string 错误说明。固定为"Success"。
result object 操作结果。
名称 类型 含义
logId string 请求的UUID。
errorCode integer 错误码。与响应状态码相同。
errorMsg string 错误说明。

服务提供的主要操作如下：

对图像进行人体关键点检测。

POST /human-keypoint-detection

名称 类型 含义 是否必填
image string 服务器可访问的图像文件的URL或图像文件内容的Base64编码结果。 是
detThreshold number | null 人体检测模型阈值 否
visualize boolean | null 是否返回可视化结果图以及处理过程中的中间图像等。
  • 传入 true：返回图像。
  • 传入 false：不返回图像。
  • 若请求体中未提供该参数或传入 null：遵循产线配置文件Serving.visualize 的设置。

例如，在产线配置文件中添加如下字段：
Serving:
  visualize: False
将默认不返回图像，通过请求体中的visualize参数可以覆盖默认行为。如果请求体和配置文件中均未设置（或请求体传入null、配置文件中未设置），则默认返回图像。 		否
名称 类型 含义
image string 服务器可访问的图像文件的URL或图像文件内容的Base64编码结果。
persons array 人体关键点检测结果。

persons中的每个元素为一个object，具有如下属性：

名称 类型 含义
bbox array 目标位置。数组中元素依次为边界框左上角x坐标、左上角y坐标、右下角x坐标以及右下角y坐标。
kpts array 关键点坐标。
detScore number 检测得分。
kptScore number 关键点得分。
多语言调用服务示例
Python 
import base64
import requests

API_URL = "http://localhost:8080/human-keypoint-detection" # 服务URL
image_path = "./demo.jpg"
output_image_path = "./out.jpg"

# 对本地图像进行Base64编码
with open(image_path, "rb") as file:
    image_bytes = file.read()
    image_data = base64.b64encode(image_bytes).decode("ascii")

payload = {"image": image_data}  # Base64编码的文件内容或者图像URL

# 调用API
response = requests.post(API_URL, json=payload)

# 处理接口返回数据
assert response.status_code == 200
result = response.json()["result"]
with open(output_image_path, "wb") as file:
    file.write(base64.b64decode(result["image"]))
print(f"Output image saved at {output_image_path}")
print("\nDetected persons:")
print(result["persons"])

📱 端侧部署：端侧部署是一种将计算和数据处理功能放在用户设备本身上的方式，设备可以直接处理数据，而不需要依赖远程的服务器。PaddleX 支持将模型部署在 Android 等端侧设备上，详细的端侧部署流程请参考[PaddleX端侧部署指南](../../../pipeline_deploy/on_device_deployment.md)。 您可以根据需要选择合适的方式部署模型产线，进而进行后续的 AI 应用集成。 ## 4. 二次开发 如果人体关键点检测产线提供的默认模型权重在您的场景中精度或速度不满意，您可以尝试利用您自己拥有的特定领域或应用场景的数据对现有模型进行进一步的微调，以提升该产线的在您的场景中的识别效果。 ### 4.1 模型微调 由于人体关键点检测产线包含两个模块（行人检测模块和人体关键点检测模块），模型产线的效果不及预期可能来自于其中任何一个模块。 您可以对识别效果差的图片进行分析，如果在分析过程中发现有较多的行人目标未被检测出来，那么可能是行人检测模型存在不足，您需要参考[行人检测模块开发教程](https://paddlepaddle.github.io/PaddleX/latest/module_usage/tutorials/cv_modules/human_detection.html)中的二次开发章节，使用您的私有数据集对行人检测模型进行微调；如果在已检测到行人出现关键点检测错误，这表明关键点检测模型需要进一步改进，您需要参考[关键点检测模块开发教程](https://paddlepaddle.github.io/PaddleX/latest/module_usage/tutorials/cv_modules/human_keypoint_detection.html)中的二次开发章节,对关键点检测模型进行微调。 ### 4.2 模型应用 当您使用私有数据集完成微调训练后，可获得本地模型权重文件。 若您需要使用微调后的模型权重，只需对产线配置文件做修改，将微调后模型权重的本地路径替换至产线配置文件中的对应位置即可： ```yaml pipeline_name: human_keypoint_detection SubModules: ObjectDetection: module_name: object_detection model_name: PP-YOLOE-S_human model_dir: null #可修改为微调后行人检测模型的本地路径 batch_size: 1 threshold: null img_size: null KeypointDetection: module_name: keypoint_detection model_name: PP-TinyPose_128x96 model_dir: #可修改为微调后关键点检测模型的本地路径 batch_size: 1 flip: False use_udp: null ``` 随后， 参考[2.2 本地体验](#22-本地体验)中的命令行方式或Python脚本方式，加载修改后的产线配置文件即可。 ## 5. 多硬件支持 PaddleX 支持英伟达 GPU、昆仑芯 XPU、昇腾 NPU 和寒武纪 MLU 等多种主流硬件设备，仅需修改 `--device`参数即可完成不同硬件之间的无缝切换。 例如，使用昇腾 NPU 进行人体关键点检测产线快速推理： ```bash paddlex --pipeline human_keypoint_detection \ --input keypoint_detection_001.jpg \ --det_threshold 0.5 \ --save_path ./output/ \ --device npu:0 ``` 当然，您也可以在 Python 脚本中 `create_pipeline()` 时或者 `predict()` 时指定硬件设备。 若您想在更多种类的硬件上使用通用图像识别产线，请参考[PaddleX多硬件使用指南](../../../other_devices_support/multi_devices_use_guide.md)。