--- comments: true --- # 人脸识别产线使用教程 ## 1. 人脸识别产线介绍人脸识别任务是计算机视觉领域的重要组成部分，旨在通过分析和比较人脸特征，实现对个人身份的自动识别。该任务不仅需要检测图像中的人脸，还需要对人脸图像进行特征提取和匹配，从而在数据库中找到对应的身份信息。人脸识别广泛应用于安全认证、监控系统、社交媒体和智能设备等场景。人脸识别产线是专注于解决人脸定位和识别任务的端到端串联系统，可以从图像中快速准确地定位人脸区域、提取人脸特征，并与特征库中预先建立的特征做检索比对，从而确认身份信息。

人脸识别产线中包含了人脸检测模块和人脸特征模块，每个模块中包含了若干模型，具体使用哪些模型，您可以根据下边的 benchmark 数据来选择。如您更考虑模型精度，请选择精度较高的模型，如您更考虑模型推理速度，请选择推理速度较快的模型，如您更考虑模型存储大小，请选择存储大小较小的模型。

人脸检测模块：

模型	模型下载链接	AP (%) Easy/Medium/Hard	GPU推理耗时 (ms)	CPU推理耗时 (ms)	模型存储大小 (M)	介绍
BlazeFace	推理模型/训练模型	77.7/73.4/49.5	49.9	68.2	0.447	轻量高效的人脸检测模型
BlazeFace-FPN-SSH	推理模型/训练模型	83.2/80.5/60.5	52.4	73.2	0.606	BlazeFace的改进模型，增加FPN和SSH结构
PicoDet_LCNet_x2_5_face	推理模型/训练模型	93.7/90.7/68.1	33.7	185.1	28.9	基于PicoDet_LCNet_x2_5的人脸检测模型
PP-YOLOE_plus-S_face	推理模型/训练模型	93.9/91.8/79.8	25.8	159.9	26.5	基于PP-YOLOE_plus-S的人脸检测模型

注：以上精度指标是在WIDER-FACE验证集上，以640 *640作为输入尺寸评估得到的。所有模型 GPU 推理耗时基于 NVIDIA V100 机器，精度类型为 FP32， CPU 推理速度基于 Intel(R) Xeon(R) Gold 6271C CPU @ 2.60GHz，精度类型为 FP32。

人脸特征模块：

模型	模型下载链接	输出特征维度	Acc (%) AgeDB-30/CFP-FP/LFW	GPU推理耗时 (ms)	CPU推理耗时	模型存储大小 (M)	介绍
MobileFaceNet	推理模型/训练模型	128	96.28/96.71/99.58	5.7	101.6	4.1	基于MobileFaceNet在MS1Mv3数据集上训练的人脸特征提取模型
ResNet50_face	推理模型/训练模型	512	98.12/98.56/99.77	8.7	200.7	87.2	基于ResNet50在MS1Mv3数据集上训练的人脸特征提取模型

注：以上精度指标是分别在 AgeDB-30、CFP-FP 和 LFW 数据集上测得的 Accuracy。所有模型 GPU 推理耗时基于 NVIDIA Tesla T4 机器，精度类型为 FP32， CPU 推理速度基于 Intel(R) Xeon(R) Gold 5117 CPU @ 2.00GHz，线程数为8，精度类型为 FP32。

## 2. 快速开始 PaddleX 所提供的预训练的模型产线均可以快速体验效果，你可以在线体验人脸识别产线的效果，也可以在本地使用命令行或 Python 体验人脸识别产线的效果。 ### 2.1 在线体验暂不支持在线体验 ### 2.2 本地体验 > ❗ 在本地使用人脸识别产线前，请确保您已经按照[PaddleX安装教程](../../../installation/installation.md)完成了PaddleX的wheel包安装。 #### 2.2.1 命令行方式体验暂不支持命令行体验默认使用内置的的通用图像识别产线配置文件，若您需要自定义配置文件，可执行如下命令获取：

👉点击展开

paddlex --get_pipeline_config face_recognition

执行后，通用图像识别产线配置文件将被保存在当前路径。若您希望自定义保存位置，可执行如下命令（假设自定义保存位置为./my_path）：

paddlex --get_pipeline_config face_recognition --save_path ./my_path

