企业官网建设流程全解析

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

本文是飞桨 PaddleX 人脸特征模块的完整实战指南。人脸特征模块以经过人脸检测、关键点矫正后的标准化人脸图像为输入，提取具有高度辨识性的判别性特征向量，供人脸匹配、人脸验证等下游任务使用。读完本文，你将掌握：两个内置人脸特征模型的选型依据与性能对比、通过create_model/predict快速完成特征提取推理、基于通用图像分类格式组织训练数据（含人脸验证集pair_label.txt的特殊格式）、以及训练、评估、推理与产线集成的完整二次开发闭环。

一、模块概述：从人脸图像到判别性特征向量

人脸特征（Face Feature）模块是 PaddleX 中负责"人脸表征学习"的核心组件。在实际人脸识别系统中，原始图片通常不能直接用于比对：光照、姿态、遮挡和拍摄角度都会干扰比对结果。标准的人脸识别流程是：

1. 人脸检测：先从图片中定位人脸位置（如 PaddleX 的 face_detection 模块）；
2. 人脸关键点矫正：根据双眼、鼻尖等关键点对人脸区域做仿射变换，得到标准化人脸图像；
3. 特征提取：将标准化人脸图像送入人脸特征模型，输出固定维度的特征向量；
4. 匹配/验证：通过计算特征向量间的余弦相似度等指标，完成 1:1 验证（同一人/非同一人）或 1:N 检索。

人脸特征模块对应的正是第 3 步，其输入约定为"已经过检测、提取和关键点矫正处理的标准化人脸图像"。输出为 L2 归一化后的判别性特征向量——PaddleX 在推理后处理阶段会对原始 logits 做 L2 归一化（详见下文源码分析），使同一身份的类内距离更小、不同身份的类间距离更大，从而让后续相似度比对更稳定。

二、支持模型列表与选型依据

PaddleX 人脸特征模块内置两个模型，配置目录位于 paddlex/configs/modules/face_feature，模型注册列表见 paddlex/modules/face_recognition/model_list.py（MODELS = ["MobileFaceNet", "ResNet50_face"]）。

2.1 测试环境说明

• 测试数据集：上述 Acc 指标分别在 AgeDB-30、CFP-FP、LFW 三个人脸基准数据集上测得；
• 硬件配置：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。

2.2 推理模式说明

选型建议：MobileFaceNet 以 4.1MB 的体积换来毫秒级推理（GPU 常规模式仅 3.31ms），适合移动端、边缘设备和海量人脸库的 1:N 检索场景；ResNet50_face 以 87.2MB 的体积提供更高精度（LFW 达 99.77%），适合对精度要求更高的金融、安防等场景。

三、快速集成：几行代码完成人脸特征推理

⚠️ 快速集成前，请先安装 PaddleX 的 wheel 包，安装步骤参见 PaddleX 本地安装教程。

安装 whl 包后，几行代码即可完成人脸特征模块的推理，可自由切换模块下的两个模型，也可以将模块推理集成进自己的项目。运行前请先下载示例图片到本地。

from paddlex import create_model model = create_model(model_name="MobileFaceNet") output = model.predict("face_recognition_001.jpg", batch_size=1) for res in output: res.print(json_format=False) res.save_to_json("./output/res.json")

3.1 运行结果示例

{'res': {'input_path': 'face_recognition_001.jpg', 'feature': [0.04121152311563492, 0.0010890548583120108, -0.03561094403266907, 0.05722084641456604, ...]}}

字段含义：

• input_path：输入的待预测图像路径；
• feature：提取的人脸特征向量，维度即模型的输出特征维度，此处 MobileFaceNet 为 128 维（ResNet50_face 为 512 维）。

从源码看，该结果由 paddlex/inference/models/face_feature/predictor.py 中的process()返回，包含input_path、page_index、input_img和feature四个字段；paddlex/inference/models/image_feature/result.py 中的IdentityResult在打印/序列化时会剔除input_img，因此终端输出只保留路径与特征向量。

3.2create_model参数说明

create_model用于实例化人脸特征模型（此处以 MobileFaceNet 为例）：

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

flip 参数的实现细节：查看 paddlex/inference/models/face_feature/predictor.py，当flip=True时，process()会对同一 batch 数据沿axis=3（宽度方向）做np.flip得到水平翻转图，再次推理后将两次推理的输出直接相加融合，再送入归一化后处理。这一"原图 + 水平翻转"的双路推理融合策略（face embedding 领域的常见测试时增强手段）能进一步提升特征稳定性，代价是推理时间翻倍，适合精度优先的离线场景。

3.3predict()方法参数说明

3.4 预测结果处理方法

每个样本的预测结果均为 Result 对象，支持打印与保存为 JSON 文件：

此外还支持通过json属性直接获取预测结果的 JSON 格式。

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

四、二次开发：从数据准备到产线集成的完整闭环

如果现有模型精度不满足需求，可使用 PaddleX 的二次开发能力训练更好的人脸特征模型。开发前请务必安装 PaddleX 的 PaddleClas 插件，安装过程见 PaddleX 本地安装教程。

