在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

ageitgey/face_recognition

菜单

核心API

相关源文件

核心 API 是 face_recognition 库的基础，提供了人脸检测、面部特征提取和人脸识别的核心功能。本文档介绍了驱动该库功能的 Python 主要函数、它们的参数、返回值以及常见的用法模式。

有关命令行工具的信息，请参阅 命令行接口。有关示例和高级用法，请参阅 示例和用法。

概述

核心 API 由实现完整人脸识别流程的几个关键函数组成。这些函数设计得易于使用，同时又利用了 dlib 提供的强大机器学习模型。

来源： face_recognition/api.py1-7 README.md257-261

核心组件

图像加载

使用人脸识别功能的第一步是加载图像进行处理。

load_image_file(file, mode='RGB')

将图像文件加载到 NumPy 数组中进行处理。

参数

  • file：图像文件名或文件对象（支持 JPG、PNG 等）
  • mode：要转换为的格式（默认为 'RGB'）

返回值

  • 包含图像数据的 NumPy 数组

示例

来源： face_recognition/api.py78-89 README.md257-261

人脸检测

加载图像后，下一步通常是检测其中的人脸。

face_locations(img, number_of_times_to_upsample=1, model="hog")

查找图像中的所有人脸位置。

参数

  • img：图像的 NumPy 数组
  • number_of_times_to_upsample：放大图像的次数（次数越多，检测到的小人脸越多）
  • model：要使用的检测模型
    • "hog"：速度更快但准确度较低，在 CPU 上运行（默认）
    • "cnn"：更准确，但需要 GPU/CUDA 才能获得良好性能

返回值

  • 按 (top, right, bottom, left) 顺序排列的人脸位置元组列表

示例

batch_face_locations(images, number_of_times_to_upsample=1, batch_size=128)

用于在图像批次中查找人脸的 GPU 优化函数。

参数

  • images：图像 NumPy 数组列表
  • number_of_times_to_upsample：放大图像的次数
  • batch_size：每个批次要处理的图像数量

返回值

  • 包含每张图像人脸位置的列表的列表

来源： face_recognition/api.py92-151 README.md257-288

面部特征分析

检测到人脸后，您可以提取面部标志（特定面部特征）。

face_landmarks(face_image, face_locations=None, model="large")

识别检测到人脸中的特定面部特征。

参数

  • face_image：图像的 NumPy 数组
  • face_locations：可选的面部位置列表（如果已检测）
  • model：要使用的特征检测模型
    • "large"：68 点模型，具有详细特征（默认）
    • "small"：5 点模型，仅包含眼睛和鼻子（速度更快）

返回值

  • 包含按名称（眼睛、鼻子等）划分的面部特征的字典列表

示例

大模型提供的面部特征

  • 下巴
  • 左眉
  • 右眉
  • 鼻梁
  • 鼻尖
  • 左眼
  • 右眼
  • 上唇
  • 下唇

小模型提供

  • 鼻尖
  • 左眼
  • 右眼

来源： face_recognition/api.py154-200 README.md292-300 examples/find_facial_features_in_picture.py1-27

人脸编码与识别

人脸识别流程的最后一步涉及生成人脸编码并进行比较。

face_encodings(face_image, known_face_locations=None, num_jitters=1, model="small")

为每个人脸生成一个 128 维的编码。

参数

  • face_image：图像的 NumPy 数组
  • known_face_locations：可选的人脸位置列表（如果已检测）
  • num_jitters：计算编码时重新采样的次数（次数越多，准确度越高，但速度越慢）
  • model：要使用的特征模型（"small" 或 "large"）

返回值

  • 128 维人脸编码列表（每人脸一个）

compare_faces(known_face_encodings, face_encoding_to_check, tolerance=0.6)

将一张人脸编码与已知编码列表进行比较以查找匹配项。

参数

  • known_face_encodings：已知人脸编码列表
  • face_encoding_to_check：要与列表进行比较的人脸编码
  • tolerance：用于将人脸视为匹配的阈值（值越低，要求越严格，默认值为 0.6）

返回值

  • 布尔值列表，指示哪些已知编码匹配

face_distance(face_encodings, face_to_compare)

计算人脸编码之间的欧氏距离。

参数

  • face_encodings：要比较的人脸编码列表
  • face_to_compare：要进行比较的人脸编码

返回值

  • 距离的 NumPy 数组（值越低表示人脸越相似）

完整的识别流程示例

来源： face_recognition/api.py203-226 README.md307-326

常见使用模式

以下是核心 API 的典型用法模式

基本人脸检测

完整人脸识别工作流程

模型选择指南

模型优点缺点用例
HOG（人脸检测）速度快，可在 CPU 上运行准确度较低实时应用、资源受限的设备
CNN（人脸检测）更准确，可检测到更小的人脸需要 GPU 才能获得良好性能批量处理，在准确性至关重要时使用
Small（面部特征）更快仅 5 个点只需要基本的眼睛/鼻子位置
Large（面部特征）详细的面部特征更慢需要详细的面部特征

来源： face_recognition/api.py1-226 README.md248-326

技术实现细节

核心 API 函数充当 dlib 的 C++ 实现人脸检测和识别算法的 Python 包装器。关键技术组件包括：

  1. 人脸检测模型:

    • 基于 HOG 的检测器：使用方向梯度直方图和线性 SVM 分类器
    • 基于 CNN 的检测器：使用专门为人脸检测训练的深度神经网络

  2. 人脸识别模型:

    • 使用 ResNet 网络训练以生成 128D 人脸编码
    • 这些编码具有同一人脸的编码距离更近的特性

  3. 内部函数:

    • _raw_face_locations：用于获取 dlib 人脸检测结果的底层函数
    • _raw_face_landmarks：用于获取 dlib 面部特征预测的底层函数
    • _rect_to_css 和 _css_to_rect：在 dlib 矩形和 CSS 样式元组之间进行转换

来源： face_recognition/api.py16-29 face_recognition/api.py32-60

性能考量

在使用核心 API 时，请考虑这些性能优化项

  1. 模型选择:

    • HOG 检测比 CNN 快得多，但准确度较低
    • Small 特征模型比 Large 模型快

  2. 批处理:

    • 使用 batch_face_locations() 对多个图像进行 GPU 加速批量处理

  3. 重复使用检测结果:

    • 当调用多个函数（例如，特征和编码）时，一次计算人脸位置，然后将其传递给后续函数

  4. 调整参数:

    • number_of_times_to_upsample：值越低速度越快，值越高检测到的小人脸越多
    • num_jitters：值越高，编码越准确，但速度越慢

来源： face_recognition/api.py108-145 face_recognition/api.py203-214