#### 2.2.2 Python脚本方式集成请下载[测试图像](https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/friends1.jpg)进行测试。在该产线的运行示例中需要预先构建人脸特征库，您可以参考如下指令下载官方提供的demo数据用来后续构建人脸特征库。您可以参考下面的命令将 Demo 数据集下载到指定文件夹： ```bash cd /path/to/paddlex wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/face_demo_gallery.tar tar -xf ./face_demo_gallery.tar ``` 若您希望用私有数据集建立人脸特征库，可以参考[2.3节构建特征库的数据组织方式](#23-构建特征库的数据组织方式)。之后通过几行代码即可完成人脸特征库建立和人脸识别产线的快速推理。 ```python from paddlex import create_pipeline pipeline = create_pipeline(pipeline="face_recognition") index_data = pipeline.build_index(gallery_imgs="face_demo_gallery", gallery_label="face_demo_gallery/gallery.txt") index_data.save("face_index") output = pipeline.predict("friends1.jpg", index=index_data) for res in output: res.print() res.save_to_img("./output/") ``` 在上述 Python 脚本中，执行了如下几个步骤：（1）实例化 `create_pipeline` 实例化人脸识别产线对象。具体参数说明如下：

参数	参数说明	参数类型	默认值
`pipeline`	产线名称或是产线配置文件路径。如为产线名称，则必须为 PaddleX 所支持的产线。	`str`	无
`index`	产线推理预测所用的特征库，支持：1. `str`类型表示的目录（该目录下需要包含索引库文件，包括`vector.index`和`index_info.yaml`）；2. `IndexData`对象。如不传入该参数，则需要在`predict()`中指定`index`。	`str`	None
`device`	产线模型推理设备。支持：“gpu”，“cpu”。	`str`	`gpu`
`use_hpip`	是否启用高性能推理，仅当该产线支持高性能推理时可用。	`bool`	`False`

（2）调用人脸识别产线对象的 `build_index` 方法，构建人脸特征库。具体参数为说明如下：

参数	参数说明	参数类型	默认值
`gallery_imgs`	要添加的底库图片，支持：1. `str`类型表示的图片根目录，数据组织方式与构建索引库时相同，参考2.3节构建特征库的数据组织方式；2. `[numpy.ndarray, numpy.ndarray, ..]`类型的底库图片数据。	`str`\|`list`	无
`gallery_label`	底库图片的标注信息，支持：1. `str`类型表示的标注文件的路径，数据组织方式与构建特征库时相同，参考2.3节构建特征库的数据组织方式；2. `[str, str, ..]`类型表示的底库图片标注。	`str`	无

特征库对象 `index` 支持 `save` 方法，用于将特征库保存到磁盘：

参数	参数说明	参数类型	默认值
`save_path`	特征库文件的保存目录，如`drink_index`。	`str`	无

（3）调用人脸识别产线对象的 `predict` 方法进行推理预测：`predict` 方法参数为`input`，用于输入待预测数据，支持多种输入方式，具体示例如下：

参数类型	参数说明
Python Var	支持直接传入Python变量，如numpy.ndarray表示的图像数据。
str	支持传入待预测数据文件路径，如图像文件的本地路径：`/root/data/img.jpg`。
str	支持传入待预测数据文件URL，如图像文件的网络URL：示例。
str	支持传入本地目录，该目录下需包含待预测数据文件，如本地路径：`/root/data/`。
dict	支持传入字典类型，字典的key需与具体任务对应，如图像分类任务对应\"img\"，字典的val支持上述类型数据，例如：`{\"img\": \"/root/data1\"}`。
list	支持传入列表，列表元素需为上述类型数据，如`[numpy.ndarray, numpy.ndarray]，[\"/root/data/img1.jpg\", \"/root/data/img2.jpg\"]`，`[\"/root/data1\", \"/root/data2\"]`，`[{\"img\": \"/root/data1\"}, {\"img\": \"/root/data2/img.jpg\"}]`。

另外，`predict`方法支持参数`index`用于设置索引库：

参数类型	参数说明
`index`	产线推理预测所用的特征库，支持：1. `str`类型表示的目录（该目录下需要包含特征库文件，包括`vector.index`和`index_info.yaml`）；2. `IndexData`对象。如不传入该参数，则默认使用在`create_pipeline()`中通过参数`index`指定的特征库。

（4）调用`predict`方法获取预测结果：`predict` 方法为`generator`，因此需要通过调用获得预测结果，`predict`方法以batch为单位对数据进行预测。（5）对预测结果进行处理：每个样本的预测结果均为`dict`类型，且支持打印，或保存为文件，支持保存的类型与具体产线相关，如：

方法	说明	方法参数
print	打印结果到终端	`- format_json`：bool类型，是否对输出内容进行使用json缩进格式化，默认为True； `- indent`：int类型，json格式化设置，仅当format_json为True时有效，默认为4； `- ensure_ascii`：bool类型，json格式化设置，仅当format_json为True时有效，默认为False；
save_to_json	将结果保存为json格式的文件	`- save_path`：str类型，保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致； `- indent`：int类型，json格式化设置，默认为4； `- ensure_ascii`：bool类型，json格式化设置，默认为False；
save_to_img	将结果保存为图像格式的文件	`- save_path`：str类型，保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致；

