简介：基于 Python 与 OpenCV 的人脸识别考勤签到系统，面向计算机相关专业的学生，适用于课程设计、期末大作业、毕业设计参考及实战练习。该项目出自个人大三高分作业，经导师指导并认可，评审达到九十九分，代码完整、注释详细，确保可直接运行，新手也能顺利上手。压缩包为 zip 格式，共四十四份文件，主要包含十二个 Python 源码文件、两个 PyQt5 界面设计文件、十个 OpenCV 人脸检测所需的级联分类器文件，还配有环境依赖说明与使用指南。整体约六百九十 KB，目录按功能模块划分，摄像头调用、人脸建模、签到数据处理等核心代码都清晰可查。系统可实现实时人脸检测、人脸特征提取、签到记录保存与图形界面交互，覆盖考勤签到流程的主要环节。目前已有 404 人浏览学习，适合作为答辩项目、课程作业或入门实战，便于在此基础上扩展新功能。
1. 把考勤从打卡机换成摄像头，这笔账怎么算
人脸识别考勤在中小团队里一直是个尴尬需求：买成品门禁机一台要几千块，还要维护本地指纹或IC卡数据；用钉钉/企微的打卡功能，又免不了有人代打。其实办公室或者实验室入口只要有一台普通USB摄像头，OpenCV完全能撑起一套够用的签到系统，核心代码量不会超过五百行。PyQt5在这里的价值是兜住交互：注册人脸、实时识别、签到记录、异常提示，全部塞进一个桌面窗口里，不用开浏览器，也不用碰命令行。
这套方案的适用人群很明确——有点Python基础、想在校招项目或内部工具里落地人脸识别考勤的开发者。它和商用设备的差距在于活体检测和云端管理，但作为一套能跑通「注册—训练—识别—写记录」闭环的源码，它的学习价值远大于买一台现成设备。下面这套实现按「检测→特征→界面→排错」的顺序展开，每一层都会给可直接运行的代码，也把参数为什么这么设说清楚。
2. 为什么用人脸检测而不是直接整图比对：OpenCV的检测原理与最小环境
2.1 检测是识别的前置条件，Haar级联和LBP级联怎么选
import cv2 # 初始化摄像头，0 代表默认摄像头，换成 1 可以指定外接 USB 相机 cap = cv2.VideoCapture(0) # 加载 OpenCV 自带的 Haar 级联模型，用于实时检测正脸 face_cascade = cv2.CascadeClassifier( cv2.data.haarcascades + "haarcascade_frontalface_default.xml" ) print("OpenCV 版本:", cv2.__version__) print("级联模型路径:", cv2.data.haarcascades) while True: ret, frame = cap.read() if not ret: break # 转为灰度图，检测器只吃单通道数据，能减少计算量 gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) # detectMultiScale 参数含义： # scaleFactor=1.1 表示每次搜索窗口缩小 10%，越小越慢但越准 # minNeighbors=5 表示一个区域至少被周围 5 个窗口命中才算人脸，抑制误检 # minSize=(80, 80) 过滤掉小于 80x80 像素的检测框，避免把噪点当人脸 faces = face_cascade.detectMultiScale( gray, scaleFactor=1.1, minNeighbors=5, minSize=(80, 80) ) for (x, y, w, h) in faces: cv2.rectangle(frame, (x, y), (x + w, y + h), (0, 255, 0), 2) cv2.imshow("Face Detection", frame) if cv2.waitKey(1) & 0xFF == ord("q"): break cap.release() cv2.destroyAllWindows()OpenCV 的人脸检测原理是基于滑动窗口 + 级联分类器，Haar 特征描述的是图像局部的明暗关系，比如眼睛区域比脸颊暗、鼻梁两侧存在光照梯度。LBP（Local Binary Pattern）则换成纹理编码，计算比 Haar 快，但对模糊和光照变化的鲁棒性更差。实际做考勤场景我一般优先用 Haar，因为摄像头角度固定、光照相对可控时，Haar 的误检率明显更低。detectMultiScale的scaleFactor和minNeighbors是一对跷跷板：scaleFactor越接近 1 检测越精细但帧率降得厉害，minNeighbors越大越不容易误报，但也可能漏掉侧脸和遮挡。摄像头画面里有 2 到 3 个人同时出现时，minNeighbors=5依然能稳定框住正脸。
2.2 环境搭建：OpenCV 和 PyQt5 的安装顺序与常见报错
# 建议先创建虚拟环境，避免和系统 Python 打架 python -m venv venv source venv/bin/activate # Windows 下执行 venv\Scripts\activate # 安装核心依赖，opencv-python 自带推理所需的级联模型文件 pip install opencv-python pip install pyqt5 pip install numpy安装顺序建议先把 OpenCV 装好，再装 PyQt5。如果先装 PyQt5 再装 OpenCV，有概率把opencv-python-headless一起带进来，导致cv2.imshow弹不出窗口。检查是否装成了 headless 版本，用下面这条命令：
python -c "import cv2; print(cv2.__version__)"如果版本号正常但imshow报错，直接pip uninstall opencv-python-headless后重装opencv-python。另一个高频坑是 PyQt5 的QtWebEngine，本系统用不到浏览器组件，不需要安装。Python 3.8 以下装新版 PyQt5 会报DISTRIBUTE相关错误，建议直接用 3.9 以上版本。
2.3 OpenCV 调用相机原理：为何必须用 VideoCapture 而不是读图片文件
VideoCapture在 Windows 上底层走 DirectShow，在 Linux 上走 V4L2。它做的事情是把摄像头的视频流按帧读取到内存，每一帧是一张 BGR 排列的 numpy 数组。和直接读图片的区别在于：摄像头帧是连续到达的，读取速度受限于传感器帧率和 USB 带宽，所以识别循环不能做重计算；否则画面会卡成 PPT。这也是人脸检测放在识别之前的原因——先拿轻量级检测器框出人脸区域，再对这个小图做特征提取和比对，比整帧做特征匹配省一个数量级的计算量。
3. 人脸识别算法的演进与选型：从 LBPH 到深度学习模型的取舍
# 查看 OpenCV 内置的人脸识别模型创建接口 python -c "import cv2; print([x for x in dir(cv2.face) if 'create' in x.lower()])"3.1 三类传统算法：EigenFaces、FisherFaces、LBPH 谁适合考勤
OpenCV 的contrib模块里内置三种传统人脸识别算法，区别在于特征提取方式：EigenFaces 用 PCA 降维，把整张人脸展开成向量再找主成分，优点是实现简单，缺点是对光照敏感，同一个人的脸换个亮度就可能认错。FisherFaces 用 LDA 做线性判别，目标是最大化类间距离、最小化类内距离，需要每个身份至少两张样本，识别效果比 EigenFaces 好一些。LBPH 把图像分成小块，每块提取局部二值模式直方图，再拼接成一个特征向量，对光照变化和表情变化都有一定耐受性。
考勤签到系统里我通常会选 LBPH，因为它不需要像深度模型那样海量数据，每个注册用户提供 5 到 10 张不同角度的脸部照片就能训练出可用模型。LBPH 的radius和neighbors参数要现场调试：radius=2比默认的1更能捕捉纹理特征，但半径太大等于把噪声也编进特征里；neighbors=10对比默认的8抗噪声能力稍强，匹配时对表情变化更宽容。识别阈值一般设50到60，低于阈值判定为已注册用户，高于阈值标记为陌生人。阈值设太小人会被频繁拒识，设太大陌生人也能签上到，需要根据实际摄像头清晰度慢慢收。
3.2 深度学习方案什么时候值得换：InsightFace 与 OpenCV DNN 的边界
# 使用 OpenCV DNN 模块加载人脸检测模型（更精确的替代方案） net = cv2.dnn.readNetFromCaffe( "deploy.prototxt", # 模型结构描述文件 "res10_300x300_ssd_iter_140000.caffemodel" # 预训练权重 ) def dnn_detect(frame): h, w = frame.shape[:2] # 构造 300x300 输入 blob，这是 SSD 模型预设的输入尺寸 blob = cv2.dnn.blobFromImage( cv2.resize(frame, (300, 300)), 1.0, (300, 300), (104.0, 177.0, 123.0) ) net.setInput(blob) detections = net.forward() faces = [] for i in range(detections.shape[2]): confidence = detections[0, 0, i, 2] if confidence > 0.7: # 置信度阈值，比 Haar 的 minNeighbors 更直观 box = detections[0, 0, i, 3:7] * np.array([w, h, w, h]) faces.append(box.astype(int)) return faces当门口摄像头角度刁钻，或者要识别侧脸、低头看手机的脸时，Haar 级联会明显力不从心——它的训练数据以正脸为主，侧脸超过 30 度就丢框。这时候换成 OpenCV DNN 模块加载 SSD 人脸检测模型，精度能上一个台阶，代价是帧率从 30 掉到 10 左右。识别部分可以继续用 LBPH，也可以用 InsightFace 提取 512 维人脸向量后自己做余弦相似度比对。
需要强调的边界是：深度学习模型对硬件有最低要求，纯 CPU 跑 InsightFace 的识别模型，一张 N 卡都没有的普通办公电脑每次比对要花 200 毫秒以上，多人连续打卡会明显卡顿。如果公司愿意给预算上 GPU 或 NPU，深度学习是更稳的长期方案；如果只是做一个内部考勤工具，LBPH 已经够用，识别速度毫秒级，还能离线运行。
3.3 训练数据集的组织方式和标签文件格式
import os import cv2 import numpy as np # 目录结构约定：dataset/张三/1.jpg, 2.jpg, ..., 张三/10jpg def load_training_data(data_dir): images, labels = [], [] label_names = {} # 用整数标签映射到人名 for label_id, person_name in enumerate(os.listdir(data_dir)): person_dir = os.path.join(data_dir, person_name) if not os.path.isdir(person_dir): continue label_names[label_id] = person_name for img_name in os.listdir(person_dir): img_path = os.path.join(person_dir, img_name) # 统一转为灰度并缩放到 200x200，LBPH 不要求固定输入尺寸但缩放能加速 img = cv2.imread(img_path, cv2.IMREAD_GRAYSCALE) img = cv2.resize(img, (200, 200)) images.append(img) labels.append(label_id) return images, np.array(labels), label_names这里的关键设计是标签用整数而不是人名，因为所有传统识别器的训练接口只接受整数标签，人名映射单独维护一个字典。收集训练数据时要注意样本多样性：每张照片在画面里的位置稍微偏移一点，转头角度有正脸也有 ±15 度，光线保持自然光。不要连续抓取同一帧存成多张，那等于只有一张有效样本，训练出来的模型会把背景也算进特征里。
4. PyQt5 界面与考勤流程整合：从单帧识别到完整签到闭环
4.1 界面布局：摄像头预览、注册面板和历史记录的模块化设计
from PyQt5.QtWidgets import QMainWindow, QLabel, QPushButton, QVBoxLayout, QWidget from PyQt5.QtCore import QTimer from PyQt5.QtGui import QImage, QPixmap class AttendanceWindow(QMainWindow): def __init__(self): super().__init__() self.setWindowTitle("人脸识别考勤签到系统") self.setFixedSize(800, 600) central_widget = QWidget() self.setCentralWidget(central_widget) layout = QVBoxLayout() # 视频显示区域，QLabel 用 setPixmap 更新帧画面 self.video_label = QLabel("摄像头未启动") self.video_label.setFixedSize(640, 360) layout.addWidget(self.video_label) # 签到状态显示区，识别成功时显示用户名和时间 self.status_label = QLabel("等待识别...") layout.addWidget(self.status_label) # 注册按钮和退出按钮 self.register_btn = QPushButton("注册新用户") self.quit_btn = QPushButton("退出系统") layout.addWidget(self.register_btn) layout.addWidget(self.quit_btn) central_widget.setLayout(layout) # 定时器驱动视频刷新，限制在 30 FPS self.timer = QTimer() self.timer.timeout.connect(self.update_frame) self.timer.start(33)PyQt5 界面里最容易踩的坑是摄像头画面无法显示，原因是QPixmap不能直接接受 OpenCV 的 BGR 数组，必须先转成 RGB 再封装成QImage。具体流程是：OpenCV 读帧得到 numpy 数组，cv2.cvtColor转颜色空间，QImage构造图像，最后setPixmap显示。另一个性能问题是QTimer的间隔设得太短——timer.start(10)会让update_frame每 10 毫秒执行一次，但摄像头实际帧率往往只有 30 FPS，多余的调用全部浪费在空转上，设 33 到 50 毫秒就足够了。
4.2 识别线程与界面线程的关系：为什么不能在 QTimer 回调里跑识别
import threading import time class RecognizerThread(threading.Thread): def __init__(self, recognizer, label_names, confidence_threshold=55): super().__init__(daemon=True) self.recognizer = recognizer self.label_names = label_names self.threshold = confidence_threshold self.running = True self.face_queue = None # 用队列传递帧数据 def run(self): while self.running: if self.face_queue is None: time.sleep(0.01) continue gray_face = self.face_queue.get() label, confidence = self.recognizer.predict(gray_face) if confidence < self.threshold: self.on_recognized(self.label_names[label], confidence)识别不能直接写进update_frame，因为 LBPH 的predict方法会阻塞当前线程。界面刷新卡顿只是表面问题，严重时整个窗口会无响应，被系统判定为「未响应」并要求强制关闭。正确做法是单独开一个识别线程，主线程只负责抓帧和显示，识别的结果通过信号槽机制回传到界面线程更新签到状态。每识别成功一次，还要做防重复签到处理：比如同一人 5 分钟内重复出现不再写入记录，这个时间窗口要根据实际考勤策略调。
4.3 签到记录的落库方案：SQLite 的表结构与防作弊字段
CREATE TABLE IF NOT EXISTS attendance_log ( id INTEGER PRIMARY KEY AUTOINCREMENT, person_name TEXT NOT NULL, sign_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP, confidence REAL NOT NULL, image_path TEXT, device_id TEXT ); CREATE INDEX idx_sign_time ON attendance_log(sign_time);SQLite 是本地考勤系统的合理默认选择，Python 内置sqlite3模块，不需要单独装数据库服务。confidence字段存识别置信度，虽然 LBPH 的返回值越大代表越不相似，但保存原始值有助于后续排查误识别的具体原因。image_path字段存签到瞬间的人脸截图，哪个人什么时候来的、当时长什么样，全部有据可查。写入操作用INSERT OR IGNORE配合唯一索引，可以进一步防止同一秒内的重复插入。
4.4 完整签到流程：注册、训练、识别的状态机
state = { "mode": "idle", # idle / registering / recognizing "current_user": "", "sample_count": 0, } def on_register_clicked(): state["mode"] = "registering" state["sample_count"] = 0 # 弹出输入框获取新用户姓名 name, ok = QInputDialog.getText(self, "注册", "请输入姓名：") if ok and name.strip(): state["current_user"] = name.strip() state["sample_count"] = 0 def capture_training_sample(frame, user_name, sample_id): # 每按下一次空格键保存一帧人脸，共采集 10 张 save_dir = f"dataset/{user_name}" os.makedirs(save_dir, exist_ok=True) file_path = f"{save_dir}/{sample_id}.jpg" cv2.imwrite(file_path, frame) return file_path注册阶段要在采集完所有样本后自动触发模型重训练。这里的细节是：每次注册完新人都调用一次trainer.train()，如果人脸库有 100 个人的时候，重训练会越来越慢，此时就应该改成增量化训练，或者把注册和训练拆开，让管理员批量导入照片后统一训练。考勤系统最忌讳的是识别循环里嵌套训练逻辑，这会直接把摄像头帧率拖到个位数。
5. 参数标定与识别准确率调优：三个必调参数和一个隐藏参数
5.1 minNeighbors 和 confidence threshold 的联动调整方法
检测阶段的minNeighbors和识别阶段的置信度阈值必须分开调。先把minNeighbors从 3 往上加，每次加 1，观察画面里有没有人脸框跳变。如果你站在摄像头前不动，框大小跳动超过 10%，说明minNeighbors太小；如果左右转头时框直接消失，说明太大，主流摄像头在 5 到 8 之间能找到平衡点。置信度阈值要在训练完成后单独标定：用已注册用户 10 次识别记录取平均，再减去 10 作为初始阈值，随后用陌生人的脸测试，如果陌生人频繁通过就把阈值往下压。
5.2 摄像头参数：曝光、对焦和白平衡的固定策略
cap = cv2.VideoCapture(0) # 关闭自动曝光，固定曝光值避免光源抖动影响识别 cap.set(cv2.CAP_PROP_AUTO_EXPOSURE, 0.25) # 0.25 表示关闭自动曝光 cap.set(cv2.CAP_PROP_EXPOSURE, 120) # 曝光值范围与摄像头型号相关 # 关闭自动白平衡，防止色温变化导致颜色偏移 cap.set(cv2.CAP_PROP_AUTO_WB, 0) cap.set(cv2.CAP_PROP_WB_TEMPERATURE, 4600)摄像头出厂默认开启自动曝光和自动白平衡，这看起来是好事，实际是考勤识别的大敌。自动曝光会在人脸靠近时疯狂调亮度，人脸特征在帧与帧之间的数值变化反而比静止时更大，LBPH 对光照的耐受性有限，最终表现为同一个人的识别置信度忽高忽低。上班时间自然光变化剧烈，固定曝光之后光线不足的时段画面会偏暗，所以还要加一个亮度判断：如果整帧平均灰度低于 40，界面提示补光而不是硬识别。后台参数用cap.set不一定在所有摄像头驱动上生效，设置完了用cap.get回读确认一下。
5.3 采样频率和样本数对 LBPH 模型的影响
| 样本数（每人） | 识别准确率 | 训练耗时 | 过拟合风险 |
|---|---|---|---|
| 3 | 约 85% | <1s | 低，但泛化不足 |
| 5 | 约 92% | 1s | 低 |
| 10 | 约 96% | 2s | 中 |
| 20 | 约 97% | 5s | 高 |
样本数从 3 涨到 10，准确率提升最明显；超过 10 之后边际收益骤减，反而可能因为采集的多张照片背景差异太大，让模型把背景纹理也学进去。每个用户采集 10 张照片是比较合适的平衡点。采集时注意覆盖面：靠近画面左侧一张、右侧一张、低头一张、抬头一张、正面平视两三张。采样期间不要频繁眨眼或做夸张表情，LBPH 对表情变化虽然有一定容忍度，但训练数据的表情分布越接近日常操作越好。
5.4 多人同时出现在画面里的处理策略
门口摄像头经常拍到前后两个人同时入境，识别逻辑要定义清楚优先级。常见做法是取画面中最大的人脸框做识别，也就是面积最大的框。小框往往是远处路过的人影，如果也参与识别，会产生「签到成功」的误报。处理方式是检测到多张人脸后按面积排序，只对最大的人脸做特征比对，其他框只画框不识别。这会导致同时进门时只有第一个被识别，所以在签到记录里要增加一个「手动补签」功能，管理员从历史抓拍里找到第二个人补上。
6. 陌生人拒识与告警：把签到系统从演示推向可用的关键技巧
# 陌生人检测的误报抑制逻辑 SUSPICIOUS_SAMPLE_COUNT = 5 # 连续 5 帧被识别为陌生人，才触发告警 class StrangerDetector: def __init__(self, recognizer, threshold=60): self.recognizer = recognizer self.threshold = threshold self.consecutive_misses = 0 self.last_alert_time = 0 def check(self, gray_face) -> bool: label, confidence = self.recognizer.predict(gray_face) if confidence >= self.threshold: self.consecutive_misses += 1 else: self.consecutive_misses = 0 if self.consecutive_misses >= SUSPICIOUS_SAMPLE_COUNT: # 达到连续帧数后才告警，避免单个误检触发噪音 self.consecutive_misses = 0 return True return False陌生人拒识在演示环境看起来很简单——置信度超过阈值就弹「陌生人」提示——但真实场景里一堆问题。人脸在画面里移动时，某些帧会失焦或运动模糊，置信度瞬间飙升到阈值以上，这时候如果立即告警，一上午能响几百次。连续 N 帧确认是陌生人再告警，是这类型系统最朴素也最有效的防抖手段。N 取 3 对步行速度的人基本够用，取 5 更稳但反应稍慢。告警动作可以是弹窗、记录日志，也可以外接一个QSound播放提示音。
另一个实用技巧是把每次识别请求的前后各一帧也保存成图片，命名带上时间戳。这样出问题时能复盘：某次「张三签到成功」是不是因为画面里恰好有两个人的脸重叠，某次「陌生人告警」是不是因为清洁阿姨拿着拖把经过。考勤系统最容易扯皮的就是「我明明打卡了为什么记录里没有」，有这个帧缓存机制，争议一眼就能查清。
最后建议在界面上放一个「识别置信度实时预览」的小进度条，绿色区域表示低于阈值、红色区域表示高于阈值。日常运行时不看它，调试时盯着它调参数就非常直观——阈值改一个数值，进度条的跳动范围立刻反馈出来，比肉眼观察签到成功率高一个量级。整个系统跑顺手之后，可以考虑把训练好的 LBPH 模型文件复制到门口的另一台电脑上独立运行，OpenCV 的write()方法会保存一个.yml文件，部署端只需加载模型，不需要重新采集人脸。
本文还有配套的精品资源，点击获取
