人脸识别 0.16.0 和 以上版本

提示

人脸识别功能需要依赖外部下载的模型文件。相关模型托管在 Github 上。

如果你在中国大陆地区，请参考通过 Docker 安装的教程，在environment中配置GITHUB_ENDPOINT环境变量，否则功能可能无法正常使用。

人脸识别功能通过将检测到的人脸与预先学习的人脸数据进行匹配，来识别已知的人员。当识别出已知人员（person）时，他们的姓名将作为子标签（sub_label）添加。这些信息会显示在页面、过滤器中，也会包含在通知中。

模型要求

人脸检测

如果你的目标/物体检测模型支持检测人脸（face），例如 Frigate+ 模型，应确保在追踪目标列表中添加face标签，该设置可以是全局设置或只针对特定摄像头。这将允许人脸检测与物体/目标检测同时运行，提高效率。

如果你的模型不支持检测人脸目标（例如 Frigate 默认的 COCO 模型或其他不包含face作为可检测标签的模型时），人脸检测将通过 CV2 使用运行在 CPU 上的轻量级 DNN 模型进行。在这种情况下，你不应在追踪目标列表中定义face。

NOTE

Frigate 需要先检测到 人（person） 后才能检测和识别人脸。

人脸识别

Frigate 支持两种人脸识别模型类型：

• small(小型): Frigate 将运行 FaceNet 嵌入模型进行人脸识别，该模型在 CPU 上本地运行。此模型针对效率进行了优化，但准确性较低。
• large(大型): Frigate 将运行大型 ArcFace 嵌入模型，该模型针对准确性进行了优化。建议仅在拥有核显或独立显卡以及 NPU 时使用。更多信息请参阅功能增强文档。

在这两种情况下，都会使用轻量级的人脸关键点检测模型在运行识别前对齐人脸。

所有系统特性都是在你本地进行的，不会上传至云端。

最低系统要求

运行人脸识别需要 CPU 支持 AVX + AVX2 指令集。

small模型针对效率进行了优化，可在 CPU 上运行，大多数 CPU 都能高效运行该模型。

large模型针对准确性进行了优化，强烈建议使用核显或独立显卡以及 NPU。

配置

人脸识别默认禁用，必须在 UI 界面或配置文件中启用后才能使用。人脸识别是全局配置设置。

face_recognition:
  enabled: true

与 Frigate 的其他实时处理器一样，人脸识别功能依赖于配置文件中detect功能定义的摄像头视频流。为确保最佳性能，请根据实际监控场景和需求，在摄像头固件中为此视频流设置合适的分辨率。

高级配置

使用以下可选参数在配置的全局级别微调人脸识别。在摄像头级别只能设置 enabled 和 min_area 这两个可选参数。

检测

• detection_threshold: 运行识别前所需的人脸检测置信度分数：
  • 默认值: 0.7
  • 注意: 此字段仅适用于独立的人脸检测模型，对于内置人脸检测的模型应使用min_score进行过滤。
• min_area: 定义运行识别前人脸的最小尺寸(以像素为单位)。
  • 默认值: 750像素。
  • 根据摄像头detect流的分辨率，可以增加此值以忽略过小或过远的人脸。

识别

• model_size: 使用的模型大小，可选small或large
• unknown_score: 将人员标记为潜在匹配的最低分数，低于此分数的匹配将被标记为未知。
  • 默认值: 0.8。
• recognition_threshold: 将人脸添加为目标子标签所需的识别置信度分数。
  • 默认值: 0.9。
• min_faces: 需满足最低人脸检测次数，子标签才会应用于目标人员。
  • 默认值: 1
• save_attempts: 保存用于训练的已识别人脸图片数量。
  • 默认值: 200。
• blur_confidence_filter: 启用计算人脸模糊程度并据此调整置信度的过滤器。
  • 默认值: True。
• device：指定在特定设备上运行人脸识别模型（适用于多 GPU 安装）。
  • 默认值：None。
  • 注意：此设置仅在使用 large 模型时适用。参见 onnxruntime 的执行提供程序选项。

