# 人脸识别
Source: [https://docs.qualcomm.com/doc/80-70018-50SC/topic/gst-ai-face-recognition.html](https://docs.qualcomm.com/doc/80-70018-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，该 pipeline 接收输入，执行预处理，在 AI 硬件上运行推理，并在屏幕上显示结果。
Figure : gst-ai-face-recognition pipeline
有关 pipeline 流中使用的插件的信息，请参见 [Pipeline 流](https://docs.qualcomm.com/doc/80-70018-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.labels
- face_recognition.labels
- face_landmark.labels
|
## 前提条件
- 如果还没有安装 eSDK，请[下载并安装 eSDK](https://docs.qualcomm.com/bundle/publicresource/topics/80-70018-51/install-sdk.html#download-and-install-esdk-)。
- [下载模型和标签文件](https://docs.qualcomm.com/doc/80-70018-50SC/topic/download-model-and-label-files.html)。
- 要访问主机，请启用 SSH。有关说明，请参阅[使用 SSH 登录](https://docs.qualcomm.com/bundle/publicresource/topics/80-70018-254/how_to.html#use-ssh)。
Note: 如果 SSH 已启用，则可以跳过此步骤。
- 从 Linux 主机推送模型文件。
scp root@:/etc/modelsCopy to clipboard
- 请注意，[下载的脚本](https://docs.qualcomm.com/doc/80-70018-50SC/topic/download-model-and-label-files.html)会将示例 video.mp4 视频下载到 /etc/media 目录。如果您使用的是自定义视频，请确保将视频推送到 /etc/media，并在应用程序的 config.JSON 文件中更新文件路径。
- 使用 HDMI 端口将显示器连接到设备。有关说明，请参见[设置 HDMI 显示器](https://docs.qualcomm.com/bundle/publicresource/topics/80-70018-18/samples.html)。
- 启用显示器：
export XDG_RUNTIME_DIR=/dev/socket/weston && export WAYLAND_DISPLAY=wayland-1Copy to clipboard
如果启用摄像头或显示器时遇到问题，请参阅[摄像头故障排除](https://docs.qualcomm.com/bundle/publicresource/topics/80-70018-17/troubleshooting.html)和[显示器故障排除](https://docs.qualcomm.com/bundle/publicresource/topics/80-70018-18/debug.html)。
- 下载以下 Qualcomm AI Engine Direct 模型：
- [face_det_quantized](https://aihub.qualcomm.com/iot/models/face_det_lite_quantized?searchTerm=face)
- [face_attrib_net_quantized](https://aihub.qualcomm.com/iot/models/face_attrib_net_quantized?searchTerm=face)
- 将这些模型推送到目标设备上的 /etc/models 目录。
scp face_det_lite_quantized.bin root@:/etc/modelsCopy to clipboard
scp face_attrib_net_quantized.bin root@:/etc/modelsCopy to clipboard
## 注册人脸进行面部识别
在运行 gst-ai-face-recognition 应用程序之前，您可以注册一张人脸，用于进行安全验证和身份验证。
1. 要注册人脸，请在目标设备的 shell 使用以下 gst-pipeline：
gst-pipeline-app -e \
qtimlvconverter name=stage_01_preproc mode=image-batch-non-cumulative \
qtimlqnn name=stage_01_inference model=/etc/models/face_det_lite_quantized.bin backend=/usr/lib/libQnnHtp.so \
qtimlvdetection name=stage_01_postproc stabilization=false threshold=40.0 results=4 module=qfd labels=/etc/labels/face_detection.labels \
qtimlvconverter name=stage_03_preproc mode=roi-batch-cumulative \
qtimlqnn name=stage_03_inference model=/etc/models/face_attrib_net_quantized.bin backend=/usr/lib/libQnnHtp.so \
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
随即显示一个选项列表。
2. 要准备采集人脸图像，请执行以下操作：
1. 从列表中选择以下选项：
1. `(3)PLAYING`：将 pipeline 切换至 Playing 状态。
2. `(p)Plugin Mode` ➔ `(26)camsrc`➔ `(37)capture-image`：使用摄像头源采集图像。
2. 使用显示器上的实时预览功能，面向摄像头，确保摄像头指向正前方，并且画面中只有一个人。
3. 在终端中，为以下值输入 1：
1. 为 `arg0` 输入 `GstImageCaptureMode`。
2. 为 `arg1` 输入 `guint`。
3. 要采集脸部所有侧面，请选择 `capture-image`，并对每侧执行以下操作：
1. 左侧和右侧：将头部左转 40°，同时保持特征点清晰可见，然后重复步骤 3 和 4。将头部右转 (40°)，然后重复上述步骤。
2. 向上和向下：抬头 30°，同时保持特征点清晰可见，然后重复步骤 3 和 4。低头 (30°)，然后重复上述步骤。
4. 要停止 pipeline，请使用 `(b)Back` 和 `(q)Quit`。
运行 pipeline 后，会创建五个单独的张量 bin（tensor\_0.bin 至 tensor\_4.bin），用于记录每一侧的面部属性。
5. 在目标设备上，转到 /etc/data/，找到这些张量 bin。要将张量 bin 从目标设备拉取到 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
6. 要将包含所有面部属性的张量 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 二进制文件。
7. 将 face.bin 二进制文件推送到 /etc/data 目录，并将其重命名为 face0.bin。
scp face.bin root@:/etc/data/face0.binCopy to clipboard
8. 要生成 face\_recognition.labels 文件并将新人注册到数据库中，请使用以下双人人脸注册的参考标签文件：
(structure)",id=(guint)0x0,database=(string)/etc/data/face0.bin,color=(guint)0x00FF00FF;"Copy to clipboard
(structure)",id=(guint)0x01,database=(string)/etc/data/face1.bin,color=(guint)0x00FF00FF;"Copy to clipboard
Note: 根据列表中的编号更新 ID 字段。如果要注册更多人脸，请在 face\_recognition.labels 文件中另起新行添加对应结构。
9. 要保存标签，请将更新后的 face\_recognition.labels 文件推送到目标设备上的 /etc/labels 目录。
scp face_recognition.labels root@:/etc/labelsCopy to clipboard
## 运行应用程序
Note: 以下命令提供默认模型和标签路径。如果您的文件夹结构不同，请替换命令行参数中的默认路径。参见[示例模型和标签文件](https://docs.qualcomm.com/doc/80-70018-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. 使用以下格式的 `/etc/configs/config-face-recognition.json`
文件：
{
"ml-framework": "",
"face-detection-model": "",
"face-landmark-model":"",
“face-recognition-model”:””,
"face-detection-labels":””,
"face-landmark-labels":””,
"face-recognition-labels":””,
"face-detection-constants":””,
"face-landmark-constants":””,
"face-recognition-constants":””
}Copy to clipboard
Note: 根据模型、输入流和其他属性更新 config JSON
文件。关于更多详细信息，请参阅 [Config JSON 字段说明](https://docs.qualcomm.com/doc/80-70018-50SC/topic/gst-ai-face-recognition.html#gst-ai-face-recognition__section_qjx_hqq_32c)。
例如，使用
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.labels",
"face-landmark-labels": "/etc/labels/face_landmark.labels",
"face-recognition-labels": "/etc/labels/face_recognition.labels",
"face-detection-constants": "DET,q-offsets=<178.0, 0.0, 102.0>,q-scales=<0.034
"face-landmark-constants":"DMM,q-offsets=<211.0>,q-scales=<0.06002333015203476
"face-recognition-constants":"qfr,q-offsets=<124.0, 153.0, 125.0, 133.0, 126.0
}Copy to clipboard
2. 运行 gst-ai-face-recognition 应用程序：
gst-ai-face-recognition --config-file=/etc/configs/config-face-recognition.jsonCopy to clipboard
请在 SSH shell 中运行以下命令，以显示可用的帮助选项：
gst-ai-face-recognition -hCopy to clipboard
要停止用例，请按 CTRL + C。
## 预期输出
## Pipeline 流
下表列出了人脸识别 pipeline 中使用的插件：| 插件 | 说明 |
| --- | --- |
| 摄像头源：[qtiqmmfsrc](https://docs.qualcomm.com/doc/80-70018-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-70018-50SC/topic/v4l2h264dec.html) | 解码视频 |
| [qtimlvconverter](https://docs.qualcomm.com/doc/80-70018-50SC/topic/qtimlvconverter.html) |
- 在其接收端口上接收视频流。
- 对流数据执行以下预处理。当模型需要浮点值作为输入时，会执行此预处理。
- 颜色转换
- 缩放（放大或缩小）
- 归一化
- 将预处理的视频流转换为其发送端口上的张量数据流。
张量数据流用于 pipeline 后期的推理。 |
| [qtimlqnn](https://docs.qualcomm.com/doc/80-70018-50SC/topic/qtimlqnn.html) | 充当 Qualcomm Neural Network 模型的推理插件。
- 推理 runtime 在其接收端口上接收到张量数据后，会运行推理。
- 生成一个张量数据流，并在其发送端口上显示推理结果。
|
| [qtimlvdetection](https://docs.qualcomm.com/doc/80-70018-50SC/topic/qtimlvdetection.html) |
- 处理来自任何人脸检测模型的推理结果。
- 将阈值应用于所选结果数。
|
| [qtimetamux](https://docs.qualcomm.com/doc/80-70018-50SC/topic/qtimetamux.html) |
- 从 qtimlvdetection 接收人脸检测模型的输出并将其进行复用。
- 从 qtimlvpose 接收面部姿态的输出并将其进行复用。
|
| tee | 分割流以进行推理。 |
| [qtimlvpose](https://docs.qualcomm.com/doc/80-70018-50SC/topic/qtimlvpose.html) | 执行面部姿态识别。 |
| [qtimlvclassification](https://docs.qualcomm.com/doc/80-70018-50SC/topic/qtimlvclassification.html) | 接收来自 qtimetamux 的流并对人脸进行分类。 |
| [qtivoverlay](https://docs.qualcomm.com/doc/80-70018-50SC/topic/qtioverlay.html) |
- 接收复用流。
- 将边界框叠加在流上。
|
| [Waylandsink](https://docs.qualcomm.com/doc/80-70018-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-70018-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-landmark-labels：人脸特征点标签的路径。
- face-recognition-labels：人脸识别标签的路径。
|
| **Constants** |
- face-detection-constants：人脸检测模型常量。
- face-landmark-constants：人脸特征点模型常量。
- face-recognition-constants：人脸识别模型常量。
|
## 已知问题
使用 LiteRT 模型时未观察到 3D 人脸特征点。
**Parent Topic:** [运行 AI/ML 示例应用程序](https://docs.qualcomm.com/doc/80-70018-50SC/topic/ai-ml-sample-applications.html)
**Related Resources**
- [目标检测](https://docs.qualcomm.com/doc/80-70018-50SC/topic/gst-ai-object-detection.html)
- [姿态检测](https://docs.qualcomm.com/doc/80-70018-50SC/topic/gst-ai-pose-detection.html)
Last Published: Nov 12, 2025
[Previous Topic
人脸检测](https://docs.qualcomm.com/bundle/publicresource/80-70018-50SC/topics/gst-ai-face-detection.md) [Next Topic
音频分类](https://docs.qualcomm.com/bundle/publicresource/80-70018-50SC/topics/audio-classification.md)