face_recognition 版本演进全解析：从 HISTORY.rst 看 Python 人脸识别库的功能里程碑与实现细节

face_recognition 版本演进全解析从 HISTORY.rst 看 Python 人脸识别库的功能里程碑与实现细节【免费下载链接】face_recognitionThe worlds simplest facial recognition api for Python and the command line项目地址: https://gitcode.com/gh_mirrors/fa/face_recognition本篇技术指南以开源仓库 docs/history.rst通过.. include:: ../HISTORY.rst引入的完整版本历史为骨架系统梳理 face_recognition 从 0.1.7 到 1.4.0 的功能演进脉络并结合仓库核心源码face_recognition/api.py、face_recognition/face_recognition_cli.py、face_recognition/face_detection_cli.py逐一还原每一项版本声明的底层实现。读完本文你将掌握该库的检测/特征点/编码三大核心 API 的演进逻辑、命令行参数体系的由来以及各版本在 Python 版本支持、模型选择与性能优化上的取舍。一、版本历史总览一条清晰的演进时间线HISTORY.rst 记录了项目从 2017 年 3 月首个可用版本0.1.7到 2020 年 9 月 1.4.0 的完整变更。将全部版本按时间排序可得到如下演进主线版本发布日期核心变更主题0.1.72017-03-13首个可工作版本0.1.82017-03-16修复缺失的 Pillow 依赖0.1.92017-03-16修正最小 scipy 版本要求0.1.102017-03-21人脸比对性能小优化、测试更新0.1.112017-03-30命令行接口小 bug 修复0.1.122017-04-13修复人脸关键点未返回全部下巴点0.1.132017-04-20支持 Raspberry Pi0.1.142017-04-22修复 Python 2.7 下 CLI 的 ValueError 崩溃0.2.02017-06-03CLI 支持多 CPU-cpus、新增 face_distance 示例0.2.12017-07-03CLI 新增--tolerance参数0.2.22017-07-07CLI 新增--show-distance、修复 tolerance 单图失效 bug1.0.02017-08-29引入 dlib CNN 人脸检测模型与 GPU 批量检测1.1.02017-09-23默认改用 5 点人脸姿态估计以提速1.2.02018-02-01修复 GPU 批量检测 batch size、示例全面更新1.2.12018-02-01修复模块内版本号编号1.2.22018-04-02新增 face_detection 命令、移除 scipy 依赖1.2.32018-08-21支持modelsmall5 点关键点模型、官方支持 Python 3.71.3.02020-02-20放弃 Python 3.4、新增 3.8、新增眨眼检测示例1.4.02020-09-26放弃 Python 2.x、CLI 新增--upsample参数这一时间线呈现出清晰的阶段划分0.1.x 为打基础阶段依赖修复、平台支持、0.2.x 为 CLI 能力成型阶段参数体系与多进程、1.0.0 为检测模型分水岭HOG 之外引入 CNN、1.1.0~1.2.x 为精度/速度平衡与工程化阶段、1.3.0/1.4.0 为 Python 版本策略收敛阶段。二、1.4.0 与 1.3.0Python 支持策略收敛与 CLI 新参数2.1 告别 Python 2.x走向 Python 3 单一支持1.4.02020-09-26最重要的决定是Dropping support for Python 2.x。这一决策在仓库的打包配置中得到印证setup.py 的classifiers只声明了Programming Language :: Python :: 3及 3.5~3.9 具体版本requirements.txt 中的依赖也全部面向 Python 3 生态。1.3.02020-02-20则完成了 Python 3 内部的支持档位调整放弃 Python 3.4新增 Python 3.8。结合 1.2.3 时官方支持 Python 3.7的声明可以推断项目在 Python 3 系内始终跟随当时的主流稳定版本。2.2--upsample参数CLI 查找小脸的能力1.4.0 记录为命令行 face_recognition 新增--upsample参数。从当前仓库源码看--upsample参数的完整实现位于 face_detection_cli.pyclick.option(--upsample, default0, helpHow many times to upsample the image looking for faces. Higher numbers find smaller faces.)其作用机制可以追溯到 api.py 中face_locations()的number_of_times_to_upsample参数——对输入图像进行上采样upsample的次数越多越能检出小尺寸人脸代价是计算量随之增大。默认值 0 表示不做上采样适合常规尺寸人脸处理合照中远距离的小脸时可适当调高该值。三、1.2.x 系列5 点模型、face_detection 命令与依赖瘦身3.1modelsmall68 点模型之外的轻量选择1.2.32018-08-21允许向face_landmarks()传入modelsmall以 5 点人脸模型替代默认的 68 点模型。源码实现位于 api.py模块加载阶段api.py同时初始化了两个 dlib 姿态预测器pose_predictor_68_point与pose_predictor_5_point模型文件分别由face_recognition_models包提供_raw_face_landmarks()根据model参数选择预测器small走 5 点预测器其余走 68 点预测器返回结构上modelsmall只给出三个部位api.pynose_tip、left_eye、right_eyemodellarge则给出 9 个部位chin、左右眉毛、鼻梁、鼻尖、左右眼、上下嘴唇。从 tests/test_face_recognition.py 的测试用例可以确认modelsmall返回的字典 key 集合恰为{nose_tip, left_eye, right_eye}且nose_tip为单点坐标。该参数同样作用于face_encodings()api.py其默认模型即为small——这与 1.1.0 中尽可能使用 5 点模型提升速度的思路一脉相承。3.2 face_detection 命令独立的人脸检测 CLI1.2.22018-04-02新增face_detectionCLI 命令。当前仓库通过 setup.py 的entry_points注册了两个控制台脚本face_recognitionface_recognition.face_recognition_cli:main, face_detectionface_recognition.face_detection_cli:mainface_detection与face_recognition的分工很清晰face_detectionface_detection_cli.py只做检测不涉及身份比对。接收单个图片或目录输出文件名,top,right,bottom,left格式的坐标行支持--cpus、--modelhog/cnn、--upsample三个选项face_recognitionface_recognition_cli.py做完整识别接收已知人脸目录与待查图片/目录输出文件名,人名或加距离格式支持--cpus、--tolerance、--show-distance。face_detection_cli.py 的坐标输出直接来自face_locations()返回的 (top, right, bottom, left) 元组def print_result(filename, location): top, right, bottom, left location print({},{},{},{},{}.format(filename, top, right, bottom, left))3.3 移除 scipy安装依赖大幅简化1.2.2 同时移除了对 scipy 的依赖以简化安装。对比 setup.py 当前的requirements列表可以验证requirements [ face_recognition_models0.3.0, Click6.0, dlib19.7, numpy, Pillow ]运行时依赖仅保留五个核心包scipy 已不在其中。需要注意examples 目录下的 blink_detection.py 仍import scipy.spatial但那只是示例代码的局部需求库本身不再强制要求 scipy。3.4 1.2.0示例工程化与 GPU 批量检测修复1.2.02018-02-01包含一批影响深远的工程化变更修复 GPU 批量人脸检测时 batch size 参数不生效的 bug对应的batch_size参数如今完整保留在 api.py 的batch_face_locations()与_raw_face_locations_batched()中默认 batch_size128用于控制每次送入 GPU 的图像数量OpenCV 示例统一做 BGR→RGB 转换因为 OpenCV 读取的图像是 BGR 通道顺序而 face_recognition 内部load_image_file 默认modeRGB面向 RGB。这一点在 find_faces_in_batches.py 等视频处理示例中通过frame[:, :, ::-1]显式完成新增 KNN 分类示例face_recognition_knn.py 与自动模糊人脸示例blur_faces_on_webcam.pyDockerfile 示例改用 dlib v19.9免去 boost 依赖相关配置见 docker/cpu/Dockerfile 与 docker/gpu/Dockerfile。1.2.1 则是一个纯粹的内部修复——保证 face_recognition/init.py 中的__version__ 1.4.0与 setup.py 的version字段始终保持一致避免出现版本号错位。四、1.1.0 与 1.0.0检测模型的两次关键转折4.1 1.0.0CNN 检测模型与 GPU 批量检测1.0.02017-08-29是整个项目能力升级的分水岭modelcnn参数face_locations()与_raw_face_locations()api.py支持通过model参数在两种检测器间切换——hog使用 dlib 的 HOG 正面人脸检测器CPU 快但精度较低为默认值cnn使用 dlib 的 CNN 深度模型api.py 中通过dlib.cnn_face_detection_model_v1加载精度更高且在带 CUDA 的 NVIDIA GPU 上可硬件加速GPU 批量检测新增batch_face_locations(images, number_of_times_to_upsample1, batch_size128)一次性处理一批同尺寸图像GPU 场景下吞吐量显著提升。对应示例 find_faces_in_batches.py 展示了以 128 帧为一批处理视频帧的完整流程该示例本身依赖 OpenCV 读取视频但 OpenCV 并非库的强制依赖新增示例find_faces_in_picture_cnn.py单图 CNN 检测注释明确指出没有 CUDA 的 GPU 时比 HOG 慢、facerec_from_video_file.py视频文件识别依赖下限提升dlib 最低版本升至 v19.5、face_recognition_models 最低版本升至 v0.2.0。4.2 1.1.05 点姿态估计带来的速度优化1.1.02017-09-23的核心优化是尽可能使用 dlib 的 5 点人脸姿态估计器代替 68 点模型以提升速度。这解释了为何 1.2.3 中modelsmall会作为face_encodings()的默认模型——对于只需左右眼与鼻尖三个参考点的 128 维编码计算而言5 点模型在精度损失可控的前提下显著更快。同时本版本将 dlib 最低版本提升到 v19.7、face_recognition_models 最低版本提升到 v0.3.0这两个下限与 setup.py 当前声明完全一致。五、0.2.x 系列命令行参数体系成型0.2.x 三个版本共同构建了face_recognition命令的完整参数体系这些参数至今仍是该命令的核心接口见 face_recognition_cli.py5.1 0.2.0多 CPU 并行-cpus0.2.02017-06-03让 CLI 可以利用多核 CPU只需传入-cpus X。当前实现中该参数名为--cpus默认 1-1表示使用系统全部核心face_recognition_cli.pyclick.option(--cpus, default1, helpnumber of CPU cores to use in parallel (can speed up processing lots of images). -1 means use all in system)底层通过multiprocessing.Pool实现进程池并行face_recognition_cli.py且针对 macOS 的 libdispatch bug 专门做了forkserver启动方式的兼容处理。当待查目标是目录时并行处理目录内所有图片目标为单图时直接串行调用test_image()。需要说明的是多进程并行仅在 Python 3.4 生效旧版本会自动回退到单线程并输出警告face_recognition_cli.py。5.2 0.2.1/0.2.2--tolerance与--show-distance0.2.12017-07-03新增--tolerance参数0.2.22017-07-07进一步新增--show-distance并修复了单张图片测试时--tolerance被忽略的 bug。这两个参数与 api.py 的compare_faces()语义直接对应--tolerance默认 0.6欧氏距离阈值数值越小判定越严格。compare_faces()内部即执行face_distance() tolerance--show-distance输出每个人脸匹配的精确距离值方便用户针对自己的数据集调优 tolerance。tests/test_face_recognition.py 对这两个参数都有回归测试--tolerance 0.55与--show-distance 1均能正确输出预期结果如obama.jpg,obama,0.0印证了 0.2.2 中实际测试 CLI 功能的改进声明。在 face_distance.py 示例中还可以看到如何直接使用face_distance()度量两张人脸编码的距离。六、0.1.x 早期版本从可用到跨平台0.1.x 阶段解决了跑得起来、跑得稳的问题其中三个节点值得注意0.1.8/0.1.9依赖修复修复缺失的 Pillow 依赖与最小 scipy 版本。Pillow 至今仍是核心依赖setup.py因为 load_image_file 完全基于PIL.Image完成图像读取与模式转换支持RGB与L两种 mode0.1.12下巴关键点修复Face landmarks wasnt returning all chin points。如今 api.py 中chin: points[0:17]明确返回全部 17 个下巴点tests/test_face_recognition.py 也以完整 17 点坐标断言验证0.1.13Raspberry Pi 支持对应示例 facerec_on_raspberry_pi.py 及其中文版 facerec_on_raspberry_pi_Simplified_Chinese.py0.2.0 时该示例还修正为以 RGB而非 BGR格式采集图像。0.1.14 修复了 Python 2.7 下 CLI 的 ValueError 崩溃这也是 1.4.0 最终放弃 Python 2 之前最后一次相关的兼容性修补。七、从版本历史看设计取舍三条可复用的经验7.1 检测器选择HOG 与 CNN 的正确打开方式综合 1.0.0、1.1.0 与 1.2.3 的演进可以看到清晰的性能分层策略场景推荐配置依据CPU、追求实时modelhognumber_of_times_to_upsample0~1HOG 检测器为默认CPU 友好api.py精度优先 / 有 CUDA GPUmodelcnnCNN 精度更高且可 GPU 加速api.py海量同尺寸图像 GPUbatch_face_locations(images, batch_size128)批量检测api.py关键点/编码速度优先face_landmarks(..., modelsmall)/face_encodings(..., modelsmall)5 点模型默认用于编码api.py找小脸增大number_of_times_to_upsample/--upsample上采样次数越高越能找到小脸7.2 CLI 输出契约稳定利于脚本化从 0.2.x 到 1.4.0face_recognition命令的 CSV 风格输出文件名,人名与face_detection命令的坐标输出文件名,top,right,bottom,left始终保持稳定配合--cpus、--tolerance、--show-distance等参数可无痛嵌入 shell 管道与自动化流程。7.3 依赖下限跟随上游模型版本历史记录中 dlib 与 face_recognition_models 的最低版本在 1.0.0v19.5 / v0.2.0和 1.1.0v19.7 / v0.3.0两次提升都对应着模型能力与库 API 的协同升级。在当前仓库中这一约束固化在 setup.py 的install_requires里安装时 pip 会自动校验。结语如何基于版本历史规划你的使用方式HISTORY.rst 不仅是一份变更记录更是一份浓缩的架构决策日志它告诉我们 face_recognition 在HOG 快 / CNN 准之间提供了可切换的双检测器在68 点全特征 / 5 点高速之间提供了可选的姿态模型并通过tolerance、upsample、cpus三个 CLI 旋钮把精度、召回与吞吐的权衡交给使用者。若你的部署环境是 Python 3.5~3.9 且需要最稳定的行为以当前仓库 setup.py 声明的依赖组合dlib19.7、face_recognition_models0.3.0为准即可若追求检测精度并拥有 NVIDIA GPU则优先使用modelcnn与batch_face_locations()所有 API 与参数的权威用法都可以在 face_recognition/api.py、face_recognition_cli.py 及其测试 tests/test_face_recognition.py 中逐一验证。【免费下载链接】face_recognitionThe worlds simplest facial recognition api for Python and the command line项目地址: https://gitcode.com/gh_mirrors/fa/face_recognition创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考