使用方法

请按照以下步骤开始：

1. 在配置文件中启用人脸识别功能并重启 Frigate。
2. 使用 Frigate 页面中的 人脸管理 部分的 添加人脸 按钮向导 上传人脸。然后阅读下方内容，了解扩展训练集的最佳做法。
3. 当 Frigate 检测并尝试识别人脸时，它会出现在人脸管理的训练标签页中，同时显示相关的识别置信度。
4. 在 训练 标签页中，你可以将人脸分配给新的或现有的人员，以提高未来的识别准确性。

创建完备的训练集

提示

简短版：从每个人几张清晰、正面的照片开始。随着人脸在"近期识别"标签页中被检测到，训练那些得分较低但仍然清晰的图片，慢慢增加多样性（不同角度、光照和表情）。多样性远比数量重要，低质量图片对识别的损害大于帮助。

有关这些最佳实践的逐步讲解（以及应用于状态和目标分类的相同原则），请参阅 Frigate Tips: Best Practices for Training 讨论帖。

人脸识别所需的足够训练集图片数量取决于多个因素：

• 数据集的多样性：包含不同的光照、姿态和面部表情变化的多样化数据集，每个人所需的图片数量会比多样性较低的数据集少。
• 期望的准确性：期望的准确性越高，通常需要的图片越多。

以下是一些通用指导原则：

• 最低要求：对于基本人脸识别任务，通常建议每人至少 5-10 张图片。
• 推荐：如果希望更健全和准确的识别，推荐每人至少 20-30 张图片。
• 理想情况：为了获得最佳性能，特别是在环境复杂的情况下，每人 50-100 张图片会更好。

人脸识别的准确性很大程度上取决于训练数据的质量。建议分阶段构建人脸训练库。

提示

选择包含在人脸训练集中的图片时，建议始终遵循以下建议：

• 如果你的摄像头录制的人脸并不清晰，请不要在人脸识别页面直接添加这些照片来进行训练，这些模糊的照片会极大的干扰训练。
• 如果难以辨认人物面部的细节，则对训练没有帮助。
• 避免曝光过度/不足的图片。
• 避免模糊/像素化的图片。
• 避免使用红外线(灰度)图片进行训练。模型是在彩色图片上训练的，能够从灰度图片中提取特征。
• 使用戴帽子/太阳镜的人物图片可能会混淆模型。
• 不要一次性上传过多相似的图片，建议每人训练不超过 4-6 张相似图片，以避免过拟合。

关于"近期识别"标签页 ​​

在人脸管理的 ​​"训练"标签页 ​​ 中，会显示近期的人脸识别尝试记录。系统会将检测到的人脸图片按照其可能匹配的人员进行分组。

每张人脸图片都会标注一个名称（或标记为未知），并附带此次识别的置信度分数。虽然每张图片都可以用于特定人员的系统训练，但并非所有图片都适合用于训练。

请参考以下指南，了解选择训练图片的最佳实践。

Frigate 如何判断一个人是谁

识别不是逐帧进行的。当 person（人员）在视野中时，Frigate 对多个帧运行人脸识别，而不仅仅是单个帧。最终的 sub_label（子标签）是根据所有尝试共同决定的，并按每个人脸的面积加权（更大、更近的人脸权重更高），而不是来自任何单个帧。

这有几个实际影响：

• 少数错误猜测在模糊或远距离的帧上通常不会改变结果。如果 Frigate 看到一个人是"Tom, Tom, Sam, Tom, Tom"，它仍然会得出这个人是 Tom 的结论。
• 目标不是让每个人脸截图都正确。目标是让每个人在其出现的整个过程中被正确识别，综合所有捕获的人脸来判断。
• 单次非常高的置信度匹配不会单独分配子标签。识别必须一致。参见下方我在近期识别标签页中看到高于阈值的分数，但没有分配子标签？。

哪些人脸值得训练？

一张人脸是否值得训练与其被识别为什么关系不大。当以下所有条件都满足时，截图才是好的训练候选：

