# 人脸识别
Source: [https://docs.qualcomm.com/doc/80-70022-50SC/topic/gst-ai-face-recognition.html](https://docs.qualcomm.com/doc/80-70022-50SC/topic/gst-ai-face-recognition.html)
**gst-ai-face-recognition** 应用程序从摄像头或 RTSP 流采集实时视频输入，并对这些输入执行人脸检测、人脸特征点定位和人脸识别。它使用 face\_det\_quantized模型进行人脸检测，使用 `facemap_3dmm_quantized` 模型进行人脸特征点定位，使用 `face_attrib_net_quantized` 模型进行人脸识别标签标注。
运行的结果是在 HDMI 显示器上预览叠加的 AI 模型。
下图展示了一个 pipeline：接收输入，对其进行预处理，在 AI 硬件上运行推理，并在屏幕上显示结果。
Figure : gst-ai-face-recognition pipeline
有关 pipeline 流中使用的插件的信息，请参见 [Pipeline 流](https://docs.qualcomm.com/doc/80-70022-50SC/topic/gst-ai-face-recognition.html#gst-ai-face-recognition__section_mrl_x4m_qdc)。
## 示例模型和标签文件
Table : gst-ai-face-detection 的示例模型和标签文件
| Runtime | 模型文件 | 标签文件 |
| :--- | :--- | :--- |
| Qualcomm AI Engine direct 和 LiteRT |
- face_det_lite_quantized.tflite
- facemap_3dmm_quantized.tflite
- face_attrib_net_quantized.tflite
- face_det_lite_quantized.bin
- facemap_3dmm_quantized.bin
- face_attrib_net_quantized.bin
|
- face_detection.json
- face_recognition_settings.json
- face_recognition.json
- facemap_3dmm_settings.json
|
- 下载以下 w8a8 精度的 LiteRT 模型。以下路径中的模型文件名可能会更改。确保在运行命令时更新模型名称。
- [face_det_quantized](https://aihub.qualcomm.com/iot/models/face_det_lite?searchTerm=fac)
- [face_attrib_net_quantized](https://aihub.qualcomm.com/iot/models/face_attrib_net?searchTerm=fac)
- 将这些模型推送到目标设备上的 /etc/models目录。
scp face_det_lite-lightweight-face-detection.tflite root@:/etc/modelsCopy to clipboard
scp face_attrib_net-facial-attribute.tflite root@:/etc/modelsCopy to clipboard
Note: 对于 Ubuntu Server，将模型文件复制到用户主文件夹，然后使用 `sudo` 命令将模型文件复制到 `/etc/models` 目录。
。
## 注册人脸进行面部识别
在运行 gst-ai-face-recognition 应用程序之前，您可以注册一张人脸，用于进行安全验证和身份验证。
1. 确保您已完成[前提条件](https://docs.qualcomm.com/doc/80-70022-50SC/topic/download-model-and-label-files.html)。
2. 要注册人脸，请在目标设备的 shell 使用以下 gst-pipeline：
gst-pipeline-app -e \
qtimlvconverter name=stage_01_preproc mode=image-batch-non-cumulative \
qtimltflite name=stage_01_inference model=/etc/models/face_det_lite-lightweight-face-detection.tflite delegate=external external-delegate-path=libQnnTFLiteDelegate.so \
external-delegate-options="QNNExternalDelegate,backend_type=htp;" \
qtimlpostprocess name=stage_01_postproc settings="{\"confidence\": 40.0}" results=4 module=qfd labels=/etc/labels/face_detection.json \
qtimlvconverter name=stage_03_preproc mode=roi-batch-cumulative \
qtimltflite name=stage_03_inference model=/etc/models/face_attrib_net-facial-attribute.tflite delegate=external external-delegate-path=libQnnTFLiteDelegate.so \
external-delegate-options="QNNExternalDelegate,backend_type=htp;" \
qtiqmmfsrc video_0::type=video name=camsrc ! video/x-raw,format=NV12,width=1920,height=1080 ! queue ! waylandsink fullscreen=true sync=false \
camsrc.image_1 ! video/x-raw,width=1920,height=1080 ! qtivtransform ! video/x-raw,format=NV12 ! tee name=t_split_1 \
t_split_1. ! queue ! metamux_1. \
t_split_1. ! queue ! stage_01_preproc. stage_01_preproc. ! queue ! stage_01_inference. stage_01_inference. ! queue ! \
stage_01_postproc. stage_01_postproc. ! text/x-raw ! queue ! metamux_1. \
qtimetamux name=metamux_1 ! queue ! tee name=t_split_3 \
t_split_3. ! queue ! stage_03_preproc. stage_03_preproc. ! queue ! stage_03_inference. stage_03_inference. ! queue ! \
multifilesink location=/etc/data/tensor_%d.bin sync=true async=false enable-last-sample=falseCopy to clipboard
随即显示一个选项列表。
3. 要准备采集人脸图像，请执行以下操作：
1. 从列表中选择以下选项：
1. `(3)PLAYING`：将 pipeline 切换至 Playing 状态。
2. `(p)Plugin Mode`➔ `(26)camsrc`➔ `(70)capture-image`：使用摄像头源采集图像。
2. 使用显示器上的实时预览功能，面向摄像头，确保摄像头指向正前方，并且画面中只有一个人。
3. 在终端中，为以下值输入 1：
1. 为 `arg0`输入 `GstImageCaptureMode`。
2. 为 `arg1`输入 `guint`。
4. 要采集脸部所有侧面，请选择 `capture-image`，并对每侧执行以下操作：
1. 左侧和右侧：将头部左转 40°，同时保持特征点清晰可见，然后重复步骤 3 和 4。将头部右转 (40°)，然后重复上述步骤。
2. 向上和向下：抬头 30°，同时保持特征点清晰可见，然后重复步骤 3 和 4。低头 (30°)，然后重复上述步骤。
5. 要停止 pipeline，请使用 `(b)Back`和 `(q)Quit`。
运行 pipeline 后，会创建五个单独的张量 bin（tensor\_0.bin至 tensor\_4.bin），用于记录每一侧的面部属性。
6. 在目标设备上，转到 /etc/data/，找到这些张量 bin。要将 bin 从目标设备拉取到 Linux 主机：
- 对于 Qualcomm Linux，运行以下命令：
scp root@:/etc/data/tensor_0.bin .Copy to clipboard
scp root@:/etc/data/tensor_1.bin .Copy to clipboard
scp root@:/etc/data/tensor_2.bin .Copy to clipboard
scp root@:/etc/data/tensor_3.bin .Copy to clipboard
scp root@:/etc/data/tensor_4.bin .Copy to clipboard
- 对于 Ubuntu Server，使用以下参考命令：
scp ubuntu@:/etc/data/tensor_.binCopy to clipboard
7. 要将包含所有面部属性的张量 bin 合并为一张连贯的图像，请在 Linux 主机上的张量 bin 目录中下载并运行 facedb.py脚本。
1. 下载 facedb.py脚本：
curl -L -O https://raw.githubusercontent.com/quic/sample-apps-for-qualcomm-linux/refs/heads/main/scripts/facedb.pyCopy to clipboard
2. 运行该脚本。请注意，<Name of the person>区分大小写和样式。请确保始终使用相同的名称。
python3 ./facedb.py "" 512 32 tensor_0.bin tensor_1.bin tensor_2.bin tensor_3.bin tensor_4.binCopy to clipboard
已创建 face.bin二进制文件。
8. 将 face.bin二进制文件推送到 /etc/data 目录，并将其重命名为 face0.bin。
scp face.bin root@:/etc/data/face0.binCopy to clipboard
对于 Ubuntu Server，将 `face.bin` 二进制文件复制到用户主目录，然后使用 `sudo` 命令将其复制到 `/etc/models` 目录。
9. 要生成 face\_recognition.json文件并将新人注册到数据库中，请使用以下双人人脸注册的参考标签文件：
[
{"id": 0, "color": "0x00FF00FF", "label": ""},
{"id": 1, "color": "0xFFFF00FF", "label": ""}
]Copy to clipboard
Note: 根据列表中的编号更新 ID 字段。如果要注册更多人脸，请在 face\_recognition.json文件中另起新行添加对应结构。
10. 要生成 face\_recognition\_settings.json 文件，请使用以下参考标签文件：
{
"confidence": 51.0,
"databases":[
{"id": 0, "database": "/etc/data/face0.bin"},
{"id": 1, "database": "/etc/data/face1.bin"}
]
}Copy to clipboard
11. 将更新的 face\_recognition.json 和 face\_recognition\_settings.json 文件推送到目标设备上的 /etc/labels 目录。
scp face_recognition.json root@:/etc/labelsCopy to clipboard
scp face_recognition_settings.json root@:/etc/labelsCopy to clipboard
对于 Ubuntu Server，将 `face_recognition.json` 和 face\_recognition\_settings.json 文件复制到用户 `home` 文件夹，然后使用 `sudo` 命令将其复制到 `/etc/labels` 目录。
## 在目标设备上运行应用程序
Note: 以下命令提供默认模型和标签路径。如果您的文件夹结构不同，请替换命令行参数中的默认路径。参见[示例模型和标签文件](https://docs.qualcomm.com/doc/80-70022-50SC/topic/gst-ai-face-recognition.html#gst-ai-face-recognition__section_bxr_x4m_qdc)。
示例应用程序使用 `/etc/configs/config-face-recognition.json`文件读取输入参数。
要创建自己的配置 JSON 文件，请使用 [config-face-recognition.json](https://git.codelinaro.org/clo/le/platform/vendor/qcom-opensource/gst-plugins-qti-oss/-/tree/imsdk.lnx.2.0.0.r2-rel/gst-sample-apps/gst-ai-face-recognition?ref_type=heads)作为参考。
1. 根据模型、输入流和其他属性更新 config JSON 文件。关于更多详细信息，请参阅 [Config JSON 字段说明](https://docs.qualcomm.com/doc/80-70022-50SC/topic/gst-ai-face-recognition.html#gst-ai-face-recognition__section_qjx_hqq_32c)。
2. 使用以下格式的 `/etc/configs/config-face-recognition.json`文件：
{
"ml-framework": "",
"face-detection-model": "",
"face-landmark-model":"",
“face-recognition-model”:””,
"face-detection-labels":””,
"face-recognition-labels":””,
"face-recognition-settings": "",
"facemap-3dmm-settings": ""
}Copy to clipboard
例如，使用 LiteRT、自定义模型、自定义标签文件运行应用：
{
"ml-framework":"tflite",
"face-detection-model":"/etc/models/face_det_lite_quantized.tflite",
"face-landmark-model":"/etc/models/facemap_3dmm_quantized.tflite",
"face-recognition-model":"/etc/models/face_attrib_net_quantized.tflite",
"face-detection-labels": "/etc/labels/face_detection.json",
"face-recognition-labels": "/etc/labels/face_recognition.json",
"face-recognition-settings": "/etc/labels/face_recognition_settings.json",
"facemap-3dmm-settings": "/etc/labels/facemap_3dmm_settings.json"
}Copy to clipboard
3. 运行 gst-ai-face-recognition 应用程序：
gst-ai-face-recognition --config-file=/etc/configs/config-face-recognition.jsonCopy to clipboard
4. 请在 SSH shell 中运行以下命令，以显示可用的帮助选项：
gst-ai-face-recognition -hCopy to clipboard
5. 要停止用例，请按 CTRL +
C。
## 预期输出
## Pipeline 流
下表列出了人脸识别 pipeline 中使用的插件：| 插件 | 说明 |
| --- | --- |
| 摄像头源：[qtiqmmfsrc](https://docs.qualcomm.com/doc/80-70022-50SC/topic/qtiqmmfsrc.html) |
- 从摄像头采集实时流。
- 使用 tee 拆分流进行推理。
|
| 文件源：filesrc |
- 使用 filesrc 采集视频流，然后使用 qtdemux 对视频流进行解复用。
- 使用 tee 拆分流进行推理。
|
| RTSP 源：rtspsrc |
- 使用 rtspsrc 采集 RTSP 流，然后使用 rtph264depay 进行视频提取。
- 使用 tee 拆分流进行推理。
|
| h264parse | 渲染 H.264 视频。 |
| [v4l2h264dec](https://docs.qualcomm.com/doc/80-70022-50SC/topic/v4l2h264dec.html) | 解码视频 |
| [qtimlvconverter](https://docs.qualcomm.com/doc/80-70022-50SC/topic/qtimlvconverter.html) |
- 在其接收端口上接收视频流。
- 对流数据执行以下预处理。当模型需要浮点值作为输入时，会执行此预处理。
- 颜色转换
- 缩放（放大或缩小）
- 归一化
- 将预处理的视频流转换为其发送端口上的张量数据流。
张量数据流用于 pipeline 后期的推理。 |
| [qtimlqnn](https://docs.qualcomm.com/doc/80-70022-50SC/topic/qtimlqnn.html) | 充当 Qualcomm Neural Network 模型的推理插件。
- 推理 runtime 在其接收端口上接收到张量数据后，会运行推理。
- 生成一个张量数据流，并在其发送端口上显示推理结果。
|
| qtimlpostprocess |
- 处理来自任何人脸检测模型的推理结果。
- 将阈值应用于所选结果数。
|
| [qtimetamux](https://docs.qualcomm.com/doc/80-70022-50SC/topic/qtimetamux.html) |
- 从 qtimlpostprocess 接收人脸检测模型的输出并将其复用。
- 从 qtimlpostprocess 接收面部姿态的输出并将其复用。
|
| tee | 分割流以进行推理。 |
| qtimlpostprocess 用于姿态估计 | 使用 lite-3dmm 模块进行人脸姿态识别。 |
| qtimlpostprocess 用于分类模型 | 使用 qfr 模块接收来自 qtimetamux 的流并对人脸进行分类。 |
| [qtivoverlay](https://docs.qualcomm.com/doc/80-70022-50SC/topic/qtioverlay.html) |
- 接收复用流。
- 将边界框叠加在流上。
|
| [Waylandsink](https://docs.qualcomm.com/doc/80-70022-50SC/topic/waylandsink.html) |
- Waylandsink 将其接收端口上接收的视频流提交给 Weston。
- Weston 在本地显示器上渲染视频流。
|
## Config JSON 字段说明
Table : 字段说明 – config-face-recognition.json 文件
| 字段 | 值/描述 |
| :--- | :--- |
| **ml-framework** | 请使用以下模型之一：
tflite–LiteRT
qnn–Qualcomm AI Engine direct
|
| **Models and labels** | 参见[示例模型和标签文件](https://docs.qualcomm.com/doc/80-70022-50SC/topic/gst-ai-face-recognition.html#gst-ai-face-recognition__section_bxr_x4m_qdc)。
- face-detection-model：人脸检测模型的路径。
- face-landmark-model：人脸特征点模型的路径。
- face-recognition-model：人脸识别模型的路径。
- face-detection-labels：人脸检测标签的路径。
- face-recognition-labels：人脸识别标签的路径。
- face-recognition-settings：人脸识别设置标签的路径。
- facemap-3dmm-settings：facemap-3dmm 设置标签的路径。
|
## 相关信息
- [目标检测](https://docs.qualcomm.com/doc/80-70022-50SC/topic/gst-ai-object-detection.html)
- [姿态检测](https://docs.qualcomm.com/doc/80-70022-50SC/topic/gst-ai-pose-detection.html)
**Parent Topic:** [运行 AI/ML 示例应用程序](https://docs.qualcomm.com/doc/80-70022-50SC/topic/ai-ml-sample-applications.html)
Last Published: Nov 05, 2025
[Previous Topic
人脸检测](https://docs.qualcomm.com/bundle/publicresource/80-70022-50SC/topics/gst-ai-face-detection.md) [Next Topic
音频分类](https://docs.qualcomm.com/bundle/publicresource/80-70022-50SC/topics/audio-classification.md)