简介：一套完整的基于深度学习的人脸识别签到系统毕业设计项目，面向计算机相关专业学生、毕业设计开发者，可有效解决传统点名签到效率低、易代签、记录易丢失等问题。项目涵盖人脸注册、特征提取、活体检测、识别签到等核心流程，并集成Web管理端，实现用户管理、签到记录查询等功能。压缩包共27个文件，以8个Python源码文件、7个HTML模板、4个dat数据文件及SQLite数据库为主体，另含依赖清单、配置文件与字体资源，压缩后约101.47MB。已有405人学习下载，内含完整的环境部署说明、数据库迁移命令、管理员初始化脚本，可快速创建虚拟环境并一键运行；前后端分层设计清晰，便于二次开发与课程设计答辩展示。通过深入阅读源码可掌握OpenCV人脸检测、深度学习模型推理与Flask框架结合的实现思路，具有较高的实战参考价值。
1. 基于深度学习的人脸识别签到系统：不只是个毕业设计
人脸识别考勤，听起来是“识别一下打个卡”的小事，但真把一个基于深度学习的人脸识别签到系统从训练跑到落地上线，中间全是暗坑：门口逆光拍不清、戴个口罩全员掉线、换了个摄像头角度识别率能掉一半。这套以“毕业设计”为定位的项目，表面上是交差用的课题，实际代码把模型训练、特征入库、签到记录、阈值调优这几件事全部串起来了。无论你是要完成一个毕业课题，还是想在团队内部做一套轻量考勤工具，这套系统的架构思路和核心实现都值得照着搬一遍。这篇笔记就带你拆开它，从技术选型到运行改造，一条路走完。
2. 系统架构与核心技术选型：从摄像头到考勤记录的完整链路
2.1 技术选型：为什么是深度学习而不是传统方法
传统人脸识别方案，比如基于LBPH或EigenFace的老路子，对角度、光线、遮挡极其敏感。在签到这种真实场景下，光线一变准确率掉得飞快，更不用说换副眼镜换个发型。深度学习方案靠大规模人脸数据集预训练的卷积神经网络，把一张人脸映射成一个高维特征向量，在姿态和光照变化下的鲁棒性明显更强。
技术栈选型上，这套系统的核心依赖如下表：
| 模块 | 技术选型 | 选择理由 |
|---|---|---|
| 后端框架 | Flask | 轻量、接口开发快，适合中小规模系统 |
| 深度学习框架 | PyTorch | 动态图调试方便，生态成熟 |
| 人脸检测 | RetinaFace | 自带五关键点输出，检测框精度高 |
| 特征提取 | ArcFace | 角度间隔损失，开集识别效果好 |
| 推理加速 | onnxruntime | CPU推理比PyTorch原生快不少，不依赖GPU |
| 数据库 | SQLite / MySQL | 开发用SQLite，部署切MySQL |
| 前端 | 原生HTML + JavaScript + canvas | 不引入前端框架，聚焦核心逻辑 |
为什么用Flask而不是Django？这个问题每次都要解释一遍。Django自带admin后台、ORM和中间件体系，功能全但重；签到系统只需要注册、签到、查询三个接口，Flask的灵活性和低复杂度更合适。刚入门的开发者看Flask代码能快速理解请求处理流程，后面改起来也没有额外学习成本。
ArcFace的选型也是同理。现在人脸识别模型很多，FaceNet、CosFace、ArcFace各有侧重。ArcFace通过角度间隔在特征空间里拉大类间距离，在公开测试集上的表现稳定，InsightFace官方提供的预训练权重直接可以用，不必从零开始训练，这步省了非常多时间。
2.2 整体架构：前端页面、后端服务与模型推理如何协作
这套系统的整体架构分成三层：浏览器端负责摄像头采集和画面预览，后端服务负责请求路由和业务逻辑，模型推理层负责从图像里找脸和提取特征。三层之间通过HTTP接口通信，前端不需要接触任何深度学习代码。
数据流的完整链路是这样：
- 用户点击“签到”，浏览器调用getUserMedia打开摄像头，视频流实时显示在页面上。
- 用户摆正姿势，点击“拍照”，前端用canvas截取当前帧，压缩成JPEG后通过FormData发送到后端。
- 后端收到图片后，先交给推理服务做人脸检测。检测不到人脸就返回提示；检测到就裁剪出人脸区域，做仿射对齐。
- 对齐后的图像送入特征提取模型，输出一个512维的归一化特征向量。
- 后端拿这个特征向量去数据库里逐条比对，计算余弦相似度。
- 最高分超过阈值就判定为同一个人，写入签到记录；否则返回识别失败。
模块划分上，后端拆成两个核心service，这个设计直接影响后面二次开发的成本：
FaceService封装所有AI能力，对外只暴露一个方法detect_and_embed(image)，输入一张图片，输出人脸是否找到和对应的特征向量。AttendanceService负责所有数据库操作，包括注册人脸、比对识别、记录签到、查询历史。这样拆的好处是，以后换人脸算法只用改FaceService，签到业务一行都不用动。我后面做门禁改造的时候感触很深，模型是“换脸”最容易的部分，真正费时的是把业务和模型耦合在一起的代码。
2.3 数据库设计：用户表、考勤表与特征存储
考勤系统的表结构很简单，核心就是用户表和签到记录表。这次我用SQLite来做开发库，生产环境平滑切MySQL，建表脚本如下：
CREATE TABLE user ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL UNIQUE, feature BLOB NOT NULL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE attendance ( id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER NOT NULL, sign_time DATETIME DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (user_id) REFERENCES user(id) ); CREATE INDEX idx_attendance_user_time ON attendance(user_id, sign_time);最后一个索引很关键，签到查询频繁用user_id + sign_time做过滤，没有索引的话，数据量大了以后每次签到都要全表扫一遍。我在第一次测试时没加这个索引，500条记录还不明显，等导入2000条历史数据后，重复签到检查从2毫秒涨到150毫秒，加了索引直接回到个位数毫秒。
为什么特征要存BLOB而不是直接存文本？原因有三：第一，512维float数组用二进制存储体积最小，每个人512乘以4约等于2KB，一千人才2MB；第二，numpy数组转bytes可以零拷贝快速还原，用np.frombuffer一秒读几千条没压力；第三，避免JSON序列化把小数精度损耗掉，虽然0.0001的精度变化对余弦相似度影响不大，但做工程时省一点是一点。
再来看注册和签到两条流程：
注册流程：用户上传一张正脸照片 → 后端检测人脸并提取特征，检测不到人脸直接返回错误 → 检查姓名是否重复注册 → 把特征以BLOB形式插入用户表。
签到流程：摄像头截帧上传 → 提取特征 → 全表循环计算相似度 → 最高分低于阈值则识别失败 → 高于阈值但今天已签到则返回“今日已签到” → 高于阈值且未签到则插入考勤记录。
这套流程的优点是简单可靠，缺点是全表扫描的性能瓶颈。注册人数到几千人以后，每次签到要算几千次余弦相似度，实测耗时在18到30毫秒波动，考虑到签到场景的并发量，这个开销完全可以接受。真到了上万人再考虑引入向量检索。
3. 核心模块拆解：人脸检测、特征提取与签到逻辑实现
3.1 人脸检测定位：RetinaFace的关键点输出与后处理
人脸检测是整条识别链路的第一个环节，选RetinaFace是因为它同时输出检测框和五个关键点坐标，关键点一是用来判断人脸朝向，二是做对齐仿射变换。代码实现不复杂：
import cv2 from retinaface import RetinaFace def detect_face(img): # img 是 BGR 格式的 numpy 数组 faces = RetinaFace.detect_faces(img) if not faces: return None, None # 只取置信度最高的一张脸 key = list(faces.keys())[0] face = faces[key] box = face['facial_area'] # [x1, y1, x2, y2] landmarks = face['landmarks'] # 五个关键点的字典 score = face['score'] return box, landmarks返回的faces是一个字典，key是face_1这样的字符串。facial_area是检测框的坐标列表，landmarks包含left_eye、right_eye、nose、mouth_left、mouth_right五个关键点，每个点都是[x, y]。这里只取第一个检测结果，默认签到场景画面里只有一个人。如果画面里可能有多人，就得遍历所有检测框逐一截取并识别，那个逻辑就得从dict.values()循环处理。
有个参数容易忽略：RetinaFace.detect_faces默认的置信度阈值在0.9左右，实际用下来0.8更合理。摄像头距离人两米左右时，小脸框的置信度天然偏低，阈值定太高会导致漏检。我调到0.8之后，教室后排的签到成功率从70%升到了92%。
3.2 特征提取：ArcFace的512维向量与归一化细节
检测到人脸框后，把框内区域裁剪出来，对齐后送入特征提取模型。实际项目中我直接用InsightFace封装好的接口，它内部把检测、对齐和特征提取全串好了，比自己手工拼要稳：
import insightface import numpy as np # buffalo_l 包含检测、关键点、特征提取全套模型 model = insightface.app.FaceAnalysis(name='buffalo_l') model.prepare(ctx_id=0, det_size=(640, 640)) def get_embedding(img): faces = model.get(img) if len(faces) == 0: return None face = faces[0] # normed_embedding 是已经归一化的512维向量 return face.normed_embedding.astype(np.float32) def cosine_similarity(a, b): # 两个向量都归一化后，点积等于余弦相似度 return float(np.dot(a, b))两点值得说明：normed_embedding已经做了L2归一化，省去了手工归一化的步骤，这样做的好处是后续比对只需要一次点积，不用再做除法；astype(np.float32)是为了控制内存体积，float64虽然精度高，但对余弦相似度没有任何帮助，存储和比对耗时都翻倍。
预处理还有一个细节：model.prepare(ctx_id=0, det_size=(640, 640))里的det_size控制检测分辨率。分辨率越高，小脸检测越准，但推理耗时也越长。我试过(1920, 1080)的输入，单次推理慢了一倍，而识别率几乎没有提升，反而因为图片过大产生了大量不必要的计算。
3.3 签到业务：识别成功后的防重复与时间逻辑
识别通过之后，核心业务逻辑反而更考验工程细节。防重复签到和跨天判断是这部分的两个坑，直接看代码：
from flask import Flask, request, jsonify import sqlite3 import datetime import numpy as np app = Flask(__name__) @app.route('/sign', methods=['POST']) def sign(): file = request.files['image'] img = file.read() embedding = get_embedding_from_bytes(img) if embedding is None: return jsonify({'code': 400, 'msg': '未检测到人脸'}) conn = sqlite3.connect('attendance.db') cur = conn.cursor() # 全表扫描，逐条比对特征 cur.execute('SELECT id, name, feature FROM user') rows = cur.fetchall() best_match = None best_score = -1 for uid, name, feat_blob in rows: feat = np.frombuffer(feat_blob, dtype=np.float32) score = cosine_similarity(embedding, feat) if score > best_score: best_score = score best_match = (uid, name) if best_score < 0.6: conn.close() return jsonify({'code': 401, 'msg': '识别失败'}) today = datetime.date.today().isoformat() cur.execute( 'SELECT COUNT(*) FROM attendance WHERE user_id=? AND sign_time>=?', (best_match[0], today) ) if cur.fetchone()[0] > 0: conn.close() return jsonify({'code': 403, 'msg': '今日已签到'}) cur.execute('INSERT INTO attendance(user_id) VALUES(?)', (best_match[0],)) conn.commit() conn.close() return jsonify({'code': 200, 'msg': f'签到成功，{best_match[1]}'})这段代码有三个关键设计。第一，np.frombuffer直接把BLOB还原成numpy数组，比用pickle先反序列化一堆对象快得多。第二，查重复签到用的是sign_time >= today，这样即使签到记录里存的是带时分秒的时间戳，也能正确覆盖当天数据。第三，事务提交是在确认没有重复签到之后才完成的，把数据库锁的持有时间压到最短。
3.4 前端摄像头调用：getUserMedia与canvas截帧
前端这块核心代码只有几十行，但有一个安全限制最容易踩：
const video = document.getElementById('video'); navigator.mediaDevices.getUserMedia({ video: { width: 640, height: 480 } }).then(stream => { video.srcObject = stream; }).catch(err => { console.error('摄像头权限被拒绝：', err); }); function captureAndUpload() { const canvas = document.getElementById('canvas'); canvas.width = 640; canvas.height = 480; const ctx = canvas.getContext('2d'); ctx.drawImage(video, 0, 0, 640, 480); canvas.toBlob(blob => { const formData = new FormData(); formData.append('image', blob, 'capture.jpg'); fetch('/sign', { method: 'POST', body: formData }).then(res => res.json()) .then(data => alert(data.msg)); }, 'image/jpeg', 0.9); }canvas.toBlob的第三个参数是压缩质量，0.9时图片体积大概60KB，识别精度基本无损。想省流量可以调到0.8，约40KB，识别效果差距不大。真正要命的是getUserMedia必须运行在HTTPS或者localhost环境，否则浏览器会直接拒绝，报NotAllowedError。本地调试用127.0.0.1没问题，一旦部署到公网服务器上，不配置SSL证书，摄像头永远打不开。这个坑卡了很多人。
4. 避坑指南：训练数据、模型精度与并发签到的常见问题
4.1 现象：注册时明明能识别，真实签到却总是失败
原因是注册阶段和签到阶段的数据分布差异太大。注册时通常人在镜头正中，光线均匀，表情自然；真实签到场景里可能出现侧脸、逆光、低头看手机这些情况，模型提取出的特征和注册时相差很远。
解决方法是注册阶段就采集多角度图片。至少三张：正脸、左右各偏15度，每张之间隔两秒拍摄，让表情略有变化。同时签到端做一个简单活体检测，让用户眨眼或者缓缓转头，一方面挡掉用照片打卡的情况，另一方面也把极端角度下质量太差的帧过滤掉。代码上在拿到视频流后，连续判断三帧人脸框位置是否连续变化，变化过小就当成静态照片拒绝。
4.2 现象：服务器上模型越跑越慢，内存还暴涨
前因后果是这样的：InsightFace默认加载全套模型，包括检测、关键点、特征提取，内存占用接近2GB。如果服务器没有独立显卡，模型被迫走CPU推理，一次识别耗时1到2秒，并发一多接口直接卡死。
解决方案是收缩检测尺寸。model.prepare(ctx_id=-1, det_size=(320, 320))可以让精度略降但速度提升四倍左右。另外后端要限制并发推理数量，我一般用一个ThreadPoolExecutor(max_workers=2)，模型推理串行化，让每次请求的响应时间稳定在800毫秒内。
from concurrent.futures import ThreadPoolExecutor inference_pool = ThreadPoolExecutor(max_workers=2) def handle_sign(request): future = inference_pool.submit(run_inference, request.files['image'].read()) embedding = future.result(timeout=5)4.3 现象：多人同时签到报database is locked
原因很简单：SQLite默认只允许一个写连接，两个请求同时执行INSERT时，第二个请求会抛OperationalError: database is locked。解决思路有两个，一是换MySQL，但从毕设体量来说有点杀鸡用牛刀；二是加一个全局写锁，把插入操作串行化。
import threading write_lock = threading.Lock() @app.route('/sign', methods=['POST']) def sign(): # 前面的识别逻辑省略 with write_lock: conn = sqlite3.connect('attendance.db') cur = conn.cursor() cur.execute('INSERT INTO attendance(user_id) VALUES(?)', (uid,)) conn.commit() conn.close()注意这里的lock必须是全局对象，不能放在函数内部，否则多个线程各持一把锁，等于没锁。另外不要在多个线程里各自创建SQLite连接并同时写库，就算加了锁也会偶发死锁，统一用一个连接配合锁是最稳的。
4.4 现象：模型路径在Windows下诡异报错
模型路径写死成Linux风格是毕设项目里的老演员了，比如/home/user/model/arcface.onnx，代码拷到Windows电脑上直接运行报FileNotFoundError。
解决方法是不要用绝对路径，在项目根目录建一个config.py，用os.path.dirname(__file__)拼路径：
import os BASE_DIR = os.path.dirname(os.path.abspath(__file__)) MODEL_DIR = os.path.join(BASE_DIR, 'models') MODEL_PATH = os.path.join(MODEL_DIR, 'arcface.onnx')这个习惯不仅是Windows和LInux通用问题，也决定了模型文件能不能随项目打包迁移。下次换电脑跑项目，不用再改任何路径相关代码。
4.5 现象：相似度阈值怎么调都不对
有人说0.5好，有人说0.7好，其实阈值只跟你的模型和数据分布有关。直接用默认阈值容易上瘾，但真上线后误识别率可能高得离谱。
正确做法是自己统计阈值分布。准备50对同一个人不同角度的照片，再准备50对不同人的照片，跑一遍特征提取和相似度计算，画出两组分数分布曲线，取两个峰谷中间的位置作为阈值。我这套系统的阈值最终定在0.6，因为同人最小分数0.58，异人最大分数0.44，中间隔了0.14，0.6正落在安全区。如果你的数据分布不同，这个值要重新标定。
5. 项目运行与部署：从数据集准备到上线签到的实操步骤
5.1 环境准备与依赖安装顺序
整套系统基于Python 3.9开发，深度学习框架用PyTorch。依赖安装的顺序很重要，顺序错了会装到CPU版PyTorch，GPU白瞎：
# 先装CUDA版PyTorch pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # 再装人脸识别和推理库 pip install insightface onnxruntime # 最后装Web框架和工具库 pip install flask flask-cors numpy opencv-python如果服务器没有NVIDIA显卡，把第一行的cu118换成cpu即可。有个血泪经验：如果你先装了insightface再装torch，pip自动解析依赖时会下载CPU版torch，之后就算你重新装CUDA版也容易版本冲突。所以顺序必须固定：先torch，后insightface。
5.2 数据集准备与模型微调（可选）
预训练模型在通用人脸识别上已经够用，但如果你要识别的是公司内部人员或者同班同学，通用模型在特定人脸上的精度可能不够。微调这一步能显著改善效果，数据集目录规范如下：
dataset/ class1_name/ img1.jpg img2.jpg class2_name/ img1.jpg img2.jpg每个文件夹代表一个人，文件夹名就是识别结果里的姓名，图片建议用摄像头采集的真实照片，每类至少10张，正脸和侧脸混合。用PyTorch的torchvision.datasets.ImageFolder可以直接读这个结构，省去自己写数据加载器。
微调的核心是损失函数，用ArcFace的ArcfaceLoss，学习率从0.001开始，在验证集上观察loss下降一批后降到1e-4。验证集里必须包含真实签到场景的摄像头截图，不能只用干净的网图验证，否则微调出来的模型在真实环境中还是不稳定。我用这种方式把内部人员识别率从91%提到了97%。
5.3 启动服务与测试
项目入口是run.py，启动后监听8000端口，测试流程用命令行配合curl最直观：
# 启动服务 python run.py # 注册人脸：传一张包含正脸的图片 curl -X POST \ -F "name=张三" \ -F "image=@./test_data/zhangsan.jpg" \ http://localhost:8000/register # 识别签到：传一张摄像头截图 curl -X POST \ -F "image=@./test_data/capture.jpg" \ http://localhost:8000/sign注册接口返回{"code": 200}表示特征已入库；签到接口返回{"code": 200, "msg": "签到成功，张三"}表示识别通过。如果返回401，优先检查图片是否包含清晰人脸，再检查阈值配置。用curl先把接口跑通，再对接前端页面，能省下很多联调时排查问题的力气。
5.4 生产环境部署：三处必改的工程点
代码在本地跑通和线上稳定运行之间隔了三个必须处理的问题。第一，SQLite换成MySQL，解决并发写锁问题；第二，Flask开发服务器换成gunicorn，解决HTTP并发能力问题；第三，模型常驻一个独立进程，避免每次请求都重新加载模型导致响应延迟。
# gunicorn 启动，4个worker进程 gunicorn -w 4 -b 0.0.0.0:8000 run:app这里有个细节：-w 4不要理解成越多越好，每个worker进程都会拷贝一份模型到内存，4个worker就是4份，2GB内存直接变8GB。一般2个worker够用，如果服务器内存有限，用1个worker配合线程模式更省资源。
6. 二次开发方向：从签到系统到通用人脸识别平台
6.1 识别与业务解耦：从考勤改造成门禁
最自然的改法是把“识别成功即签到”替换成“识别成功即开门”。在AttendanceService之外加一个AccessService，把核心判断逻辑抽出来，识别成功后调用外设模块。比如在某ARM开发板上接一个继电器：
import serial ser = serial.Serial('/dev/ttyUSB0', 9600) def open_door(): ser.write(b'1') # 高电平触发继电器 time.sleep(1) ser.write(b'0')核心思路是：FaceService只回答“这个人是谁”，业务层决定“接下来干什么”。换一个场景就重写业务层，识别链路不动。这也是整个项目最值得保留的架构设计。
6.2 性能优化：用特征向量缓存替代全库扫描
注册人数超过3000人后，全表扫描的延迟开始明显。可以用BallTree把所有特征加载进内存做近邻检索：
from sklearn.neighbors import BallTree # 启动时加载全部特征 features = load_all_features() # shape: (N, 512) tree = BallTree(features, metric='cosine') # 识别时 dist, idx = tree.query([new_feature], k=1) threshold = 0.4 # BallTree的cosine距离与相似度相反注意这里的metric='cosine'返回的是距离值，距离越小越相似，和之前余弦相似度的方向相反。另外注册接口每次插入新用户后要重建树，虽然重建有开销，但注册频率低，这个成本完全可接受。
6.3 端侧部署：替换轻量移动端模型
如果要把签到系统跑到平板上，现在的InsightFace全套模型太重。现成方案是换成MobileFaceNet或SFace，量化成int8后模型体积降到几MB，在ARM处理器上也能保持实时的推理速度。
替换模型这个动作恰好验证了架构设计的合理性：只要服务接口不变，输入是图片，输出是特征向量，内部模型随意替换。把FaceService的模型权文件换掉，改几行加载配置，业务层完全不用动。我后来接平板方案时，整个替换过程不到半小时。
做完这套系统，我最大的收获不是某个模型怎么调参，而是认识到识别精度只是系统里很小的一块拼图。真正的难点在工程链路：图像采集质量、特征存储格式、相似度阈值、并发控制、数据库锁，任何一环出问题，都会让你误以为是模型不行。从那以后我每次搭人脸识别项目，都强制先跑通一条最小链路——拍一张照、提取特征、比对、写入记录——再往上叠需求。这个习惯帮我少走了很多弯路，希望也能帮到你。
本文还有配套的精品资源，点击获取