• 它尚未得分很高且正确。已经被自信识别的人脸添加价值有限，且增加过拟合风险。
• 它足够清晰可用：不模糊、不是严重侧脸、不是红外（灰度）。如果连你都难以辨认这张脸，它对模型也没有帮助。
• 它添加了新信息：与你已有的相比，不同的角度、光照、表情或距离。

第一步 - 打好基础

首次启用人脸识别时，建立高质量的图片数据集基础非常重要。建议首先为每个人上传 1-5 张"肖像"照片。确保照片中人物的面部是正面的，没有侧转，这将提供一个良好的起点。

然后建议使用 Frigate 中的人脸管理选项卡，在检测到每个人时选择和训练图片。在建立坚实基础时，强烈建议仅训练正面图片。忽略从识别侧面人脸的摄像头获取的图片。

目标是平衡图片质量的同时，也要包含各种条件(白天/夜晚、不同天气、不同时间段等)的图片，以确保每个人的训练图片具有多样性，避免过拟合。

一旦某个人开始在正面训练图片上持续被正确识别（置信度>90%），这些图片已经被可靠识别。本步骤的目标是训练清晰但置信度较低的正面图片，直到给定人物的绝大多数正面图片都能被持续正确识别。然后就可以进入下一步。

第二步 - 扩展数据集

当正面图片的识别表现良好后，开始选择稍微有角度的图片进行训练。重要的是仍然选择那些能看到足够面部细节以识别某人的图片。

常见问题

让识别开始工作

如何调试人脸识别问题？

请从使用方法说明章节开始，并重新阅读上方模型要求的说明。

1.确保系统能检测到 person 目标。Frigate 会自动对检测到的person进行人脸扫描，所有识别到的人脸将显示在 Frigate 界面"人脸管理"的"近期识别"标签页中。

若你使用的是 Frigate+ 或能检测 face 的模型：

• 通过调试页面确认系统是否同时检测到person和face目标
• 若未检测到人脸，可能需要调整 face 目标的 min_score 阈值

若你未使用 Frigate+ 或能检测 face 的模型：

• 检查 detect 视频流的分辨率，确保其足够高以捕捉 person 目标的人脸细节
• 若人脸检测失败，可能需要降低detection_threshold阈值

2. 所有检测到的人脸将进入识别阶段：

• 请确保已按照上述建议完成至少一个人脸样本的训练
• 根据上文说明调整recognition_threshold参数

人脸识别会在录制流上运行吗？

人脸识别不会在录制流上运行，这有很多不利原因：

1. 访问录制的延迟意味着通知中不会包含已识别人员的姓名，因为识别要到之后才能完成。
2. 使用的嵌入模型在固定图片尺寸上运行，因此较大的图片会被缩小以匹配。
3. 运动清晰度比额外像素重要得多，过度压缩和运动模糊对结果的影响比分辨率更大。

提高准确性和训练

模糊的画面会影响检测效果吗？

检测精度确实会随着摄像头/视频流质量的提升而改善。

若你使用的摄像头标注了DORI（检测-观察-识别-辨认）参数范围，建议重点关注该指标。这个技术参数定义了摄像头在不同距离上对人体实现检测、观察、识别和辨认的能力范围。其中"辨认"距离最为关键——摄像头标称的这个距离值，实际上就是人脸识别功能能够稳定生效的最远物理距离。

部分用户反馈，将摄像头设置中的码流设置为固定码率（CBR）相比可变码率（VBR），画面中的人脸将更加清晰。

我可以为只在夜间出现的人训练人脸吗？

嵌入模型是在彩色图片上训练的，因此灰度和红外（IR）人脸处于不同的特征分布中，更容易与其他人员混淆。优先使用彩色图片，在打好基础期间避免混合灰度样本。如果有人只在夜间出现，灰度训练是可以接受的，但应保持样本有限且尽可能清晰，并且只有在其他人物的彩色识别稳定后再添加。

为什么不能批量上传照片？

有方法地添加照片到库中非常重要，批量导入照片（特别是来自普通照片库）会导致特定场景下的过拟合，降低识别性能。

