简介：这是一套面向高校毕业设计与课程实践的深度学习人脸识别签到系统源码，适合具备Python基础、希望完成完整项目实战的学生和开发者，可用于课堂考勤、实验室门禁等场景的二次开发与论文复现。压缩包共27个文件，约101.47MB，以8个Python脚本承载后端逻辑与模型调用，7个HTML模板配合CSS样式完成登录、注册、用户管理等页面，另含SQLite数据库、数据文件、字体资源及项目说明文档，目录覆盖数据存储、模型调用与界面交互的主要环节。已有407人学习下载。读者可据此理解人脸注册、用户管理与签到识别的业务闭环，参考后端应用分层、数据库迁移和后台页面的组织方式，并借助现有模板、脚本与说明文档快速搭建可演示环境，梳理二次开发入口和答辩展示要点，减少从零搭建与排错的成本。

1. 替人答到这个痛点：人脸识别签到系统真正的难点不在模型

人脸识别签到是毕业设计选题里被选得最多的一类：需求直观、演示效果好、技术栈看起来也够深度学习。但真正动手的人往往很快会撞上同一堵墙——模型能跑通，Demo 也能认出自己，可底库一扩到几百人、摄像头换成教室里的普通 USB 设备，识别率立刻下降；签到记录里开始出现张冠李戴，演示时最怕的那次误识别偏偏就落在答辩老师身上。这套方案要解决的不是「能不能识别一张脸」，而是「识别结果能不能被当作考勤依据」。它面向正在做深度学习方向毕业设计、课程设计的读者，也面向要交付一套可演示、可验收的考勤原型的从业者。后面按需求边界、总体架构、识别链路、业务落地、避坑排查、验收答辩的顺序，把每个环节的选型理由和实现细节逐层展开。

2. 需求边界与技术选型：四类角色、五项指标和三次技术分叉

动手写代码之前最容易犯的错误，是先下载一个预训练模型跑通 demo，然后就默认「需求已经清楚了」。人脸识别签到系统的麻烦几乎全部藏在业务边界里：谁发起签到、底库有多大、一次识别要多久、误识一次要付多大代价。这些问题的答案直接决定你用 128 维还是 512 维特征、用不用活体、要不要上向量检索库。选型做错，后面写多少代码都是白费。

2.1 角色、场景与签到范围

系统里有四类角色，每类角色对应一组接口，别混在一个页面里。被签到方是学生或员工，只做三件事：注册人脸、参加签到、查自己的记录；发起方是教师或管理员，创建签到任务、设定时间窗、查看实时到勤率和导出报表；系统本身负责识别与判定，是唯一有权写签到记录的角色；运维方负责底库清理、模型版本切换和异常日志。把这四类角色写进需求文档的第一页，答辩时「你的系统有几个模块」这种问题就有得答了。

场景上必须先区分 1:N 和 1:1，这两者是两套完全不同的工程。教室或实验室的集中签到是 1:N：一个人脸对上整个底库，底库规模从几十到几千不等，阈值要兼顾误识和拒识，性能预算按「一次比对覆盖全库」来算。门口闸机式的签到是 1:1：先刷卡或扫码拿到身份，再比对该身份下的人脸，底库只有一条记录，阈值可以卡得更严，速度也快得多。毕业设计绝大多数选 1:N，因为演示时「不用刷卡直接走过去就签到」的观感更强，但要清楚它的工程代价：底库每增加一个人，误识概率就上升一点。

还有一条边界经常被忽略——签到的时间窗和重复签到。签到任务必须有明确的开始与结束时间，服务端要校验，不能只靠前端按钮置灰。同一个人在同一场次里只能有一条记录，这条约束交给数据库唯一索引，比在应用层写「先查再插」可靠得多。这两条属于业务规则，但它们的实现方式会影响表结构，所以在需求阶段就得定下来。

2.2 检测、特征、比对：三次技术分叉

第一次分叉在检测器。经典的 Haar 级联速度快、依赖少，但侧脸和逆光基本失效，教室里学生一歪头就漏检。MTCNN 用三级级联网络，正脸和轻微侧脸都能稳定出框，还自带 5 个关键点，缺点是 CPU 上单帧要一两百毫秒。RetinaFace 精度更高，MobileNet 主干版本在 CPU 上也能跑到接近实时。OpenCV 自带的 DNN SSD 人脸检测是个折中选项，模型小、依赖少，适合配置不高的机器。毕设场景我一般推荐 RetinaFace 的轻量主干或 MTCNN，理由不是精度最高，而是它们同时给出关键点，省掉了单独做对齐的一步。

