简介这是一套面向高校计算机相关专业毕业设计场景的完整项目源码主题为基于Python与OpenCV的人脸识别员工考勤系统适合正在准备毕设、课程设计或需要人脸识别实战案例的学生与开发者参考使用。资源包共收录26个文件以15个png界面素材、3个py核心脚本为主另含ttf字体、md说明、config配置、ico图标及api接口文件等压缩包整体约239.37MB目录结构清晰涵盖人脸检测、考勤记录与前端界面等模块。目前已有1778人学习下载说明其具备一定的参考热度。项目据描述已通过导师指导并获高分评价下载后无需大幅修改即可运行读者可据此快速理解人脸识别考勤的完整实现流程包括界面布局、识别逻辑与配置方式适合作为毕设模板或二次开发起点。1. 从一份能跑通的考勤源码说起它到底解决了什么问题很多做毕业设计或者公司内部小工具的朋友都会卡在同一个地方人脸识别听起来不难OpenCV 装完、摄像头打开、检测到人脸这几步网上教程一抓一大把。但要把「检测到脸」变成「这个人是谁、几点几分签到了、数据存哪、界面长什么样」串成一条完整链路中间隔着一堆没人愿意细讲的工程活。这份基于 pythonopencv 人脸识别的员工考勤系统源码价值就在这儿——它不是一段孤立的识别 demo而是一个带 UI、带签到状态、带用户信息管理的成品项目目录里能看到face.py、Ui_test_01.py、api、static、config这些模块说明前后端和识别逻辑是分开组织的。它适合谁一是赶毕业设计、需要一份结构完整且能演示的系统二是想拿现成骨架改造成自己公司内部考勤工具的人。核心链路是摄像头采集 → OpenCV 做人脸检测 → 识别出员工身份 → 写入签到记录 → 界面反馈签到状态。下面我按「先跑起来、再拆模块、最后避坑」的顺序把这份源码拆开讲清楚参数怎么调、哪里容易翻车都会落到具体位置。2. 环境搭建与首次运行把依赖和入口文件对齐2.1 依赖清单与版本选择这份源码的技术栈是 Python OpenCV人脸识别部分大概率依赖face_recognition目录里有face_recognition-masterUI 部分从Ui_test_01.py和static里的 png 资源看应该是 PyQt 或类似的桌面框架。装环境时最容易翻车的就是版本face_recognition依赖dlib而dlib对编译环境挑剔这是血泪经验里出现频率最高的一条。常见做法是先用 conda 建一个干净环境避免和系统里已有的包打架# 建一个 Python 3.8 的环境版本太新 dlib 编译容易失败 conda create -n attendance python3.8 conda activate attendance # 先装 dlib 的预编译版本省去本地编译 cmake 的麻烦 pip install dlib19.24.0 # 再装 face_recognition 和 opencv pip install face_recognition1.3.0 pip install opencv-python4.5.5.64 # UI 框架按源码实际用的装PyQt5 是这类项目最常见的选择 pip install PyQt55.15.9参数说明dlib19.24.0这个版本在 Windows 和 Linux 上都有较成熟的预编译 wheel能绕开cmake编译报错opencv-python选 4.5.x 是因为 4.6 之后部分 API 有调整老项目直接跑可能报module cv2 has no attribute之类的错。如果你在pip install dlib时卡在编译先确认系统装了cmake和 C 编译工具链Windows 上装 Visual Studio Build ToolsLinux 上apt install build-essential cmake。2.2 入口文件与目录结构对应关系拿到源码别急着python xxx.py先看清楚哪个是入口。从目录看Ui_test_01.py带Ui前缀基本可以确定是界面主入口face.py是识别逻辑api目录负责数据接口config放配置static放界面图片资源。首次运行的正确姿势是先确认入口再检查它引用的路径是不是相对路径。# 典型的入口文件结构先看 import 部分判断依赖 # Ui_test_01.py 开头大概率是这样 import sys import cv2 import face_recognition from PyQt5.QtWidgets import QApplication, QMainWindow # 注意这里如果 import 的是自定义模块路径要对得上 from face import FaceRecognizer from api.user_api import UserApi if __name__ __main__: app QApplication(sys.argv) window QMainWindow() window.show() sys.exit(app.exec_())逻辑说明入口文件负责初始化 UI 和调用识别模块真正的识别逻辑在face.py里。运行前要确认config里的路径配置指向的是你本机的实际路径很多「下载即用」的项目跑不起来就是因为作者写死了自己的绝对路径。检查方法很简单全局搜一下C:\或者/home/这类绝对路径改成相对路径或者你本机的路径。提示如果运行时报ModuleNotFoundError: No module named opencv不是没装而是你装到了别的 Python 环境里。用which pythonLinux/Mac或where pythonWindows确认当前解释器再pip list看 opencv 在不在这个环境里。2.3 摄像头与识别阈值参数识别能不能用关键在几个参数摄像头索引、识别容差、帧率降采样。face_recognition的compare_faces有个tolerance参数默认 0.6值越小越严格越大越宽松。考勤场景下建议调到 0.45 到 0.5 之间因为员工打卡要求「认对人」宁可让他多试一次也不能把张三认成李四。# face.py 里识别逻辑的典型写法 import face_recognition def recognize(known_encodings, known_names, frame): # 降采样到 1/4 尺寸再检测速度能快 4 倍左右 small_frame cv2.resize(frame, (0, 0), fx0.25, fy0.25) # 转 RGBOpenCV 默认是 BGR rgb_small small_frame[:, :, ::-1] # 检测人脸位置 face_locations face_recognition.face_locations(rgb_small) # 提取特征编码 face_encodings face_recognition.face_encodings(rgb_small, face_locations) results [] for encoding in face_encodings: # tolerance 调小考勤场景更看重准确率 matches face_recognition.compare_faces( known_encodings, encoding, tolerance0.45) name unknown if True in matches: idx matches.index(True) name known_names[idx] results.append(name) return results参数说明fx0.25, fy0.25是降采样比例摄像头分辨率越高越要降否则每帧检测会卡到没法用tolerance0.45是识别容差比默认严格代价是光线不好时可能认不出需要配合补光或者多存几张底图。摄像头索引一般是 0如果你有多个摄像头改成 1 或 2 试。3. 人脸识别模块拆解从检测到比对的数据流3.1 人脸检测与特征编码的分离这份源码把检测和识别分开处理是合理的工程做法。检测只负责「画面里有没有脸、在哪」识别负责「这张脸是谁」。face_recognition底层用 HOG 或 CNN 做检测HOG 快但精度一般CNN 准但吃算力。考勤机这种场景如果机器没有独立显卡老老实实用 HOG别硬上 CNN。# 检测和编码分开方便单独调优 def detect_faces(frame): # HOG 模型CPU 上跑得动 locations face_recognition.face_locations(frame, modelhog) return locations def encode_faces(frame, locations): # 对检测到的人脸提取 128 维特征向量 encodings face_recognition.face_encodings(frame, locations) return encodings逻辑说明modelhog是检测模型选择换成cnn精度会提升但需要 GPU 支持face_encodings返回的是 128 维向量这个向量就是后续比对的依据。员工底图录入时每张脸都会生成一个这样的向量存起来打卡时拿实时向量和底图向量算欧氏距离距离小于容差就算匹配。3.2 员工底图录入与特征库管理系统要认人前提是先把员工的脸存进去。目录里有llz_userinfo_all.png、llz_user_list_bg.png这些界面资源说明有用户管理页面。底图录入的常见做法是每个员工存 3 到 5 张不同角度的照片提取特征后取平均或者全部保留做多模板匹配。import os import pickle import face_recognition def build_encoding_db(photo_dir): known_encodings [] known_names [] # 遍历员工照片目录文件名建议用员工工号或姓名 for filename in os.listdir(photo_dir): if not filename.lower().endswith((.jpg, .png)): continue path os.path.join(photo_dir, filename) image face_recognition.load_image_file(path) encodings face_recognition.face_encodings(image) if len(encodings) 0: print(f{filename} 没检测到人脸跳过) continue # 一张图可能有多张脸取第一张 known_encodings.append(encodings[0]) # 文件名去掉扩展名当姓名 known_names.append(os.path.splitext(filename)[0]) # 特征库序列化存盘下次启动直接加载 with open(encodings.pkl, wb) as f: pickle.dump((known_encodings, known_names), f) return known_encodings, known_names参数说明photo_dir是员工照片目录建议按工号命名文件方便和数据库对应encodings[0]取第一张脸如果照片里有其他人会误取所以录入照片要保证单人pickle序列化是为了避免每次启动都重新提取特征几百个员工的话重新提取要等好几分钟。注意底图质量直接决定识别率。常见翻车是拿证件照录入结果现场光线和证件照差太多认不出来。录入时最好用和打卡现场类似的光线和角度拍。3.3 签到状态判定与去重逻辑考勤系统最核心的业务逻辑不是识别是「签到状态判定」。同一个人站在摄像头前系统每秒可能识别几十次不能每次都写一条签到记录。目录里有sign_status.png说明界面会显示签到状态。去重的常见做法是设一个时间窗口比如 5 分钟内同一个人只记一次。import time from datetime import datetime # 记录每个人上次签到时间 last_sign {} def check_in(name, window_seconds300): now time.time() if name in last_sign: # 在时间窗口内不重复记录 if now - last_sign[name] window_seconds: return False, 已签到 last_sign[name] now # 写入签到记录实际项目里这里调 api 存数据库 record { name: name, time: datetime.now().strftime(%Y-%m-%d %H:%M:%S) } save_record(record) return True, 签到成功 def save_record(record): # 这里对接 api 目录里的接口或者直接写文件 with open(attendance.csv, a, encodingutf-8) as f: f.write(f{record[name]},{record[time]}\n)参数说明window_seconds300是去重窗口5 分钟适合大多数考勤场景如果公司要求更严格可以调到 60 秒save_record里对接的是api目录的接口如果接口没跑起来先降级成写 CSV保证数据不丢。签到状态要反馈到界面sign_status.png就是用来显示「已签到/未签到」的图标。4. 界面与数据接口让识别结果落到业务上4.1 UI 资源与界面逻辑的对应static目录里那一堆 pngllz_background.png是背景llz_user_list_bg.png是用户列表背景llz_video_rect.png是视频显示区域的框。这些资源说明界面是定制过的不是随便拖几个控件。改界面时要注意图片路径PyQt 里加载图片如果路径写错界面会显示空白但不报错这是很隐蔽的坑。# PyQt 里加载背景图的典型写法 from PyQt5.QtGui import QPixmap from PyQt5.QtWidgets import QLabel def set_background(label, image_path): pixmap QPixmap(image_path) if pixmap.isNull(): # 图片加载失败要显式报出来否则就是一片空白 print(f背景图加载失败: {image_path}) return label.setPixmap(pixmap) label.setScaledContents(True)逻辑说明QPixmap加载失败不会抛异常只会返回一个空的 pixmap所以必须用isNull()判断。路径建议用os.path.join拼避免 Windows 和 Linux 的斜杠差异。视频显示区域用llz_video_rect.png做边框实际视频帧画在这个区域里尺寸要对上否则画面会被拉伸变形。4.2 数据接口与签到记录存储api目录是数据层负责用户信息和签到记录的读写。如果这份源码用的是 Flask 或 FastAPI 做本地接口启动方式通常是单独跑一个服务。但很多毕业设计项目为了简化api只是几个 Python 函数直接 import 调用。# api/user_api.py 可能的接口定义 import csv def get_all_users(): users [] with open(users.csv, r, encodingutf-8) as f: reader csv.DictReader(f) for row in reader: users.append(row) return users def add_user(user_id, name, photo_path): with open(users.csv, a, encodingutf-8, newline) as f: writer csv.writer(f) writer.writerow([user_id, name, photo_path]) return True参数说明users.csv是用户表字段是工号、姓名、照片路径add_user追加写入注意newline不加的话 Windows 上会多出空行。如果源码用的是 SQLite把 CSV 操作换成sqlite3即可逻辑一样。签到记录建议单独一张表字段包含工号、签到时间、签到状态方便后续导出考勤报表。4.3 识别结果到界面的刷新链路识别是后台线程跑的界面是主线程两者之间要通信。PyQt 里跨线程更新 UI 必须用信号槽直接在工作线程里改控件会崩。这是新手最容易踩的坑之一程序跑着跑着就闪退还找不到原因。from PyQt5.QtCore import QThread, pyqtSignal class RecognizeThread(QThread): # 定义信号传识别结果出去 result_ready pyqtSignal(str, str) def run(self): while self.running: frame self.capture.read() names recognize(self.known_encodings, self.known_names, frame) for name in names: if name ! unknown: success, msg check_in(name) # 通过信号通知主线程更新界面 self.result_ready.emit(name, msg) # 主线程里连接信号 self.thread.result_ready.connect(self.update_ui) def update_ui(self, name, msg): # 这里才真正改界面安全 self.status_label.setText(f{name} {msg})逻辑说明pyqtSignal定义信号类型emit发信号主线程的槽函数接收后更新界面。识别线程里绝对不能直接调self.status_label.setText否则就是随机崩溃。self.running是个标志位退出时要置 False 并wait()等线程结束不然程序关了线程还在跑。5. 避坑与排查那些让项目跑不起来的细节5.1 摄像头打不开或画面全黑现象程序启动后视频区域一片黑或者直接报cant open camera。原因通常是摄像头索引不对或者被其他程序占用。笔记本自带摄像头一般是 0外接 USB 摄像头可能是 1 或 2。解决方法是写个小脚本遍历索引试import cv2 for i in range(5): cap cv2.VideoCapture(i) if cap.isOpened(): print(f摄像头索引 {i} 可用) cap.release()如果所有索引都打不开检查系统权限Linux 下当前用户要在video组里Windows 下检查隐私设置里有没有允许应用访问摄像头。5.2 识别率低、频繁认错人现象同一个人有时认得出有时认不出或者把两个人搞混。原因有三个底图质量差、容差参数不合适、光线变化大。解决方法是先调tolerance从 0.45 往 0.5 试还不行就重新录入底图每个员工多存几张不同光线的照片。如果还是认错检查底图里是不是混进了别人的脸face_encodings取第一张脸时可能取错。5.3 程序运行一段时间后卡死现象刚启动流畅跑几分钟后界面无响应。原因基本是识别线程没做帧率控制CPU 被吃满。解决方法是在识别循环里加time.sleep或者用cv2.waitKey控制节奏import time # 每处理一帧休息 0.05 秒相当于最高 20 帧 time.sleep(0.05)另外确认降采样比例1080P 的帧不降采样直接送检测再好的 CPU 也扛不住。5.4 中文路径或中文姓名乱码现象员工姓名是中文时签到记录里显示乱码或者读照片时报路径错误。原因是文件编码没统一。解决方法是所有文件读写都显式指定encodingutf-8CSV 写入加newline。Windows 下控制台输出中文乱码是另一回事改chcp 65001或者用 IDE 的运行窗口看。5.5 依赖装完但 import 报错现象pip list里明明有 opencv运行还是ModuleNotFoundError。原因是 pip 和 python 不是同一个环境。用python -m pip install opencv-python确保装到当前解释器而不是直接pip install。虚拟环境激活后which pip和which python的路径前缀应该一致。6. 进阶改造把 demo 变成能长期用的考勤工具跑通只是第一步真要拿去用还得解决几个工程问题。第一个是数据持久化CSV 存签到记录撑不过几百人换成 SQLite 或者 MySQLapi目录里的接口改成数据库操作加个索引按工号和日期查导出月报就是一条 SQL 的事。第二个是底图更新员工胖了瘦了换了发型老底图会失效加个「重新录入」按钮新特征覆盖旧的别让特征库越积越乱。第三个是异常处理摄像头断连、识别线程崩溃、数据库写失败这些都要有兜底。我一般会在识别线程外面包一层 try出错就重启线程并记日志而不是让整个程序挂掉。日志用 Python 自带的logging按天切文件出问题能回溯。import logging from logging.handlers import TimedRotatingFileHandler logger logging.getLogger(attendance) logger.setLevel(logging.INFO) # 按天切日志保留 7 天 handler TimedRotatingFileHandler(attendance.log, whenD, backupCount7, encodingutf-8) handler.setFormatter(logging.Formatter(%(asctime)s %(levelname)s %(message)s)) logger.addHandler(handler) try: names recognize(known_encodings, known_names, frame) except Exception as e: logger.error(f识别失败: {e}, exc_infoTrue)参数说明whenD按天切backupCount7保留一周exc_infoTrue把堆栈也记下来排查时能直接定位到行号。这套日志习惯是我踩过无数次「程序半夜挂了第二天才发现」的坑之后养成的从那以后我每次部署这类常驻程序都强制先把日志和异常兜底加上再谈功能。最后一个技巧是识别结果的二次确认。考勤场景下误识别的代价比漏识别高所以可以要求同一个人连续 3 帧都被识别到才判定签到成功单帧结果只做界面提示不写记录。这个逻辑加在check_in之前用一个计数器实现能显著降低误打卡概率。希望帮到你。本文还有配套的精品资源点击获取
