1. 项目概述与核心价值最近在折腾一个挺有意思的小项目起因是看到学校和企业里还在用传统的手工点名或刷卡考勤效率低不说还容易出错代签。作为一个喜欢鼓捣嵌入式设备和计算机视觉的学生我就琢磨着能不能用身边常见的硬件比如树莓派结合现在挺火的YOLOv8模型自己搭一个人脸识别考勤系统。这个想法听起来有点“硬核”但实际拆解下来你会发现它融合了深度学习模型部署、嵌入式系统编程和简单的应用逻辑是一个非常好的全栈式练手项目。简单来说这个系统的目标就是让一台连接了摄像头的树莓派能够自动识别出现在镜头前的人脸并与预先注册的数据库进行比对从而完成自动签到或签退。整个过程无需人工干预真正实现自动化考勤。它的核心价值在于将前沿的计算机视觉技术落地到一个非常具体的应用场景中用极低的硬件成本一台树莓派加一个普通USB摄像头解决了实际的管理痛点。无论是用于小型团队、创客空间的管理还是作为学生课题研究都具有很强的实践意义和可复现性。2. 系统整体设计与思路拆解2.1 为什么选择树莓派 YOLOv8 这个组合在做技术选型时我主要考虑了性能、成本、易用性和社区支持这几个维度。首先硬件平台我选择了树莓派。原因很简单它是一台完整的微型计算机运行Linux系统有丰富的GPIO接口和强大的社区生态。相比于直接用一台旧笔记本或台式机树莓派功耗极低通常5V/3A供电即可体积小巧可以非常方便地部署在门口、教室讲台等任何位置甚至用移动电源供电实现真正的“嵌入式”部署。我这次用的是性能更强的树莓派5其算力对于运行轻量级AI模型已经绰绰有余。其次在模型选择上我放弃了需要庞大计算资源的重型人脸识别网络如FaceNet、ArcFace等转而使用YOLOv8。这里需要澄清一个关键点YOLOv8本身是一个目标检测模型并非专门的人脸识别模型。我的设计思路是分两步走人脸检测使用YOLOv8检测出图像中所有的人脸位置bounding box。YOLOv8的检测速度快、精度高且有针对边缘设备优化的轻量版本如YOLOv8n非常适合在树莓派上运行。人脸特征提取与比对从YOLOv8框出的人脸区域中裁剪出人脸图像再送入一个轻量级的人脸特征提取模型例如使用OpenCV DNN模块加载一个预训练的MobileFaceNet或类似的ONNX模型来生成一个128维或512维的特征向量face embedding。识别过程就是计算当前人脸特征与数据库中已注册人脸特征的余弦相似度或欧氏距离。这个“检测特征提取”的两阶段方案比端到端的人脸识别模型更灵活也更容易在资源受限的设备上实现和调试。YOLOv8负责“找到脸”另一个小模型负责“认出这是谁的脸”。2.2 系统架构与工作流程整个系统的架构可以清晰地分为离线训练和在线推理两个阶段。离线训练阶段数据采集与标注收集目标人员的人脸图片并使用标注工具如Roboflow、LabelImg为每张图片中的人脸画上边界框并打上人名标签。这部分数据用于训练YOLOv8的人脸检测模型。模型训练在拥有GPU的电脑或云端平台上使用标注好的数据集训练YOLOv8模型。训练的目标是让模型能准确地从复杂背景中检测出人脸。特征库构建对于每个需要注册的人员采集多张不同角度和光照条件下的人脸图片用训练好的检测模型框出人脸再用特征提取模型计算出平均特征向量将其与人员姓名/ID一起存入数据库例如一个简单的JSON文件或SQLite数据库。这就是我们的“人脸指纹库”。在线推理阶段树莓派端视频流捕获树莓派上的程序通过USB摄像头实时捕获视频流。人脸检测对每一帧图像运行YOLOv8模型检测出所有出现的人脸框。人脸对齐与裁剪根据检测框坐标从原图中裁剪出每一张人脸区域。这里通常还会做一个简单的对齐处理例如根据眼睛位置旋转图像以提高后续特征提取的稳定性。特征提取与比对对每一张裁剪后的人脸图像运行特征提取模型得到其特征向量。然后遍历本地特征库计算相似度。识别与记录如果最高相似度超过预设的阈值例如0.6或0.7则认为识别成功系统记录该人员的姓名和当前时间戳到考勤日志如CSV文件。同时可以在连接的LCD屏幕上显示识别结果和欢迎信息。反馈与交互通过RGB LED灯提供状态反馈例如识别成功亮绿灯识别失败或未注册亮红灯。注意在实际部署中必须严格遵循隐私和数据安全规范。所有数据采集需获得当事人明确同意考勤数据应加密存储并且系统最好运行在本地局域网内避免人脸数据上传至不安全的云端。3. 核心模块详解与实操要点3.1 硬件准备与树莓派系统配置硬件清单是项目启动的第一步。我的配置如下主控板树莓派54GB或8GB版本均可。树莓派4B也完全足够性能差距在实际应用中感知不明显。摄像头Logitech C920s Pro HD Webcam。选择它的原因是它支持1080P自带麦克风并且在Linux系统下免驱兼容性极好。任何支持UVC协议的USB摄像头都可以。显示与反馈Freenove项目套件中的一块小LCD屏用于显示识别结果和RGB LED灯环用于状态指示。这部分是可选的但能极大提升系统的交互感和完成度。其他树莓派官方电源必须保证稳定供电尤其是树莓派5、MicroSD卡至少32GB、散热片/风扇树莓派5运行时发热较大、键盘鼠标显示器用于初次配置后续可通过SSH远程操作。树莓派基础配置步骤烧录系统从树莓派官网下载最新的Raspberry Pi OS64位Bullseye或Bookworm版本使用Raspberry Pi Imager工具烧录到MicroSD卡。烧录时Imager工具可以预先配置Wi-Fi、开启SSH、设置主机名和密码非常方便。首次启动与更新插入SD卡连接电源、摄像头、显示器等外设启动。完成系统初始化后第一件事就是打开终端执行sudo apt update sudo apt upgrade -y更新系统。启用摄像头接口运行sudo raspi-config进入Interface Options-Legacy Camera选择启用Enable。重启树莓派。测试摄像头使用libcamera-hello或raspistill命令测试摄像头能否正常工作。例如libcamera-hello --timeout 0会打开一个实时预览窗口。3.2 数据采集、标注与YOLOv8模型训练这是整个项目中最需要耐心和细致的一环数据质量直接决定最终模型的性能。数据采集目标为每个需要注册的人员采集约50-100张人脸图片。总数据量建议在2000-3000张以上以确保模型的泛化能力。方法可以写一个简单的Python脚本使用OpenCV调用摄像头定时如每秒捕获一帧并保存。要求被采集者在摄像头前缓慢移动头部展现不同的角度左转、右转、抬头、低头并最好能在不同的光照环境下室内光、窗边侧光、稍暗环境进行采集。伦理与合规务必务必务必事先获得每一位参与者的书面或明确口头同意告知数据用途仅用于本项目测试并承诺项目结束后删除。这是红线。数据标注 我强烈推荐使用Roboflow这个在线平台。它免费 tier 的功能对于这个项目完全够用。将收集好的图片按人名创建文件夹然后整体上传到Roboflow的一个新项目中。在Roboflow的Web界面中可以非常方便地用鼠标框选出每一张人脸并为其打上对应人名的标签如“Person_A”, “Person_B”。这个过程虽然枯燥但至关重要。标注时要尽量紧贴人脸边缘但也不要太紧而裁掉头发等部分。标注完成后Roboflow可以提供强大的数据增强功能。我建议启用“水平翻转”、“随机旋转±15°”、“亮度与饱和度随机调整”等选项。这能显著增加数据的多样性模拟真实场景下的变化让模型更鲁棒。最后将数据集以“YOLOv8”的格式导出。Roboflow会生成一个包含data.yaml配置文件和所有图片、标签文件的压缩包以及用于下载的代码片段。模型训练 训练过程需要在算力更强的机器上进行比如有NVIDIA GPU的电脑或者使用Google Colab等云端平台。环境准备在训练机上安装PyTorch和Ultralytics YOLO库。pip install ultralytics即可。准备数据将Roboflow导出的数据集解压其目录结构通常能被YOLO直接识别。开始训练创建一个简单的Python脚本或在命令行执行。关键参数需要仔细设置。from ultralytics import YOLO # 加载一个预训练的轻量模型例如YOLOv8n model YOLO(yolov8n.pt) # 开始训练 results model.train( datapath/to/your/data.yaml, # Roboflow导出的配置文件路径 epochs100, # 训练轮数根据数据集大小调整 imgsz640, # 输入图像尺寸与Roboflow导出时设置一致 batch16, # 批大小根据GPU内存调整 devicecuda, # 使用GPU如果是CPU则改为‘cpu’ nameface_detection_v1, # 本次训练的实验名称 pretrainedTrue # 使用预训练权重 )评估与导出训练完成后模型会自动在验证集上评估给出mAP等指标。使用model.export(formatonnx)将模型导出为ONNX格式。ONNX格式的模型在树莓派上可以通过ONNX Runtime或OpenCV DNN来高效推理兼容性更好速度也往往比原生PyTorch模型快。3.3 树莓派端软件环境搭建在树莓派上我们需要一个精简但高效的Python环境来运行我们的识别程序。安装Miniforge与创建虚拟环境为了避免污染系统Python环境我使用Miniforge一个针对ARM架构优化的Conda发行版。# 下载并安装Miniforge wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-aarch64.sh bash Miniforge3-Linux-aarch64.sh # 安装完成后创建一个新的虚拟环境 conda create -n face_attendance python3.9 conda activate face_attendance安装核心依赖pip install opencv-python-headless # 无GUI版本的OpenCV节省空间 pip install onnxruntime # 用于推理ONNX模型注意选择arm64版本 pip install ultralytics # 用于加载YOLO模型但推理时我们主要用ONNX Runtime pip install numpy pandas # 数据处理和日志记录 pip install Pillow # 图像处理 # 如果你使用了特定硬件如Freenove的LCD屏还需要安装其厂商提供的SDK pip install freenove-lcd # 示例具体包名需查厂商文档测试ONNX模型推理将训练好的yolov8n_face.onnx模型和特征提取模型如mobilefacenet.onnx拷贝到树莓派。写一个简单的测试脚本确保能正常加载并进行一次前向传播。4. 系统集成与核心代码实现4.1 主程序逻辑与流程控制主程序是一个无限循环不断从摄像头读取帧进行处理。下面我勾勒出核心代码结构并解释关键部分。import cv2 import onnxruntime as ort import numpy as np from datetime import datetime import json import csv # 1. 初始化 # 加载YOLOv8人脸检测ONNX模型 detection_session ort.InferenceSession(yolov8n_face.onnx, providers[CPUExecutionProvider]) # 加载人脸特征提取ONNX模型 recognition_session ort.InferenceSession(mobilefacenet.onnx, providers[CPUExecutionProvider]) # 加载人脸特征数据库 with open(face_database.json, r) as f: face_db json.load(f) # 假设格式: {name: [feature_vector_list], ...} # 初始化摄像头 cap cv2.VideoCapture(0) cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640) cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480) # 考勤记录文件 attendance_log attendance.csv # 2. 主循环 while True: ret, frame cap.read() if not ret: break # 2.1 人脸检测 # 预处理调整大小、BGR2RGB、归一化、增加批次维度 input_img cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) input_img cv2.resize(input_img, (640, 640)) input_tensor input_img.astype(np.float32) / 255.0 input_tensor np.transpose(input_tensor, (2, 0, 1)) # HWC to CHW input_tensor np.expand_dims(input_tensor, axis0) # Add batch dimension # YOLOv8 ONNX模型推理 outputs detection_session.run(None, {images: input_tensor}) # outputs[0] 的形状通常是 [1, 84, 8400]需要后处理解析出框、置信度、类别 detections postprocess_yolo_output(outputs[0], frame.shape) # 自定义后处理函数 # 2.2 遍历每个检测到的人脸框 for det in detections: x1, y1, x2, y2, conf, cls_id det if conf 0.5: # 置信度阈值 continue # 裁剪人脸区域 face_roi frame[y1:y2, x1:x2] if face_roi.size 0: continue # 2.3 人脸对齐简化版直接resize到特征提取模型需要的尺寸如112x112 face_aligned cv2.resize(face_roi, (112, 112)) # 预处理归一化、转置等需匹配特征提取模型的输入要求 face_for_recog preprocess_for_recognition(face_aligned) # 2.4 特征提取 recog_output recognition_session.run(None, {input: face_for_recog}) current_feature recog_output[0].flatten() # 得到当前人脸的特征向量 # 2.5 与数据库比对 best_match_name Unknown best_match_score 0 threshold 0.6 # 相似度阈值 for name, registered_features in face_db.items(): for reg_feat in registered_features: # 计算余弦相似度 similarity np.dot(current_feature, reg_feat) / (np.linalg.norm(current_feature) * np.linalg.norm(reg_feat)) if similarity best_match_score: best_match_score similarity best_match_name name # 2.6 识别结果处理与记录 if best_match_score threshold: # 在图像上画框和名字 cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2) cv2.putText(frame, f{best_match_name}: {best_match_score:.2f}, (x1, y1-10), cv2.FONT_HERSHEY_SIMPLEX, 0.9, (0, 255, 0), 2) # 记录考勤避免短时间内重复记录 record_attendance(best_match_name) # 控制RGB LED亮绿灯 set_led_color(green) # 在LCD屏幕上显示欢迎信息 lcd_display(fWelcome, {best_match_name}!) else: # 未知人脸或置信度不足 cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 0, 255), 2) cv2.putText(frame, Unknown, (x1, y1-10), cv2.FONT_HERSHEY_SIMPLEX, 0.9, (0, 0, 255), 2) set_led_color(red) lcd_display(Please register.) # 显示实时画面可选会消耗一定性能 cv2.imshow(Face Attendance System, frame) if cv2.waitKey(1) 0xFF ord(q): break # 3. 释放资源 cap.release() cv2.destroyAllWindows()关键函数说明postprocess_yolo_output: 这个函数负责解析YOLOv8模型的原始输出。YOLOv8的输出是密集预测需要应用置信度阈值和非极大值抑制NMS来筛选出最终的人脸检测框。这是整个检测环节的难点需要仔细调试阈值参数。preprocess_for_recognition: 根据你选用的人脸特征提取模型的要求对人脸图像进行预处理可能包括减去均值、除以标准差、特定的归一化等。record_attendance(name): 这个函数负责将识别成功的人员姓名和时间戳写入CSV文件。必须加入防重复记录逻辑例如同一个人在一分钟内只记录一次避免因为人在镜头前停留而生成大量重复记录。set_led_color()和lcd_display(): 这些是与具体硬件交互的函数需要根据你使用的硬件库来编写。4.2 性能优化技巧在树莓派上运行AI模型性能是必须考虑的问题。以下是几个实测有效的优化点模型量化将训练好的FP32精度模型转换为INT8精度可以大幅减少模型体积并提升推理速度而精度损失通常很小。ONNX Runtime支持动态和静态量化可以尝试使用。帧采样策略无需对每一帧视频都进行识别。可以每间隔N帧例如3-5帧处理一帧这能极大减轻CPU/GPU负载。对于考勤场景人员移动速度不快这个策略完全可行。输入分辨率YOLO检测时将图像resize到640x640是平衡速度和精度的常用选择。如果场景中人脸都比较大可以尝试降到480x480甚至320x320速度会快很多。使用多线程可以将摄像头捕获、人脸检测、特征提取与比对、UI更新如显示画面放在不同的线程中利用树莓派的多核能力避免因某个环节阻塞导致整体卡顿。关闭不必要的显示cv2.imshow()会消耗不少资源。在最终部署版本中可以关闭实时视频显示只保留日志输出和硬件反馈LED LCD。5. 常见问题、调试心得与部署建议5.1 开发与调试阶段常见问题摄像头无法打开或帧率极低可能原因USB摄像头供电不足或者与其他USB设备冲突。排查尝试将摄像头直接连接到树莓派的USB接口避免使用扩展坞。使用lsusb和v4l2-ctl --list-formats命令检查摄像头是否被系统正确识别。在代码中尝试降低cv2.VideoCapture读取的分辨率。心得树莓派的USB总线带宽有限使用高分辨率、高帧率的摄像头时可能会出现瓶颈。对于考勤场景720P15FPS已经足够。模型推理速度慢实时性差可能原因模型太大或者没有使用合适的推理后端。排查使用top或htop命令查看CPU占用。确保使用的是ONNX Runtime的CPU版本并且providers参数设置为[CPUExecutionProvider]。尝试使用更小的YOLOv8模型如nano版本。心得在树莓派上OpenCV DNN模块推理ONNX模型有时比ONNX Runtime更快可以两者都测试一下。关键是将模型优化如剪枝、量化做到极致。识别准确率低误识别或无法识别可能原因训练数据质量差、光照变化大、人脸角度过于极端、相似度阈值设置不合理。排查数据问题检查训练集是否包含了足够多样的光照和角度。可以尝试在部署环境中临时采集一些“困难样本”加入训练集重新训练。阈值问题调整threshold参数。调高会减少误识别将陌生人认作熟人但可能增加拒识熟人认不出调低则相反。需要在验证集上反复测试找到平衡点。特征提取问题确保人脸对齐裁剪的步骤正确。歪斜的人脸会严重影响特征提取的准确性。心得增加一个“活体检测”的简单逻辑如要求眨眼、摇头可以极大防止照片攻击。另外对于特征比对使用余弦相似度通常比欧氏距离更适合人脸特征这种高维向量。考勤记录重复或遗漏可能原因没有做防重复记录处理或者识别间隔内人员快速进出视野。解决方案在record_attendance函数中实现一个简单的“冷却时间”机制。例如用一个字典记录每个人最后一次成功识别的时间如果当前时间与上次记录时间差小于设定的最小间隔如60秒则不再记录。心得除了时间冷却还可以结合简单的轨迹跟踪。如果同一个人脸框在连续几帧中都出现只记录一次。5.2 系统部署与长期运行建议开机自启动将主程序Python脚本设置为系统服务实现开机自动运行。创建一个face-attendance.service文件放在/etc/systemd/system/下使用systemctl命令管理。[Unit] DescriptionFace Attendance System Afternetwork.target [Service] Typesimple Userpi WorkingDirectory/home/pi/face_attendance ExecStart/home/pi/miniforge3/envs/face_attendance/bin/python /home/pi/face_attendance/main.py Restarton-failure RestartSec10 [Install] WantedBymulti-user.target日志与监控使用Python的logging模块将系统运行状态、识别事件、错误信息记录到文件中方便后期排查问题。可以定期如每天滚动日志文件避免单个文件过大。数据备份与清理考勤记录的CSV文件应定期备份到其他位置。同时程序应具备基本的磁盘空间检查功能避免日志或临时文件占满SD卡导致系统崩溃。网络远程管理通过配置SSH可以远程登录树莓派进行维护。更进阶的做法是可以写一个简单的Flask或FastAPI Web服务运行在树莓派上提供一个局域网内的Web页面用于查看实时考勤状态、导出数据、甚至远程添加新用户需严格授权。功耗与散热长期运行时确保树莓派通风良好最好加装散热风扇。使用可靠的电源适配器避免因电压不稳导致设备重启。5.3 项目扩展方向这个基础版本完成后还有很多可以深化和扩展的地方多人同时识别当前的循环处理逻辑天然支持多人但性能是关键。优化后的模型和代码应能同时处理3-5人。戴口罩识别可以专门收集戴口罩的人脸数据对检测和识别模型进行微调提升在特定场景下的实用性。与云端同步增加一个客户端定时将本地的考勤CSV文件上传到云存储如阿里云OSS、腾讯云COS或数据库方便在手机或电脑端统一查看。考勤规则引擎在记录时间戳的基础上加入简单的规则判断如判断是否迟到、早退并生成每日/每周考勤报表。硬件升级使用树莓派官方的High Quality Camera模块搭配定焦镜头可以获得更稳定、画质更好的人脸图像进一步提升识别率。