若您获取了配置文件，即可对人脸识别产线各项配置进行自定义，只需要修改 `create_pipeline` 方法中的 `pipeline` 参数值为产线配置文件路径即可。例如，若您的配置文件保存在 `./my_path/face_recognition.yaml` ，则只需执行： ```python from paddlex import create_pipeline pipeline = create_pipeline(pipeline="./my_path/face_recognition.yaml", index="face_index") output = pipeline.predict("friends1.jpg") for res in output: res.print() res.save_to_img("./output/") ``` #### 2.2.3 人脸特征库的添加和删除操作若您希望将更多的人脸图像添加到特征库中，则可以调用 `append_index` 方法；删除人脸图像特征，则可以调用 `remove_index` 方法。 ```python from paddlex import create_pipeline pipeline = create_pipeline(pipeline="face_recognition") index_data = pipeline.build_index(gallery_imgs="face_demo_gallery", gallery_label="face_demo_gallery/gallery.txt", index_type="IVF", metric_type="IP") index_data = pipeline.append_index(gallery_imgs="face_demo_gallery", gallery_label="face_demo_gallery/gallery.txt", index=index_data) index_data = pipeline.remove_index(remove_ids="face_demo_gallery/remove_ids.txt", index=index_data) index_data.save("face_index") ``` 上述方法参数说明如下：

参数	参数说明	参数类型	默认值
`gallery_imgs`	要添加的底库图片，支持：1. `str`类型表示的图片根目录，数据组织方式与构建索引库时相同，参考2.3节构建特征库的数据组织方式；2. `[numpy.ndarray, numpy.ndarray, ..]`类型的底库图片数据。	`str`\|`list`	无
`gallery_label`	底库图片的标注信息，支持：1. `str`类型表示的标注文件的路径，数据组织方式与构建特征库时相同，参考2.3节构建特征库的数据组织方式；2. `[str, str, ..]`类型表示的底库图片标注。	`str`\|`list`	无
`remove_ids`	待删除的索引序号，支持：1. `str`类型表示的txt文件的路径，内容为待删除的索引id，每行一个“id”；2. `[int, int, ..]`类型表示的待删除的索引序号。仅在 `remove_index` 中有效。	`str`\|`list`	无
`index`	特征库，支持：1. 特征库文件（`vector.index`和`index_info.yaml`）所在目录的路径；2. `IndexData`类型的特征库对象，仅在 `append_index` 和 `remove_index` 中有效，表示待修改的特征库。	`str`\|`IndexData`	无
`index_type`	支持 `HNSW32`、`IVF`、`Flat`。其中，`HNSW32` 检索速度较快且精度较高，但不支持 `remove_index()` 操作；`IVF` 检索速度较快但精度相对较低，支持 `append_index()` 和 `remove_index()` 操作；`Flat` 检索速度较低精度较高，支持 `append_index()` 和 `remove_index()` 操作。	`str`	`HNSW32`
`metric_type`	支持：`IP`，内积（Inner Product）；`L2`，欧几里得距离（Euclidean Distance）。	`str`	`IP`

### 2.3 构建特征库的数据组织方式 PaddleX的人脸识别产线示例需要使用预先构建好的特征库进行人脸特征检索。如果您希望用私有数据构建人脸特征库，则需要按照如下方式组织数据： ```bash data_root # 数据集根目录，目录名称可以改变 ├── images # 图像的保存目录，目录名称可以改变 │ ├── ID0 # 身份ID名字，最好是有意义的名字，比如人名 │ │ ├── xxx.jpg # 图片，此处支持层级嵌套 │ │ ├── xxx.jpg # 图片，此处支持层级嵌套 │ │ ... │ ├── ID1 # 身份ID名字，最好是有意义的名字，比如人名 │ │ ├── xxx.jpg # 图片，此处支持层级嵌套 │ │ ├── xxx.jpg # 图片，此处支持层级嵌套 │ │ ... │ ... └── gallery.txt # 特征库数据集标注文件，文件名称可以改变。每行给出待检索人脸图像路径和图像标签，使用空格分隔，内容举例：images/Chandler/Chandler00037.jpg Chandler ``` ## 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参考

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

HTTP请求方法为POST。
请求体和响应体均为JSON数据（JSON对象）。
当请求处理成功时，响应状态码为200，响应体的属性如下：

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

当请求处理未成功时，响应体的属性如下：

