简介这是一份基于Python构建的多人人脸识别课堂考勤系统源码包适合Python初学者、计算机视觉爱好者以及需要实现自动化考勤的教学管理人员。系统涵盖OpenCV人脸检测、Dlib关键点定位、深度学习模型匹配、SQLite数据库存储及实时视频流处理等核心环节并配有基于Tkinter/PyQt风格的前端页面便于教师录入学生信息、查看考勤记录。压缩包共36个文件以10个Python脚本为主体辅以21个HTML模板、SQL建表脚本、CSS样式及说明文档整体仅29KB代码结构清晰、模块划分明确。目前已有923人学习下载。通过阅读或二次开发读者能够掌握从人脸采集、特征提取到数据库比对的完整流程同时学到异常处理与实时帧优化的实用思路是一份适合课设、毕设或生产环境快速落地的参考资源。1. 课堂考勤为什么必须上多人人脸识别这个源码包到底解决什么问题高校和培训机构的课堂考勤一直是点名、刷卡、扫码轮流上但代答到、代刷卡、手机扫码后放口袋这类操作让考勤数据基本靠不住。基于多人人脸识别的课堂考勤系统本质上是用一台普通摄像头对着教室一次性识别画面里的多张人脸自动生成出勤记录把“点名”这件事从人工操作变成后台静默完成。Python在这个方向上的优势很明显OpenCV负责图像采集和检测dlib或insightface负责特征提取比对逻辑几十行就能写完整个方案对硬件的要求也低一台带摄像头的笔记本就能跑。这篇笔记我会按拿到源码包之后实际会走的路径来讲怎么读代码、怎么配环境、怎么调参、哪些地方最容易翻车以及最后怎么验证系统真的能用。适合正在做课程设计、毕业设计的学生也适合想在学校机房或培训教室快速搭一套本地考勤原型的运维老师。我不会去复述源码里每一行注释而是把这条技术路线上的关键决策点和踩坑点摆出来让你少走弯路。2. 读懂源码骨架目录结构、识别主链路与考勤数据流2.1 解压后的目录结构哪些文件是核心哪些是点缀拿到Python基于多人人脸识别的课堂考勤系统源码.zip之后第一件事不是急着跑而是先看目录。通常这类项目的结构大同小异核心文件不会太多但容易被无关文件干扰。我一般会按下面的清单来分辨文件价值文件/目录作用重要程度main.py或run.py程序入口负责初始化摄像头、加载模型、启动识别循环核心先读这个face_register.py人脸注册脚本录入学生姓名和照片特征核心决定考勤能不能认对人face_recognizer.py封装检测和识别逻辑包括加载模型、比对特征核心调参主要在这里models/存放人脸检测和特征提取模型文件如.dat、.onnx、.pb核心注意模型文件是否齐全attendance/或utils/数据库操作、CSV写入、时间格式化等辅助函数辅助requirements.txt依赖包清单核心环境安装靠它README.md使用说明但经常与真实环境有出入辅助别全信dataset/可能存放注册照片或训练数据看源码怎么引用决定能不能删config.py摄像头索引、识别阈值、模型路径等全局配置核心几乎所有坑都从这里开始拿到手先看config.py或叫settings.py的文件这类项目一般会有一个集中管理配置的地方。确认三件事摄像头索引是多少0还是1模型路径是不是写死成了绝对路径识别阈值是多少。这三个参数是后面90%问题的源头。如果源码里没有配置文件而是写死在主程序里那就先全局搜一下cv2.VideoCapture和threshold这两个关键词。2.2 多人脸考勤的识别主链路检测、特征提取、比对、入库不管界面写得多花哨基于多人人脸识别的课堂考勤系统识别主链路只有四步。理解了这条链路你才知道源码里每个函数在干什么出了问题也知道去哪个环节找原因。第一步是摄像头帧采集。常见做法是cv2.VideoCapture(0)循环读取画面每一帧先缩小再送模型因为教室场景下画面尺寸1280x720已经足够缩小能显著提高检测速度。第二步是人脸检测这一步决定画面里有几个人、每张脸在哪个位置。这个源码可能用的dlib的HOG检测器也可能用OpenCV自带的DNN检测器两者对遮挡和侧脸的容忍度差异很大。第三步是特征提取把检测到的人脸区域送入特征模型得到一个128维或512维的特征向量。第四步是比对拿这个向量去和数据库里预先注册的学生特征做距离计算距离小于阈值就认为是同一个人。考勤记录的逻辑一般放在比对成功之后先查这张脸今天有没有签到记录没有就写入一条出勤记录有就跳过或更新最后识别时间。多人同框时检测步骤会产生多个人脸框源码通常用一个for循环依次处理每个人脸框。需要注意的是这种串行处理在画面里人数超过5人时帧率会明显下降后面第5章会提到怎么应对。2.3 数据库与考勤记录落盘人脸特征库和签到表的组织方式特征库的记录方式决定系统能不能迁移到另一台机器。有些源码把特征向量压缩成字符串存进SQLite有些直接以.npy文件形式存在本地目录有些更简单注册时把照片文件名和姓名关联。这个源码大概率用了SQLite加本地图片文件的组合students表存学号、姓名face_features表存特征attendance_records表存每天的签到记录。在跑之前我建议先手动打开数据库文件看一眼表结构。如果源码里用的sqlite3直接执行sqlite3 attendance.db .schema就能看到建表语句。确认三张表的主外键关系特别是考勤记录表里有没有student_id关联到students表如果没有说明考勤记录可能只存了姓名文本重名会成为隐患。3. 在本地把系统跑起来环境版本选择与最小启动步骤3.1 Python解释器与虚拟环境的版本选择这类源码最大的坑是依赖包版本互相打架尤其是dlib和OpenCV。我强烈建议用Python 3.8或3.9跑不要用3.10以上。原因很现实dlib在Windows上的预编译wheel只到3.93.10以上需要自己编译而CMake编译dlib在无GPU的机器上可能要等二十分钟以上还容易因为Boost版本问题失败。创建虚拟环境这步不要省哪怕你机器上已经装了Python。因为项目依赖的opencv-python、dlib、face_recognition、numpy这些包版本锁得比较死直接往全局环境里装会把其他项目搞坏。用下面的命令隔离环境# 创建虚拟环境python3.8-dlib作为环境名可自行修改 python -m venv face_attendance_env # Windows激活 face_attendance_env\Scripts\activate # macOS / Linux激活 source face_attendance_env/bin/activate # 先升级pip再装依赖避免旧pip解析依赖树报错 python -m pip install --upgrade pip激活成功的标志是命令行前面出现(face_attendance_env)。这一步如果失败先检查虚拟环境目录是否生成完整Windows下常见问题是执行策略限制可以改用cmd而不是PowerShell激活。Linux下则要确认python3-venv系统包已安装。3.2 安装依赖包requirements.txt与常见版本锁拿到源码先看requirements.txt里写了什么。常见做法是列出opencv-python、dlib、face_recognition、numpy、Pillow、tkinter或PyQt5。这里最容易翻车因为face_recognition这个库对Python版本和dlib版本都有隐性要求。我的建议是放弃直接pip install -r requirements.txt手工逐个安装并锁定版本# 先装numpy注意1.24.0以上版本在Windows上可能找不到预编译wheel pip install numpy1.23.5 # 再装dlibPython 3.8/3.9在Windows上可直接用wheel pip install dlib19.24.1 # 装OpenCV注意不要同时装opencv-python和opencv-contrib-python pip install opencv-python4.8.1.78 # 再装face_recognition它会自动依赖前面已装好的dlib pip install face_recognition1.3.0 # 其他依赖按requirements.txt逐个补齐 pip install pillow pyyaml这里逐个装的逻辑是先解决最难的编译依赖再装上层封装库。如果face_recognition装完测试导入时报ModuleNotFoundError八成是虚拟环境没有激活或者pip装到了全局环境里。验证环境是否可用的最小命令是import cv2 import dlib import face_recognition print(OpenCV:, cv2.__version__) print(dlib:, dlib.__version__) print(face_recognition:, face_recognition.__version__)能正常打印版本号说明环境已经就绪。如果dlib导入报DLL load failed先卸载重装到指定版本不要尝试用conda混装会引入更多问题。3.3 首次启动前的最小配置摄像头索引、模型路径、数据库初始化环境就绪后先别直接跑main.py你大概率会一上来就被摄像头打不开或模型路径报错卡住。先打开配置文件确认以下几项。摄像头索引是第一个坑。笔记本自带摄像头一般是0外接USB摄像头可能是0或1如果配置写的是1而电脑只有内置摄像头cv2.VideoCapture不会报错但返回的帧一直是None源码会在读取帧的地方卡死或跳过。先单独测一下import cv2 # 依次尝试0和1两个索引找到能读到帧的那个 for idx in [0, 1]: cap cv2.VideoCapture(idx) ret, frame cap.read() if ret and frame is not None: print(f摄像头索引 {idx} 可用画面尺寸: {frame.shape}) cap.release() break cap.release()模型路径是第二个坑。很多源码把模型路径写成models/shape_predictor_68_face_landmarks.dat这种相对路径导致必须在项目根目录下启动程序才能找到文件。如果你在别的目录执行python src/main.py就会报FileNotFoundError。解决办法是用Path(__file__).parent来定位模型目录而不是用当前工作目录。数据库初始化一般不用手动做源码启动时会自动建表。但如果用sqlite3打开数据库发现表不存在就说明建表逻辑没触发先检查是否缺少init_db()调用。手动补一次建表也可以后面第5章会给出具体排查方式。4. 把识别参数调到可用状态阈值、注册库与多人场景的模型边界4.1 识别阈值怎么设距离阈值与置信度阈值的对应关系识别阈值是这类系统里最需要微调的数字直接决定“认错人”和“认不出人”哪个更频繁。人脸识别库里两个常见度量标准在face_recognition库中用的是欧氏距离通常小于0.45到0.5认为是同一个人在insightface或OpenCV DNN模型中用的是余弦相似度通常阈值在0.5到0.7之间越大越严格。我建议先别信源码里写死的阈值。把阈值调成偏严格的方向观察识别表现再逐步放宽。因为考勤场景里“认错人”的代价远高于“漏签到”——漏签到还可以人工补认错人会让整份考勤数据失去可信度。实际操作中先用face_recognition.api.face_distance拿到实际距离分布import face_recognition # 假设known_face是注册好的特征unknown_face是当前检测到的特征 # face距离越小表示越相似 matched_distances face_recognition.face_distance([known_face], unknown_face) print(与注册特征的距离:, matched_distances[0])如果同一个人的距离通常在0.30到0.35而不同人通常在0.55以上中间有大约0.2的间隔带那阈值取0.45就处于比较合理的位置。如果间隔带很窄比如同一人也到0.45不同人也低到0.50说明注册照片质量太差或光照影响太强此时调阈值救不回来得重新注册人脸。记住阈值永远不能代替数据质量。4.2 注册环节的细节一个人一张照片还是每人多张入库很多源码的注册脚本是打开摄像头拍一张就存然后提取特征入库。这种方式在多人考勤场景下会埋雷。因为教室光照、角度、距离和注册时差别很大单张照片的特征泛化能力不足会导致识别失败。最可靠的做法是每人注册3到5张照片分别在不同的脸部角度和光照条件下拍摄将特征向量取平均或分别存储比对时只要其中任意一张匹配成功就判定为同一人。如果源码的注册脚本只支持单张可以自己在数据库表结构里增加特征字段把多张照片的特征向量追加存为新的记录并在识别比对时遍历同一个人名下的全部特征。伪代码逻辑如下import sqlite3 import numpy as np def load_features_by_name(db_path, name): conn sqlite3.connect(db_path) rows conn.execute( SELECT feature_vector FROM face_features WHERE student_name ?, (name,) ).fetchall() conn.close() # 每行特征向量可能是BLOB或文本统一转成numpy数组后返回列表 features [] for row in rows: if isinstance(row[0], bytes): features.append(np.frombuffer(row[0], dtypenp.float64)) else: features.append(np.fromstring(row[0], sep,)) return features这段代码的逻辑是查询某个学生的全部注册特征逐条反序列化后返回。比对时当前人脸特征与这个列表里的每个特征分别算距离取最小值作为最终距离。这样做的代价是比对耗时随注册照片数线性增加但一个班40人、每人3张照片的规模下完全可接受。4.3 多人场景下的检测能力限制画面人数上限与帧率取舍多人考勤的核心矛盾在于检测和识别都是计算密集操作。画面里同时出现10个人和30个人识别耗时差异很大。实测下来face_recognition库自带的HOG检测器在CPU上单帧检测耗时约0.1到0.2秒特征提取每张脸还要0.1秒左右所以10人同框的理论帧率只能到每秒2到3帧。这种帧率下人快速走过摄像头会直接漏检。解法有两个方向源码里通常以参数形式暴露。一是调检测器的upsample_times默认是1改为0会牺牲小脸检测率但能显著提速。二是使用GPU版本的dlib或换用OpenCV DNN检测器DNN模型在CPU上的检测速度通常比HOG快一个量级。如果源码用的是face_recognition.face_locations可以看它是否允许传modelcnn有CUDA显卡时可以开启CPU上反而更慢。我的建议是如果教室能保证学生坐在固定位置把摄像头架高一点用更少但更清晰的人脸画面换取帧率。5. 多人人脸考勤翻车现场5条高频踩坑记录5.1 报错AttributeError: module cv2 has no attribute faceOpenCV扩展包缺失这是OpenCV系人脸识别最常见的翻车点。很多源码在cv2.face.LBPHFaceRecognizer_create()这里报错原因是opencv-python这个包不带face子模块face模块在opencv-contrib-python里。只有装过contrib版cv2.face才存在。解决方法是先卸载现有的OpenCV再安装contrib版pip uninstall opencv-python opencv-contrib-python然后pip install opencv-contrib-python4.8.1.78。注意不要两个包同时存在会相互覆盖dll。装完后重新import cv2并检查cv2.__version__同时确认hasattr(cv2, face)返回True。如果你用face_recognition库而不是cv2.face基本不会遇到这个问题如果你坚持用LBPH或FisherFace做训练式识别就必须走这一步。5.2 识别结果反复横跳同一人在几秒内时而识别成功时而失败现象是同一张脸在镜头前不动考勤记录里一会儿显示已签到一会儿又显示识别中或者识别成另一个人。原因通常是两个一是阈值设置在了距离分布的密集区人脸角度或表情的细微变化就让距离跨越阈值二是注册照片太少特征表达不稳定。解决方法是先打印人脸距离来确认波动范围。如果同一人的距离在0.35到0.52波动而阈值是0.45那波动就解释了为什么时好时坏。应对措施是把阈值放宽到0.55同时给每个学生补注册两张偏侧面和低角度的照片。如果这样还抖动需要检查预处理是否统一做了人脸对齐dlib的68点关键点对齐能显著提升特征稳定性。5.3 摄像头输出正常但考勤记录为空检测循环卡在某个子模块现象是窗口画面流畅但考勤表里一条记录都没有。原因多数出在识别分支抛了异常被外层continue吞掉比如某张脸提取特征时返回空数组源码没有做空值判断直接进入比对抛出的ValueError被无限循环捕获后跳过了整帧。排查思路是先缩小范围。把识别逻辑单独拉出来跑一遍静态图片看能否生成记录。常见做法是写一个人工触发函数直接传入一帧图像然后逐行定位异常是在face_locations、face_encodings还是数据库插入阶段。我在实际项目里发现这类源码最常见的是数据库插入前忘了检查学生是否已在考勤表导致重复插入异常被吞后逻辑中断。可以先手动执行一次插入确保SQL语句没有语法错误。5.4 注册成功但识别时总是提示未知人脸特征库索引与匹配逻辑错位现象是注册时提示Register Success但识别时任何一张脸都匹配不上哪怕注册者本人来看也不行。这种问题多数出在特征比对的索引错位上即face_encodings(known_face_names, known_face_encodings)这两个列表顺序不一致。注册时存入数据库的姓名顺序和特征顺序不是一一对应比对时就会拿名字A的特征与名字B的距离做判断。这个很隐蔽根源通常是注册脚本在写入数据库时用了两个独立的游标。解决方法是打印一下注册后加载出来的姓名与特征数量是否一致仔细检查数据库表里的student_name与feature_vector字段是否按预期一一配对import sqlite3 conn sqlite3.connect(attendance.db) rows conn.execute(SELECT student_name, feature_vector FROM face_features).fetchall() # 检查名字和特征的配对 for name, feat in rows: print(name, 特征长度:, len(feat)) conn.close()如果发现姓名有重复或特征长度对不上把注册数据清空重录一遍并且每次写入后立即验证可回读。5.5 源码跑起来后CPU占用拉满、课堂中途卡死单线程循环缺帧率控制现象是程序在无人状态下CPU占用率一直100%教室人一多直接卡死。原因是主循环里没有做帧率限制cap.read()频率远高于实际识别速度积压了大量帧在等待队列中。源码可能写成了while True: ret, frame cap.read()然后立刻识别没有time.sleep或帧间隔控制。解决方法是手动在循环结尾加入一个延迟把识别帧率限制在2到3帧每秒即可。因为考勤不需要流畅视频1秒处理1到2帧已经足够考生从容走过摄像头import time while True: ret, frame cap.read() if not ret: time.sleep(0.1) continue # 识别逻辑 # 每帧之间至少间隔0.2秒避免无人时CPU空转 time.sleep(0.2)如果发现间隔0.2秒还是卡把摄像头分辨率调低用cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)和cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)把画面降到VGA级别。教室考勤不需要1080pVGA分辨率下检测速度能提升超过两倍。6. 把系统搬进真实课堂一个更稳的多人识别验证方案如果你已经走到了这一步说明系统在本地基本能跑通了。但“能跑通”和“敢在真实课堂上用”之间还隔着一次可靠性验证。单人坐在摄像头前识别成功只能算功能演示真实课堂的多人场景必须有系统性验证。我建议从硬件和策略两个方向做最后的加固。硬件上如果使用笔记本原装摄像头画面角度太低学生被书本遮挡的概率极高。外接一个广角USB摄像头架在教室前方黑板正上方俯视角度能让所有人脸朝向镜头检测成功率会显著提高。策略上给考勤设置一个时间窗口比如课堂开始前5分钟和前10分钟各启动一轮识别同一学生只需在一个窗口期内成功一次即可不要追求实时识别所有人那在纯CPU环境下不现实。# 统计一轮多人识别中漏检情况的最小验证脚本 import cv2 import face_recognition cap cv2.VideoCapture(0) total_frames 30 success_frames 0 for _ in range(total_frames): ret, frame cap.read() if not ret: continue # 缩放到宽度640提升检测速度 small_frame cv2.resize(frame, (0, 0), fx0.5, fy0.5) rgb_frame cv2.cvtColor(small_frame, cv2.COLOR_BGR2RGB) locations face_recognition.face_locations(rgb_frame, modelhog) if locations: success_frames 1 print(当前帧检测到人脸数:, len(locations)) cap.release() print(f30帧中检测到人脸的帧数: {success_frames})逻辑说明正常在教室环境下30帧里只要有20帧以上能检测到人脸说明检测链路稳定如果检测到人脸的帧数不足一半多半是摄像头角度或距离问题需要调整设备而不是改代码。你也可以把模型参数从modelhog换成modelcnn对比一下在无GPU的CPU机器上hog检测更稳因为不会因为推理超时而丢帧。最后提醒一个常被忽略的细节考勤时间别用time.time()取服务器时间直接写入本地时间在跨时区和夏令时场景下会有偏差但有人值守的教室环境通常无所谓。这个源码适合作为课程设计和中小规模课堂的考勤底座不要直接梭哈到大型阶梯教室或非受控光线环境。多年来我带学生做这类系统最后都会让学生先记录自己的识别距离分布再写定阈值——把数据先拿出来再去说系统好不好用这是我认为做考勤系统最重要的一条习惯希望帮到你。本文还有配套的精品资源点击获取