第二次分叉在特征提取模型。FaceNet 输出 128 维，模型小、推理快，在底库几百人的规模下够用，缺点是不同人之间的区分度不如新一代损失函数训出来的模型。ArcFace 系列输出 512 维，用加性角度间隔把类间距离拉开，1:N 场景下 Top-1 准确率明显更好，代价是模型稍大、单次推理多几十毫秒。做毕设如果机器不是特别紧张，用 512 维的方案更稳，因为答辩现场的光线和角度一定不如实验室，留出的区分度余量就是你的容错空间。

第三次分叉在比对方式。特征比对只有两种主流做法：余弦相似度和欧氏距离。选了哪一种就必须全程统一，注册入库时怎么算、签到比对时也怎么算，中间不能换。工程上更常见的做法是先把特征做 L2 归一化，归一化之后余弦相似度和欧氏距离是单调对应的，此时用矩阵乘一次性算出全库相似度，代码最短、速度最快。这一步做错，后面调阈值会调到怀疑人生。

提示：模型选型要在需求文档里写明版本标识，并把标识存进特征表。换模型必须重刷底库，这条规则后面第 5 章还会再提一次。

2.3 五项指标先定死，再谈准确率

「准确率 98%」这种说法在答辩现场是站不住的，因为没有说明在什么底库规模、什么光照条件下、用什么口径统计。把指标拆成五项分别写清楚，验收时才有据可依。第一项是注册成功率，指一次注册流程内能采到合格特征的比例，受摄像头和引导界面影响很大。第二项是 1:N 的 Top-1 准确率，要在固定底库规模下测，比如 200 人底库、每人 3 张不同角度。第三项是误识率，用不在底库里的陌生人去测，看系统会不会错误通过，这一项最能体现阈值定得是否合理。第四项是单次识别耗时，从图片上传到接口返回，CPU 环境下控制在 800 毫秒以内，演示时观感才不卡。第五项是并发下的数据一致性，同一人连点多次只能产生一条记录。

这五项指标不需要全部做到极致，但必须全部有数。答辩老师问「你这个系统准不准」，你回答「200 人底库 Top-1 是 96.5%，50 个陌生人测了 150 次误通过 1 次，单次 620 毫秒」，和回答「挺准的」，是完全不同的两种效果。

3. 总体架构与数据模型：四层结构和五张核心表

架构图不用画得很花哨，但每一层负责什么必须能一句话说清。人脸识别签到系统天然适合分层：接入层负责采集和页面交互，服务层负责业务规则和接口，算法层负责检测、对齐、特征与比对，数据层负责持久化。分层的好处是算法可以单独替换——你今天用 A 模型，明天想换 B 模型，只要算法层对外暴露的接口不变，服务层一行都不用改。这在答辩时是个加分项，因为「可替换性」是真实工程才会考虑的问题。

3.1 四层结构与模块职责

接入层包含 Web 前端和图像采集两个部分。前端只做三件事：调摄像头、把画面裁好上传、展示结果，所有判定逻辑都不能放在前端。采集部分要注意分辨率——上传原图会让接口变慢，通常在前端压到长边 640 像素再传，既够检测用，也省带宽。

服务层是 Flask 或 Django 写的 REST 接口，核心有四组：注册接口、签到接口、任务管理接口、统计导出接口。签到接口是全系统唯一的写入入口，必须在这里做时间窗校验、阈值校验和幂等写入，不能把校验分散到多个地方。

算法层封装成一个独立的 Python 模块，对外只暴露两个函数：extract(img)返回特征和质量码，match(feature, gallery, threshold)返回身份和相似度。内部用哪个检测器、哪个特征模型，服务层不需要知道。这个封装看似多此一举，实则是为了让第 5 章提到的「特征不同源」问题有地方修。

数据层用 MySQL 存业务数据和特征，图片原图存本地目录或对象存储，只存路径不存二进制。底库规模上千之后，可以在内存里维护一份特征矩阵常驻，避免每次都从数据库拉全表。

3.2 五张核心表的字段设计