名称	类型	含义
`logId`	`string`	请求的UUID。
`errorCode`	`integer`	错误码。与响应状态码相同。
`errorMsg`	`string`	错误说明。

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

buildIndex

构建特征向量索引。

POST /face-recognition-index-build

请求体的属性如下：

名称	类型	含义	是否必填
`imageLabelPairs`	`array`	用于构建索引的图像-标签对。	是

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

名称	类型	含义
`image`	`string`	服务器可访问的图像文件的URL或图像文件内容的Base64编码结果。
`label`	`string`	标签。

请求处理成功时，响应体的result具有如下属性：

名称	类型	含义
`indexKey`	`string`	索引对应的键，用于标识建立的索引。可用作其他操作的输入。
`idMap`	`object`	向量ID到标签的映射。

addImagesToIndex

将图像（对应的特征向量）加入索引。

POST /face-recognition-index-add

请求体的属性如下：

名称	类型	含义	是否必填
`imageLabelPairs`	`array`	用于构建索引的图像-标签对。	是
`indexKey`	`string`	索引对应的键。由`buildIndex`操作提供。	否

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

名称	类型	含义
`image`	`string`	服务器可访问的图像文件的URL或图像文件内容的Base64编码结果。
`label`	`string`	标签。

请求处理成功时，响应体的result具有如下属性：

名称	类型	含义
`idMap`	`object`	向量ID到标签的映射。

removeImagesFromIndex

从索引中移除图像（对应的特征向量）。

POST /face-recognition-index-remove

请求体的属性如下：

名称	类型	含义	是否必填
`ids`	`array`	需要从索引中移除的向量的ID。	是
`indexKey`	`string`	索引对应的键。由`buildIndex`操作提供。	否

请求处理成功时，响应体的result具有如下属性：

名称	类型	含义
`idMap`	`object`	向量ID到标签的映射。

infer

进行图像识别。

POST /face-recognition-infer

请求体的属性如下：

名称	类型	含义	是否必填
`image`	`string`	服务器可访问的图像文件的URL或图像文件内容的Base64编码结果。	是
`indexKey`	`string`	索引对应的键。由`buildIndex`操作提供。	否

请求处理成功时，响应体的result具有如下属性：

名称	类型	含义
`faces`	`array`	检测到的人脸的信息。
`image`	`string`	识别结果图。图像为JPEG格式，使用Base64编码。

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

名称	类型	含义
`bbox`	`array`	人脸目标位置。数组中元素依次为边界框左上角x坐标、左上角y坐标、右下角x坐标以及右下角y坐标。
`recResults`	`array`	识别结果。
`score`	`number`	检测得分。

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

名称	类型	含义
`label`	`string`	标签。
`score`	`number`	识别得分。

多语言调用服务示例

Python

import base64
import pprint
import sys

import requests

API_BASE_URL = "http://0.0.0.0:8080"

base_image_label_pairs = [
    {"image": "./demo0.jpg", "label": "ID0"},
    {"image": "./demo1.jpg", "label": "ID1"},
    {"image": "./demo2.jpg", "label": "ID2"},
]
image_label_pairs_to_add = [
    {"image": "./demo3.jpg", "label": "ID2"},
]
ids_to_remove = [1]
infer_image_path = "./demo4.jpg"
output_image_path = "./out.jpg"

for pair in base_image_label_pairs:
    with open(pair["image"], "rb") as file:
        image_bytes = file.read()
        image_data = base64.b64encode(image_bytes).decode("ascii")
    pair["image"] = image_data

payload = {"imageLabelPairs": base_image_label_pairs}
resp_index_build = requests.post(f"{API_BASE_URL}/face-recognition-index-build", json=payload)
if resp_index_build.status_code != 200:
    print(f"Request to face-recognition-index-build failed with status code {resp_index_build}.")
    pprint.pp(resp_index_build.json())
    sys.exit(1)
result_index_build = resp_index_build.json()["result"]
print(f"Number of images indexed: {len(result_index_build['idMap'])}")

for pair in image_label_pairs_to_add:
    with open(pair["image"], "rb") as file:
        image_bytes = file.read()
        image_data = base64.b64encode(image_bytes).decode("ascii")
    pair["image"] = image_data

payload = {"imageLabelPairs": image_label_pairs_to_add, "indexKey": result_index_build["indexKey"]}
resp_index_add = requests.post(f"{API_BASE_URL}/face-recognition-index-add", json=payload)
if resp_index_add.status_code != 200:
    print(f"Request to face-recognition-index-add failed with status code {resp_index_add}.")
    pprint.pp(resp_index_add.json())
    sys.exit(1)