为什么不能批量重新处理人脸？

人脸嵌入模型的工作原理是将人脸分解为不同的特征。这意味着当重新处理图片时，只有角度相似的图片才会影响其分数。

为什么未知人员的分数与已知人员相似？

这可能由几个不同原因引起，但通常表明训练集需要改进。这通常与过拟合有关：

• 如果每个人只训练少量图片，特别是这些图片非常相似时，识别模型会过度专门化于这些特定图片。
• 当提供不同姿态、光照和表情的图片时，算法会提取这些变化中一致的特征。
• 通过在多样化的图片集上训练，算法对输入图片中的微小变化和噪声变得不那么敏感。

检查你的人脸集合，移除大部分不清晰或低质量的图片。然后使用训练标签页中每个人脸上的重新处理按钮，评估这些更改如何影响识别分数。

避免训练已经得分很高的图片，因为这可能导致过拟合。相反，应专注于对相对清晰但得分较低的图片（理想情况下具有不同光照、角度和条件）进行训练，以帮助模型更有效地泛化。

我应该纠正被误识别为错误人员的人脸吗？

只有当它是好的图片时才应该。重新分配人脸确实会将其添加到该人员的训练集中，但两个事实同时成立：

• 重新分配单个误分类帧的效果很小。该图片会与该人员的所有其他样本加权平均，因此从 20 帧中纠正 1 帧不会显著改变识别结果。在质量差的帧上偶尔出现错误猜测是正常的，不需要修复。
• 重新分配质量差的图片（模糊、侧面、低分辨率、灰度）可能比误识别造成的伤害更大，因为低质量样本会降低该人员的整体识别质量。

所以决定因素是图片质量，而不是错误的标签。如果截图清晰、光照良好且相对正面，并且得分低或被误识别，将其分配给正确的人员是有用的。如果连你自己都难以辨认这张脸，忽略它；不要仅仅为了纠正标签而训练它。

如果某个人反复被误识别，不要一直重新分配相同的帧。相反，移除低质量或误导性的图片，并为正确的人员添加一些高质量样本。参见上方为什么未知人员的分数与已知人员相似？。

Frigate 将某张人脸误识别了。我能否告知它某张人脸"不是"某个特定的人？

不可以，人脸识别功能不支持负样本训练（即明确告知系统某人不是某个特定目标）。

最佳解决方案是通过为每个人提供更多样化且具有代表性的图片集，并且使用高质量的照片进行训练，从而优化训练数据质量。

这也适用于陌生人反复被匹配为已知人员的情况（例如快递司机被识别为你）。不要为他们创建档案，不要将他们的人脸重新分配给你自己，因为这会污染你的训练集并使识别变得更糟。将检测结果保留为未知，而是改进已知人员的训练集。人脸识别学习的是某人是谁，而非某人不是谁。

在训练选项卡中看到分数超过阈值，但没有分配子标签？

Frigate 会考虑每个人物目标的所有识别尝试的分数。分数会根据人脸区域持续加权，只有当一个人物被持续自信地识别时，才会为其分配子标签。这避免了单次高置信度识别影响结果的情况。

兼容性和维护

可以同时使用其他人脸识别软件(如 DoubleTake)和内置的人脸识别吗？

不可以，使用其他人脸识别服务会干扰 Frigate 内置的人脸识别。当使用 double-take 时，如果还希望使用内置的人脸识别功能，必须禁用 sub_label 功能。

直接用 iPhone 拍照时出现未知错误

iOS 设备默认使用 HEIC（高效图片容器）格式保存照片，但该格式不支持上传。若选择large格式（而非original原生），系统将自动转换为 JPG 格式，从而确保正常上传。

如何删除人脸数据库并重新开始？

Frigate 在其数据库中不存储任何与人脸识别相关的内容。你可以通过以下两种方式之一重置人脸数据库：

• 通过 Frigate 用户界面直接删除所有人脸数据
• 删除/media/frigate/clips/faces目录下的所有内容