树莓派人脸识别全攻略：环境搭建、LBPH训练与项目部署

简介这份资源面向人工智能、通信工程、自动化、电子信息、物联网等专业的在校学生和教师也适合用于毕业设计、课程设计、项目初期演示或小白进阶学习。内容以树莓派为硬件平台围绕人脸识别从数据采集、人脸检测、特征提取到实时识别展开包含可直接运行的源码、详细文档和答辩PPT便于快速理解项目架构并在此基础上二次开发。压缩包共79个文件以jpg图像样本、Python脚本为主辅以xml配置文件、csv特征数据、txt说明文档及pptx演示文稿整体大小1.53MB结构清晰适合按模块查阅。目前已有36人学习下载。资源已经过完整测试运行稳定且获导师指导认可、答辩评审分达95分无论是用于课程作业、课设毕设还是作为人脸识别入门实践都能提供从代码到文档的完整支撑帮助读者节省搭建环境与调试的时间直接聚焦核心功能实现与效果展示。1. 树莓派人脸识别为什么“高分项目”资料包到手第一步是退环境你手里那份带“高分项目”字样的树莓派人脸识别资料包打开之后十有八九是几十个.py文件、几份截图和一套 README。但真正把树莓派 4B 烧好系统、插上 OV5647 摄像头、跑通 OpenCV 人脸识别的人都知道这个项目最大的坎不是算法而是环境。基于树莓派的人脸识别本质上是嵌入式 Linux、Python 虚拟环境、OpenCV 编译链、摄像头驱动和 GPIO 控制这几件事的叠加任何一个环节版本对不上典型现象就是ImportError、摄像头读不出帧、识别结果像抽签。这篇文章就是沿着这条链路把“下载即跑”和“真能跑”之间的差距一层层补上。适合课设毕设、门禁考勤 demo 和想把 AI 应用落到嵌入式板卡上的从业者。2. 硬件与系统先行4B/5 选型、OV5647 摄像头和 OpenCV 安装的最终方案2.1 树莓派选型4B 4GB 是甜点位5 是加分项很多人拿到资料包第一个问题是“我手上这块板子能不能跑”。结论先给出来树莓派 4B 4GB 是性价比最稳的选择树莓派 5 建议有散热条件下再考虑3B 能跑但别开 GPU 推理Zero 2W 只适合跑纯 LBPH 识别、不适合跑界面。型号内存OpenCV 人脸识别体感适合场景3B1GBHaar 检测 15fps 左右DNN 明显掉帧纯识别模块不跑界面4B2GB/4GB/8GBHaar 实时DNN 可跳帧运行门禁、考勤、课设毕设54GB/8GB能跑轻量 YOLOOpenCV 余量充足要上深度学习模型的进阶项目Zero 2W512MB识别能转界面和并发不行低成本的隐藏式识别选 4B 的另一个理由是散热和电源都成熟。5 代性能强一截但原装电源加主动散热片是刚性需求否则满载时降频会让识别帧率忽高忽低表现还不如 4B 稳定。如果你的资料包里有 DNN 模型或者 YOLOv5 转换脚本预算够就上 5否则 4B 完全够跑完课设答辩。2.2 系统烧录与换源给 Bookworm/Trixie 一条不玄学的落地路径资料包里的旧代码大多按 Python 3.7 OpenCV 3.x raspistill来写但在新版树莓派系统上这条路已经走不通了。建议直接用 Raspberry Pi Imager 烧录官方 64 位系统桌面版和 Lite 版都可以要跑 PyQt 界面的选桌面版纯命令行识别选 Lite 版。烧录完成后第一件事不是装 OpenCV而是把 apt 源换掉。换源是树莓派人脸识别资料包复现时最容易忽略的一步默认源在新版系统下做apt upgrade可能要等很久。老版本系统改/etc/apt/sources.list新版本Bookworm 之后改/etc/apt/sources.list.d/下的raspi.list和debian.sources把默认域名替换成国内镜像地址即可。sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo sed -i s|deb.debian.org|mirrors.tuna.tsinghua.edu.cn|g /etc/apt/sources.list sudo apt update sudo apt full-upgrade -y这段命令先把源文件备份到.bak出了事随时后悔药sed只替换域名不动注释和格式。树莓派系统更新后很多老教程的源路径失效所以看到apt update报 404先别怀疑网络检查.list文件里有没有过时的仓库条目。换完源后确认摄像头能被系统认出。CSI 接口接 OV5647 摄像头时排线金属触点朝向 HDMI 口一侧插反会导致图像全花或纯黑。新版系统用libcamera-hello测试老命令raspistill已经废弃。libcamera-hello --list-cameras如果这条命令能列出摄像头型号说明硬件链路没问题。这里看不到设备就先去处理排线和接口不要急着装 OpenCV否则后面每一步都在黑匣子里猜。2.3 安装 OpenCV虚拟环境里用 opencv-contrib-python别一上来就源码编译很多资料包会让新手用apt install python3-opencv或者源码编译 OpenCV。我的建议是除非你就是想学编译否则直接用 pip 在虚拟环境里装 opencv-contrib-python。原因有两个第一LBPH 人脸识别器在cv2.face模块里这个模块属于 OpenCV contrib 扩展包普通opencv-python里没有第二apt 自带的 OpenCV 版本通常偏老和资料包里的代码容易撞版本问题。sudo apt install -y python3-venv libgl1 libglib2.0-0 python3 -m venv --system-site-packages ~/venv source ~/venv/bin/activate pip install --upgrade pip pip install opencv-contrib-python python3 -c import cv2; print(cv2.__version__, cv2.face.LBPHFaceRecognizer_create)这里每一行都有目的。libgl1和libglib2.0-0是 OpenCV 在精简系统上最容易缺的动态库缺了会报libGL.so.1: cannot open shared object file--system-site-packages让虚拟环境复用系统已装的libcamera相关包最后一行用cv2.face.LBPHFaceRecognizer_create做冒烟测试比打印版本号更能证明 contrib 装成功了。源码编译 OpenCV 在树莓派 4B 上要一两个小时中间还容易因为内存不足被 kill。除非你要在树莓派 5 上跑 YOLOv5 并做算子优化否则这条路的性价比太低。先让项目跑起来再谈性能优化这是树莓派项目的铁律。3. 检测与识别落地Haar、DNN、LBPH 三选一与可复制的训练代码3.1 人脸检测选型Haar 快、DNN 准、YOLO 是后话人脸识别分成两步检测框出人脸和识别判断是谁。树莓派上最常用的人脸检测有两种Haar Cascade 和 OpenCV 自带的 DNN SSD 模型。Haar Cascade 用haarcascade_frontalface_default.xml这个文件几十 KB检测速度快树莓派 4B 上 640×480 画面能做到实时缺点是侧脸、暗光、戴帽子容易漏检。DNN 模型用的是res10_300x300_ssd_iter_140000.caffemodel准确率高很多但对树莓派 4B 的 CPU 来说每帧要 0.2 秒以上直接跑实时视频会卡。我一般这样选择实时门禁用 Haar 做前端检测识别用 LBPH如果要做演示效果、要求框得准就用 DNN 配合跳帧检测每 3 帧检测一次。两个方案代码都不长import cv2 # Haar 方案适合树莓派 4B 实时画面 face_cascade cv2.CascadeClassifier(haarcascade_frontalface_default.xml) gray cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces face_cascade.detectMultiScale( gray, scaleFactor1.1, minNeighbors5, minSize(60, 60) ) # DNN 方案适合精度优先、能接受跳帧的场景 net cv2.dnn.readNetFromCaffe(deploy.prototxt, res10_300x300_ssd_iter_140000.caffemodel) blob cv2.dnn.blobFromImage(frame, 1.0, (300, 300), (104.0, 177.0, 123.0)) net.setInput(blob) detections net.forward()scaleFactor1.1表示每次缩放窗口缩小 10%越小检测越细但越慢minNeighbors5是“至少被多少个相邻窗口确认才算人脸”调大能减少误检调小能找回漏检暗光环境建议降到 3 试试。DNN 的blobFromImage里的三个均值是模型训练时的固定值不要随意改不然精度会明显下降。3.2 采集训练数据目录结构、单次按键存图、每类 30 张起步LBPH 是基于纹理特征的识别算法对训练数据的要求比深度学习模型更高。一个人只拍 5 张正面照识别效果基本靠运气。我的经验是每类人至少 30 张包含正脸、左右侧脸、戴不戴眼镜、室内灯光下两种姿态。目录结构建议按data/用户号/分文件夹这样训练时遍历目录就能生成标签不用手写映射表。import cv2 import os save_dir data/user_1 os.makedirs(save_dir, exist_okTrue) cap cv2.VideoCapture(0) cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640) cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480) count 0 while count 50: ret, frame cap.read() if not ret: continue gray cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) face_cascade cv2.CascadeClassifier(haarcascade_frontalface_default.xml) faces face_cascade.detectMultiScale(gray, 1.3, 5) for (x, y, w, h) in faces: face gray[y:yh, x:xw] cv2.imshow(capture, cv2.resize(face, (200, 200))) cv2.imwrite(f{save_dir}/{count}.jpg, face) count 1 print(fsaved {count}) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()这段代码的写法和很多资料包里的采集脚本不同它只保存检测框内的人脸区域而不是整张画面。这么做的好处是训练时不需要再检测一次省掉中间环节的两次检测误差。每存一张都resize到 200×200 并显示出来方便在采集时就发现人脸区域裁偏了。采集时注意让被采集者轻微转动头部不要一动不动盯着摄像头否则后期识别一偏头就认不出。3.3 训练 LBPH 识别器不要用 opencv-python要用 opencv-contrib-python训练代码本身很短但有一个前置条件cv2.face模块只存在于opencv-contrib-python里。上一章装的 contrib 包在这里就发挥作用了。import cv2 import os import numpy as np faces [] labels [] label_map {} for label, name in enumerate(os.listdir(data)): label_map[label] name for img_name in os.listdir(fdata/{name}): img_path fdata/{name}/{img_name} img cv2.imread(img_path, cv2.IMREAD_GRAYSCALE) faces.append(img) labels.append(label) recognizer cv2.face.LBPHFaceRecognizer_create( radius1, neighbors8, grid_x8, grid_y8 ) recognizer.train(faces, np.array(labels)) recognizer.save(trainer.yml) print(训练完成保存为 trainer.yml)这里有个容易翻车的小细节os.listdir(data)返回的目录顺序不一定是user_0, user_1, user_2可能是乱序。所以代码里用enumerate实时生成label_map而不是硬编码 label 值。trainer.yml保存后识别端的names字典一定要和这里的label_map对应否则就会出现“识别成功但名字错位”的诡异情况。LBPH 的四个参数里radius1是纹理采样半径neighbors8是采样点个数grid_x和grid_y是图像分块数。neighbors调大能提升抗噪能力但样本少时反而容易过拟合grid分块越细局部纹理保留越多但对对齐要求更高。新手不要乱动等识别不稳定再逐个试。3.4 识别与置信度判定LBPH 的 confidence 是距离不是概率训练完模型识别端用predict接口它返回两个值标签和置信度。很多人第一次用会把 confidence 当概率用这是错的。LBPH 的 confidence 是样本与模型之间的距离越小越像。常见经验值是小于 80 判为“认识”80 到 100 判为“可疑”大于 100 判为“不认识”。但这个阈值在不同摄像头、不同光照下差异很大我建议拿训练样本回测一遍取所有回测结果的最大值再加 20 作为上线阈值。import cv2 names {0: user_1, 1: user_2} recognizer cv2.face.LBPHFaceRecognizer_create() recognizer.read(trainer.yml) cap cv2.VideoCapture(0) while True: ret, frame cap.read() if not ret: break gray cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces face_cascade.detectMultiScale(gray, 1.1, 5) for (x, y, w, h) in faces: roi gray[y:yh, x:xw] label, confidence recognizer.predict(roi) if confidence 80: text f{names[label]} ({confidence:.1f}) else: text Unknown cv2.rectangle(frame, (x, y), (xw, yh), (0, 255, 0), 2) cv2.putText(frame, text, (x, y-10), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2) cv2.imshow(recognition, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()识别循环里我刻意把predict放进for循环内不做跳帧是为了让逻辑最简化。实际部署时如果觉得卡就在循环开头加一个帧计数器if frame_count % 2 ! 0: continue就能省一半算力。cv2.rectangle和putText的坐标都来自检测框roi 直接从原灰度图里切不要在彩色图和灰度图之间反复转换浪费内存。4. 做成高分项目PyQt5 界面、SQLite 打卡记录和 GPIO 继电器开锁4.1 高分项目的骨架识别只是核心评分看的是完整度资料包里标着“高分项目”的作品通常不是单纯一个识别脚本而是把识别嵌进一个完整应用里有界面、有记录、有物理动作。我接触过的树莓派人脸识别高分项目结构基本可以分成五块采集模块、训练模块、识别模块、日志模块和控制模块。评阅老师眼里能演示“识别成功 → 记录入库 → 继电器开锁 → 界面刷新记录”这一条完整链路比单独跑通 LBPH 高一个量级。这也是这类资料包存在的价值代码本身不难难的是把树莓派、OpenCV、数据库和外设接口串起来。下面这三节就是这条链路里最容易出彩也最容易踩坑的三个节点。4.2 PyQt5 上机界面QTimer 拉帧 信号槽更新结果树莓派上跑 PyQt5 界面最忌讳的是把识别循环写死在 UI 线程里。摄像头读取和 LBPH 预测都是阻塞操作写在一起必然导致窗口拖不动、关不掉。正确做法是工作线程只负责取帧和识别识别结果通过信号发回主线程主线程只做显示。from PyQt5.QtCore import QThread, pyqtSignal import cv2 class RecognitionThread(QThread): result pyqtSignal(object, object) # (frame, text) def __init__(self): super().__init__() self.running True self.cap cv2.VideoCapture(0) self.recognizer cv2.face.LBPHFaceRecognizer_create() self.recognizer.read(trainer.yml) self.detector cv2.CascadeClassifier(haarcascade_frontalface_default.xml) def run(self): while self.running: ret, frame self.cap.read() if not ret: continue gray cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces self.detector.detectMultiScale(gray, 1.1, 5) text for (x, y, w, h) in faces: label, conf self.recognizer.predict(gray[y:yh, x:xw]) if conf 80: text names[label] else: text Unknown cv2.rectangle(frame, (x, y), (xw, yh), (0, 255, 0), 2) self.result.emit(frame, text) def stop(self): self.running False self.cap.release()线程类在run里做循环读帧result信号把 BGR 帧和识别文本一起发出去。主线程里连接这个信号后先把 BGR 转成 RGB 再给 QLabel 显示否则画面会整体偏蓝。关窗口时一定要调用stop()否则摄像头资源不释放下一次启动会报could not open camera。界面刷新频率可以靠QTimer控制如果线程跑太快直接在线程里加time.sleep(0.03)比用 Qt 定时器控制线程更可靠。4.3 打卡记录入库SQLite 足够没必要上 MySQL门禁类项目一定要有记录模块。树莓派上跑 SQLite 是最省资源的方案一个文件搞定不需要单独装数据库服务导师打开就能看到.db文件里的记录。建表语句和插入逻辑如下。CREATE TABLE IF NOT EXISTS records ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, time TIMESTAMP DEFAULT CURRENT_TIMESTAMP, status TEXT DEFAULT pass );识别通过时插入一条记录但要注意去重同一个人的脸在摄像头前停留 3 秒线程可能插了 30 条记录。常见做法是 1 分钟内同一用户只记第一次。import sqlite3 import time last_record {} def record_attendance(name): now time.time() if name in last_record and now - last_record[name] 60: return False last_record[name] now conn sqlite3.connect(attendance.db) cursor conn.cursor() cursor.execute( INSERT INTO records (name, status) VALUES (?, ?), (name, pass) ) conn.commit() conn.close() return True这段代码把去重逻辑放在数据库写入之前用 Python 字典缓存每个人的最后记录时间避免频繁写库。数据库文件attendance.db会生成在项目目录下答辩时可以直接打开给老师看查询结果。如果还要导出考勤表写一个简单的SELECT name, time FROM records ORDER BY time DESC再加to_csv导出就够展示了。4.4 GPIO 继电器开锁低电平触发与延时回锁物理反馈是最能让项目“看起来能落地”的部分。树莓派 GPIO 默认输出 3.3V直接接电磁锁既带不动也危险正确做法是用 GPIO 控制继电器继电器再控制锁的电源通路。from gpiozero import DigitalOutputDevice import time lock DigitalOutputDevice(17, initial_valueFalse) def open_lock(duration3): lock.on() # GPIO17 输出高电平触发继电器 time.sleep(duration) lock.off() # 3 秒后自动回锁接线时注意继电器模块的电源和信号逻辑模块 VCC 接树莓派 5VGND 接 GNDIN 接 GPIO17。很多常见继电器模块是低电平触发也就是 IN 脚为低电平时继电器吸合。如果你的模块是这种上面的代码要改成DigitalOutputDevice(17, initial_valueTrue)然后lock.off()表示吸合。判断方法是看模块上的 LED 指示灯和卖家给出的触发说明用万用表测一下更放心。电磁锁属于感性负载接继电器时要在锁的两端并联一个续流二极管吸收反向电动势否则断电瞬间的高压尖峰有可能反过来打坏继电器甚至树莓派 GPIO。这是个容易被资料包忽略的硬件细节但恰恰是答辩老师喜欢追问的点。5. 树莓派人脸识别的 5 个高发坑现象、原因与排查顺序5.1 摄像头打不开或画面全是花屏现象VideoCapture(0).isOpened()返回False或者画面出现彩色斜纹、半黑半绿。原因八成是 CSI 排线问题剩下两成是驱动没加载。OV5647 的排线方向反了、没插到底、或者接头没扣紧都会导致系统检测不到设备。另外在老系统上需要手动加载bcm2835-v4l2模块新版系统走libcamera如果项目代码用的是旧版 V4L2 接口就冲突。解决先拔掉排线重新插金属触点朝外插到底后扣紧卡扣。然后用libcamera-hello --list-cameras确认系统能识别再用ls -l /dev/video*看设备节点是否存在。libcamera识别到但 OpenCV 打不开时在/boot/firmware/config.txt里加一行dtoverlayov5647重启后再试。5.2 同一张脸多次识别结果不一样label 随机跳变现象摄像头对着同一张脸识别结果一会儿是 user_1一会儿是 user_2置信度也很难看。原因这个坑基本不是算法问题而是采集样本质量差或训练标签错位。采集时人脸区域不居中、亮度忽明忽暗、同一人样本里混入了其他人的脸都会让 LBPH 的纹理特征分布乱掉。还有一种情况是os.listdir读取图片顺序随机标签对错了人。解决把训练集挨张检查一遍删掉非人脸和模糊图。每类人重新采集 30 张以上分三次采、每次换角度。训练脚本里打印每张图片对应的 label人工确认后再执行train。识别端不要直接打印 label先通过label_map映射成名字发现问题时能更快定位。5.3 ImportError: LBPHFaceRecognizer_create 不存在现象cv2.face调用报AttributeError或者代码里找不到haarcascade_frontalface_default.xml。原因安装的是opencv-python而不是opencv-contrib-python人脸识别器不在主包里。另一个常见原因是代码里用相对路径加载 xml 文件但当前工作目录不对。解决先执行pip show opencv-contrib-python确认版本再跑python3 -c import cv2; print(cv2.face.LBPHFaceRecognizer_create)。如果没装 contrib按第 2 章的步骤重装。xml 文件的问题用绝对路径或者把 xml 文件复制到项目根目录解决不要依赖系统搜索路径。5.4 PyQt 界面点关闭没反应窗口变白板现象程序能跑识别也正常但窗口拖不动、点 X 没反应最后只能强制重启树莓派。原因摄像头线程还在while循环里跑closeEvent没有通知线程停止主线程退出时资源没释放造成死锁。或者你把识别代码直接写在了主线程的QTimer回调里阻塞了 Qt 的事件循环。解决用 QThread 把识别循环隔离出来重写closeEvent在里面调用线程的stop()方法并wait()等线程退干净。如果用了QTimer回调里的识别代码要尽量短或者干脆让 QTimer 只负责触发一次“开始识别”不做实时循环。5.5 现场演示时灯光一换识别率立刻崩现象在工位上调好的阈值和模型拿到答辩教室后连续误判认识的人被识别成 Unknown。原因LBPH 对光照极其敏感它在局部纹理上做直方图统计光照一变纹理分布整个平移。训练时室内暖光、演示时顶光直射置信度会整体抬高 20 到 30。解决采集训练样本时主动覆盖两种以上的光照条件比如开灯一组、关灯开台灯一组。识别循环里先让摄像头自动曝光稳定 2 秒再做第一次预测别一开画面就识别。另外阈值不要定太死留出 10 到 15 的余量这个动作比换算法立竿见影。6. 从演示到交付识别性能调优与开机自启的细节项目跑通之后接下来要解决的是“演示能不能体面收场”。我建议按这个顺序做三件小事。第一件把识别区域裁剪到检测框内不要对整帧做预测。LBPH 的predict输入只有人脸区域把 640×480 的整图缩到 200×200 再预测等于把大量背景纹理塞进模型既慢又容易误判。正确做法是先detectMultiScale找出人脸再predict人脸框区域。第二件把摄像头参数固定下来。cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)和cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)不能只在采集脚本里写识别脚本里也要同样设置否则系统可能给你默认 1280×720检测速度直接掉一半。第三件开机自启。树莓派跑人脸识别门禁演示时最尴尬的就是现场敲命令行。用桌面自启最简单在~/.config/autostart/下建一个.desktop文件指向启动脚本即可如果用的是 Lite 版无桌面系统就写一个 systemd serviceRestartalways保证程序崩了能自动拉起来。[Unit] DescriptionFace Recognition Service Afternetwork.target [Service] Typesimple Userpi ExecStart/home/pi/venv/bin/python /home/pi/face_recognition/main.py Restartalways RestartSec3 [Install] WantedBymulti-user.target写成 systemd 服务有几个隐藏收益Restartalways能扛住偶发崩溃Typesimple适合这种常驻循环程序日志用journalctl -u face-recognition -f就能实时看输出比nohup加日志文件方便得多。还有一个小技巧是我自己的血泪经验演示前把摄像头对着墙面测 50 次空白背景把置信度的最大值记下来作为参考底噪。这样做的好处是你能直观判断当前光线环境对模型有多不友好然后决定是把阈值放宽 10 还是先调整现场灯光。上次在教室答辩翻车就是因为我低估了顶光对 LBPH 的影响阈值定在了 80现场识别结果全是 85 上下。后来改成先跑底噪再调阈值再也没有出现“演示现场认不出自己人”的尴尬。树莓派人脸识别这个方向算法选型不复杂真正拉开差距的是环境管理、样本质量和阈值校准这些细节。希望帮到你。本文还有配套的精品资源点击获取