简介基于Python与FaceNet实现的人脸检测与识别课堂学生签到系统是一份面向高校毕业设计或课程项目的完整源码包系统以人脸特征提取为核心解决传统点名效率低、代签等问题适合具备一定Python基础、希望学习深度学习落地应用的开发者参考。压缩包共包含21个文件其中15个Python脚本构成主要业务逻辑4个pyc为预编译模块另附字体文件与演示动图整体大小约40MB文件组织清晰涵盖人脸检测、摄像头调用、界面初始化等模块。该资源目前已有152人学习使用源码均已本地编译可运行评审分达95分以上并经助教老师审定。随包附带数据集与详细文档便于对照理解FaceNet模型的调用流程与签到系统的完整实现可作为毕业设计、课程作业或人脸识别入门项目的优质参考。1. 基于PythonFaceNet的课堂签到系统它解决的是“点名”这个真问题一个基于PythonFaceNet的人脸检测与识别课堂学生签到系统核心思路是把“老师点名”拆成三个自动环节先用人脸检测模型在教室画面里找到每一张脸再用FaceNet把每张脸压缩成一个固定长度的特征向量最后拿这个向量和已注册学生的人脸特征库做比对相似度超过阈值就写入签到记录。它解决的核心诉求是学生不排队、不刷卡、不用手工勾名单坐下即完成考勤同时每节课的签到时间自动留存课后随时可核对。这个方向适合三类人。第一类是正在选题的毕业生课题闭环完整有数据、有文档、有可演示界面答辩时模型原理和工程链路都能讲透第二类是厌倦了点名的授课老师想花一两节课时间部署一套能用的教室考勤第三类是刚开始接触度量学习的开发者想找一个FaceNet落地到真实业务的最小案例。需要提前说明的是课堂场景里光线、遮挡、角度、后排距离都会让识别翻车本文不吹准确率每章都在处理这些现实约束照着走完一遍你能得到一条可演示、可讲清的完整链路。2. FaceNet原理与系统架构为什么签到要用度量学习而不是分类网络2.1 FaceNet的Embedding机制把一张脸压缩成固定维度向量早期人脸识别系统几乎都走分类路线用Softmax训练一个网络输出是“这人是谁”类别数等于学生人数。这个方案有三个硬伤每来一个新生就要重训一次训练数据必须覆盖每个学生的所有姿态类别太多时最后一层全连接参数膨胀到难以训练。课堂签到恰恰最怕这三点学生名单每学期都在变注册照片只有三五张可识别的人还要持续增加。FaceNet换了一条路它不回答“你是谁”而是回答“这张脸和那张脸有多像”。FaceNet把一张对齐后的人脸图片喂进卷积网络输出一个固定维度的向量原始论文是128维现在常见的开源实现输出512维。训练时用三元组损失Triplet Loss一个锚点样本、一个同人正样本、一个异人负样本目标是把正样本拉近、负样本推远距离边界由margin控制。训练完成后这个向量空间就有了语义同一个人不管换角度、换表情、换光线向量都落在相近区域不同人的向量彼此远离。推理阶段就更简单了一张脸过一遍网络得到一个向量和库里所有注册向量算距离取最近的那个距离小于阈值就算命中。这意味着新增学生不需要重训模型只要把他的照片也过一遍网络存进向量库系统立刻认识他。这个特性是签到系统选择FaceNet的决定性理由模型只需训练一次学生库的增删改查都是数据操作。代价是精度上限取决于预训练模型的质量和注册照片的覆盖度这两点在后面章节专门展开。2.2 三层架构人脸检测、特征提取、身份比对各司其职一套完整的人脸签到系统从上到下分三层。第一层是人脸检测输入是摄像机整帧画面输出是画面里所有人脸的边界框。最常见的选型是MTCNN它用三个级联网络P-Net、R-Net、O-Net由粗到细地筛人脸先快速框出候选区域再逐步精修坐标和关键点关键点还能用来做对齐。OpenCV自带的DNN人脸检测器是另一个选择速度快但缺少关键点输出对齐得自己补。第二层是特征提取也就是FaceNet本体。检测层切出的人脸区域经过缩放、对齐、归一化后喂进InceptionResnetV1输出归一化后的特征向量。这里有个容易忽略的细节对齐不是可选项。MTCNN检测到的关键点两只眼睛、鼻尖、嘴角可以用来做仿射变换把脸摆正到统一位置能显著降低姿态差异带来的向量漂移。偷懒跳过对齐识别率会掉一到两个档次。第三层是身份比对与业务逻辑。注册阶段生成的向量库加载进内存当前帧的每个新向量和库里的向量逐一算余弦相似度取最高值跟阈值比。命中后进入业务层写入签到记录、绑定课程和学号、生成迟到早退标记、去重防止一节课重复签到。这三层是串行依赖的检测漏了后续全白搭比对阈值设错了记录就张冠李戴所以排错时要从第一层开始逐层验证不要一上来就怀疑FaceNet模型。2.3 数据集怎么组织注册照片、验证集与目录约定压缩包里的数据集一般长这个结构dataset/ ├── register/ # 注册照片每个学生一个目录 │ ├── 2021001/ │ │ ├── front.jpg │ │ ├── left.jpg │ │ └── right.jpg │ ├── 2021002/ │ │ ├── front.jpg │ │ └── up.jpg │ └── ... # 学号目录目录名就是学生ID ├── test/ # 阈值调优用的验证集与注册照片不同人/不同时刻 └── attendance/ # 签到记录输出目录目录名直接当学号用这是最简单也最不容易出错的约定。注册阶段遍历dataset/register下的子目录子目录名就是学生ID子目录里的每张照片都提取一个向量同一个学生的多个向量取平均后入库。注意“多个向量取平均”是常见做法但如果某个角度的照片质量明显差平均反而会把好向量带偏我一般会先看一眼每张照片提取出的向量和同人其他向量的距离剔除明显离群的再平均。验证集和注册集要严格分开这是很多人忽略的。验证集的作用是调阈值如果调阈值用的照片和注册照片是同一批测出来的相似度虚高现场一换光线就露馅。正确的做法是验证集用另一天、另一个场景拍的学生照片模拟真实课堂里“注册时和签到时长相有差异”的情况。课堂场景的验证集不需要很大每个学生三五张、另外找十几个不同的人当负样本就已经能算出可用的阈值了。3. 从零跑通签到系统环境配置、注册脚本与实时签到链路3.1 环境准备依赖清单与版本组合这类毕业设计通常不用自己从零训练FaceNet而是加载预训练权重环境要求不算苛刻。我按常见配置整理了一张表依赖常见版本作用Python3.8 / 3.9运行环境PyTorch1.10深度学习计算框架facenet-pytorch2.5提供MTCNN检测与InceptionResnetV1模型opencv-python4.5摄像头读取、图像裁剪、画框numpy1.21向量与距离计算Pillow8.x图片文件读写安装就一条命令pip install torch opencv-python numpy pillow facenet-pytorch如果你机器上没有独立显卡torch会默认装CPU版检测和推理都能跑只是慢一些。第一次实例化MTCNN和InceptionResnetV1时facenet-pytorch会自动下载预训练权重网络环境不好的时候可能要多试几次也可以手动下载权重文件放到缓存目录。GPU不是必须的但后续做多人同时签到、实时视频流处理时CPU推理会明显掉帧有显卡的话建议装CUDA版torch。注意facenet-pytorch 的 InceptionResnetV1 默认输出 512 维向量原始 FaceNet 论文是 128 维。维度不同只影响存储大小和计算量不改变比对逻辑不要因为看到 512 就以为模型不对。3.2 注册学生人脸库从照片到Embedding库的完整脚本注册阶段的目标是扫描dataset/register目录对每个学生的每张照片提取向量输出一个向量库文件。下面的脚本是完整的可以直接存成register.py使用import os import argparse import numpy as np import torch from PIL import Image from facenet_pytorch import MTCNN, InceptionResnetV1 parser argparse.ArgumentParser(description注册学生人脸库) parser.add_argument(--register_dir, defaultdataset/register) parser.add_argument(--output, defaultdata/embeddings.npz) parser.add_argument(--min_face_size, typeint, default40) args parser.parse_args() device torch.device(cuda if torch.cuda.is_available() else cpu) # MTCNN 负责检测对齐image_size160 是 FaceNet 的固定输入尺寸 mtcnn MTCNN(image_size160, margin20, min_face_sizeargs.min_face_size, devicedevice) facenet InceptionResnetV1(pretrainedvggface2).eval().to(device) def embed_img(path): img Image.open(path).convert(RGB) face mtcnn(img) # 未检测到人脸时返回 None if face is None: return None with torch.no_grad(): emb facenet(face.unsqueeze(0).to(device)) # L2 归一化后向量点积就等于余弦相似度 return torch.nn.functional.normalize(emb, p2, dim1).cpu().numpy()[0] ids, embs [], [] for student_id in sorted(os.listdir(args.register_dir)): stu_dir os.path.join(args.register_dir, student_id) if not os.path.isdir(stu_dir): continue vecs [] for fname in sorted(os.listdir(stu_dir)): if not fname.lower().endswith((.jpg, .jpeg, .png)): continue emb embed_img(os.path.join(stu_dir, fname)) if emb is not None: vecs.append(emb) if len(vecs) 0: print(f[跳过] {student_id}: 没有可用的脸) continue ids.append(student_id) embs.append(np.mean(vecs, axis0)) # 多张照片的平均向量 print(f[完成] {student_id}: {len(vecs)} 张照片 - 1 个向量) np.savez(args.output, idsnp.array(ids), embsnp.array(embs)) print(f共注册 {len(ids)} 名学生向量库已保存到 {args.output})这段脚本的要点有三个。第一facenet(face.unsqueeze(0))里的unsqueeze(0)是在给单张图片补一个batch维度这个维度漏了就报维度错误。第二归一化在注册和签到两端必须同时做否则余弦相似度算出来是错的很多同学只在注册端归一化签到端忘了结果相似度全部偏高。第三min_face_size这个参数控制多小的脸才算是人脸注册照片里脸一般很大设40没问题但签到端如果照到后排学生需要把这个值调小。跑完脚本后检查一下输出。向量库里有一个学生是空列表多半是照片本身模糊或MTCNN误判每个学生的平均向量和单张照片向量的最大距离如果超过0.3说明这名学生的照片之间差异过大需要补拍。注册阶段多花十分钟检查能避免签到阶段一整个学期的烦恼。3.3 实时签到推理摄像头画面里的检测、比对与记录注册完成拿到data/embeddings.npz后就可以跑实时签到。下面的脚本读取摄像头画面对每一帧做人脸检测、向量提取、比对和签到记录import cv2 import numpy as np import torch import datetime from facenet_pytorch import MTCNN, InceptionResnetV1 threshold 0.65 # 余弦相似度阈值先用这个值跑后面用验证集精调 frame_skip 3 # 每 3 帧处理一次降低 CPU 压力 device torch.device(cuda if torch.cuda.is_available() else cpu) mtcnn MTCNN(image_size160, margin20, min_face_size40, devicedevice) facenet InceptionResnetV1(pretrainedvggface2).eval().to(device) data np.load(data/embeddings.npz, allow_pickleTrue) student_ids, emb_db data[ids], data[embs] signed_set set() # 已签到的学号一个进程内去重 def sign_in(student_id): if student_id in signed_set: return False signed_set.add(student_id) now datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S) with open(attendance/records.csv, a, encodingutf-8) as f: f.write(f{student_id},{now},已到\n) return True cap cv2.VideoCapture(0) # 0 是本机摄像头局域网摄像头可换 RTSP 地址 frame_count 0 while True: ret, frame cap.read() if not ret: break frame_count 1 if frame_count % frame_skip ! 0: continue faces mtcnn(frame) # 整帧输入返回对齐后的人脸张量 if faces is None: continue if faces.ndim 3: faces faces.unsqueeze(0) with torch.no_grad(): embs facenet(faces) embs torch.nn.functional.normalize(embs, p2, dim1).cpu().numpy() for emb in embs: sims emb_db emb # 归一化后点积 余弦相似度 idx int(np.argmax(sims)) if sims[idx] threshold: if sign_in(student_ids[idx]): print(f{student_ids[idx]} 签到成功相似度 {sims[idx]:.3f}) # 这里可以叠加画框逻辑把识别结果画在 frame 上 cv2.imshow(Attendance, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()代码里有三个值得展开的点。一个是emb_db emb这行因为注册和签到两端都做了L2归一化两个向量的点积就是余弦相似度省去了手动调np.linalg.norm的麻烦也避免了逐条循环的低效写法。另一个是signed_set去重它防止某个人在镜头前停留30秒就被写入30条签到记录这是课堂考勤的硬需求但它的局限是进程重启后去重失效更稳妥的方案是把去重条件落到CSV文件本身按“学号日期”做唯一约束。第三个是frame_skip跳过中间帧能大幅降低CPU占用代价是会漏掉短暂转头的人脸通常3到5比较平衡。跑通这一版之后你已经有了一个可演示、可签到的完整系统。这时候别急着换模型或调参先拿自己的照片注册进去在摄像头前前后左右转一转感受一下哪些姿势和光线条件下识别稳定、哪些不稳定这比直接改代码更有价值。4. 模型训练与阈值调优把识别准确率从及格拉到可用4.1 预训练模型怎么选直接复用、冻结微调还是完整重训拿到压缩包后很多人第一反应是“我要自己训练模型”其实没必要。FaceNet的预训练权重是在千万级人脸数据上训出来的课堂场景属于下游应用直接复用通常已经够用。先看三种方案的成本收益方案是否需要GPU新增学生准确率提升空间适合情况直接复用预训练权重不需要无需训练低毕设演示、小班签到、快速验证冻结主干 微调输出层推荐需重新微调中有少量课堂数据想压特定场景完整训练Triplet Loss需要无需训练高有大体量自建数据集追求上限我一般建议先把方案一跑通得到一条完整链路后再决定要不要微调。原因很现实一旦改动模型前面注册阶段生成的向量库全部作废得重新提取一次如果微调手法不熟练准确率反而可能比预训练权重更低。很多翻车案例都是“模型是自己训的但还不如网上现成权重”不是模型差是数据量撑不起训练。如果确实要微调推荐折中路线加载预训练权重冻结前面的骨干卷积层只让最后几个block和输出层参与训练。这样需要的训练数据量小、不容易过拟合而且因为骨干网络的特征提取能力被保留课堂场景下微调几百步就能看到效果。完整重训是最后的选择它需要每一类每个学生至少几十张照片、做严格的数据清洗绝大多数毕业设计的数据量根本不够。4.2 Triplet训练脚本的关键参数margin、学习率与难样本挖掘微调场景下最常用的损失还是三元组损失。下面是一个最小训练循环理解它比跑通它更重要import torch import torch.nn.functional as F from torch.utils.data import DataLoader def triplet_loss(anchor, positive, negative, margin0.2): # 三个向量的欧氏距离缩放到 [-1,1] 范围后计算 pos_dist F.pairwise_distance(anchor, positive, p2) neg_dist F.pairwise_distance(anchor, negative, p2) # relu 保证损失不为负正样本距离必须比负样本距离小 margin 以上 return torch.relu(pos_dist - neg_dist margin).mean() # 假设 dataloader 每个 batch 返回 (anchor, positive, negative) def train_one_epoch(model, dataloader, optimizer, margin0.2): model.train() total_loss 0.0 for anchor, positive, negative in dataloader: anchor anchor.to(model.device) positive positive.to(model.device) negative negative.to(model.device) optimizer.zero_grad() a_emb F.normalize(model(anchor), p2, dim1) p_emb F.normalize(model(positive), p2, dim1) n_emb F.normalize(model(negative), p2, dim1) loss triplet_loss(a_emb, p_emb, n_emb, margin) loss.backward() optimizer.step() total_loss loss.item() return total_loss / len(dataloader)三个参数的设定逻辑值得单独说。margin控制“正样本要比负样本近多少”默认0.2是论文原值课堂数据不够干净时可以放宽到0.3但不要超过0.5否则模型会过度拉大不同人之间的距离反而挤压了同人脸向量聚拢的空间。学习率从1e-4起步每5个epoch降为原来的0.1倍动量SGD在这个任务上比Adam更稳Adam收敛快但容易把向量空间压得太紧。batch size建议32以上因为三元组是从batch内部采样的batch太小采不到有效的难样本。这里要重点提醒一个黑匣子问题Triplet Loss的训练效果极度依赖难样本挖掘策略。随机挑三元组大部分组合里的负样本和锚点长得完全不同损失接近0梯度没有信号。常见做法是batch内难负样本挖掘Batch Hard也就是对batch里每个锚点选距离最近的那个异人样本当负样本这样每步都能产生有效梯度。不加挖掘策略直接训loss曲线会一路平稳看着像收敛了实际模型什么都没学到。4.3 阈值调优用ROC曲线和验证集定下你的签到及格线阈值是整个人脸签到系统里最像玄学的参数但它其实有标准的定量方法。思路是把验证集里所有两两配对算一遍相似度同一个人两两配对得到“类内相似度”分布不同人的配对得到“类间相似度”分布然后在两个分布之间找分割点。用验证集数据算出来比自己拍脑袋猜0.65靠谱一个量级。import numpy as np # 假设 val_embs 是验证集向量val_labels 是每张图对应的学生ID def roc_threshold(val_embs, val_labels): same_sims, diff_sims [], [] n len(val_embs) for i in range(n): for j in range(i 1, n): sim float(val_embs[i] val_embs[j]) if val_labels[i] val_labels[j]: same_sims.append(sim) else: diff_sims.append(sim) same_sims np.array(same_sims) diff_sims np.array(diff_sims) best_t, best_score 0.0, -1.0 for t in np.arange(0.4, 0.8, 0.01): # 准确率 类内高于阈值 类间低于阈值的比例 acc (same_sims t).mean() (diff_sims t).mean() score acc / 2 if score best_score: best_score, best_t score, t return best_t这段代码用网格搜索在0.4到0.8之间找使准确率最高的阈值。现实经验是类内和类间分布总是有重叠的重叠区越大说明注册照片质量越差或预训练模型越不适合当前场景此时调阈值是治标不治本。如果类内相似度平均值低于0.7第一优先不是调阈值而是回头检查注册照片的对齐质量、增加每名学生的注册照片数。阈值只能单点比对多人同时出现在画面里时还需要叠加一个时序策略来抗噪。常见做法是多帧投票同一学号在连续N帧里被识别到M次比如5帧中出现3次才确认签到。这个策略能把偶发的误识别滤掉代价是学生必须面向镜头停留一小段时间。投票帧数N不建议设太大课堂场景学生是走动的N超过10帧会明显漏签。5. 避坑指南课堂场景签到系统翻车的六个典型问题这一章是血泪经验汇总。课堂场景和实验室演示最大的区别在于人脸尺度小、角度杂、遮挡频繁、光线不可控。下面六条是我按出现频率排序的踩坑记录每条都按“现象→原因→解决”来讲你照着排查能省下大量时间。5.1 戴眼镜、换发型就识别失败现象学生注册时没戴眼镜上课戴了眼镜就签不上男生剪了短发后反复识别失败。原因FaceNet对局部遮挡和外观突变有敏感性眼镜框、刘海变化会改变向量在特征空间的位置使其偏离注册时的聚簇中心。如果注册照片只有正脸一张这种偏差很容易把向量推出阈值边界。解决注册时要求每名学生提供至少3张不同姿态和光照的照片签到端对连续识别失败的学生通过学号触发“现场补采”流程灰度化、直方图均衡化后再比对一次。真正长期可用的做法是每半个学期用签到过程中成功识别的高置信度截图更新一次向量库让库跟着学生的实际外观走。5.2 后排学生人脸太小导致漏检现象第一排识别率接近100%第五排以后几乎签不到人画面里明明有脸。原因MTCNN的min_face_size默认值较大后排人脸在画面里只有二三十像素高低于检测器的最小脸阈值直接被过滤掉了。这是漏检问题不是识别问题特征提取模型再强也没用。解决把签到端的min_face_size从默认值调小到20左右并适当增大原图分辨率。另外可以按区域处理检测失败时把画面上下分成几个带对每个带做一次放大后再检测后排区域用1.5到2倍放大重试。这个技巧对教室这类固定机位场景特别有效。5.3 多人同框时张冠李戴现象两个学生挨着坐识别结果频繁错乱A的脸识别成BB的脸识别成A。原因检测框抖动导致裁出的人脸区域不干净或者比对逻辑没有和检测框绑定视频流里目标在移动向量库比对结果错位。解决在比对前给每个检测框分配一个跟踪ID用IoU匹配前后帧的同一个框对同一个跟踪ID做多帧投票后再定位到学生。另一个容易忽略的点是检测框要向外扩10到20像素再裁人脸把下巴和额头边缘完整包含进去裁剪太紧会把特征切丢。5.4 GPU显存不足或CPU推理卡顿现象多人同框时显存报错程序崩溃CPU机器上画面像幻灯片签到响应延迟好几秒。原因把整帧的所有人脸同时喂给模型时batch大小不受控CPU推理本身慢再加上每帧都跑一次完整检测和特征提取。解决显存不足就把批量推理改成逐张推理并每处理完一个人脸就清一次中间张量更彻底的做法是限制单帧最多处理10张脸超出部分排队到下一帧。CPU机器把frame_skip调到5并把画面分辨率缩到640x480再送检测检测耗时会降为原来的三分之一。卡顿时优先看检测层耗时它通常占整体时间的70%以上。5.5 阈值拍脑袋导致误签或漏签现象阈值设0.5学生A没来却显示A已签到阈值设0.8来了半天签不上。原因0.5太宽松不同人的向量也可能达到这个相似度产生误签0.8太严格同一人换个角度就够不着产生漏签。阈值不是经验值它由注册照片质量和模型能力共同决定每个数据集的最优阈值都不一样。解决按4.3节的ROC方法用验证集算出阈值每换一批注册照片就重算一次。如果类内和类间的相似度分布重叠严重说明问题不在阈值而在注册数据优先补照片而不是继续压阈值。5.6 同一人一节课签到十几次现象签到记录里同一个学号重复出现导出考勤表时还得人工去重。原因视频流每一帧都在跑比对只要人没离开画面就一直命中。signed_set只解决了单次运行内的去重程序重启或跨课时就失效了。解决把去重下沉到数据层签到记录表用“学号日期课程序号”做主键写入前先查重同时加一个签到冷却时间同一个学号在5分钟内不重复写入。界面端也要有反馈某人已经签到时画框旁边显示“已签”避免学生反复刷脸。6. 把签到系统用到真实课堂离线验收、量化指标与三个进阶方向6.1 现场部署前的一次离线验收量化准确率、漏检率、误检率别急着把笔记本搬到教室先在已有数据上做一次离线验收。准备一段教室场景的视频人工标注出每个学生出现的起止时间作为“真实名册”跑完签到程序后对比三组数字识别准确率签到成功的人次除以应签人次、漏检率出现在画面里但没签到的人次占比、误检率签到了但实际没来的人次占比。漏检率超过5%就先调检测参数误检率超过1%就先调阈值两个指标都合格再上现场。这一步能给所有后续改动留一条对比基线现场翻车时也知道往哪层查。6.2 从及格到好用活体检测、异步推理与补签机制基础链路跑通后三个进阶方向按性价比排序。第一个是活体检测课堂签到最常见的作弊是拿同学照片往镜头前一放就骗过系统加一步“眨眼检测”或“点头动作检测”能挡住绝大多数静态照片攻击实现成本不高只需要在人脸关键点序列上判断动作模式。第二个是异步推理把检测、特征提取、比对分别放进独立线程摄像头不等待模型处理完就继续取帧视频流延迟能明显下降这在CPU机器上提升尤其大。第三个是补签机制允许学生在课后限定时间内自助补签一次系统记录补签时间并标记该记录为“补签”既保住考勤数据完整又防止一次性签到玩消失。最后说一个我自己的教训第一次上真实课堂我带着预设阈值直接演示结果班里后排几乎全军覆没场面一度很尴尬。后来发现原因不在模型是我根本没有做离线验收没意识到教室摄像头的视场角和注册照片差别那么大。从那以后凡是涉及人脸的项目我都先跑一遍量化验收再上现场。这一套从环境搭建、人脸注册、实时识别到阈值调优的流程反复打磨之后已经能在一节课内完成整个链路的部署和校验。希望这篇笔记能帮你少走这些弯路让你的课堂签到系统第一次上现场就不翻车。本文还有配套的精品资源点击获取