4.1 数据准备

训练前需准备任务模块的数据集。PaddleX 对每个模块提供数据校验功能，只有通过数据校验的数据才能用于模型训练。同时每个模块都提供 demo 数据集，可基于官方 Demo 数据完成后续开发。

• 若用私有数据集训练：人脸特征模块训练数据集采用通用图像分类数据集格式组织，可参考 PaddleX 图像分类任务模块数据标注教程；
• 若用私有数据集评估：注意验证数据集格式与训练数据集不同，请参考下方"4.1.4 人脸特征模块数据集组织方式"。

4.1.1 Demo 数据下载

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

4.1.2 数据校验

一行命令完成数据校验：

python main.py -c paddlex/configs/modules/face_feature/MobileFaceNet.yaml \ -o Global.mode=check_dataset \ -o Global.dataset_dir=./dataset/face_rec_examples

执行后 PaddleX 会校验数据集并统计基本信息，成功时日志打印Check dataset passed !。校验结果文件保存在./output/check_dataset_result.json，可视化示例样本等产出保存在./output/check_dataset目录。

校验结果文件内容示例（节选）：

{ "done_flag": true, "check_pass": true, "attributes": { "train_label_file": "../../dataset/face_rec_examples/train/label.txt", "train_num_classes": 995, "train_samples": 1000, "val_label_file": "../../dataset/face_rec_examples/val/pair_label.txt", "val_num_classes": 2, "val_samples": 500 }, "dataset_path": "./dataset/face_rec_examples", "show_type": "image", "dataset_type": "ClsDataset" }

结果指标解读：

• check_pass=True：数据集格式符合要求；
• attributes.train_num_classes：训练类别数为 995；
• attributes.val_num_classes：验证类别数为 2（pair 验证任务按"同人/非同人"二分类计算）；
• attributes.train_samples：训练样本数 1000；
• attributes.val_samples：验证样本数 500；
• attributes.train_sample_paths：训练样本可视化图片的相对路径列表。

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

完成数据校验后，可通过修改配置文件或追加超参数进行格式转换与训练/验证比例重划分。人脸特征模块不支持数据格式转换与数据集划分（配置文件中CheckDataset.convert.enable与CheckDataset.split.enable均为False）。

4.1.4 人脸特征模块数据集组织方式

人脸特征模块验证数据集与训练数据集格式不同。若需在私有数据上训练并评估模型精度，请按如下结构组织：

face_rec_dataroot # 数据集根目录，目录名称可改 ├── train # 训练数据保存目录，目录名称不可改 │ ├── images # 图像保存目录，目录名称可改，需与 label.txt 内容对应 │ │ ├── xxx.jpg # 人脸图像文件 │ │ └── ... │ └── label.txt # 训练集标注文件，文件名不可改。每行给出图像相对 train 的路径和人脸身份 id，空格分隔，如：images/image_06765.jpg 0 └── val # 验证数据保存目录，目录名称不可改 ├── images # 图像保存目录，目录名称可改，需与 pair_label.txt 内容对应 │ ├── xxx.jpg # 人脸图像文件 │ └── ... └── pair_label.txt # 验证集标注文件，文件名不可改。每行给出两张待比对人脸图像路径及 0/1 标签（是否同一人），空格分隔

验证集标注文件pair_label.txt内容示例：

# 人脸图像1.jpg 人脸图像2.jpg 标签(0 表示不属于同一个人，1 表示属于同一个人) images/Angela_Merkel_0001.jpg images/Angela_Merkel_0002.jpg 1 images/Bruce_Gebhardt_0001.jpg images/Masao_Azuma_0001.jpg 0 images/Francis_Ford_Coppola_0001.jpg images/Francis_Ford_Coppola_0002.jpg 1 images/Jason_Kidd_0006.jpg images/Jason_Kidd_0008.jpg 1 images/Miyako_Miyazaki_0002.jpg images/Munir_Akram_0002.jpg 0

验证集与训练集的本质区别（源码佐证）：训练集label.txt按"图像-身份 id"逐行组织，走通用分类训练流程；验证集则按"图像对-0/1标签"组织，对应 pair 验证评测。查看 paddlex/modules/face_recognition/evaluator.py，评估器update_dataset_cfg()会读取dataset_dir/val/pair_label.txt，并将其配置为DataLoader.Eval.dataset.name=FaceEvalDataset、pair_label_path=...，这正是验证集必须使用pair_label.txt的原因。

4.2 模型训练

一条命令完成模型训练，以 MobileFaceNet 为例：

python main.py -c paddlex/configs/modules/face_feature/MobileFaceNet.yaml \ -o Global.mode=train \ -o Global.dataset_dir=./dataset/face_rec_examples

需要如下几步：

• 指定模型的.yaml配置文件路径（此处为MobileFaceNet.yaml）；
• 指定模式为模型训练：-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 训练时有不同程度加速，可指定-o Train.dy2st=True开启。

训练关键默认超参（来自 MobileFaceNet.yaml）：

训练产出说明：