result_index_add = resp_index_add.json()["result"]
print(f"Number of images indexed: {len(result_index_add['idMap'])}")

payload = {"ids": ids_to_remove, "indexKey": result_index_build["indexKey"]}
resp_index_remove = requests.post(f"{API_BASE_URL}/face-recognition-index-remove", json=payload)
if resp_index_remove.status_code != 200:
    print(f"Request to face-recognition-index-remove failed with status code {resp_index_remove}.")
    pprint.pp(resp_index_remove.json())
    sys.exit(1)
result_index_remove = resp_index_remove.json()["result"]
print(f"Number of images indexed: {len(result_index_remove['idMap'])}")

with open(infer_image_path, "rb") as file:
    image_bytes = file.read()
    image_data = base64.b64encode(image_bytes).decode("ascii")

payload = {"image": image_data, "indexKey": result_index_build["indexKey"]}
resp_infer = requests.post(f"{API_BASE_URL}/face-recognition-infer", json=payload)
if resp_infer.status_code != 200:
    print(f"Request to face-recogntion-infer failed with status code {resp_infer}.")
    pprint.pp(resp_infer.json())
    sys.exit(1)
result_infer = resp_infer.json()["result"]

with open(output_image_path, "wb") as file:
    file.write(base64.b64decode(result_infer["image"]))
print(f"Output image saved at {output_image_path}")
print("\nDetected faces:")
pprint.pp(result_infer["faces"])

📱 端侧部署：端侧部署是一种将计算和数据处理功能放在用户设备本身上的方式，设备可以直接处理数据，而不需要依赖远程的服务器。PaddleX 支持将模型部署在 Android 等端侧设备上，详细的端侧部署流程请参考[PaddleX端侧部署指南](../../../pipeline_deploy/edge_deploy.md)。您可以根据需要选择合适的方式部署模型产线，进而进行后续的 AI 应用集成。 ## 4. 二次开发如果人脸识别产线提供的默认模型权重在您的场景中，精度或速度不满意，您可以尝试利用您自己拥有的特定领域或应用场景的数据对现有模型进行进一步的微调，以提升通用该产线的在您的场景中的识别效果。 ### 4.1 模型微调由于人脸识别产线包含两个模块（人脸检测和人脸特征），模型产线的效果不及预期可能来自于其中任何一个模块。您可以对识别效果差的图片进行分析，如果在分析过程中发现有较多的人脸未被检测出来，那么可能是人脸检测模型存在不足，您需要参考[人脸检测模块开发教程](../../../module_usage/tutorials/cv_modules/face_detection.md)中的[二次开发](../../../module_usage/tutorials/cv_modules/face_detection.md#四二次开发)章节，使用您的私有数据集对人脸检测模型进行微调；如果在已检测到的人脸出现匹配错误，这表明人脸特征模块需要进一步改进，您需要参考[人脸特征模块开发教程](../../../module_usage/tutorials/cv_modules/face_feature.md)中的[二次开发](../../../module_usage/tutorials/cv_modules/face_feature.md#四二次开发)章节,对人脸特征模块进行微调。 ### 4.2 模型应用当您使用私有数据集完成微调训练后，可获得本地模型权重文件。若您需要使用微调后的模型权重，只需对产线配置文件做修改，将微调后模型权重的本地路径替换至产线配置文件中的对应位置即可： ```bash ...... Pipeline: device: "gpu:0" det_model: "BlazeFace" #可修改为微调后人脸检测模型的本地路径 rec_model: "MobileFaceNet" #可修改为微调后人脸特征模型的本地路径 det_batch_size: 1 rec_batch_size: 1 device: gpu ...... ``` 随后，参考[2.2 本地体验](#22-本地体验)中的命令行方式或Python脚本方式，加载修改后的产线配置文件即可。注：目前暂不支持为人脸检测和人脸特征模型设置单独的batch_size。 ## 5. 多硬件支持 PaddleX 支持英伟达 GPU、昆仑芯 XPU、昇腾 NPU和寒武纪 MLU 等多种主流硬件设备，仅需修改 `--device`参数即可完成不同硬件之间的无缝切换。例如，使用Python运行人脸识别产线时，将运行设备从英伟达 GPU 更改为昇腾 NPU，仅需将脚本中的 `device` 修改为 npu 即可： ```python from paddlex import create_pipeline pipeline = create_pipeline( pipeline="face_recognition", device="npu:0" # gpu:0 --> npu:0 ) ``` 若您想在更多种类的硬件上使用人脸识别产线，请参考[PaddleX多硬件使用指南](../../../other_devices_support/multi_devices_use_guide.md)。