简介这套基于Python的员工人脸识别考勤系统面向需要实现摄像头实时检测与身份验证的中高级Python开发者结合OpenCV与Dlib完成人脸检测、特征点定位及模型训练可应用于企业门禁、课堂签到等场景。压缩包共657个文件大小196.19MB包含501个py源码、44个pyd动态库、22个exe可执行文件以及pth模型、xml配置、bat脚本、png图像等涵盖图像处理、模型训练、实时检测、记录报告等完整模块。已有2514人学习下载。项目以WorkAttendanceSystem-master组织目录除核心代码外还附带数据集、配置文件和README便于直接搭建运行。通过学习可掌握Haar级联、LBPH、Dlib 68点关键点及CNN人脸识别在真实考勤流程中的落地方式也能参考项目拆分与文件组织思路适合作为课程设计或企业二次开发的基础。1. 从“dilb”这个拼写说起OpenCV 与 dlib 在人脸识别考勤系统里的分工“dilb”是 dlib 的常见笔误很多分享源码的帖子都会打错这个库名。这类 Python OpenCV dlib 的员工考勤系统解决的是中小型公司在离线环境下做刷卡替代方案员工站到摄像头前系统判断这个人是谁、工号多少、今天是否已经打卡然后把记录写进考勤表。和刷指纹、刷工牌相比它不需要额外硬件一台带摄像头的 PC 或工控机就能跑。整套链路由三部分构成OpenCV 负责读取摄像头帧和图像预处理dlib 负责检测人脸、定位关键点、提取 128 维特征向量SQLite 或 MySQL 负责员工档案与打卡记录的持久化。很多人以为难点在算法实际上把“采集—检测—对齐—比对—写库”这条链串稳才是项目能否落地的关键。2. 环境搭建与版本匹配opencv 和 dlib 安装跑通的正确顺序2.1 先看编译工具链再装 dlib能少踩一半坑在“python安装教程”“opencv下载安装教程”这类检索词背后真正让新手卡住的是 dlib 的安装。dlib 在 PyPI 上主要以源码包方式发布pip install dlib 时会现场编译 C 代码Windows 上动不动报ModuleNotFoundError: No module named dlibLinux 上则常见CMake must be installed。以 Ubuntu 22.04 为例推荐按下面顺序执行sudo apt update sudo apt install -y build-essential cmake python3-dev python3-pip python3 -m venv ~/face_attendance source ~/face_attendance/bin/activate pip install --upgrade pip pip install numpy1.24.4 opencv-python4.8.1.78 dlib19.24.2这里把系统级编译工具装好再创建虚拟环境是为了让 dlib 源码编译时能找到 CMake 和 C 编译器。Windows 上同样的思路是提前装 Visual Studio Build Tools勾选“使用 C 的桌面开发”工作负载。numpy、opencv-python、dlib 三个版本号之间没有强耦合但 numpy 不要直接装最新版部分 dlib 轮子对 numpy 2.x 的接口还没完全适配。装完后不要急着跑业务代码先做一个最小验证import cv2 import dlib detector dlib.get_frontal_face_detector() print(opencv:, cv2.__version__) print(dlib:, dlib.__version__) print(detector ready:, detector is not None)这段代码验证两件事import 阶段能否同时加载 opencv 和 dlibdlib 自带的人脸检测器能否实例化。如果出现No module named opencv先检查当前激活的解释器是不是虚拟环境里的 python很多时候是系统自带 python 和 venv 混用导致。dlib 的编译期报错则要回退到 apt 安装列表确认 cmake、boost、libx11-dev 是否齐全。提示PyPI 上没有名为 opencv 的包只有 opencv-python别在源里写错包名。2.2 两个模型文件决定系统的“眼睛”和“大脑”dlib 完成人脸识别需要两个不同作用的模型文件。源码包里通常会包含二者解压后建议固定放到项目根目录的 models/ 子目录中避免摄像头循环里频繁拼路径出错。模型文件名作用加载函数shape_predictor_68_face_landmarks.dat定位 68 个人脸关键点用于对齐dlib.shape_predictor()dlib_face_recognition_resnet_model_v1.dat把对齐后的脸转成 128 维特征向量dlib.face_recognition_model_v1()第一个模型约 90MB负责找眉毛、眼睛、鼻子、嘴巴的位置第二个模型是 ResNet 网络权重负责编码人脸身份。两个文件缺一不可特征提取器单独加载时不会报错但计算描述符时会一直失败或返回空结果。下载时留意文件名需要完全一致版本不一致的模型文件会在加载阶段抛deserialize相关异常。2.3 摄像头输出格式与检测器输入的匹配OpenCV 的VideoCapture(0)打开摄像头后每一帧默认是 BGR 三通道图像。dlib 的 HOG 检测器对灰度图处理效果最稳定速度也快因此每帧先转灰度是固定写法cap cv2.VideoCapture(0) if not cap.isOpened(): raise RuntimeError(camera open failed) while True: ret, frame cap.read() if not ret: continue gray cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces detector(gray, 1) for face in faces: left, top, right, bottom face.left(), face.top(), face.right(), face.bottom() cv2.rectangle(frame, (left, top), (right, bottom), (0, 255, 0), 2) cv2.imshow(attendance, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()detector(gray, 1)的第二个参数 1 表示对图像做一次金字塔上采样让画面里较小的脸放大以后再检测能明显提升远距离召回率代价是单帧耗时增加。考勤场景里员工通常距离摄像头 0.5 到 1.5 米上采样 1 次足够如果人员经常站在三米外可以改成 2同时把预览窗口缩小否则普通笔记本 CPU 会掉帧。3. 人脸检测与关键点对齐把“有一张脸”升级为“一张可识别的正脸”3.1 HOG SVM 为什么是考勤系统的默认选择dlib 的get_frontal_face_detector()内部是 HOG方向梯度直方图加线性 SVM 分类器的组合。它把图像分成小块统计每个小块里梯度方向的分布再用线性分类器判断当前滑动窗口是否包含人脸。这个方案对算力要求极低在 i5 级别的 CPU 上处理 640×480 灰度图单帧通常只要几十毫秒。另一类检测器是 dlib 的 CNN 人脸检测器需要额外下载mmod_human_face_detector.dat对遮挡和侧脸更鲁棒但 CPU 环境下单帧可能跑到几百毫秒甚至一秒。考勤系统的体验预期是“站过去一秒内给结果”而且员工会主动正对摄像头HOG 检测器在实际部署里往往更合适。class FaceAnalyzer: def __init__(self): self.detector dlib.get_frontal_face_detector() self.predictor dlib.shape_predictor(models/shape_predictor_68_face_landmarks.dat) self.embedder dlib.face_recognition_model_v1( models/dlib_face_recognition_resnet_model_v1.dat) def locate(self, bgr): gray cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY) return self.detector(gray, 1) def landmarks(self, bgr, rect): gray cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY) return self.predictor(gray, rect)把检测器、关键点预测器、特征提取器封装成一个类是为了让摄像头循环里只初始化一次模型。否则每帧重新加载三个模型文件不仅启动慢还容易造成内存持续上涨。locate返回的是dlib.rectangles对象列表每个矩形有left/right/top/bottom四个属性坐标系与 OpenCV 一致左上角是原点x 轴向右。3.2 68 个关键点和仿射对齐的具体实现关键点预测器输出的 68 个点中人脸轮廓占 17 个其余分布在眉毛、眼睛、鼻子和嘴巴。考勤识别要稳定不能直接把检测框里的图像送进特征提取器而是先用双眼位置把人脸旋转到水平。角度偏 5 度可能影响不大偏 15 度时同一个人的特征距离会被拉大跨过阈值造成漏识别。dlib 没有提供现成的对齐函数常见做法是自己算仿射变换。核心逻辑是取左右眼外眼角坐标计算连线与水平方向的夹角然后构造旋转矩阵import numpy as np def align_face(image, shape): left_eye (shape.part(36).x, shape.part(36).y) right_eye (shape.part(45).x, shape.part(45).y) dx right_eye[0] - left_eye[0] dy right_eye[1] - left_eye[1] angle np.degrees(np.arctan2(dy, dx)) eyes_center ((left_eye[0] right_eye[0]) // 2, (left_eye[1] right_eye[1]) // 2) matrix cv2.getRotationMatrix2D(eyes_center, angle, 1.0) aligned cv2.warpAffine(image, matrix, (image.shape[1], image.shape[0])) return aligned旋转时以两只眼睛的中点为中心angle 的单位是度正值代表逆时针旋转。变换后双眼连线被拉成水平线再送入后续模型时特征描述符的稳定性会明显提升。注意warpAffine会让图像边缘出现黑边后续裁剪人脸区域时建议在原检测框宽高基础上放大 1.2 倍再裁剪把五官完整包含进来。关键点的索引在不同版本模型上是固定的考勤系统里主要用以下几组关键点索引部位常用场景36 和 45左右眼外眼角人脸对齐、角度纠正27 到 30鼻梁口罩遮挡判断48 到 68嘴唇轮廓活体检测、张嘴动作如果后续想判断员工是否戴口罩不需要额外模型直接对比 8 号点到 30 号点的距离就可以做一个粗糙判断。鼻子区域的梯度变化被口罩抹平后这两个点的位置关系会明显异常。4. 128 维特征与相似度阈值考勤系统“认人”的参数决定识别率4.1 员工注册的本质是向量入库注册员工时把摄像头拍到的脸转换成 128 维浮点向量再存入数据库。这里最常见的错误是直接拿检测框内的原图做特征提取。dlib 的 ResNet 模型预期输入是一张正脸图如果现场拍的是略带俯视角度注册时又是正面照那么同一个人两次算出的特征距离可能超过 0.6直接被判成两个人。建议注册时也走一遍对齐流程def enroll_employee(self, bgr, rect): gray cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY) shape self.predictor(gray, rect) aligned align_face(bgr, shape) a_gray cv2.cvtColor(aligned, cv2.COLOR_BGR2GRAY) a_rect dlib.rectangle(0, 0, a_gray.shape[1], a_gray.shape[0]) a_shape self.predictor(a_gray, a_rect) descriptor self.embedder.compute_face_descriptor(aligned, a_shape) return np.array(descriptor)对齐后的图像需要重新跑一次关键点定位因为原图里的人脸位置在旋转后已经偏移不能再沿用旧 rect。compute_face_descriptor返回一个 dlib description 对象转成 numpy 数组后方便做欧氏距离计算和持久化。注册员工时每人建议拍三张照片正面、向左偏 15 度、向右偏 15 度。三张向量都存下来考勤比对时取距离最小值比只存一张或取三张向量的平均值更稳。原因很简单不同光照和姿态下128 维空间里的特征点分布不是均匀球面平均值会抹掉个体差异。4.2 欧氏距离与阈值档位人脸比对一般用欧氏距离。每个员工对应的多个向量一起参与计算取最小的那个作为最终距离def match_employee(query_embedding, employee_vectors, threshold): min_dist float(inf) matched_id None for emp_id, vectors in employee_vectors.items(): for vec in vectors: dist np.linalg.norm(query_embedding - vec) if dist min_dist: min_dist dist matched_id emp_id if min_dist threshold: return matched_id, min_dist return None, min_dist距离越小代表越像同一个人。代码里的 threshold 是识别准确率最敏感的旋钮经验值如下阈值效果适用场景0.45严格漏识别率偏高光线稳定、员工人数少0.55均衡误报和漏报相对平衡办公室室内正常照明0.65宽松容易误识别户外、逆光、人员长期戴帽子阈值低于 0.4 时员工稍微换个发型就可能打不上卡高于 0.7 时相似脸型的同事之间会出现互相误打卡。上线前可以先用 20 个人、每人 5 张照片做一轮距离统计把“同一个人最小距离”和“不同人最大距离”画出来在两个分布的中间取阈值。4.3 特征向量的持久化方案128 维浮点向量不能直接按文本存常见做法是序列化成 bytes 写入 SQLite。保存时转成np.float32可以把体积压缩一半读取时再恢复成向量embedding_bytes embedding.astype(np.float32).tobytes() employee_vectors[emp_id] [ np.frombuffer(row[embedding], dtypenp.float32) for row in fetch_rows(emp_id) ]tobytes()和frombuffer的 dtype 必须一致否则读出来的 128 维会变成 256 个 float16匹配距离全部异常。建议在模型封装类里单独写一个load_embeddings()方法统一负责数据库读取和解码不要在业务代码里散落frombuffer调用。5. 摄像头、打卡逻辑和 SQLite 串起来的最小可用系统5.1 考勤打卡系统的表结构设计考勤系统功能设计里最核心的是两张表员工表和打卡记录表。员工表存工号、姓名、部门和特征向量打卡记录表存员工 ID 与打卡时间。SQLite 单文件部署简单几十个员工的场景完全够用不需要单独跑 MySQL 服务。CREATE TABLE employees ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, department TEXT, embedding BLOB NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE attendance_logs ( id INTEGER PRIMARY KEY AUTOINCREMENT, employee_id INTEGER NOT NULL, punch_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (employee_id) REFERENCES employees(id) );给attendance_logs的employee_id和punch_time建联合索引因为每天查询时要反复执行“某个员工当天是否已打卡”的判断。不建索引的话数据量到一万条以后查询耗时可能从毫秒级涨到百毫秒级。5.2 打卡循环中的去重与冷却窗口摄像头循环里每帧都可能检测到同一个人脸如果每帧都写一次数据库一分钟会产生几十条重复记录。常见的处理方式是在内存里维护一个打卡时间缓存同一工号在冷却时间内只打一次卡同时再去数据库确认当天是否已经打过卡last_punch_time {} COOLDOWN_SECONDS 5 def already_punched_today(emp_id): row conn.execute( SELECT COUNT(*) FROM attendance_logs WHERE employee_id? AND date(punch_time)date(now), (emp_id,) ).fetchone() return row[0] 0 def insert_attendance(emp_id): conn.execute( INSERT INTO attendance_logs (employee_id, punch_time) VALUES (?, datetime(now, localtime)), (emp_id,) ) conn.commit()每次识别到一张脸先算特征向量再与员工库比对。匹配成功且不在冷却窗口内就执行already_punched_today查询。当天没记录才允许写入否则界面提示“今日已打卡”。主循环里要多考虑一个场景画面里同时出现多个员工。此时要对每个检测框独立执行识别但数据库写入和内存缓存都要按 emp_id 分别处理避免 A 员工的脸被识别成 B 员工并写入 B 的考勤记录。实践中可以用置信度过滤距离超过阈值的框直接忽略不参与打卡。5.3 视频流不要无限处理要做抽帧如果每一帧都跑完整检测加比对普通笔记本 CPU 的占用率会长期处于 80% 以上并且发热严重。更合理的做法是设置一个处理时间间隔比如每 0.4 秒处理一帧其余帧只做预览回显frame_interval 0.4 last_process_time 0.0 while True: ret, frame cap.read() now time.time() if now - last_process_time frame_interval: process_frame(frame) last_process_time now if cv2.waitKey(1) 0xFF ord(q): break0.4 秒的间隔意味着每秒最多比对 2.5 次对考勤场景已经足够。人员站定后第一次识别成功就会写库后面的帧即使没来得及处理也不影响结果。这样 CPU 占用可以压到 20% 以下。6. 现场调优阈值档位、照片攻击与离线部署的三个细节考勤系统上线后最先暴露的问题通常是误识别和漏识别。先按上一章的阈值表设成 0.55再根据一星期的实际记录调整。逆光环境建议把摄像头改成固定曝光让 dlib 检测器在亮度变化大的时段也能稳定找到人脸。如果员工背景经常有人走动可以把摄像头广角收窄或者把检测框限制在画面中央区域减少远处路人脸的干扰。照片代打卡是这类离线系统被质疑最多的地方。dlib 本身不带活体检测最简单的缓解手段是用关键点算眼睛纵横比要求考勤时连续几帧检测到眨眼动作def eye_aspect_ratio(shape, sideright): pts [shape.part(i) for i in range(36, 42)] if side right \ else [shape.part(i) for i in range(42, 48)] vertical_1 np.linalg.norm(np.array((pts[1].x, pts[1].y)) - np.array((pts[5].x, pts[5].y))) vertical_2 np.linalg.norm(np.array((pts[2].x, pts[2].y)) - np.array((pts[4].x, pts[4].y))) horizontal np.linalg.norm(np.array((pts[0].x, pts[0].y)) - np.array((pts[3].x, pts[3].y))) return (vertical_1 vertical_2) / (2.0 * horizontal)正常睁眼时 EAR 大约在 0.2 到 0.35闭眼时降到 0.1 以下。考勤时连续三帧 EAR 小于 0.15就提示“请注视摄像头”防止员工低头录入或直接用照片遮挡。这个方法不依赖任何额外模型是 dlib 68 关键点在考勤系统里最实用的扩展。部署时还有一些小坑值得提前处理。第一dlib模型路径不要写死绝对路径把检测器模型、特征模型和数据库连接字符串都抽到一个 config 文件中不同工控机上的目录差异就不会影响启动。第二摄像头索引不一定是 0USB 摄像头可能被识别成 1 或 2启动时循环尝试VideoCapture并检查isOpened()。第三SQLite 写入频率不高但记得到期清理历史数据半年后打卡表轻松超过十万行时再用开工号和日期的联合索引查询依然能保持在几十毫秒内。本文还有配套的精品资源点击获取