• 训练中 PaddleX 自动保存模型权重文件，默认输出到output，可用-o Global.output指定路径；
• PaddleX 屏蔽了动态图/静态图权重概念：训练同时产出两类权重，推理时默认选静态图权重；
• 训练其他模型时指定对应配置文件，模型与配置对应关系见 PaddleX 模型列表（CPU/GPU）；
• 完成训练后，默认./output/下通常包含：
  • train_result.json：训练结果记录，含任务完成状态、权重指标与相关文件路径；
  • train.log：训练日志，记录指标与 loss 变化；
  • config.yaml：本次训练的超参配置；
  • .pdparams、.pdema、.pdopt.pdstate、.pdiparams、.json：模型权重相关文件，包括网络参数、优化器、EMA、静态图网络参数与静态图网络结构；
  • 注意：Paddle 3.0.0 起静态图网络结构存储格式由 protobuf（.pdmodel）升级为 JSON（.json），以兼容 PIR 体系并获得更好的灵活性与扩展性。

4.3 模型评估

完成训练后，可在验证集上评估指定权重文件的精度，一条命令完成：

python main.py -c paddlex/configs/modules/face_feature/MobileFaceNet.yaml \ -o Global.mode=evaluate \ -o Global.dataset_dir=./dataset/face_rec_examples

• 指定模型.yaml配置文件路径（此处为MobileFaceNet.yaml）；
• 指定模式为模型评估：-o Global.mode=evaluate；
• 指定验证数据集路径：-o Global.dataset_dir；
• 评估时需要指定模型权重文件路径，每个配置文件内置默认权重保存路径（如Evaluate.weight_path=output/best_model/best_model.pdparams），如需更改可通过命令行追加，如-o Evaluate.weight_path=./output/best_model/best_model/model.pdparams；
• 评估完成后产出evaluate_result.json，记录评估任务是否正常完成及模型评估指标（包含 Accuracy——基于 pair 验证任务，模型输出特征经归一化后按阈值判定是否同一人）。

4.4 模型推理与集成

完成训练与评估后，即可用训练好的权重进行推理预测，PaddleX 支持命令行与 wheel 包两种方式。

4.4.1 命令行推理

python main.py -c paddlex/configs/modules/face_feature/MobileFaceNet.yaml \ -o Global.mode=predict \ -o Predict.model_dir="./output/best_model/inference" \ -o Predict.input="face_recognition_001.jpg"

• 指定模型.yaml配置文件路径；
• 指定模式为推理预测：-o Global.mode=predict；
• 指定模型权重路径：-o Predict.model_dir=./output/best_model/inference；
• 指定输入数据路径：-o Predict.input=...；
• 其他参数可修改Global与Predict字段，如 MobileFaceNet.yaml 中Predict.batch_size=1、Predict.kernel_option.run_mode=paddle，详见 PaddleX 通用模型配置文件参数说明。

4.4.2 模型集成

训练得到的模型可直接集成到 PaddleX 产线或自有项目中。

1. 产线集成：人脸特征模块可集成到 PaddleX 人脸识别产线。从 paddlex/configs/pipelines/face_recognition.yaml 可以看到，人脸识别产线由face_detection（默认PP-YOLOE_plus-S_face）与face_feature（默认ResNet50_face）两个子模块组成——只需替换Recognition.model_dir即可完成人脸特征模块的模型更新；产线集成中可使用高性能部署与服务化部署部署所得模型。

2. 模块集成：产出的权重可直接集成进人脸特征模块，参考上文"三、快速集成"的 Python 示例，将模型替换为训练所得模型路径即可（即create_model(model_dir="...")）。

此外，可利用 PaddleX 高性能推理插件（use_hpip=True与hpi_config）优化模型推理过程、进一步提升效率，详细流程见 PaddleX 高性能推理指南。

五、附：推理链路源码速览

了解底层实现有助于调参与二次开发。人脸特征推理的核心链路如下：

1. 预测器：paddlex/inference/models/face_feature/predictor.py 中的FaceFeaturePredictor继承自 image_feature 的 ImageFeaturePredictor，额外接收flip参数；
2. 预处理管线：按Read(RGB) → Resize → Normalize → ToCHW → ToBatch顺序执行（paddlex/inference/models/image_feature/predictor.py），其中 Normalize 默认使用 ImageNet 统计量（mean=[0.485, 0.456, 0.406]、std=[0.229, 0.224, 0.225]）；
3. 特征归一化：paddlex/inference/models/image_feature/processors.py 的NormalizeFeatures对模型输出做 L2 归一化——先计算sqrt(sum(x^2))，再逐元素除以该范数，最终feature即为单位长度的判别性特征向量，可直接用于余弦相似度计算；
4. 结果封装：IdentityResult在打印/转 JSON 时剔除input_img，保证序列化结果只含路径与特征。

结合上述源码，你可以清晰地理解flip翻转融合、128/512 维特征输出的归一化处理，以及验证集 pair 数据在评估阶段（FaceEvalDataset+pair_label_path）是如何被读取并参与 Accuracy 计算的，从而更自如地完成从数据、训练到部署的完整闭环。

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