树莓派人脸识别实战：基于dlib与face_recognition的完整项目

简介这是一份基于树莓派的人脸识别完整项目包面向人工智能、通信、自动化、电子信息、物联网等专业的在校学生和开发者尤其适合毕业设计、课程设计及项目初期演示。资源包含从人脸数据采集、特征提取到实时识别的完整 Python 代码并有配套 PPT 和说明文档可帮助快速搭建可运行的人脸识别系统。压缩包共 79 个文件约 1.53MB。其中 68 张 JPG 图片用于人脸样本库5 个 Python 脚本覆盖摄像头取图、人脸描述子提取、特征写入 CSV、实时识别等关键流程另含 XML 配置文件、CSV 特征数据、项目配置文件及介绍 PPT目录结构清晰便于对照学习与二次开发。这份项目为高分项目代码已通过运行测试和导师评审可直接复用或在此基础上扩展功能。已有 36 人学习下载适合希望系统掌握树莓派人脸识别落地流程的入门及进阶用户。1. 树莓派人脸识别一套能直接答辩的人脸识别完整源码树莓派人脸识别这个方向网上能找到的代码不少但多数是单一脚本跑通容易、拿去答辩难。这套高分项目的价值在于完整摄像头采集、128维特征提取、CSV特征库、实时识别四个环节都有独立脚本还带了 face_recognition 库源码和答辩 PPT改动量很小就能支撑课程设计或毕业设计。适合手里有树莓派4B和 OV5647 摄像头的学生也适合想快速看完整链路的人。核心基于 dlib 的128维人脸特征不依赖 GPU4B 上能跑只是帧率要接受 1~2fps。压缩包里的授权码文件在解压后先看里面就是上面说的全部源码、文档和 PPT。2. 环境搭建树莓派4B上把 dlib 和 face_recognition 跑通2.1 为什么选 face_recognition 而不是纯 OpenCV这套项目把核心识别放在 face_recognition 库上底层是 dlib 的 128 维人脸特征提取。OpenCV 自带的 LBPH、EigenFaces 也能做人脸识别但它们在姿态和光照变化下掉点很厉害树莓派拍到的画面本身偏暗偏糊用传统算法容易翻车。face_recognition 把 dlib 的检测和特征提取封装成两行调用对入门者友好对毕设来说特征维度、欧氏距离这些概念也有得写。dlib 的 128 维特征本质是一个训练好的深度学习模型推理结果不需要 GPU 就能跑树莓派4B 的 CPU 可以扛只是慢。这套项目不是实时高清视频流那种而是「检测-比对-出结果」的流水线识别一帧大概 1 秒左右放在门禁演示场景完全够用。对比下来自己用 OpenCV 训练 LBPH 需要收集大量正样本并处理光照归一化效果还不稳定face_recognition 库直接给出人脸框和特征向量后面做相似度用的是欧氏距离原理好讲也好复现。顺带说一句项目包里 FACE_recognition-master 就是 face_recognition 的源码目录如果网络环境不方便从 pip 拉包直接pip3 install ./FACE_recognition-master也能装。答辩时讲清楚这里用的是开源库并且 PPT 里做了标注评审一般不会在这个点上刁难。2.2 编译安装swap 调整、依赖包与两个坑树莓派4B 建议直接装 Raspberry Pi OS64位的完整版或者 Ubuntu Server 22.04。我个人的习惯是用官方系统因为对 CSI 摄像头OV5647支持最顺少折腾驱动。系统装好后先把 apt 源换了再执行下面的依赖安装sudo apt update sudo apt upgrade -y sudo apt install -y build-essential cmake pkg-config \ libopenblas-dev liblapack-dev libjpeg-dev libtiff-dev \ libavcodec-dev libavformat-dev libswscale-dev python3-dev这些包对应 dlib 编译时需要的 BLAS/LAPACK 线性代数库和图像 IO 库。如果少装 libopenblas-dev编译过程中经常在 CMake 阶段直接报错报错信息会提示找不到 OpenBLAS这时候回头把依赖装上重新编就行。依赖装完后先别急着pip3 install dlib树莓派4B 物理内存 4GB但默认 swap 只有 100MBdlib 多线程编译时内存峰值会冲高gcc 进程被系统 OOM 杀掉是常事。解决方法是把 swap 临时调大sudo dphys-swapfile swapoff sudo sed -i s/CONF_SWAPSIZE100/CONF_SWAPSIZE2048/ /etc/dphys-swapfile sudo dphys-swapfile setup sudo dphys-swapfile swaponswapoff先释放旧 swapsed直接改配置setup根据新配置生成 swap 文件swapon重新挂载。改完可以用free -h确认 swap 变成了 2GB。然后开始编译 dlib这一步在 4B 上大约要 40 到 60 分钟期间 CPU 温度会到 80 度左右建议加散热片和风扇否则过热降频会让编译时间翻倍MAKEFLAGS-j2 pip3 install --verbose dlibMAKEFLAGS-j2限制编译线程数为 2减少内存峰值和发热。装完先验证python3 -c import dlib; print(dlib.__version__)能输出版本号再继续。如果这一步被 Killed回到上面检查 swap 是否真的生效。dlib 装好后再装 face_recognition 以及项目要用到的 OpenCV。树莓派上建议用 headless 版不依赖桌面窗口少一层图形库冲突pip3 install face_recognition pip3 install opencv-contrib-python-headless pip3 install picamera[array] numpy这里有个新老环境常踩的坑如果系统是 bookwormpip 默认会装 numpy 2.x而 dlib 老版本编译时用的是 numpy 1.x 接口import 时直接报错。遇到这种情况强制降级pip3 install numpy2然后重装dlib。我在很多机器上遇到过属于最常见的「玄学问题」。另外不要用 apt 里的python3-opencv和 pip 里的 dlib 混用一个走 apt 的 so 库一个走 pip 的 so 库运行 face_reco_from_camera.py 时大概率段错误。统一用 pip 安装的版本少一半兼容性问题。2.3 摄像头选型与初始化OV5647 接入树莓派4B项目资料里默认的是树莓派官方 OV5647 摄像头模块500 万像素接在 CSI 接口上。人脸识别不需要高分辨率640x480 就够OV5647 在这个分辨率下进光量不错。USB 摄像头也能用但驱动方式不同cv2.VideoCapture(0)可能要改成VideoCapture(1)多一个不确定变量不建议一开始就混用。接好排线后系统里默认摄像头是关闭状态需要手动开启sudo raspi-config在 Interface Options 里找到 Camera 或 Legacy Camera按回车启用然后重启。重启之后验证摄像头是否被识别raspistill -o test.jpg ls /dev/video0如果能生成图片说明 CSI 驱动正常。如果/dev/video0不存在OpenCV 的VideoCapture(0)会打不开摄像头需要手动加载 V4L2 驱动模块sudo modprobe bcm2835-v4l2 echo bcm2835-v4l2 | sudo tee -a /etc/modules这是树莓派人脸识别里最常见的摄像头黑屏原因。排线方向不对或没插到底也会造成同样现象但 raspistill 出图时一般不是排线问题就是驱动模块没加载。2.4 use_camera.py 验证摄像头通路环境装完先用项目里的 use_camera.py 验证摄像头到 OpenCV 的通路。这个脚本很短核心就是一个 VideoCapture 循环import cv2 cap cv2.VideoCapture(0) cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640) cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480) print(camera opened:, cap.isOpened()) while True: ret, frame cap.read() if ret: cv2.imshow(camera, frame) key cv2.waitKey(1) 0xFF if key ord(q): break cap.release() cv2.destroyAllWindows()运行python3 use_camera.py窗口能弹出实时画面就说明整条链路 OK。参数上640x480 是速度和安全性折中的选择分辨率再高后面人脸检测耗时会翻倍。如果窗口打开是黑的优先怀疑上面的 bcm2835-v4l2 模块其次是 CSI 排线松紧。3. 核心流程从采集样本到128维特征入库的三个脚本3.1 get_faces_from_camera.py从摄像头批量采集人脸样本人脸识别项目的质量一半由样本质量决定。get_faces_from_camera.py 干的事是打开摄像头检测画面里的人脸把每一帧的人脸区域裁剪成图片存到data/faces_demo/下以姓名命名的子目录里。后面提取特征就是从这些图片里算。import os import cv2 import face_recognition SAVE_DIR data/faces_demo person_name input(请输入人脸ID如 zhang_san: ) person_dir os.path.join(SAVE_DIR, person_name) os.makedirs(person_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 small cv2.resize(frame, (0, 0), fx0.25, fy0.25) rgb_small cv2.cvtColor(small, cv2.COLOR_BGR2RGB) locations face_recognition.face_locations(rgb_small, modelhog) for (top, right, bottom, left) in locations: top, right, bottom, left top*4, right*4, bottom*4, left*4 face_img frame[top:bottom, left:right] if face_img.size 0: continue count 1 path os.path.join(person_dir, f{count:03d}.jpg) cv2.imwrite(path, face_img) cv2.rectangle(frame, (left, top), (right, bottom), (0, 255, 0), 2) cv2.imshow(collect, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()逻辑说明small cv2.resize把原图缩到 1/4是为了让 HOG 检测在树莓派上跑得动face_locations返回的是缩小图坐标所以要乘 4 还原到原图坐标系。裁剪时不要框得太死人脸边缘切掉会严重影响后续特征提取我一般会按检测框再外扩 10 到 15 个像素。每检测到一张脸就存一张count命名的 jpg30 张起步50 张稳妥。参数怎么改fx0.25是检测加速系数改成 0.5 检测更准但更慢count 50是采集总张数做实验可以先设 20 张跑通。采集时人不要一动不动左右转头、轻微上下点头、换一下室内光线样本多样性直接决定后面的识别准确率。这一步偷懒后面识别阶段必定翻车。运行完data/faces_demo/下目录结构是这样data/faces_demo/zhang_san/001.jpg、data/faces_demo/lisi/001.jpg标签就是文件夹名命名规范很重要不要用中文名CSV 文件名和显示名都会直接用文件夹名。3.2 get_features_into_CSV.py提取128维特征并写入CSV样本图片收集完后get_features_into_CSV.py 负责把这些图片变成特征向量。原理是face_recognition.face_encodings把每张人脸图映射成一个 128 维向量同一个人不同照片算出来的向量在欧氏距离上很接近不同人则距离较大。脚本把某个人的所有照片特征取平均得到一个更稳定的「人脸模板」写进 CSV。import os import csv import face_recognition FACES_DIR data/faces_demo CSV_DIR csvs os.makedirs(CSV_DIR, exist_okTrue) for person_name in sorted(os.listdir(FACES_DIR)): person_dir os.path.join(FACES_DIR, person_name) if not os.path.isdir(person_dir): continue encodings [] for img_name in os.listdir(person_dir): img_path os.path.join(person_dir, img_name) image face_recognition.load_image_file(img_path) locations face_recognition.face_locations(image, modelhog) if len(locations) ! 1: continue encoding face_recognition.face_encodings(image, known_face_locationslocations)[0] encodings.append(encoding) if len(encodings) 0: continue avg [sum(col) / len(col) for col in zip(*encodings)] csv_path os.path.join(CSV_DIR, person_name .csv) with open(csv_path, w, newline) as f: writer csv.writer(f) writer.writerow(avg) print(f{person_name}: {len(encodings)} 张已写入 {csv_path})关键细节len(locations) ! 1的判断是必须的。如果一张照片里检测到多人脸[0]取到的可能是别人如果检测不到人脸face_encodings会返回空列表直接索引会报错。所以用这个条件过滤保证入特征库的每张图恰好包含一个人脸。avg [sum(col) / len(col) for col in zip(*encodings)]是特征平均。encodings是若干个 128 维向量的列表zip(*encodings)把每个维度的所有值聚在一起sum再除以样本数得到该维度的均值。平均的好处是抵消单帧噪声比直接拿一张图入库稳得多。写入的 CSV 只有一行、128 个浮点数没有列名。参数说明如果你希望一个人有多个模板比如区分戴眼镜和不戴眼镜的状态那就不要平均把每张图的特征作为单独一行写进同一个 CSV识别时全部加载比对。多模板做法在光线变化大时更有效但 CSV 文件会变大几十倍树莓派加载耗时也上升按需选择。3.3 test_get_face_descriptor.py单张图片验证特征提取在跑完整链路前先用 test_get_face_descriptor.py 确认特征提取这步是通的。脚本输入一张图片输出这张图的人脸数量和 128 维向量相当于给整个流程做一个单元测试。import sys import face_recognition if len(sys.argv) 2: print(用法: python3 test_get_face_descriptor.py 图片路径) sys.exit(1) image face_recognition.load_image_file(sys.argv[1]) encodings face_recognition.face_encodings(image) print(f检测到 {len(encodings)} 张人脸) if encodings: vec encodings[0] print(特征维度:, len(vec)) print(前5个值:, [round(v, 4) for v in vec[:5]])运行python3 test_get_face_descriptor.py data/faces_demo/zhang_san/001.jpg。正常情况下输出「检测到 1 张人脸」和特征维度 128。如果输出 0说明这张图片里的人脸太小、太模糊或者 HOG 没检测到回到 3.1 重新采集。这个脚本还有个用途快速生成单个陌生人的特征临时加入识别库不需要重建整个 CSV。4. 实时识别实战与常见问题排查四个踩坑与阈值调优4.1 face_reco_from_camera.py 识别主流程识别脚本是整个项目的主程序。流程是启动时把 csvs 目录下所有 CSV 加载成已知特征列表然后循环读摄像头帧缩小检测人脸对每张人脸提取 128 维特征和已知特征逐个算 face_distance取最小距离和阈值比较小于阈值就认定为对应的人否则标 unknown。import os import csv import glob import numpy as np import cv2 import face_recognition known_names [] known_encodings [] for csv_file in glob.glob(csvs/*.csv): name os.path.basename(csv_file)[:-4] with open(csv_file, r) as f: reader csv.reader(f) for row in reader: enc np.array([float(x) for x in row], dtypenp.float64) known_names.append(name) known_encodings.append(enc) cap cv2.VideoCapture(0) while True: ret, frame cap.read() if not ret: break small cv2.resize(frame, (0, 0), fx0.25, fy0.25) rgb_small cv2.cvtColor(small, cv2.COLOR_BGR2RGB) locations face_recognition.face_locations(rgb_small, modelhog) encodings face_recognition.face_encodings(rgb_small, locations) for encoding, location in zip(encodings, locations): distances face_recognition.face_distance(known_encodings, encoding) best int(np.argmin(distances)) name known_names[best] if distances[best] 0.5 else unknown top, right, bottom, left [v * 4 for v in location] cv2.rectangle(frame, (left, top), (right, bottom), (0, 255, 0), 2) cv2.putText(frame, name, (left, top - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2) cv2.imshow(face reco, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()几个关键点。CSV 读取时一定要用float(x)转类型CSV 文件里是字符串直接参与 face_distance 计算会报错或者算出错误结果。face_distance内部用的是欧氏距离小于阈值才判定为同一个人阈值 0.5 是 face_recognition 库的默认值实测场景可以往下调。另外encodings和locations是一一对应的zip拉链后循环不会错位。性能上树莓派4B 跑 HOG 检测加 128 维特征提取一帧耗时大约 0.8 到 1.5 秒imshow 会明显卡顿。常见做法是只保留最近一次的识别结果把识别到的名字和距离用日志打印出来窗口卡一点不影响最终结果。如果对帧率有硬要求把输入分辨率降到 640x480或者用 CSI 摄像头专用路径但这套项目的定位是演示级不建议过度优化。4.2 四个高频踩坑记录坑1pip install dlib 编译到一半被杀掉报 Killed现象终端输出里没有报错只有一行 Killed然后进程退出。原因树莓派4B 物理内存够但 swap 默认只有 100MBdlib 多线程编译时内存峰值超过物理内存加 swapOOM 后系统直接 kill 掉 gcc。解决按 2.2 把 swap 调到 2048MB编译时用MAKEFLAGS-j2限制线程数重跑一次。坑2VideoCapture(0) 能打开但读到的画面全黑现象use_camera.py 运行后窗口有画面但全黑或者读帧返回 False。原因摄像头驱动未加载OpenCV 走的是 V4L2 接口而树莓派默认没有生成/dev/video0节点。解决检查ls /dev/video0是否存在不存在就执行sudo modprobe bcm2835-v4l2并把模块写入/etc/modules。如果已经存在还是黑把排线重新插一下金手指要完全插进 CSI 座并扣紧OV5647 排线方向很敏感。坑3识别结果把两个人互相认错现象A 能识别B 也能识别但 A 偶尔被显示成 B。原因特征库样本质量问题比如 B 的照片集中在某一角度或者光线过暗导致特征向量偏移到 A 一侧也可能是阈值 0.5 太宽松。解决先调阈值到 0.4 试试再重新采集样本保证每人的 50 张图里包含正面、左右转头、室内灯光变化采集后重新生成 CSV。另外确认 get_features_into_CSV.py 里没有把含多张脸的图片入库否则特征被污染。坑4运行识别脚本报 AttributeError 或者 Segmentation fault现象import face_recognition 时正常一运行就段错误或 numpy 版本相关报错。原因numpy 2.x 和 dlib 版本不兼容或者系统 apt 装的 OpenCV 和 pip 装的 dlib 混用两者 so 库版本冲突。解决按 2.2 统一 pip 环境强制numpy2后重装 dlib 和 face_recognition如果还不行新建python3 -m venv虚拟环境从零装一遍这个方案能屏蔽掉 90% 的树莓派环境问题。4.3 阈值怎么调face_distance 与误识别边界阈值是这套识别系统最核心的参数。face_distance 距离越小表示越像同一个人同一个人不同照片的距离通常在 0.3 到 0.5 之间不同人一般超过 0.45但受样本质量和光线影响边界是模糊的最终要靠实际数据定。下表是经验区间阈值误识别人数漏识别人数适用场景0.40低会增多门禁、考勤等严格场景0.50中中face_recognition 默认值多数室内场景0.60高低演示场景优先保证认得出来我的做法是先不做太多理论推演在脚本里把每一帧的最小距离打印出来print(fbest distance: {distances[best]:.4f})。收集几十次同一个人正面、侧面、暗光下的距离也记录几个陌生人的距离然后把阈值定在两组数据的中间值附近。比如自测同类最大 0.44异类最小 0.51阈值取 0.47 最稳。这个习惯能省掉大量反复试错的时间。5. 从识别到门禁GPIO舵机扩展与验证方法固化5.1 把实时摄像头改成视频文件识别把 face_reco_from_camera.py 里的cap cv2.VideoCapture(0)换成视频文件路径即可cap cv2.VideoCapture(test.mp4)配合cap.get(cv2.CAP_PROP_FRAME_COUNT)拿总帧数每 10 帧抽 1 帧做识别识别结果写回原帧最后用cv2.VideoWriter输出到新文件。这个改法适合毕业设计里「识别结果演示」的场景不用人一直坐在摄像头前复现起来也稳定。5.2 加一个GPIO舵机模拟门禁开锁识别成功后给 GPIO 一个动作项目就从「识别」变成「门禁」。用一个舵机接树莓派 GPIO18代码里这样写from gpiozero import Servo from time import sleep servo Servo(18) if name ! unknown: servo.max() sleep(2) servo.min()servo.max()让舵机转到开门位置2 秒后回到关闭位置。gpiozero 会自动处理 PWM比直接用 RPi.GPIO 写 PWM 省事。注意舵机电源要单独从 5V 引脚取不能靠 GPIO 引脚供电否则电流不够会让树莓派重启。5.3 验证思路与参数固化我一般留一套固定测试流程同一个人分别在室内灯光、逆光、戴眼镜三种条件下各采集 20 次记录识别成功率和 raw distance调整阈值后再跑一遍确认成功率不掉到 85% 以下。这套项目的 CSV 和脚本结构都简单换人也只需要加一个文件夹、跑一遍两个脚本整个验证半天能完成。从那以后我每次在树莓派上跑人脸识别项目都会先跑 use_camera.py 确认摄像头通路再采集样本、生成 CSV、最后才调识别脚本顺序一旦颠倒问题就分不清是环境还是数据。这个小习惯帮我省了不少时间希望帮到你。本文还有配套的精品资源点击获取