表设计有几个决定一旦定错，后面改起来非常痛苦。特征维度要存下来，模型标识要存下来，质量分要存下来，签到记录要有唯一约束。下面五张表是最小可用集合。

-- 人员表：业务身份的唯一来源，人脸只是它的一种凭证 CREATE TABLE `user` ( `id` INT UNSIGNED NOT NULL AUTO_INCREMENT, `student_no` VARCHAR(32) NOT NULL COMMENT '学号/工号，业务唯一键', `name` VARCHAR(64) NOT NULL, `class_id` INT UNSIGNED DEFAULT NULL COMMENT '班级/部门，用于按范围发起签到', `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`id`), UNIQUE KEY `uk_student_no` (`student_no`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 人脸特征表：一个人可以有多条样本，靠 model_tag 区分模型版本 CREATE TABLE `face_feature` ( `id` INT UNSIGNED NOT NULL AUTO_INCREMENT, `user_id` INT UNSIGNED NOT NULL, `model_tag` VARCHAR(32) NOT NULL COMMENT '特征模型标识，换模型必须换 tag', `dim` SMALLINT UNSIGNED NOT NULL DEFAULT 512, `feature` VARBINARY(4096) NOT NULL COMMENT 'float32 小端序字节流，512 维占 2048 字节', `quality` FLOAT NOT NULL DEFAULT 0 COMMENT '注册质量分，低分样本不参与比对', `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`id`), KEY `idx_user_model` (`user_id`,`model_tag`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 签到任务表：阈值放在任务上而不是写死在代码里，方便按场次调整 CREATE TABLE `sign_task` ( `id` INT UNSIGNED NOT NULL AUTO_INCREMENT, `title` VARCHAR(128) NOT NULL, `creator_id` INT UNSIGNED NOT NULL, `start_at` DATETIME NOT NULL, `end_at` DATETIME NOT NULL, `threshold` FLOAT NOT NULL DEFAULT 0.62 COMMENT '本场次生效的相似度阈值', `status` TINYINT NOT NULL DEFAULT 1 COMMENT '1进行中 2已结束', PRIMARY KEY (`id`), KEY `idx_time` (`start_at`,`end_at`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 签到记录表：唯一索引是防重复签到的最后一道防线 CREATE TABLE `sign_record` ( `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, `task_id` INT UNSIGNED NOT NULL, `user_id` INT UNSIGNED NOT NULL, `similarity` FLOAT NOT NULL, `liveness` TINYINT NOT NULL DEFAULT 0 COMMENT '活体通过标记', `sign_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, `client_ip` VARCHAR(45) DEFAULT NULL, PRIMARY KEY (`id`), UNIQUE KEY `uk_task_user` (`task_id`,`user_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

第五张是管理员表，字段和人员表类似，只是多了角色和密码哈希。它单独建表而不是在人员表里加一个is_admin字段，原因是管理员不需要人脸特征，混在一起会让底库查询多一层过滤条件，也容易在 1:N 比对时把管理员误识别成学生。

特征表里存的是VARBINARY，不是 JSON 数组也不是逗号分隔字符串。原因是 float32 的精度必须原样保留，转成文本再解析回来会丢低位，虽然影响很小，但没必要的损失不必承受。2048 字节的定长二进制读写都很快，MySQL 层面也不需要额外解析开销。

3.3 1:N 检索的实现取舍

底库在几百到两三千人这个量级，最省事的做法是把特征全量读进内存，用 numpy 做一次矩阵乘法拿到全部相似度。这个规模下矩阵乘的耗时在毫秒级，比引入 FAISS 之类的向量检索库简单得多，也少一个依赖。只有在底库上万、或者要求单次比对在 10 毫秒以内时，才需要考虑上索引结构。毕设场景基本用不到，硬上反而是给自己找麻烦。

import numpy as np def load_gallery(rows, model_tag): """把数据库中的二进制特征还原成 (N, D) 矩阵，只保留指定模型版本。""" feats, user_ids = [], [] for r in rows: # 换过模型的旧特征直接跳过，避免不同特征空间混算 if r["model_tag"] != model_tag: continue vec = np.frombuffer(r["feature"], dtype="<f4") if vec.shape[0] != r["dim"]: continue feats.append(vec) user_ids.append(r["user_id"]) if not feats: return np.zeros((0, 512), dtype=np.float32), [] mat = np.vstack(feats).astype(np.float32) # 兜底归一化：历史脏数据可能没有归一化过 norms = np.linalg.norm(mat, axis=1, keepdims=True) mat = mat / np.clip(norms, 1e-8, None) return mat, user_ids def match_1n(query, gallery, user_ids, threshold): """1:N 检索：一次矩阵乘得到全库相似度，取最大者与阈值比较。""" q = query.astype(np.float32) q /= max(float(np.linalg.norm(q)), 1e-8) sims = gallery @ q # 两边都已归一化，点积即余弦相似度 idx = int(np.argmax(sims)) best = float(sims[idx]) if best < threshold: return None, best # 低于阈值判为陌生人，不能强行给结果 return user_ids[idx], best

load_gallery里的dtype="<f4"是小端序 32 位浮点，写入时也要用同样的小端序，否则跨平台读出来的数会是乱的。model_tag的过滤看起来是防御性代码，实际上是整个系统最关键的隔离机制：一旦换过模型而底库没清干净，新旧特征混在同一个矩阵里做点积，得到的相似度毫无意义，表现就是「昨天还好好的，今天就全认错了」。match_1n里np.argmax之后必须再判断一次阈值，这一步不能省，因为 1:N 检索永远会返回一个「最像的人」，哪怕这个人根本不在底库里。

内存里维护这份矩阵时，通常的做法是启动时加载一次，注册新用户后追加一行，删除用户后重建。用一把读写锁保护，避免签到高峰期矩阵正在重建而读请求拿到半成品。

4. 识别链路与签到实现：从检测对齐到幂等写入的四段代码

识别链路是整个系统里最容易写出「能跑但不好用」的部分。同一个模型，有的实现能在教室里稳定签到，有的实现换个角度就认不出，差别往往不在模型本身，而在检测后的质量过滤、特征是否归一化、阈值放在哪里。这一段按数据流顺序展开：先检测出人脸并做质量评估，再提取特征，再和底库比对，最后把结果幂等地写进数据库。

4.1 检测、对齐与质量分过滤

检测之后直接送进特征网络是最常见的错误。一张 60×60 的侧脸、一张糊掉的逆光照片，都会被强行抽出一个 512 维向量，这个向量会污染底库，让同一个人之后的正常照片反而匹配不上。正确做法是在检测之后加一道质量闸门：人脸尺寸不够、清晰度不够、置信度不够的样本一律拒收，让用户重拍。这道闸门看起来降低了注册成功率，实际上把识别准确率往上抬了一大截。

import cv2 import numpy as np from insightface.app import FaceAnalysis # 检测 + 5 点关键点 + 512 维识别模型打包好的推理管道 app = FaceAnalysis(name="buffalo_l", providers=["CPUExecutionProvider"]) app.prepare(ctx_id=0, det_size=(640, 640)) def laplacian_score(gray): """清晰度打分：拉普拉斯方差越小越模糊，经验阈值在 45 到 60 之间。""" return float(cv2.Laplacian(gray, cv2.CV_64F).var()) def extract(img_bgr, min_side=80, blur_thr=45.0, det_thr=0.6): """返回 (特征, 状态码)。状态码用于前端提示用户重拍，而不是笼统报错。""" faces = app.get(img_bgr) if not faces: return None, "no_face" # 底库大时只取面积最大的人脸，防止背景里的路人脸干扰 face = max(faces, key=lambda f: (f.bbox[2] - f.bbox[0]) * (f.bbox[3] - f.bbox[1])) if float(face.det_score) < det_thr: return None, "low_confidence" x1, y1, x2, y2 = face.bbox.astype(int) if min(x2 - x1, y2 - y1) < min_side: return None, "face_too_small" roi = img_bgr[max(0, y1):y2, max(0, x1):x2] gray = cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY) if laplacian_score(gray) < blur_thr: return None, "blur" # normed_embedding 已做过 L2 归一化，直接入库即可 return face.normed_embedding.astype(np.float32), "ok"

min_side=80的含义是短边至少 80 像素，低于这个尺寸的人脸，特征向量基本靠猜。blur_thr需要在你的实际摄像头上标定：先用手机拍几张正常照片和几张运动模糊照片，分别算一下拉普拉斯方差，把阈值卡在两者中间。det_thr是检测置信度，调高会减少误检但增加漏检，教室场景建议 0.6 起步。

关键点对齐这一步由推理管道内部完成，不需要自己写仿射变换。如果你用的是不带对齐的模型，那就必须用 5 个关键点做相似变换，把眼睛和鼻尖对齐到标准位置，否则同一个人在歪头和正脸状态下的特征差异会非常大。这条是很多实现「在实验室很准、在教室就不行」的根本原因之一。

4.2 特征比对与阈值判定

比对部分短，但每个参数都有讲究。相似度阈值不是一个可以随便填的常数，它需要你在自己的数据上标定。做法是：用底库里的每个人各拍几张不同角度的照片，算出同一个人之间的相似度分布；再拿一批不在底库里的人，算出他们和底库里最像那个人的相似度分布。两条分布的交叠位置就是阈值的合理区间，往上偏是严，往下偏是松。

import numpy as np # 这两个值应该在你自己采集的数据上标定，不要直接抄 SAME_PERSON_P5 = 0.55 # 同人相似度的 5% 分位，低于它的同人样本会被拒 IMPOSTOR_P95 = 0.42 # 陌生人相似度的 95% 分位，高于它的陌生人会被误通过 def calib_threshold(same_sims, impostor_sims, bias=0.02): """在两条分布之间取一个偏保守的点，bias 越大越严格。""" lo = float(np.percentile(same_sims, 5)) hi = float(np.percentile(impostor_sims, 95)) # 两条分布若有空隙，取中间；若已交叠，取靠近陌生人均值的一侧 if lo > hi: return (lo + hi) / 2.0 + bias return float(np.mean(same_sims)) * 0.85

这段代码的意义不在于算法多复杂，而在于它把一个「拍脑袋的常数」变成了一个可以写进论文的实验过程。答辩时被问「阈值 0.62 怎么来的」，你能拿出两条分布曲线，这个问题就答完了。通常同人相似度在 0.6 到 0.85 之间，陌生人相似度在 0.1 到 0.4 之间，中间如果留出空隙，阈值就取在空隙中央偏保守的位置，把误识率压到最低——签到场景里错误通过一个人的代价，比让一个人重拍一次的代价大得多。

注意：底库里的每个人最好保留 2 到 3 条不同角度的特征，比对时取所有样本中的最大相似度。单样本底库在真实光照下非常脆弱，这一点在验收数据里会体现得很明显。

4.3 签到接口与幂等写入

接口层要守住三条底线：时间窗由服务端判断、相似度由服务端计算、重复签到由数据库拦住。前端传上来的任何判定结果都不可信，尤其是相似度这类可以被改包伪造的字段。

from datetime import datetime from flask import Blueprint, request, jsonify import pymysql bp = Blueprint("sign", __name__) @bp.post("/api/sign") def sign(): task_id = int(request.form["task_id"]) img = read_upload(request.files["frame"]) # 后端收图，自己重算 feature, status = extract(img) if feature is None: return jsonify(code=4010, msg=f"图像不合格:{status}"), 200 conn = get_conn() try: with conn.cursor(pymysql.cursors.DictCursor) as cur: cur.execute( "SELECT threshold, start_at, end_at, status FROM sign_task WHERE id=%s", (task_id,), ) task = cur.fetchone() now = datetime.now() if not task or task["status"] != 1: return jsonify(code=4001, msg="签到已结束"), 200 if not (task["start_at"] <= now <= task["end_at"]): return jsonify(code=4002, msg="不在签到时间窗内"), 200 gallery, user_ids = get_gallery_cached() # 常驻内存的特征矩阵 user_id, sim = match_1n(feature, gallery, user_ids, task["threshold"]) if user_id is None: return jsonify(code=4003, msg="人脸比对未通过", score=round(sim, 3)), 200 try: cur.execute( "INSERT INTO sign_record(task_id,user_id,similarity,liveness,client_ip)" " VALUES(%s,%s,%s,%s,%s)", (task_id, user_id, sim, 1, request.remote_addr), ) except pymysql.err.IntegrityError: # 唯一索引 uk_task_user 拦住重复签到，直接返回成功语义 conn.rollback() return jsonify(code=0, msg="已签到", duplicate=True), 200 conn.commit() finally: conn.close() return jsonify(code=0, msg="签到成功", score=round(sim, 3))

四个返回值设计成不同的业务码，是为了让前端能给出不同的提示：4001 是任务结束了，4002 是还没开始或已超时，4003 是没认出来，0 是成功。把「没认出来」和「系统出错」混成一个 500，用户完全不知道该干什么，这是实际交付里最容易返工的地方。IntegrityError那个分支不要改成先查后插，并发下先查后插一定会漏，唯一索引是唯一可靠的手段。

get_gallery_cached()返回的内存矩阵要带版本号，注册或删除人员后版本号加一，下次请求触发重建。这一步不做，新注册的人当场签不上到，演示时非常尴尬。

4.4 活体检测与轻量防作弊

照片攻击是这类系统绕不过去的问题。答辩老师经常拿手机翻出一张照片凑到摄像头前，问「这个能不能过」。毕设阶段不需要上双目或结构光，做动作配合式活体最稳妥：随机下发一个动作序列，比如「眨眼 + 张嘴」，前端连续采帧，后端判断动作是否真的发生。

import numpy as np def eye_aspect_ratio(pts): """EAR：上下眼睑距离与左右眼角距离的比值，闭眼时明显下降。""" a = np.linalg.norm(pts[1] - pts[5]) b = np.linalg.norm(pts[2] - pts[4]) c = np.linalg.norm(pts[0] - pts[3]) return (a + b) / (2.0 * c + 1e-6) def check_blink(ear_seq, low=0.18, high=0.26): """连续帧内 EAR 先降到 low 以下、再回到 high 以上，才算一次完整眨眼。""" dipped = False for v in ear_seq: if v < low: dipped = True elif dipped and v > high: return True return False

ear_seq是连续采到的 20 到 30 帧的眼部纵横比序列，low和high两个阈值要在你的摄像头上标定一次。张嘴用同样的思路，把眼部换成嘴部的上下唇间距与嘴宽比值。逻辑上必须「先降后升」才算完成，只降不升说明用户可能只是低头或画面丢失，防止有人用静帧蒙混。

动作序列要随机，每次签到从「眨眼」「张嘴」「向左转头」里抽两个，顺序也打乱。固定的动作序列在第二次演示时就失效了，因为对方知道要做什么，可以用提前录好的视频。这套方案防不住高质量的视频重放，但足以应付课程设计和毕设答辩的检查，写进论文时也要老实说明局限，反而显得专业。

5. 避坑与常见问题排查：五个最容易翻车的点

这一类系统的 bug 有个共同特点：代码不报错，日志也正常，但结果就是不对。下面五条是我见过最多的，按出现频率排序，每条都给出可操作的排查路径。

5.1 底库特征与运行时特征不同源

现象是系统刚上线时一切正常，某天开始识别率骤降，同一个人站在摄像头前相似度只有 0.3 左右，换个人反而更高。原因通常是特征提取链路被改过：注册时用的是 A 模型的输出，运行时换成了 B 模型，或者注册时做了归一化而运行时没做，甚至只是预处理时 BGR 和 RGB 通道顺序不同。两个不同特征空间算出来的余弦相似度没有任何物理意义。

解决办法是给每个特征打上model_tag，比对时只加载同一 tag 的特征，不同 tag 一律跳过。同时把extract函数封装成唯一入口，注册和签到都只能调用它，禁止在别处再写一遍预处理。上线前做一次一致性自检：随便取底库里一条特征，用原始图片重新跑一遍extract，两条向量的相似度应该大于 0.99，低于这个数就说明链路有问题。

5.2 阈值直接抄了别人代码里的默认值

现象是系统太严，正常签到总被拒，或者太松，陌生人也能通过。原因很简单，0.6 这个数在不同模型、不同数据集上含义完全不同，FaceNet 在 LFW 上的推荐阈值和 ArcFace 在你的教室数据上的合理阈值不是一回事。

解决办法是按 4.2 节的方法标定一次，用自己采集的同人样本和陌生人样本各算一组相似度分布，取空隙中点。标定数据不需要很多，同人 30 组、陌生人 50 组就够看出趋势。标完之后把阈值写进签到任务表，不同场次可以微调，但改动要有记录，别在代码里直接改常数。

5.3 环境依赖版本冲突导致推理结果异常

现象是换了台机器或重装环境之后，模型能加载、图片能读入，但输出的特征和之前完全不一样，识别全乱。这类问题最耗时间，因为不报错。常见原因是 numpy 大版本升级导致的默认类型变化、opencv 与 numpy 的 ABI 不兼容、onnxruntime 和 CUDA 版本对不上、以及 torch 版本跨度太大导致权重加载时静默降级。

解决办法是锁死依赖版本，把requirements.txt里的包全部写成==而不是>=，并在项目 README 里记录验证过的 Python 版本。装完环境后先跑一次固定的自检脚本：读一张固定图片，输出特征的哈希值或前 6 位小数，和基准值比对。这个脚本五分钟能写完，能省掉一晚上的排查。

5.4 光照与侧脸导致漏检，前端只报系统错误

现象是用户在某个位置站着怎么都签不上，换个角度立刻就好。原因通常有两个：一是逆光导致人脸区域过暗，检测器置信度低于阈值被过滤；二是侧脸角度超过检测器的舒适区，关键点本身就不准。还有一种情况是摄像头广角畸变，画面边缘的人脸被拉伸。

解决办法分两层。算法层把失败原因透传出去，no_face、face_too_small、blur、low_confidence各对应一句人话提示，让用户知道该往前走还是该转头。工程层在采集端加引导框和光线提示，必要时开一盏补光灯——我见过一个项目调了两周模型，最后发现是教室背光，加一盏灯就解决了，这种问题模型层面是无解的。

5.5 特征存储方式导致精度丢失或查询变慢

现象有两种：一种是识别率莫名其妙地低了一点点，另一种是底库上千之后每次签到要等两三秒。前者往往是因为把 float32 转成 JSON 字符串或逗号分隔文本再存回去，精度被截断；后者往往是因为每次比对都从数据库全表拉取特征，还顺带做了字符串解析。

解决办法是特征用VARBINARY存原始 float32 字节流，写入时用np.float32(vec).tobytes()，读取时用np.frombuffer(..., dtype="<f4")，全程不经过文本。比对用的矩阵缓存在内存里，注册、删除时增量更新，不要每次查库。另外记得给sign_record的(task_id, user_id)建唯一索引，这一条索引同时解决了重复签到和统计查询两个问题。

6. 验收与答辩：一张表证明系统能用，五个问题答得住

验收这一步很多人做得太随意，跑一遍流程截图就算完事，结果答辩时被追问细节就说不清楚。比较稳妥的做法是提前准备一张验收表，每项都写清测试方法、样本量和实测结果，现场翻到哪一页都能对上。

演示脚本要提前写死，不要临场发挥。建议顺序：先用一个未注册的新人演示「识别失败」，证明系统不是谁都能过；再用底库人员演示一次完整签到，包括动作活体；接着连续点两次签到展示幂等；最后打开统计页展示到勤率和导出。这个顺序把「能识别」「不乱识别」「不重复记录」三件事一次性讲完了，比逐个功能点罗列有说服力得多。

答辩提问有几个几乎必问的，提前把答案写成三句话。第一个是「为什么选这个模型不选那个」，答法是比较两个模型在你数据集上的实测指标，而不是背论文里的数字。第二个是「阈值怎么定的」，答法是两条相似度分布和取中点的过程。第三个是「照片能不能骗过去」，老实说清动作活体防住了什么、防不住什么，比强装全能更可信。第四个是「并发下会不会重复签到」，答唯一索引加IntegrityError处理。第五个是「你的工作量在哪」，这一问最容易答崩，建议从数据采集标注、质量过滤设计、阈值标定、幂等与超时处理四个点讲，每个点都能对应到具体代码。

有一个技巧值得单独说：把失败案例也放进答辩材料里。比如那 2 次注册失败的逆光照片、那 1 次误通过的具体相似度值，配上原因分析和改进方案。评委看到的是「这个人真的跑过数据」，而不是「这个人跑通了 demo」。我带的项目里，凡是准备了失败案例的那几组，答辩分数都明显高一档，因为追问到深处时他们有东西可讲。

从那以后我每次接这类识别项目，都强制先做一件事：拿底库里的第一条特征，用原始图片重新跑一遍提取链路，算一下两条向量的相似度，低于 0.99 就不往下做。这个习惯帮我拦下过至少三次「模型没换但预处理变了」的隐性事故。希望这套结构能帮你把毕设稳稳交出去。

本文还有配套的精品资源，点击获取