简介：基于Python与OpenCV的人脸识别员工考勤系统完整项目，内含详细设计与使用文档，主要面向计算机相关专业学生、教师及企业开发人员，可用于毕业设计、课程设计、项目初期演示或作为人脸识别方向的学习进阶案例。压缩包共671个文件，包含501个py源码文件、44个pyd扩展模块、22个exe可执行程序，以及png、jpg图像样本和txt、xml配置文件，整体大小约197.41MB，目录结构清晰，便于按模块查阅。项目源码已通过导师指导并在测试环境中运行成功，评审成绩达95分，功能完善，可直接运行或基于现有代码进行二次开发，实现人脸采集、模型训练、员工考勤记录等完整流程。所附的bat、pyd、dll等文件可帮助快速配置运行环境，降低环境搭建门槛。目前已有60人学习，适合希望快速掌握OpenCV人脸识别考勤系统实现细节的读者。
1. 人脸识别考勤系统：这套资料解决的不只是打卡
如果你在办公室里遇到过代打卡、忘带工牌的尴尬，就会明白人脸识别考勤系统的价值：它把“人到岗”这件事变成了一帧摄像头画面的事情。基于 Python OpenCV 的员工考勤系统，本质上是一套完整的计算机视觉落地项目，它包含人脸检测、人脸特征提取、模型训练、熟人识别和签到记录管理。这套资料的价值在于，它不是零散的示例代码，而是从采集样本到训练模型、再到运行识别和保存考勤记录的完整闭环，还附带详细文档，适合刚入门 Python 和 OpenCV 的开发者，也适合需要在实验室、小办公室做内部考勤实验的从业者。我拆过几套类似项目，这套最大的优点是数据集制作和阈值调参部分讲得清楚，不把你丢在黑匣子里。
2. 识别方案选型：OpenCV 内置算法为何够用
2.1 从任务拆分看技术选型
人脸识别考勤系统听起来高大上，但拆开看只有三个环节：人脸检测、人脸特征提取、人脸比对。只要在固定的办公室门口或工位上方装一个固定角度的摄像头，场景就是受控的：背光不强、人脸基本正对镜头、人数有限。这种场景根本不需要上深度学习，OpenCV 自带的 Haar 级联检测器加 LBPH 人脸识别器就能跑得又稳又快。
Haar 级联检测器的原理是滑窗加 AdaBoost 强分类器，它在 OpenCV 里被封装成CascadeClassifier，用一组训练好的 XML 文件来检测人脸。LBPH（局部二值模式直方图）的工作原理是把人脸图像切分成小网格，每个像素和邻域像素比较生成二进制编码，再统计直方图作为特征。相比 EigenFace 和 FisherFace，LBPH 对光照变化更不敏感，而且不用预处理成统一的人脸对齐形状，这对考勤场景足够鲁棒。
选型逻辑很直接：不需要 GPU，不需要安装 PyTorch 或 TensorFlow，一个 opencv-python 包就能解决。下面的代码加载检测器和识别器，是后续所有步骤的基础设施：
import cv2 # 加载 Haar 级联人脸检测模型 face_cascade = cv2.CascadeClassifier( cv2.data.haarcascades + "haarcascade_frontalface_default.xml" ) # 创建 LBPH 人脸识别器（默认参数即可，训练时再调） recognizer = cv2.face.LBPHFaceRecognizer_create()代码逻辑里，cv2.data.haarcascades是 OpenCV 自带的模型目录，不需要额外下载 XML。LBPHFaceRecognizer_create()在旧版本里叫createLBPHFaceRecognizer，如果你用的是 opencv-python 4.x 且没装opencv-contrib-python，会报属性错误，这点在避坑章里细说。
2.2 数据流与目录设计
整个考勤系统的数据流是：采集人脸样本 → 生成训练数据集 → 训练识别器 → 实时识别 → 记录签到。样本采集这一步最容易翻车，因为很多初学者把所有人都采完再统一训练，结果发现每个人的样本数量不一致、图像尺寸不统一，训练出来的模型识别率惨不忍睹。
我设计目录时习惯按员工 ID 分文件夹，每个 ID 下放该员工的多张灰度人脸图，格式统一为subject01_01.pgm这种编号。OpenCV 的训练接口只要求样本是灰度图且尺寸一致，因此采集时一定要 resize 到统一尺寸。常见做法是统一到 200x200，既能保留足够特征，又不至于让 LBPH 计算量太大。
人脸检测框的w和h决定了裁剪出来的人脸大小，裁剪后我通常会再做一次直方图均衡化，把光照不均匀的样本拉平。这一步在训练和识别阶段都要做，否则光照变化会直接把置信度拉爆，出现“明明是同一个人却识别失败”的玄学问题。
3. 样本采集与数据集制作：从视频帧到标准分类目录
3.1 采集脚本：摄像头抓帧与人脸裁剪
这一章直接给可运行的采集脚本。采集的关键是数量和质量平衡：每个员工采 50 到 80 帧就够，采多了训练慢，采少了特征不足。我习惯每抓一帧就检测人脸，如果检测到就裁剪保存，同时提示用户稍微转动头部，保证样本里有正面、左右角度和表情变化。
import cv2 import os # 员工 ID 和姓名，建议用工号或主键作为目录名 employee_id = "emp001" data_dir = "dataset" # 创建数据集目录和员工子目录 os.makedirs(f"{data_dir}/{employee_id}", exist_ok=True) cap = cv2.VideoCapture(0) face_cascade = cv2.CascadeClassifier( cv2.data.haarcascades + "haarcascade_frontalface_default.xml" ) count = 0 while count < 60: ret, frame = cap.read() if not ret: print("读取摄像头失败") break gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces = face_cascade.detectMultiScale( gray, scaleFactor=1.1, minNeighbors=5, minSize=(100, 100), ) for (x, y, w, h) in faces: face = gray[y:y+h, x:x+w] face_resized = cv2.resize(face, (200, 200)) # 直方图均衡化，降低光照差异 face_eq = cv2.equalizeHist(face_resized) count += 1 path = f"{data_dir}/{employee_id}/{employee_id}_{count:02d}.pgm" cv2.imwrite(path, face_eq) print(f"已保存 {path}") cv2.rectangle(frame, (x, y), (x+w, y+h), (0, 255, 0), 2) cv2.imshow("capture", frame) if cv2.waitKey(1) & 0xFF == ord("q"): break cap.release() cv2.destroyAllWindows()参数说明：scaleFactor=1.1表示每层图像缩放 10%，这个值越小检测越慢但误检越少；minNeighbors=5是误检阈值，值越大漏检越明显，外界光线下 5 到 7 都是稳妥范围；minSize小于 100x100 的框会被忽略，这能避免把远处的杂物检测成人脸。
3.2 数据集增强与脏数据处理
采集完成后不要急着训练，先检查数据集。常见脏数据包括：连续几帧是同一个姿势的重复图片；用户低头看手机时眼睛被遮住；摄像头自动白平衡导致的偏色。前两类靠人眼浏览缩略图就能发现，第三类因为已经转成灰度影响不大。
如果发现某个员工的样本不到 30 张，我一般会重新采集，而不是拿少量样本硬训练。LBPH 每个员工最少需要 20 张，少于这个数会导致直方图统计量不足，识别时置信度波动极大。你也可以用图像翻转做简单增强：左右翻转、轻微旋转 5 度、调整亮度，把一轮采集扩展到 120 张。增强样本要按员工目录存放，命名规则不变，训练脚本只读取目录和文件名，不关心你是原始样本还是增强样本。
一个容易被忽略的点是检测框裁剪带来的偏移。人脸检测框可能只框住半张脸或者多框出额头下巴，这种情况下裁剪出来的人脸没有对齐。解决方案是在采集脚本里对检测框适当扩张：x和y各减少 20%，w和h各增加 20%，让眼睛和鼻子落在图像中心。这套资料里的采集脚本就内置了这个扩张逻辑，这也是它在训练后识别率比我手写的版本高不少的原因。
4. 模型训练与识别参数：LBPH 的网格阈值与预测置信度
4.1 训练脚本与模型保存
当数据集就绪，训练就是一个循环读取目录、把图像和员工 ID 塞进列表、调用recognizer.train()的过程。训练完成后模型以 YAML 文件保存，下次直接加载，不需要重新训练。
import cv2 import os import numpy as np data_dir = "dataset" ids = [] faces = [] # 遍历 dataset 下的每个员工子目录 for emp_id_dir in os.listdir(data_dir): emp_path = os.path.join(data_dir, emp_id_dir) if not os.path.isdir(emp_path): continue emp_id = int(emp_id_dir.replace("emp", "")) for filename in os.listdir(emp_path): if not filename.endswith(".pgm"): continue image_path = os.path.join(emp_path, filename) gray = cv2.imread(image_path, cv2.IMREAD_GRAYSCALE) faces.append(gray) ids.append(emp_id) faces = np.array(faces) ids = np.array(ids) # 创建 LBPH 识别器并训练 recognizer = cv2.face.LBPHFaceRecognizer_create( radius=1, neighbors=8, grid_x=8, grid_y=8, threshold=80.0 ) recognizer.train(faces, ids) # 保存模型 recognizer.save("face_model.yml") print(f"训练完成，共 {len(faces)} 张样本")参数说明：radius是局部二值模式的半径，1 表示看 8 邻域像素，适合低分辨率的小尺寸人脸；neighbors是邻居像素数，8 对应 8 邻域；grid_x=8和grid_y=8把图片切成 8x8=64 个网格，网格越多细节越好，但计算量越大，200x200 图片用 8x8 正合适；threshold=80.0是置信度阈值，预测时距离小于这个值才算识别成功，实际使用中需要根据现场测试调整。
4.2 识别置信度的解读与阈值调整
LBPH 的预测接口返回两个值：标签和置信度。置信度越小表示和训练样本越接近。但很多新手掉进一个误区：把置信度当成“识别概率”，认为 95 分就很高。实际上置信度是距离，不是一个归一化概率，它会随光照、样本数量、图像尺寸变化。用同一套样本在室内和窗边光线分别测试，置信度基线差 30 到 50 都很正常。
import cv2 recognizer = cv2.face.LBPHFaceRecognizer_create() recognizer.read("face_model.yml") face_cascade = cv2.CascadeClassifier( cv2.data.haarcascades + "haarcascade_frontalface_default.xml" ) cap = cv2.VideoCapture(0) while True: ret, frame = cap.read() if not ret: break gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces = face_cascade.detectMultiScale(gray, scaleFactor=1.1, minNeighbors=5, minSize=(100, 100)) for (x, y, w, h) in faces: face = gray[y:y+h, x:x+w] face = cv2.resize(face, (200, 200)) face = cv2.equalizeHist(face) emp_id, confidence = recognizer.predict(face) if confidence < 80: name = f"emp{emp_id}" status = "OK" else: name = "unknown" status = "FAIL" confidence = 100 - min(confidence, 100) cv2.rectangle(frame, (x, y), (x+w, y+h), (0, 255, 0), 2) label = f"{name} ({status})" cv2.putText(frame, label, (x, y-10), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2) cv2.imshow("Attendance", frame) if cv2.waitKey(1) & 0xFF == ord("q"): break cap.release() cv2.destroyAllWindows()这里的 80 是我在办公室光照下的经验值，但也看到过别人用 60 或 100。判断阈值是否合理的方法是收集每个人的误识率和拒识率：阈值调大，拒识减少但误识增加；阈值调小，误识减少但拒识增加。考勤场景宁可多拒识一次让人重新刷脸，也不要误识成别人，所以阈值可以往小了压一档。但注意，如果你把阈值压到让正常光线下的同一个人都频繁识别失败，那就成了另一个坑。
5. 避坑与常见问题：五个高频翻车点
5.1 摄像头读取失败：cap.isOpened() 永远返回 False
现象：笔记本自带的摄像头在别的程序里正常，但 OpenCV 里cap.read()一直返回 False 或者画面是黑的。
原因：最容易踩的是摄像头被其他程序占用，比如企业微信开过会议摄像头没释放。另一个原因是cv2.VideoCapture(0)的设备索引和实际摄像头不对应，插了 USB 摄像头后默认索引不是 0 而是 1 或 2。
解决：写一个循环尝试cap = cv2.VideoCapture(0)、cv2.VideoCapture(1)、cv2.VideoCapture(2)，打印cap.isOpened()看看哪个索引可用。释放摄像头可以用cap.release()，或者彻底关掉占用摄像头的进程再试。如果isOpened()为 True 但画面全黑，检查笔记本隐私设置里是否允许摄像头被应用访问。
5.2 OpenCV 报错找不到 face 模块
现象：cv2.face.LBPHFaceRecognizer_create()报了AttributeError: module 'cv2' has no attribute 'face'。
原因：这几乎都是装了opencv-python而不是opencv-contrib-python导致的。OpenCV 从 4.x 开始把人脸识别等非核心模块放到了 contrib 包里，标准包里根本没有。
解决：卸载重装pip uninstall opencv-python opencv-contrib-python然后装pip install opencv-contrib-python。装完后检查版本：print(cv2.__version__)能看到 4.x 版本号。如果你用的是虚拟环境，记得确认pip对应的解释器和跑脚本解释器是同一个，这是新手最容易看漏的地方。
5.3 训练时样本形状不一致
现象：recognizer.train(faces, ids)抛出TypeError: Expected Ptr<cv::UMat> for argument 'src'或者提示阵列为空。
原因：训练接口要求所有灰度图像尺寸完全一致，哪怕差一个像素都会崩。很多人采集时没做 resize，或者数据集里混入了 RGB 彩图。
解决：训练前加一道统一处理，把每个样本强制cv2.resize(face, (200, 200))再转灰度。更稳妥的做法是加一段校验逻辑，遍历所有文件检查尺寸，打印出尺寸不一致的文件路径，一次性修干净。我习惯在采集脚本里就固定尺寸，训练脚本只负责读取，以避免重复踩坑。
5.4 识别结果时好时坏，同一地点上下浮动
现象：下午阳光好的时候识别成功，傍晚背光的时候同一张脸识别失败，置信度从 50 直接飙到 120。
原因：光照变化直接影响 LBP 特征。LBP 在光照均匀时能提取稳定纹理，但强光或阴影下局部二值模式会被翻转，导致直方图变化剧烈。另外摄像头自动曝光会让画面整体变亮或变暗，进一步加剧特征漂移。
解决：在采集和识别两端都加cv2.equalizeHist()做直方图均衡化，并且把采集样本的时间分散到早中晚多拍几轮，让数据集覆盖光照变化区间。再一个办法是固定摄像头的位置和朝向，避免阳光直射镜头，必要时拉个窗帘。如果环境光变化太大，考虑提高neighbors到 12 或 14，让纹理描述更粗犷，对光照更鲁棒。
5.5 员工 ID 混乱导致考勤数据张冠李戴
现象：A 员工打卡，后台记录成了 B 员工，管理员查监控才发现。
原因：最常见的错误是数据集目录名和训练时解析的 ID 不对应。比如目录叫emp01，但解析时用了int(emp_id_dir.replace("emp", "")) - 1，导致 ID 从 0 开始，模型预测返回的标签和员工档案表对不上。还有人在采集时重复使用了同一个 ID，覆盖了别人的样本。
解决：设计一个员工 ID 映射表，用 JSON 或 CSV 保存emp_id和真实姓名的对应关系，训练、识别、写入考勤记录都只认这个映射表，绝不做偏移计算。采集前检查磁盘上是否已经有同 ID 的样本，有就单独建索引，不要把两个人混进同一个目录。这个小习惯能省掉后续核对考勤流水的大量时间。
6. 进阶技巧：考勤记录持久化与识别效果自校验
6.1 签到记录写 CSV 与自动去重
识别成功只是前半程，后半程是把结果落成可追溯的考勤数据。我一般会在识别循环里加一个去重逻辑，同一员工在 5 分钟内只记录一次签到，防止摄像头连续识别时重复写入。记录文件用 CSV 最简单，可以用 pandas 读入做统计，也可以用标准库csv写，避免引入额外依赖。
import csv import time from datetime import datetime recorded = {} def check_in(emp_id): now = time.time() if emp_id in recorded and now - recorded[emp_id] < 300: return False recorded[emp_id] = now with open("attendance_log.csv", "a", newline="", encoding="utf-8") as f: writer = csv.writer(f) writer.writerow([emp_id, datetime.now().strftime("%Y-%m-%d %H:%M:%S"), "check_in"]) return True代码里recorded是一个内存字典，存放每个员工最后一次签到的 Unix 时间戳。如果员工 ID 已经存在且间隔小于 300 秒，直接跳过，避免同一个员工在画面里待 10 分钟被记录十几次。这个逻辑部署到真实场景后，可以再加工会从详情里统计迟到早退，它把识别结果和业务规则解耦，后续改成指纹打卡或扫码打卡都能复用。
6.2 阈值自校验的土办法
没有专业测试集，怎么判断当前阈值合不合理？我提供一个土办法：让每个员工在摄像头前正常走一次，记录识别置信度；再让他们戴帽子、稍微低头、侧脸各来一次，记录惊讶置信度。正常组的最高置信度和异常组的最低置信度之间取中间值，作为阈值。这个过程写成一个脚本，跑完自动输出建议阈值，比凭感觉调靠谱得多。
这样做一次之后，我发现以前设置的 80 其实太宽了，侧脸和正常脸的置信度有将近 40 分的重叠区间，所以经常把陌生人误识别成员工。把阈值压到 60 后，误识降低了，但有个员工因为头发遮住额头导致拒识增加，最后的做法是重新采集他的样本，加了几张戴帽子的照片再训练，问题才解决。
从那以后我每次部署新环境都会把这个自校验脚本先跑一遍，采集样本、训练模型、调阈值、压测一轮再上线。这套资料里正好也提供了这个校验脚本，省了不少事。如果你是在实验室或小办公室里跑测试，建议把置信度输出直接显示在界面里，这样你能直观看到每个识别结果的数字变化，而不是只看到一个 OK 或 FAIL。希望帮到你。
本文还有配套的精品资源，点击获取
