PaddleX 3.0 Face Recognition Pipeline: End-to-End Cartoon Face Recognition via Detection and Feature Model Fine-Tuning
PaddleX 3.0 Face Recognition Pipeline: End-to-End Cartoon Face Recognition via Detection and Feature Model Fine-Tuning
本教程以"卡通人脸识别"这一典型跨域场景为主线,完整演示 PaddleX 3.0 人脸识别 Pipeline(Face Recognition Pipeline)的使用流程:从快速体验官方预训练模型,到构建/维护人脸特征库,再到用卡通数据分别微调人脸检测模型与人脸特征模型,最后把微调后的模型集成回 Pipeline 并完成服务化部署。读者学完后,将掌握 create_pipeline、build_index/append_index/remove_index 等核心 API 的用法,以及 main.py 命令行训练、评估、预测和 paddlex --serve 部署的完整实战方案。
1. 先选定 Pipeline:人脸识别任务对应哪个工具?
PaddleX 提供丰富的模型 Pipeline,每个 Pipeline 由一个或多个模型组合而成,面向特定场景解决特定任务问题。所有 Pipeline 均支持快速体验;当效果不满足预期时,还可以用私有数据对模型进行微调,并通过 Python API 将 Pipeline 轻松集成进个人项目。使用前需要先安装 PaddleX,安装方法请参考 PaddleX 安装指南。
针对"人脸识别"这一任务场景,对应的工具就是 Face Recognition Pipeline。如果不确定任务与 Pipeline 之间的对应关系,可以查阅 PaddleX 支持的 Pipeline 列表 了解各 Pipeline 的能力边界。
从源码实现看,Face Recognition Pipeline 在推理侧由检测子模型与特征子模型串联而成:FaceRecPipeline 继承自 ShiTuV2Pipeline(检索式识别架构),推理时先由检测模型输出人脸框,再按框裁剪出人脸图像送入特征模型提取特征向量,最后用向量索引(Faiss)完成 TopK 检索,参见 pipeline.py 与 pp_shitu_v2/pipeline.py。Pipeline 的默认配置见 face_recognition.yaml,其中 det_threshold(检测阈值)、rec_threshold(检索阈值)、rec_topk(返回候选数)等参数都可在配置中直接调整。
2. 快速体验:先跑通官方预训练模型
PaddleX Face Recognition Pipeline 官方提供的模型权重基于真实人脸数据训练。因此先用真实人脸演示数据集体验,再切换到卡通人脸数据对比效果,从而判断是否需要二次开发。
2.1 真实人脸数据本地体验
(1) 下载真实人脸演示数据集并解压到本地目录:
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/face_demo_gallery.tar
tar -xf ./face_demo_gallery.tar
(2) 执行 Python 脚本进行图像推理:
from paddlex import create_pipeline
# 创建人脸识别 pipeline
pipeline = create_pipeline(pipeline="face_recognition")
# 构建真实人脸特征库
index_data = pipeline.build_index(gallery_imgs="face_demo_gallery", gallery_label="face_demo_gallery/gallery.txt")
# 图像预测
output = pipeline.predict("face_demo_gallery/test_images/friends1.jpg", index=index_data)
for res in output:
res.print()
res.save_to_img("./output/") # 保存可视化结果图
build_index 会读取图库目录与标注文件,逐张提取人脸特征并构建索引,返回的 index_data 可直接传给 predict;predict 返回的每个 res 支持 print() 打印结构化结果与 save_to_img() 保存可视化图片。
2.2 卡通人脸数据本地体验
(1) 下载卡通人脸演示数据集并解压:
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/cartoonface_demo_gallery.tar
tar -xf ./cartoonface_demo_gallery.tar
(2) 执行 Python 脚本进行图像推理:
from paddlex import create_pipeline
# 创建人脸识别 pipeline
pipeline = create_pipeline(pipeline="face_recognition")
# 构建卡通人脸特征索引
index_data = pipeline.build_index(gallery_imgs="cartoonface_demo_gallery", gallery_label="cartoonface_demo_gallery/gallery.txt")
# 图像预测
output = pipeline.predict("cartoonface_demo_gallery/test_images/cartoon_demo.jpg", index=index_data)
for res in output:
res.print()
res.save_to_img("./output/") # 保存可视化结果图
2.3 体验后评估:是否需要微调?
体验完 Pipeline 后,需要判断 Pipeline 是否满足预期(包括精度、速度等),以及其中包含的模型是否需要进一步微调。如果模型的速度或精度不满足预期,应先更换候选模型继续测试,看结果是否令人满意;如果最终结果仍不理想,再对模型进行微调。
本教程的目标是卡通人脸识别。从快速体验结果可以观察到:官方默认模型在真实人脸场景下表现良好,但在推理卡通数据时无法满足实际应用需求,出现卡通人脸漏检(missed detections)与人脸误识别(misidentifications)。因此需要开展二次开发,对人脸检测模型与人脸特征模型分别进行训练微调。
3. 人脸特征库的构建
特征库的质量直接决定人脸识别的最终效果,本部分介绍数据组织方式与特征库构建 API。
3.1 数据准备
本教程以官方真实人脸演示数据集为例,下载并解压即可:
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/face_demo_gallery.tar
tar -xf ./face_demo_gallery.tar
如果要用私有数据构建人脸特征库,需要按以下目录结构组织数据:
data_root # 数据集根目录,目录名可自行修改
├── images # 存放图像的目录,目录名可自行修改
│ ├── ID0 # 身份 ID 名称,建议使用有意义的名称,如人名
│ │ ├── xxx.jpg # 图像,这里支持嵌套层级
│ │ ├── xxx.jpg # 图像,这里支持嵌套层级
│ │ ...
│ ├── ID1 # 身份 ID 名称,建议使用有意义的名称,如人名
│ │ ├── xxx.jpg # 图像,这里支持嵌套层级
│ │ ├── xxx.jpg # 图像,这里支持嵌套层级
│ │ ...
│ ...
└── gallery.txt # 特征库数据集标注文件,文件名可自行修改。每行给出待检索图像的路径和标签,以空格分隔。
# 示例内容:images/Chandler/Chandler00037.jpg Chandler
3.2 特征库的构建
PaddleX 提供简洁的特征库构建命令,只需几行代码即可完成人脸特征库的构建与保存:
from paddlex import create_pipeline
pipeline = create_pipeline(pipeline="face_recognition")
# gallery_imgs: 图库图像根目录,gallery_label: 标注文件
index_data = pipeline.build_index(gallery_imgs="face_demo_gallery", gallery_label="face_demo_gallery/gallery.txt")
# 保存人脸特征库
index_data.save("face_index")
从源码看,build_index 由 ShiTuV2Pipeline.build_index 实现,它调用 FaissBuilder.build,用特征模型的 predict 接口批量提取特征并建立 Faiss 索引,支持 metric_type(默认 IP,内积度量)与 index_type(默认 HNSW32)等参数,参见 pp_shitu_v2/pipeline.py。特征模型在推理时会先对输出特征做 NormalizeFeatures 归一化,还支持可选的 flip(水平翻转推理融合)以提升鲁棒性,参见 face_feature/predictor.py。
4. 特征库的增删维护
人脸特征库的质量对人脸识别结果至关重要。对于特定光照条件、特定拍摄角度等识别效果较差的场景,需要收集相应图像并加入特征库;当新增身份时,也需要把人脸图像加入特征库;反之,对于错误索引或需要移除的身份,应将其从特征库中删除。
PaddleX 提供简洁的特征库调整命令:向特征库添加图像调用 append_index 方法,删除索引调用 remove_index 方法。以本教程的人脸识别数据集为例,特征库调整命令如下:
from paddlex import create_pipeline
pipeline = create_pipeline("face_recognition")
index_data = pipeline.build_index(gallery_imgs="face_demo_gallery", gallery_label="face_demo_gallery/gallery.txt", index_type="Flat")
index_data.save("face_index_base")
index_data = pipeline.remove_index(remove_ids="face_demo_gallery/remove_ids.txt", index="face_index_base")
index_data.save("face_index_del")
index_data = pipeline.append_index(gallery_imgs="face_demo_gallery", gallery_label="face_demo_gallery/gallery.txt", index="face_index_del")
index_data.save("face_index_add")
注意:
- 默认的
HNSW32索引方式不支持删除索引,因此这里使用Flat。各索引方式的差异详见 Face Recognition Pipeline 使用教程(特征库增删操作); - 命令中参数的详细说明同样参见 Face Recognition Pipeline 使用教程(特征库增删操作)。
上述两个方法在 ShiTuV2Pipeline 中分别对应 FaissBuilder.remove 与 FaissBuilder.append 的封装(参见 pp_shitu_v2/pipeline.py):remove_index 依据 remove_ids 文件中的身份列表删除索引,append_index 对新增图库增量提取特征并追加进已有索引。
删除与添加特征后,用示例图像依次测试生成的不同底库:
from paddlex import create_pipeline
# 创建人脸识别 pipeline
pipeline = create_pipeline(pipeline="face_recognition")
# 传入待预测图像与本地特征索引
output = pipeline.predict("face_demo_gallery/test_images/friends1.jpg", index='./face_index_del')
for res in output:
res.print()
res.save_to_img("./output/")
对比 face_index_base、face_index_del、face_index_add 三种底库的预测可视化结果,即可直观验证增删操作对识别结果的影响。
5. 使用卡通数据微调人脸检测模型
5.1 模型选择
PaddleX 提供 4 个人脸检测模型,完整列表参见 模型列表,对应配置文件位于 face_detection。部分人脸检测模型的 benchmark 如下:
| 模型 | 模型下载链接 | AP(%) | GPU 推理耗时 (ms) [常规模式 / 高性能模式] |
CPU 推理耗时 (ms) [常规模式 / 高性能模式] |
模型存储大小 (MB) | 模型介绍 |
|---|---|---|---|---|---|---|
| BlazeFace | 推理模型 / 训练模型 | 50.90 / 45.74 | 71.92 / 71.92 | 84.18 / 84.18 | 0.447 | 轻量高效的人脸检测模型 |
| BlazeFace-FPN-SSH | 推理模型 / 训练模型 | 18.7 | 58.99 / 51.75 | 87.39 / 87.39 | 0.606 | BlazeFace 的改进模型,增加了 FPN 与 SSH 结构 |
| PicoDet_LCNet_x2_5_face | 推理模型 / 训练模型 | 31.4 | 33.91 / 26.53 | 153.56 / 79.21 | 28.9 | 基于 PicoDet_LCNet_x2_5 的人脸检测模型 |
| PP-YOLOE_plus-S_face | 推理模型 / 训练模型 | 36.1 | 21.28 / 11.09 | 137.26 / 72.09 | 26.5 | 基于 PP-YOLOE_plus-S 的人脸检测模型 |
注:上述精度指标在 WIDER-FACE 验证集上以 COCO 格式、输入尺寸 640×640 评测。所有模型的 GPU 推理耗时基于 NVIDIA V100 机器、FP32 精度;CPU 推理速度基于 Intel(R) Xeon(R) Gold 6271C CPU @ 2.60GHz、FP32 精度。
5.2 数据准备与校验
本教程以 Cartoon Face Detection Dataset(卡通人脸检测数据集) 为例,可通过以下命令获取。若使用自己标注的数据集,需按 PaddleX 的格式要求整理,数据格式细节参见 PaddleX 目标检测任务模块数据准备教程。
数据集获取命令:
cd /path/to/paddlex
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/cartoonface_coco_examples.tar -P ./dataset
tar -xf ./dataset/cartoonface_coco_examples.tar -C ./dataset/
数据集校验只需一条命令:
python main.py -c paddlex/configs/modules/face_detection/PP-YOLOE_plus-S_face.yaml \
-o Global.mode=check_dataset \
-o Global.dataset_dir=./dataset/cartoonface_coco_examples
执行上述命令后,PaddleX 会对数据集进行校验并统计数据集基本信息。命令运行成功后,日志中会打印 Check dataset passed ! 信息,相关输出保存在当前目录的 ./output/check_dataset 下,包括可视化样例图与样本分布直方图。校验结果文件保存在 ./output/check_dataset_result.json,具体内容如下:
{
"done_flag": true,
"check_pass": true,
"attributes": {
"num_classes": 1,
"train_samples": 2000,
"train_sample_paths": [
"check_dataset/demo_img/personai_icartoonface_dettrain_27140.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_23804.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_76484.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_18197.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_35260.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_00404.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_15455.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_10119.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_26397.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_17044.jpg"
],
"val_samples": 500,
"val_sample_paths": [
"check_dataset/demo_img/personai_icartoonface_dettrain_77030.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_36265.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_63390.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_59167.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_82024.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_50449.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_71386.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_23112.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_69609.jpg",
"check_dataset/demo_img/personai_icartoonface_dettrain_39296.jpg"
]
},
"analysis": {
"histogram": "check_dataset/histogram.png"
},
"dataset_path": "./dataset/cartoonface_coco_examples",
"show_type": "image",
"dataset_type": "COCODetDataset"
}
上述校验结果中,check_pass 为 True 表示数据集格式符合要求。其余指标说明如下:
attributes.num_classes:该数据集仅包含 1 个类别,即人脸;attributes.train_samples:该数据集训练集样本数为 2000;attributes.val_samples:该数据集验证集样本数为 500;attributes.train_sample_paths:训练集可视化样本的相对路径列表;attributes.val_sample_paths:验证集可视化样本的相对路径列表。
此外,数据集校验会对数据集中所有类别的标注数量分布进行分析,并生成直方图 histogram.png。
注意:只有通过校验的数据集才能用于训练和评估。
5.3 数据集格式转换 / 数据集切分(可选)
如需转换数据集格式或重新切分数据集,可通过修改配置文件或追加超参数来设置。
与数据集校验相关的参数可通过修改配置文件中 CheckDataset 下的字段进行设置。配置文件中部分参数示例如下:
CheckDataset:convert:enable:是否进行数据集格式转换。设为True时将转换数据集格式,默认为False;src_dataset_type:若进行数据集格式转换,需指定源数据集格式,可选格式为LabelMe和VOC。
split:enable:是否重新切分数据集。设为True时将重新切分数据集,默认为False;train_percent:若重新切分数据集,需设置训练集百分比,为 0~100 之间的整数,且需与val_percent之和为 100;val_percent:若重新切分数据集,需设置验证集百分比,为 0~100 之间的整数,且需与train_percent之和为 100。
数据转换与数据切分可以同时开启。进行数据切分时,原始标注文件会在原路径下被重命名为 xxx.bak。这些参数也可以通过追加命令行参数设置,例如重新切分数据集并设置训练集、验证集比例为 -o CheckDataset.split.enable=True -o CheckDataset.split.train_percent=80 -o CheckDataset.split.val_percent=20。
5.4 模型训练与评估
模型训练
训练前请确保已通过数据集校验。完成 PaddleX 模型训练只需一条命令:
python main.py -c paddlex/configs/modules/face_detection/PP-YOLOE_plus-S_face.yaml \
-o Global.mode=train \
-o Global.dataset_dir=./dataset/cartoonface_coco_examples \
-o Train.epochs_iters=10
PaddleX 的模型训练支持修改训练超参数、单机单卡/多卡训练等功能,只需修改配置文件或追加命令行参数即可。PaddleX 中每个模型都提供一份模型开发配置文件用于设置相关参数,训练相关参数可通过修改配置文件中 Train 下的字段设置。配置文件部分参数示例如下:
Global:mode:模式,支持数据校验(check_dataset)、模型训练(train)、模型评估(evaluate);device:训练设备,可选cpu、gpu、xpu、npu、mlu。除cpu外,多卡训练可指定卡号,如gpu:0,1,2,3;
Train:训练超参数设置;epochs_iters:训练轮数设置;learning_rate:训练学习率设置。
更多超参数说明参见 PaddleX 通用模型配置文件参数说明。以 PP-YOLOE_plus-S_face.yaml 为例,其默认 epochs_iters 为 50、batch_size 为 4、learning_rate 为 0.0001,并内置了基于 WIDER-FACE 的预训练权重下载地址,微调时可直接沿用。
注意:
- 上述参数均可通过追加命令行参数设置。例如指定模式为模型训练:
-o Global.mode=train;指定在前 2 张 GPU 上训练:-o Global.device=gpu:0,1;设置训练轮数为 10:-o Train.epochs_iters=10。- 模型训练过程中,PaddleX 会自动保存模型权重文件,默认目录为
output。如需指定保存路径,可使用配置文件中的-o Global.output字段。- PaddleX 为您屏蔽了动态图权重和静态图权重的概念。模型训练过程中会同时生成动态图和静态图权重,模型推理默认使用静态图权重。
训练输出说明:
模型训练完成后,所有输出保存在指定的输出目录(默认为 ./output/)。常见输出包括:
train_result.json:训练结果记录文件,记录训练任务是否正常完成,以及产出权重的指标、相关文件路径等;train.log:训练日志文件,记录训练过程中模型指标与 loss 的变化;config.yaml:训练配置文件,记录本次训练的超参数设置;.pdparams、.pdema、.pdopt.pdstate、.pdiparams、.pdmodel:模型权重相关文件,包括网络参数、优化器、EMA、静态图网络参数、静态图网络结构等。
模型评估
模型训练完成后,可在验证集上对指定模型权重文件进行评估,验证模型精度。使用 PaddleX 进行模型评估只需一条命令:
python main.py -c paddlex/configs/modules/face_detection/PP-YOLOE_plus-S_face.yaml \
-o Global.mode=evaluate \
-o Global.dataset_dir=./dataset/cartoonface_coco_examples
注意:评估模型时,需要指定模型权重文件路径。每个配置文件都内置了默认权重保存路径,如需更改,追加命令行参数即可,例如
-o Evaluate.weight_path=./output/best_model/best_model.pdparams。
5.5 模型调优
了解模型训练与评估后,可通过调整超参数提升模型精度。合理调整训练轮数可控制模型训练深度,避免过拟合或欠拟合;学习率设置与模型收敛的速度和稳定性相关。因此优化模型性能时,应仔细权衡这两个参数,并结合实际情况灵活调整,以获得最佳训练效果。
调参建议采用控制变量法:
- 先固定训练迭代为 10、batch size 为 4;
- 基于 PP-YOLOE_plus-S_face 模型,分别以 0.001 和 0.0001 的学习率启动两组实验;
- 可以观察到,实验 2 中精度最高的配置是学习率 0.0001。在此训练超参数基础上,将训练轮数增加到 20,可获得更高精度。
学习率探索实验结果:
| 实验 | Epochs | 学习率 | Batch Size | 训练环境 | mAP@0.5 |
|---|---|---|---|---|---|
| 实验 1 | 10 | 0.001 | 4 | 4 GPUs | 0.323 |
| 实验 2 | 10 | 0.0001 | 4 | 4 GPUs | 0.334 |
改变训练轮数的实验结果:
| 实验 | Epochs | 学习率 | Batch Size | 训练环境 | mAP@0.5 |
|---|---|---|---|---|---|
| 实验 2 | 10 | 0.0001 | 4 | 4 GPUs | 0.334 |
| 实验 2 增加训练轮数 | 20 | 0.0001 | 4 | 4 GPUs | 0.360 |
注意:本教程面向 4 卡环境。如果只有 1 张 GPU,可调整训练 GPU 数量完成本实验,但最终指标可能与上述指标不一致,这属于正常现象。
5.6 模型推理
完成模型训练、评估与调优后,即可使用满足指标的模型权重进行推理预测。通过命令行进行推理预测只需以下命令,这里使用上一节快速体验中官方模型权重表现较差的卡通人脸演示数据进行推理:
python main.py -c paddlex/configs/modules/face_detection/PP-YOLOE_plus-S_face.yaml \
-o Global.mode=predict \
-o Predict.model_dir="output/best_model/inference" \
-o Predict.input="cartoonface_demo_gallery/test_images/cartoon_demo.jpg"
通过上述指令可在 ./output 下生成预测结果,对比快速体验阶段的漏检结果,即可直观看到微调后检测模型对卡通人脸的召回明显改善。
6. 使用卡通数据微调人脸特征模型
PaddleX 训练过程中会把最优模型的路径保存到 output/best_model/inference。开始本节实验前,请注意将之前实验得到的最优权重保存到其他路径,避免被新实验覆盖。
6.1 模型选择
PaddleX 提供 2 个人脸特征模型,完整列表参见 模型列表,对应配置位于 face_feature。人脸特征模型 benchmark 如下:
| 模型 | 模型下载链接 | 输出特征维度 | Acc (%)
AgeDB-30/CFP-FP/LFW | GPU 推理耗时 (ms)
[常规模式 / 高性能模式] | CPU 推理耗时 (ms)
[常规模式 / 高性能模式] | 模型存储大小 (MB) | 模型介绍 |
| --- | --- | --- | --- | --- | --- | --- |
| MobileFaceNet | 推理模型 / 训练模型 | 128 | 96.28/96.71/99.58 | 3.31 / 0.73 | 5.93 / 1.30 | 4.1 | 基于 MobileFaceNet、在 MS1Mv3 数据集上训练的人脸特征提取模型 |
| ResNet50_face | 推理模型 / 训练模型 | 512 | 98.12/98.56/99.77 | 6.12 / 3.11 | 15.85 / 9.44 | 87.2 | 基于 ResNet50、在 MS1Mv3 数据集上训练的人脸特征提取模型 |
注:上述精度指标在 AgeDB-30、CFP-FP、LFW 数据集上评测。GPU 推理耗时基于 NVIDIA Tesla T4、FP32 精度;CPU 推理速度基于 Intel(R) Xeon(R) Gold 5117 CPU @ 2.00GHz、8 线程、FP32 精度。
6.2 数据准备与校验
本教程以 Cartoon Face Recognition Dataset(卡通人脸识别数据集) 为例,可通过以下命令获取。若使用自己标注的数据集,需按 PaddleX 的格式要求整理,数据格式细节参见 人脸特征模块教程文档(数据集组织)。
数据集获取命令:
cd /path/to/paddlex
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/cartoonface_rec_examples.tar -P ./dataset
tar -xf ./dataset/cartoonface_rec_examples.tar -C ./dataset/
数据校验只需一条命令:
python main.py -c paddlex/configs/modules/face_feature/ResNet50_face.yaml \
-o Global.mode=check_dataset \
-o Global.dataset_dir=./dataset/cartoonface_rec_examples
执行上述命令后,PaddleX 会对数据集进行校验并收集数据集基本信息。命令运行成功后,日志中会打印 Check dataset passed ! 信息,相关输出保存在当前目录的 ./output/check_dataset 下(包括可视化样例图),校验结果文件保存在 ./output/check_dataset_result.json,具体内容如下:
{
"done_flag": true,
"check_pass": true,
"attributes": {
"train_label_file": "../../dataset/cartoonface_rec_examples/train/label.txt",
"train_num_classes": 5006,
"train_samples": 77934,
"train_sample_paths": [
"check_dataset/demo_img/0000259.jpg",
"check_dataset/demo_img/0000052.jpg",
"check_dataset/demo_img/0000009.jpg",
"check_dataset/demo_img/0000203.jpg",
"check_dataset/demo_img/0000007.jpg",
"check_dataset/demo_img/0000055.jpg",
"check_dataset/demo_img/0000273.jpg",
"check_dataset/demo_img/0000006.jpg",
"check_dataset/demo_img/0000155.jpg",
"check_dataset/demo_img/0000006.jpg"
],
"val_label_file": "../../dataset/cartoonface_rec_examples/val/pair_label.txt",
"val_num_classes": 2,
"val_samples": 8000,
"val_sample_paths": [
"check_dataset/demo_img/0000011.jpg",
"check_dataset/demo_img/0000121.jpg",
"check_dataset/demo_img/0000118.jpg",
"check_dataset/demo_img/0000034.jpg",
"check_dataset/demo_img/0000229.jpg",
"check_dataset/demo_img/0000070.jpg",
"check_dataset/demo_img/0000033.jpg",
"check_dataset/demo_img/0000089.jpg",
"check_dataset/demo_img/0000139.jpg",
"check_dataset/demo_img/0000081.jpg"
]
},
"analysis": {},
"dataset_path": "./dataset/cartoonface_rec_examples",
"show_type": "image",
"dataset_type": "ClsDataset"
}
上述校验结果中,check_pass 为 True 表示数据集格式符合要求。其余指标说明如下:
attributes.train_num_classes:该数据集训练集包含 5006 个人脸类别,该类别数即后续训练需要传入的类别数;attributes.val_num_classes:人脸特征模型验证集只有 0 和 1 两类,分别表示两张人脸图像不属于同一身份、属于同一身份;attributes.train_samples:该数据集训练集样本数为 77934;attributes.val_samples:该数据集验证集样本数为 8000;attributes.train_sample_paths:该数据集训练集样本可视化相对路径列表;attributes.val_sample_paths:该数据集验证集样本可视化相对路径列表。
注意:只有通过数据校验的数据才能用于训练和评估。
6.3 模型训练与评估
模型训练
训练前请确保已通过数据集校验。完成 PaddleX 模型训练只需以下命令:
python main.py -c paddlex/configs/modules/face_feature/ResNet50_face.yaml \
-o Global.mode=train \
-o Global.dataset_dir=./dataset/cartoonface_rec_examples \
-o Train.num_classes=5006 \
-o Train.log_interval=50
PaddleX 的模型训练支持修改训练超参数、单机单卡/多卡训练等功能,只需修改配置文件或追加命令行参数即可。PaddleX 中每个模型都提供一份模型开发配置文件设置相关参数,训练相关参数可通过修改配置文件中 Train 下的字段设置。配置文件部分参数示例如下:
Global:mode:模式,支持数据校验(check_dataset)、模型训练(train)、模型评估(evaluate);device:训练设备,可选cpu、gpu、xpu、npu、mlu。除cpu外,多卡训练可指定卡号,如gpu:0,1,2,3;
Train:训练超参数设置;epochs_iters:训练轮数设置;learning_rate:训练学习率设置。
更多超参数说明参见 PaddleX 通用模型配置文件参数说明。以 ResNet50_face.yaml 为例,其默认 epochs_iters 为 25、batch_size 为 64、learning_rate 为 0.004、num_classes 为 995(使用卡通数据时需改为实际类别数)。训练器实现上,FaceRecTrainer 继承自图像分类训练器 ClsTrainer,训练数据集读取 train/label.txt,验证数据集读取 val/pair_label.txt(成对人脸标签),并支持 num_classes、learning_rate、epochs_iters、log_interval 等参数的覆盖,参见 face_recognition/trainer.py。
注意:
- 上述参数均可通过追加命令行参数设置。例如指定模式为模型训练:
-o Global.mode=train;指定在前 2 张 GPU 上训练:-o Global.device=gpu:0,1;设置训练轮数为 50:-o Train.epochs_iters=50。- 模型训练过程中,PaddleX 会自动保存模型权重文件,默认目录为
output。如需指定保存路径,可使用配置文件中的-o Global.output字段。- PaddleX 为您屏蔽了动态图权重和静态图权重的概念。模型训练过程中会同时生成动态图和静态图权重,模型推理默认使用静态图权重。
训练输出说明:
模型训练完成后,所有输出保存在指定的输出目录(默认为 ./output/)。常见输出包括:
train_result.json:训练结果记录文件,记录训练任务是否正常完成,以及产出权重的指标、相关文件路径等;train.log:训练日志文件,记录训练过程中模型指标与 loss 的变化;config.yaml:训练配置文件,记录本次训练的超参数设置;.pdparams、.pdema、.pdopt.pdstate、.pdiparams、.pdmodel:模型权重相关文件,包括网络参数、优化器、EMA、静态图网络参数、静态图网络结构等。
模型评估
模型训练完成后,可在验证集上对指定模型权重文件进行评估,验证模型精度。使用 PaddleX 进行模型评估只需一条命令:
python main.py -c paddlex/configs/modules/face_feature/ResNet50_face.yaml \
-o Global.mode=evaluate \
-o Global.dataset_dir=./dataset/cartoonface_rec_examples \
-o Evaluate.log_interval=50
6.4 模型调优:ArcFace margin 参数
PaddleX 的人脸特征模型基于 ArcFace 损失函数训练。除学习率与训练轮数外,ArcFace 损失函数中的 margin 参数是关键超参数:它通过在角度空间引入固定的角度间隔(angular margin)增强类别间的可分性,从而提升模型的判别能力。在模型调优实验中,主要针对 margin 参数进行实验。
margin 大小对模型训练效果和最终性能影响显著。一般而言:增大 margin 会使不同类别间的决策边界更清晰,迫使模型在特征空间中把不同类别的特征向量分得更开,从而提升类间可分性。但 margin 过大可能增大训练时的优化难度,收敛速度变慢,甚至无法收敛;此外,在训练数据不足或数据噪声较大的情况下,过大的 margin 可能使模型过拟合训练数据,降低对未见数据的泛化能力。
较小的 margin 可以降低模型训练难度、更易收敛。对于数据量小或数据质量低的训练集,降低 margin 可以降低过拟合风险,提升模型泛化能力。但 margin 过小可能不足以将不同类别的特征充分分开,模型可能学不到判别性特征,影响识别精度。
在数据校验阶段可以看到,本教程使用的卡通人脸识别数据集有 77,934 个训练样本。相比通用人脸识别数据集(MS1Mv2 有 580 万、Glint360K 有 1700 万样本),这是一个相对较小的数据集。因此使用该数据集训练人脸特征模型时,建议减小 margin 参数以降低过拟合风险、提升泛化能力。在 PaddleX 中,可通过追加命令行参数 -o Train.arcmargin_m=xx 指定人脸特征模型训练时的 margin 值。示例训练命令:
python main.py -c paddlex/configs/modules/face_feature/ResNet50_face.yaml \
-o Global.mode=train \
-o Global.dataset_dir=./dataset/cartoonface_rec_examples \
-o Train.num_classes=5006 \
-o Train.log_interval=50 \
-o Train.arcmargin_m=0.3
从底层配置看,人脸特征模型的分类头为 ArcMargin 结构,其默认 margin 为 0.5、scale 为 64、embedding_size 与模型输出维度一致(如 ResNet50_face 为 512),参见 ResNet50_face.yaml。Train.arcmargin_m 即用于覆盖该 margin 值。
调参时遵循控制变量法:
- 固定训练迭代为 20、学习率为 4e-4;
- 基于 ResNet50_face 模型,分别以 margin 0.5 和 0.3 启动两组实验。
margin 探索实验结果:
| 实验 | Epochs | 学习率 | Margin | 训练环境 | Acc |
|---|---|---|---|---|---|
| 实验 1 | 25 | 4e-4 | 0.5 | 4 GPUs | 0.925 |
| 实验 2 | 25 | 4e-4 | 0.3 | 4 GPUs | 0.928 |
注意:本教程面向 4 卡环境。如果只有 1 张 GPU,可调整训练 GPU 数量完成实验,最终指标可能与上述指标不一致,属于正常现象。
7. Pipeline 集成:把微调后的模型接入人脸识别 Pipeline
完成人脸检测模型与人脸特征模型在卡通场景数据上的微调后,即可选择高精度模型权重集成进 PaddleX 人脸识别 Pipeline。
首先获取 face_recognition Pipeline 配置文件并加载配置进行预测。执行以下命令可将结果保存到 my_path:
paddlex --get_pipeline_config face_recognition --save_path ./my_path
修改配置文件中的 SubModules.Detection.model_dir 和 SubModules.Recognition.model_dir,分别指向微调后的人脸检测模型与人脸特征模型路径。若需将人脸识别 Pipeline 直接集成进 Python 项目,可参考以下示例:
pipeline_name: face_recognition
index: None
det_threshold: 0.6
rec_threshold: 0.4
rec_topk: 5
SubModules:
Detection:
module_name: face_detection
model_name: PP-YOLOE_plus-S_face
model_dir: "path/to/your/det_model" # 使用卡通人脸数据微调后的人脸检测模型
batch_size: 1
Recognition:
module_name: face_feature
model_name: ResNet50_face
model_dir: "path/to/your/rec_model" # 使用卡通人脸数据微调后的人脸特征模型
batch_size: 1
随后,在 Python 代码中即可这样使用该 Pipeline:
from paddlex import create_pipeline
# 创建人脸识别 pipeline
pipeline = create_pipeline(pipeline="my_path/face_recognition.yaml")
# 构建卡通人脸特征库
index_data = pipeline.build_index(gallery_imgs="cartoonface_demo_gallery", gallery_label="cartoonface_demo_gallery/gallery.txt")
# 预测卡通演示图像
output = pipeline.predict("cartoonface_demo_gallery/test_images/cartoon_demo.jpg", index=index_data)
for res in output:
res.print()
res.save_to_img("./output/") # 保存结果图片
若出现卡通人脸能检测到、但被识别为 "Unknown0.00" 的情况,可以修改配置文件中的 rec_thresholds,降低检索阈值后重试;若出现人脸识别错误的情况,请将最优权重替换为最后一次训练的权重,或替换为使用不同超参数训练出的识别模型权重后重试。
8. Pipeline 服务化部署
除上述 Python API 集成开发方式外,PaddleX 还提供高性能部署与服务化部署能力:
- 高性能部署:实际生产环境中,许多应用对部署策略的性能指标(尤其是响应速度)有严格要求,以保证系统高效运行与用户体验流畅。为此 PaddleX 提供高性能推理插件,深度优化模型推理及前后处理的性能,实现端到端流程显著加速。详细的高性能部署流程参见 PaddleX 高性能推理指南。
- 服务化部署:服务化部署是生产环境中常见的部署形式,通过将推理功能封装为服务,客户端可通过网络请求访问服务获取推理结果。PaddleX 支持用户低成本实现 Pipeline 服务化部署,详细流程参见 PaddleX 服务化部署指南。
可根据需求选择合适的部署方式,再进行后续 AI 应用集成。本节以服务化部署为例,演示 Pipeline 服务化部署与 API 调用,仅需 5 步:
步骤 (1):执行以下 Python 脚本,保存卡通人脸演示数据的特征库:
from paddlex import create_pipeline
# 创建人脸识别 pipeline
pipeline = create_pipeline(pipeline="face_recognition")
# 构建卡通人脸特征库
index_data = pipeline.build_index(gallery_imgs="cartoonface_demo_gallery", gallery_label="cartoonface_demo_gallery/gallery.txt")
# 保存卡通人脸特征库
index_data.save("cartoonface_index")
步骤 (2):命令行安装服务化部署插件:
paddlex --install serving
步骤 (3):获取人脸识别 Pipeline 配置文件:
paddlex --get_pipeline_config face_recognition --save_path ./
步骤 (4):修改配置文件,设置特征库目录:
pipeline_name: face_recognition
index: ./cartoonface_index # 本地特征库目录,使用步骤 (1) 构建的特征库
det_threshold: 0.6
rec_threshold: 0.4
rec_topk: 5
SubModules:
Detection:
module_name: face_detection
model_name: PP-YOLOE_plus-S_face
model_dir: "path/to/your/det_model" # 使用卡通人脸数据微调后的人脸检测模型
batch_size: 1
Recognition:
module_name: face_feature
model_name: ResNet50_face
model_dir: "path/to/your/rec_model" # 使用卡通人脸数据微调后的人脸特征模型
batch_size: 1
步骤 (5):启动服务端服务:
paddlex --serve --pipeline face_recognition.yaml
客户端调用
PaddleX 提供简单便捷的调用接口与示例代码,这里以单张图像推理为例。更多调用接口支持详见 Face Recognition Pipeline 使用教程(开发集成部署)。
客户端调用示例代码:
import base64
import pprint
import sys
import requests
API_BASE_URL = "http://0.0.0.0:8080"
infer_image_path = "cartoonface_demo_gallery/test_images/cartoon_demo.jpg" # 测试图像路径
with open(infer_image_path, "rb") as file:
image_bytes = file.read()
image_data = base64.b64encode(image_bytes).decode("ascii")
payload = {"image": image_data}
resp_infer = requests.post(f"{API_BASE_URL}/face-recognition-infer", json=payload)
if resp_infer.status_code != 200:
print(f"Request to face-recognition-infer failed with status code {resp_infer}.")
pprint.pp(resp_infer.json())
sys.exit(1)
result_infer = resp_infer.json()["result"]
output_image_path = './out.jpg'
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"])
执行示例代码后,可在输出日志中查看服务化部署的推理结果,并查看保存的推理图片。至此,一条完整的"卡通人脸识别"链路——快速体验 → 特征库构建与维护 → 检测/特征模型微调 → Pipeline 集成 → 服务化部署——即全部打通。