简介：这份资源是一套基于Python的在线课堂考勤系统完整项目源码，面向具备一定Python基础、希望将CNN与计算机视觉落地到教育场景的开发者与学习者。项目以卷积神经网络为核心，结合OpenCV与深度学习框架完成人脸特征提取与识别，并配套Web界面与数据库设计，覆盖数据收集、预处理、模型构建、训练优化到测试部署的完整链路，适合作为课程设计、毕业设计或AI入门实战参考。压缩包共98个文件，约409.43MB，包含22个py源码、28张jpg样本图、15个xml配置、6张png、5个dat数据文件及3个pt模型权重等，源码、模型与素材齐备，目录按功能模块划分清晰。目前已有1461人学习下载，可帮助读者快速理解人脸考勤的工程实现思路，对照源码复现训练与识别流程，并在此基础上做二次开发与功能扩展。
1. 从一份压缩包说起：Python+CNN 的在线课堂考勤系统能落地到什么程度
线上课点名这件事，做过助教的人都懂——老师对着屏幕喊名字，学生刷个"到"，代签、漏签、重复签全来了。这份「基于 Python 的在线课堂考勤系统」压缩包，走的是另一条路：用摄像头抓脸，靠 CNN 提特征，自动比对身份后写库。解压后能看到code主目录、.idea工程配置、face_recognize_FK人脸识别模块、attentionDetect_FK注意力检测模块，以及code.iml、misc.xml、modules.xml、workspace.xml这套 PyCharm 工程文件。技术栈是 Python + OpenCV + 深度学习框架 + Web 层，适合两类人：一是想拿它当课程设计或毕设底座的在校生，二是想拆一套"人脸识别 + 业务系统"完整链路的中级开发者。它解决的不是"能不能识别人脸"这个单点问题，而是把识别结果接进考勤业务流——谁到了、几点到的、哪节课没到，全部落库可查。下面按"资源是什么 → 怎么跑起来 → 坑在哪 → 怎么改"的顺序拆。
2. 拆包看结构：face_recognize_FK 与 attentionDetect_FK 各管什么
拿到压缩包先别急着pip install，把目录结构摸清楚，后面调参和排错才不会抓瞎。这份工程是典型的 PyCharm 项目布局，.idea目录里那堆 xml 是 IDE 的工程元数据，跟业务逻辑无关，但删了会导致导入后目录结构错乱，建议原样保留。
2.1 工程文件与业务代码的分层
先看根目录的构成。code.iml是 IntelliJ 系 IDE 的模块描述文件，misc.xml记录 Python SDK 版本，modules.xml声明模块归属，workspace.xml存的是窗口布局、最近打开文件这类本地状态。这四个文件加上.gitignore和inspectionProfiles，构成了完整的工程骨架。真正的业务代码在code目录下，而face_recognize_FK和attentionDetect_FK是两个功能子模块——从命名看，FK大概率是作者或团队的缩写后缀，不影响功能。
常见做法是：把face_recognize_FK理解成"人脸识别引擎"，负责检测人脸框、提取特征向量、跟底库比对；attentionDetect_FK则是"注意力检测"，通过头部姿态或眼部开合判断学生是否在看屏幕。两者一个管"你是谁"，一个管"你在不在状态"，组合起来才是完整的课堂考勤语义。
| 目录/文件 | 作用 | 是否可改 |
|---|---|---|
.idea/ | IDE 工程配置 | 不建议手改 |
code/ | 主业务代码 | 核心改动区 |
face_recognize_FK/ | 人脸识别模块 | 按需替换模型 |
attentionDetect_FK/ | 注意力检测模块 | 按需调阈值 |
code.iml/misc.xml | 模块与 SDK 声明 | 换 Python 版本时改 |
2.2 人脸识别链路的四个环节
face_recognize_FK内部跑的是标准的人脸识别流水线，拆开就是四步：人脸检测、对齐、特征提取、比对。检测环节常见用 OpenCV 的 Haar 级联或 DNN 模块，前者轻量但侧脸容易漏，后者精度高一点但要多下一个模型文件。对齐是把歪头、旋转的人脸摆正，这一步不做的话，后面 CNN 提取的特征会飘。特征提取就是 CNN 的主场——卷积层抓局部纹理（眼角、鼻翼、唇形），池化层降维，全连接层把特征压成一个固定长度的向量。最后拿这个向量跟底库里每个学生的向量算距离，小于阈值就判定为同一人。
这里有个容易被忽略的点：CNN 输出的不是"这是张三"，而是一个高维向量。真正决定识别结果的是比对阶段的距离度量和阈值。阈值设 0.6 还是 0.4，直接决定误识率和拒识率的平衡，后面第 4 章会专门讲怎么调。
2.3 注意力检测模块的判定逻辑
attentionDetect_FK相对独立，它不关心你是谁，只关心你的脸朝向哪、眼睛睁没睁。常见实现有两种：一是基于面部关键点（68 点或 5 点）算头部姿态角，俯仰角或偏航角超过阈值就判为"低头/转头"；二是基于眼睛纵横比（EAR）判断闭眼，连续多帧低于阈值就判为"走神"。
这个模块的价值在于：光识别到人脸不等于在听课，学生把手机架在摄像头前人就跑了，纯人脸考勤照样能签上。加上注意力检测，才能把"人在"和"人在听"区分开。不过要注意，注意力检测的误报率天然比人脸识别高——揉眼睛、低头记笔记都可能被误判，所以它的输出一般只做参考标记，不直接否决考勤。
3. 把工程跑起来：环境配置、依赖安装与首次推理
结构看明白了，接下来是动手环节。这份工程是 Python 项目，跑起来的关键是把依赖装对、把模型文件放对位置、把入口脚本找对。下面按顺序走一遍。
3.1 Python 环境与依赖安装
先确认 Python 版本。深度学习框架对版本敏感，TensorFlow 2.x 和 PyTorch 对 Python 的要求不同，建议用 3.8～3.10 这个区间，太新的版本（3.12+）有些老库还没适配。装完 Python 后建虚拟环境，别往全局环境里怼。
# 建虚拟环境，隔离依赖 python -m venv venv # 激活（Windows） venv\Scripts\activate # 激活（Linux / macOS） source venv/bin/activate # 装核心依赖 pip install opencv-python numpy flask # 深度学习框架二选一，看工程用的是哪个 pip install tensorflow # 或 pip install torch torchvision逻辑说明：venv建独立环境是为了避免跟系统里其他项目的库版本打架，人脸识别项目经常卡在 numpy 版本冲突上。opencv-python负责图像读取、人脸检测和画框显示；numpy是底层数组运算；flask是 Web 层，用来起考勤管理界面。深度学习框架按工程实际用的选，装之前先翻一下code目录里的 import 语句，别两个都装，容易互相干扰。
参数说明：如果pip install卡在下载，换国内镜像源，命令后面加-i https://pypi.tuna.tsinghua.edu.cn/simple。如果装 TensorFlow 报错，先看 Python 版本对不对，再看是不是缺 Visual C++ 运行库（Windows 上常见）。
3.2 模型文件与底库的准备
代码跑不起来，十有八九是模型文件没放对位置。人脸识别工程通常需要两类文件：一是检测模型（如haarcascade_frontalface_default.xml或 DNN 的 caffemodel），二是特征提取模型（自己训练的 CNN 权重，或预训练模型）。这些文件在压缩包里不一定齐全，缺的话要按代码里的路径提示补上。
底库是另一回事。底库就是"已知学生的人脸特征库"，每个学生对应一个特征向量。首次运行前，得先采集每个学生的照片，跑一遍特征提取，把向量存成文件（常见是.npy或.pkl）。这一步不做，系统认不出任何人。
import cv2 import numpy as np import os # 人脸检测器，路径按工程实际位置改 detector = cv2.CascadeClassifier('face_recognize_FK/haarcascade_frontalface_default.xml') # 底库字典：姓名 -> 特征向量 face_db = {} def build_face_db(students_dir): """遍历学生照片目录，提取特征存入底库""" for name in os.listdir(students_dir): person_dir = os.path.join(students_dir, name) if not os.path.isdir(person_dir): continue features = [] for img_file in os.listdir(person_dir): img = cv2.imread(os.path.join(person_dir, img_file)) gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) faces = detector.detectMultiScale(gray, 1.3, 5) for (x, y, w, h) in faces: roi = gray[y:y+h, x:x+w] roi = cv2.resize(roi, (100, 100)) # 统一尺寸 features.append(roi.flatten()) if features: # 取均值作为该学生的代表特征 face_db[name] = np.mean(features, axis=0) np.save('face_db.npy', face_db) print(f'底库构建完成，共 {len(face_db)} 人') build_face_db('students')逻辑说明：这段脚本遍历students目录，每个子目录是一个学生的多张照片。对每张照片做人脸检测，裁出人脸区域，统一缩放到 100×100，展平成一维向量。一个学生多张照片的特征取均值，作为这个人的代表向量。最后存成face_db.npy。
参数说明：detectMultiScale的1.3是每次扫描的缩放比例，值越小检测越细但越慢；5是邻域阈值，越大越严格、误检越少但可能漏检。resize的目标尺寸要跟后面 CNN 输入尺寸一致，不一致会导致比对时报维度错误。取均值是最简单的聚合方式，样本多的话可以改用聚类中心。
3.3 启动入口与首次推理
底库建好后，找入口脚本。常见命名是main.py、app.py或run.py，在code目录下。启动前确认三件事：模型文件路径对、底库文件存在、摄像头能打开。
# 进主代码目录 cd code # 启动 Web 服务（假设入口是 app.py） python app.py # 如果是纯识别脚本 python main.py逻辑说明：Web 入口一般会起一个 Flask 服务，监听本地端口（常见 5000），浏览器打开就能看到考勤界面。纯识别脚本则直接调摄像头，窗口里实时画框、显示识别结果。
参数说明：摄像头打不开，先查是不是被其他程序占用，Linux 下看/dev/video0权限，Windows 下看设备管理器。识别结果一直显示"未知"，八成是底库没建或阈值太严，下一章细说。
4. 避坑与排查：识别不准、摄像头打不开、依赖冲突怎么破
这套工程跑通不难，跑准很难。下面五条是我拆这类项目时踩过的真实坑，按"现象 → 原因 → 解决"记下来。
现象一：识别结果频繁跳变，同一个人一会儿认出一会儿认不出。原因：底库样本太少，或者光照条件跟采集时差太多。CNN 提取的特征对光照敏感，训练集全是正面亮光脸，实际课堂是侧光、背光，特征分布就偏了。 解决：每个学生至少采集 10～20 张不同角度、不同光照的照片重建底库；比对时不要只看单帧，连续 5 帧里 3 帧命中才判定，用投票平滑掉抖动。
现象二：摄像头打开报错can't open camera by index。原因：索引号不对，或者设备被占用。笔记本自带摄像头通常是 0，外接 USB 摄像头可能是 1 或 2。 解决：把cv2.VideoCapture(0)里的 0 依次换成 1、2 试；Linux 下用ls /dev/video*看设备号；确认没有其他程序（如会议软件）占着摄像头。
现象三：pip install装到一半报 numpy 版本冲突。原因：OpenCV、TensorFlow、PyTorch 对 numpy 的版本要求不一致，后装的会覆盖先装的。 解决：先装框架再装 OpenCV，或者用pip install "numpy<1.24"锁定版本。实在理不清就重建虚拟环境，按"框架 → opencv → 其他"的顺序装。
现象四：注意力检测误报太多，低头记笔记被判成走神。原因：阈值设得太激进，或者只用了单帧判定。 解决：把俯仰角阈值放宽（比如从 15° 放到 25°），闭眼判定改成连续 15 帧以上才触发；把注意力结果只做标记不做否决，让老师人工复核。
现象五：Web 界面能打开但提交考勤没反应。原因：数据库没初始化，或者 Flask 的路由跟前端请求路径对不上。 解决：看app.py里有没有db.create_all()之类的初始化调用；打开浏览器 F12 看 Network 面板，确认请求发到了哪个路径、返回了什么状态码，再回头对路由。
提示：这套工程的坑大多集中在"环境"和"阈值"两块，代码逻辑本身出问题的概率反而低。跑不通先查依赖和路径，别急着改代码。
5. 从能跑到好用：阈值调优、底库增量更新与注意力联动
跑通只是起点，真正决定这套系统能不能用在真实课堂的，是三个进阶动作：把比对阈值调到误识和拒识的平衡点、让底库支持增量更新、把注意力检测跟考勤结果联动起来。
5.1 用 ROC 思路找比对阈值
人脸比对的核心参数是距离阈值。阈值太松，别人刷脸也能签上；太紧，本人站歪一点就认不出。工程里常见用欧氏距离或余弦相似度，判定逻辑是"距离小于阈值即同一人"。调这个值不能拍脑袋，得用数据说话。
做法是：准备一批已知身份的测试样本，对每个样本算它跟底库里正确身份和错误身份的距离，画一条阈值-准确率曲线。实操上简化一点，直接跑一组阈值看准确率变化：
import numpy as np def evaluate_threshold(face_db, test_samples, thresholds): """test_samples: [(特征向量, 真实姓名), ...]""" for th in thresholds: correct = 0 for feat, true_name in test_samples: best_name, best_dist = None, float('inf') for name, db_feat in face_db.items(): dist = np.linalg.norm(feat - db_feat) # 欧氏距离 if dist < best_dist: best_dist, best_name = dist, name # 距离小于阈值且名字对，才算正确 if best_dist < th and best_name == true_name: correct += 1 acc = correct / len(test_samples) print(f'阈值 {th:.2f} -> 准确率 {acc:.2%}') # 阈值从 0.3 扫到 0.8 evaluate_threshold(face_db, test_samples, np.arange(0.3, 0.81, 0.05))逻辑说明：对每个测试样本，遍历底库找距离最近的人，如果最近距离小于当前阈值且名字匹配，记为正确。扫一遍阈值区间，看准确率在哪个点最高。
参数说明：欧氏距离适合特征向量已归一化的情况，没归一化的话改用余弦相似度。阈值区间要根据实际特征尺度定，不同模型输出的向量范围不一样，别照搬 0.3～0.8，先打印几个样本的距离看看分布。
5.2 底库增量更新
真实场景里学生是流动的，每学期都有新人。全量重建底库费时费力，更好的做法是增量更新——新学生来了只加他那条，老学生转走了只删他那条。
def add_student(face_db, name, features): """增量添加一个学生，features 是该学生多张照片的特征列表""" face_db[name] = np.mean(features, axis=0) np.save('face_db.npy', face_db) print(f'已添加 {name}，当前底库 {len(face_db)} 人') def remove_student(face_db, name): """删除一个学生""" if name in face_db: del face_db[name] np.save('face_db.npy', face_db) print(f'已移除 {name}')逻辑说明：add_student把新学生的多张特征取均值后写入字典并落盘，remove_student直接删键。两个操作都不影响其他学生的数据。
参数说明：增量更新要注意特征提取用的模型必须跟建库时一致，换了模型整个底库都得重建，否则向量不在同一空间，比对全乱。这是血泪经验——我见过有人换了模型只更新了部分底库，结果新旧向量混在一起，识别率直接崩了。
5.3 注意力与考勤的联动策略
最后说联动。注意力检测的输出不该直接否决考勤，而应该作为附加标记。合理的策略是：人脸识别确认身份后记"已签到"，注意力检测在签到后的时间窗内持续采样，算出"专注时长占比"，低于某个比例（比如 60%）就在考勤记录里标一个"注意力异常"。
这样老师看到的不只是"到没到"，还有"到了之后在不在状态"。实现上，注意力模块按固定间隔（比如每 30 秒）输出一次状态，考勤模块累计统计。阈值和采样间隔都要按实际课堂节奏调，采样太密浪费算力，太疏又抓不住走神。
从那以后我每次拆这类人脸考勤工程，都强制先跑一遍阈值扫描、再确认底库和模型版本一致，最后才动业务逻辑——顺序反了，调半天都是在跟环境较劲。希望帮到你。
本文还有配套的精品资源，点击获取
