简介这是一套基于机器学习的人脸识别系统Python源码及配套报告文档主要面向需要完成期末大作业或课程设计的高校学生也适合Python初学者参考进阶。项目功能完善、界面友好含详尽代码注释与设计报告下载后简单部署即可运行降低了二次开发门槛。压缩包共4个文件包括2个Python程序文件主程序与分类模块、1份PDF版大作业报告和1个Markdown说明文档整包大小仅631KB结构紧凑便于学习与提交。已有283人查看学习其内容覆盖人脸检测、特征提取、模型训练与识别流程配套报告对各模块设计思路和测试结果进行了梳理能帮助读者快速掌握项目全貌也可作为答辩讲解的重要参考具备很高的课程设计完成度与实际应用价值。1. 人脸识别期末大作业先想清楚你拿到的是一个完整的交付物一门课程的期末大作业评分点往往不在模型 acc 多高而在这套系统能否讲清原理、跑通流程、兜住边界。市面上流传的基于机器学习的人脸识别系统源码报告文档.zip拆开看基本是四样东西人脸检测模块、特征提取与分类器、训练和识别脚本、一份能直接改名字交上去的报告文档。你要做的不是找一个能跑的 demo 复制粘贴而是把这条链路里的每一步解释清楚并且有能力回答老师随手提出的为什么用 LBPH 不用 CNN阈值为什么设 80这类问题。这篇博文的路线是先讲人脸识别系统的技术选型与核心原理然后用 OpenCV 把人脸采集、训练、预测的完整流程跑通再落到期末交付需要的评估指标、报告文档结构和 ZIP 打包规范最后给三个真正影响评分和运行的调优技巧。适合课程任务在 2 周内、需要快速理解并独立复现的同学也适合想把这套老牌方案讲清楚的一线工程师。2. 机器学习人脸识别的技术选型从检测、特征到分类器2.1 人脸识别系统的完整链路人脸识别看似是一个输入图片、输出姓名的端到端问题工程上却要拆成三个独立环节人脸检测、人脸特征提取、人脸分类。期末作业最常见的翻车点是把三个环节混在一个脚本里结果检测框画出来了分类准确率却一塌糊涂最后只能靠调阈值硬撑。检测环节解决脸在哪里。OpenCV 的 Haar Cascade 和 dlib 的 HOG 检测器是两种典型实现前者靠 AdaBoost 级联弱分类器后者靠梯度直方图加线性分类器扫描窗口。特征提取环节解决这张脸长什么样。机器学习时代常用的不是深度学习 embedding而是 LBPHLocal Binary Pattern Histogram局部二值模式直方图——它把图像分成若干格子对每个像素与邻域比较产生二值编码统计直方图作为特征向量。分类环节解决这个特征属于谁。常见做法是支撑向量机、K 近邻或者直接使用 LBPH 自带的距离度量后者的实现更轻适合课程作业。我在给这类项目做评审时第一眼看的不是代码有没有跑通而是作者有没有把三个环节在文档里画清楚。很多同学把人脸检测写成人脸识别把分类器写成神经网络导致文档前后不一致这是最冤枉的扣分点。2.2 为什么期末项目常用 LBPH 而不是 CNN卷积神经网络在 LFW 数据集上早就是 99% 以上的准确率为什么期末大作业还要用老掉牙的 LBPH原因很直接CNN 方案需要的训练数据量、标注成本和调参周期2 周内很难走完一遍。用 MobileNet 微调至少需要几百张到上千张不同人的照片才能保证不严重过拟合而 LBPH 每人给 10-20 张正面照在一台普通笔记本上几秒钟就能完成训练识别速度也完全够用。从评分角度讲期末报告要展示的是你理解了什么而非砸了多少算力。LBPH 的可解释性极强你能在报告中贴出某人的直方图长什么样能解释 radius 和 neighbors 对纹理粗粒度的影响能画出 confidence 得分的分布曲线。这些内容放到深度学习方案里就变成了loss 降了acc 升了答辩时容易被追问到无法收场。不过需要注意如果课程名称里有深度学习或神经网络字样LBPH 就不够贴题了这时建议保留人脸检测用 Haar替换分类器为一个小型 CNN 或 MLP代码量增加不大但技术路线与课程要求对齐。2.3 开源组件选型与依赖关系组件作用推荐选型说明人脸检测在图像中定位人脸框OpenCV Haar Cascadecv2.data.haarcascades自带模型无需额外下载特征提取将人脸转为特征向量LBPHOpenCV contribcv2.face.LBPHFaceRecognizer_create()分类器将特征向量映射为 IDOpenCV FaceRecognizer自带 predict 接口与置信度输出图像处理灰度化、尺寸归一化OpenCV 基础库不用额外安装 dlib数据集管理组织不同人的照片本地目录结构每人一个子目录目录名即标签依赖组件唯一的坑是 OpenCV 版本。LBPH 相关接口在opencv-contrib-python包里如果你只安装了opencv-python调用cv2.face会直接报AttributeError: module cv2 has no attribute face。我在实际环境中踩过这个坑解决办法是统一安装 contrib 版本并且不要再装回非 contrib 版两个包同时存在会导致 Python 加载混乱。3. 用 Python 把人脸识别系统跑起来环境、采集、训练与预测3.1 搭建 Python 与 OpenCV 运行环境期末项目最忌讳的是在我电脑上能跑换台电脑就报错。建议从一开始就用虚拟环境固定依赖版本并在报告文档里写清 Python 版本与依赖列表。# Python 3.9 及以上版本均可 python -m venv face_env source face_env/bin/activate # Windows 下为 face_env\Scripts\activate pip install opencv-contrib-python4.8.1.78 pip install numpy matplotlib scikit-learn代码逻辑说明第一行创建独立虚拟环境避免污染全局 Python。后续所有依赖装在这个环境里打包时只需要把环境目录从项目结构里剔除即可。固定opencv-contrib-python版本号是为了防止最新版接口变动导致课程代码执行到一半报错。参数说明opencv-contrib-python是带扩展模块的 OpenCVcv2.face、cv2.xphoto等模块都在里面。如果你的pip install opencv-python已经装过务必先卸载两个包并存时import cv2可能会指向错误版本。3.2 人脸采集与数据集目录组织训练一个能识别的人脸分类器第一步是准备每个人的样本。标准结构是主目录下按人分文件夹文件夹名用学号或姓名拼音内部放该人的多张人脸图片。dataset/ ├── zhangsan/ │ ├── 001.jpg │ ├── 002.jpg │ └── 003.jpg ├── lisi/ │ ├── 001.jpg │ └── 002.jpg └── wangwu/ ├── 001.jpg └── 002.jpg采集脚本的核心逻辑是用 Haar 检测器在摄像头画面中找到人脸把脸部区域裁剪后统一缩放到 200x200 像素灰度图保存。import cv2 import os cascade_path cv2.data.haarcascades haarcascade_frontalface_default.xml face_cascade cv2.CascadeClassifier(cascade_path) person_name input(输入姓名用作文件夹名) save_dir os.path.join(dataset, person_name) os.makedirs(save_dir, exist_okTrue) cap cv2.VideoCapture(0) count 0 while count 20: # 每人采集 20 张 ret, frame cap.read() if not ret: break gray cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces face_cascade.detectMultiScale(gray, scaleFactor1.1, minNeighbors5, minSize(100, 100)) for (x, y, w, h) in faces: face_roi gray[y:yh, x:xw] face_resized cv2.resize(face_roi, (200, 200)) cv2.imwrite(os.path.join(save_dir, f{count:03d}.jpg), face_resized) count 1 # 在画面中框出人脸方便确认角度 for (x, y, w, h) in faces: cv2.rectangle(frame, (x, y), (xw, yh), (0, 255, 0), 2) cv2.imshow(collect, frame) if cv2.waitKey(100) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()代码逻辑说明detectMultiScale返回所有人脸框的坐标、宽高循环里把每个框对应的灰度区域裁剪出来resize统一尺寸后写入硬盘。采集 20 张的目的是覆盖不同角度和表情变化太少会导致 LBPH 对光照过于敏感。关键参数说明scaleFactor1.1表示检测窗口每次缩小 10%值越小检测越慢但更精确minNeighbors5表示一个区域至少被 5 个相邻窗口确认才算人脸值越大漏检越多但误检越少minSize(100, 100)忽略小于该尺寸的候选框避免把远处的人或噪声算进来。建议提醒采集对象轻微转头、变换光照方向不要始终正对摄像头不动否则训练集里的变化不足识别阶段换个角度就崩。3.3 训练 LBPH 分类器的最小代码训练阶段需要读入所有子目录的图片将文件夹名映射为整数标签然后调用 LBPH 的 train 方法。import cv2 import os import numpy as np dataset_dir dataset images [] labels [] label_map {} # 记录标签数字到姓名的映射 current_label 0 for person_name in os.listdir(dataset_dir): person_dir os.path.join(dataset_dir, person_name) if not os.path.isdir(person_dir): continue label_map[current_label] person_name for file_name in os.listdir(person_dir): if not file_name.lower().endswith((.jpg, .png, .jpeg)): continue img_path os.path.join(person_dir, file_name) img cv2.imread(img_path, cv2.IMREAD_GRAYSCALE) images.append(img) labels.append(current_label) current_label 1 recognizer cv2.face.LBPHFaceRecognizer_create(radius1, neighbors8, grid_x8, grid_y8) recognizer.train(images, np.array(labels)) recognizer.save(face_model.yml) print(训练完成模型已保存为 face_model.yml)代码逻辑说明os.listdir按目录读取所有样本label_map维护数字标签与姓名的对应关系因为 LBPH 只接受连续的整数标签。recognizer.save把训练结果写到磁盘识别阶段直接加载。LBPH 核心参数表参数默认值推荐值影响radius11 或 2邻域半径越大对低频纹理越敏感但过大会模糊个体差异neighbors88邻域采样点数8 对应二进制编码的 256 种模式grid_x88图像水平分块数分块越多空间信息越细grid_y88图像垂直分块数与 grid_x 共同决定特征向量维度需要注意grid_x和grid_y增大时直方图拼接后的特征维度会显著提升训练集样本数不变的情况下容易过拟合。我一般建议课程作业直接保留默认值除非识别效果明显差再调整为grid_x12, grid_y12。3.4 实时识别与置信度阈值设定识别阶段加载模型对摄像头画面中检测到的每张人脸调用predict方法得到预测标签和置信度。置信度越低表示匹配度越高OpenCV 内部采用了某种距离度量具体阈值需要根据实验调整不要不加判断地使用文档示例。import cv2 recognizer cv2.face.LBPHFaceRecognizer_create() recognizer.read(face_model.yml) label_map {0: zhangsan, 1: lisi, 2: wangwu} # 训练时保存的映射实际应从文件中读取 confidence_threshold 80 cascade_path cv2.data.haarcascades haarcascade_frontalface_default.xml face_cascade cv2.CascadeClassifier(cascade_path) 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, scaleFactor1.1, minNeighbors5, minSize(100, 100)) for (x, y, w, h) in faces: face_roi gray[y:yh, x:xw] face_resized cv2.resize(face_roi, (200, 200)) label, confidence recognizer.predict(face_resized) name label_map.get(label, unknown) if confidence confidence_threshold: name unknown cv2.rectangle(frame, (x, y), (xw, yh), (0, 255, 0), 2) cv2.putText(frame, f{name} ({confidence:.0f}), (x, y-10), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2) cv2.imshow(face recognition, frame) if cv2.waitKey(100) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()代码逻辑说明predict返回的confidence与阈值比较决定是否显示为 unknown这是处理陌生人脸的关键防线。实际测试中同一人在不同光照下的置信度波动可达 20-30所以 80 只是一个起点要收集多组数据画出置信度分布后再定。这里有一个常见的认识误区confidence数值越大代表越不相似不同版本的 OpenCV 内部计算方式略有差异。如果发现阈值需要设到 130 以上才有反应建议先回头检查训练图片是否包含过多背景而不是盲目上调阈值。4. 面向期末交付评估指标、报告文档与 ZIP 打包的注意点4.1 模型评估准确率、混淆矩阵与交叉验证课程报告里只写一句经过测试系统识别准确率达到 95%是不够的评审老师会追问95% 是在什么数据集上测的测试集和训练集是否重叠每个人测试多少张。一个严谨的评估流程应该包含三个部分。留出法评估是最简单的操作每个目录下随机取 80% 作为训练集20% 作为测试集训练后统计整体准确率。代码思路是读取所有样本路径用sklearn.model_selection.train_test_split按人分组切分而不是直接对图片列表乱序切割否则同一个人的照片会同时出现在训练集和测试集里准确率虚高。混淆矩阵能看到更细粒度的问题两个人互相混淆往往说明光照角度差异大、样本数量不均对角线上的值普遍偏低说明特征提取参数有问题。绘制混淆矩阵用 scikit-learn 的三行代码即可重要的是把测试流程封装成独立脚本evaluate.py让它输出准确率、混淆矩阵和每类的准确率清单这份统计结果可以直接粘贴到报告文档。交叉验证对课程作业属于加分项不必强求。如果要做建议用StratifiedKFold按类别分层否则随机划分可能让某一类样本全部落在验证集。4.2 报告文档的结构与内容建议报告文档是期末大作业的评分主体代码只是佐证。一份能拿高分的报告不是把代码注释抄一遍而是让读者在不看代码的情况下理解你的设计思路、实现过程和实验结果。推荐结构章节内容要点篇幅建议引言人脸识别应用背景、课程目标、系统整体功能描述1-2 页系统设计整体架构图检测-特征-分类、开发环境与依赖版本、模块划分2-3 页核心原理人脸检测原理Haar 级联、LBPH 原理局部二值模式与直方图、为什么要用机器学习分类器3-4 页实现过程数据集采集方案、训练代码关键片段、识别流程描述3-5 页实验结果准确率统计、混淆矩阵、不同参数下的对比实验、失败案例分析2-3 页总结与展望系统优点、不足、可能的改进方向1 页写文档时几个容易踩的坑一是总结与展望写得太假动辄深度学习将极大提升准确率却没有对应实验二是不写环境版本导致别人无法复现三是图片不编号不引用正文和图表脱节。注意不要编造实验数据基础不牢的时候宁可只测 10 个人也不要编造 99% 的准确率。4.3 把源码与报告打成结构清晰的 ZIP 包期末作业提交的 ZIP 包评阅者的体验直接影响印象分。一个结构清晰的打包目录应该是这样的人脸识别系统_学号_姓名.zip ├── code/ │ ├── collect_face.py # 数据采集脚本 │ ├── train_model.py # 模型训练脚本 │ ├── recognize.py # 实时识别脚本 │ ├── evaluate.py # 模型评估脚本 │ └── requirements.txt # 依赖列表 ├── dataset/ # 训练用数据集如果太大可放到网盘文档内注明 ├── model/ │ └── face_model.yml # 训练好的模型 ├── docs/ │ ├── 实验数据.xlsx │ └── 人脸识别系统报告.docx └── README.md # 运行说明环境配置、命令、注意事项打包时注意排除虚拟环境目录和临时文件。__pycache__、.idea、.vscode这类文件不仅没用还会让评阅者觉得你缺乏工程意识。python -m zipfile -c 人脸识别系统_学号_姓名.zip code dataset model docs README.md命令说明python -m zipfile -c是标准库提供的打包命令参数依次是压缩包名和待打包目录/文件。用这套命令的好处是不需要安装额外工具Windows、macOS、Linux 下表现一致。解压方用unzip或双击即可保持 ZIP 格式不变不要用 RAR 或 7z 格式兼容性更好。文档里还要写清楚如何运行从安装 Python、创建虚拟环境、安装依赖到执行三条命令的完整步骤并注明摄像头编号。很多同学代码写得很好但 README 里只写了一句运行 recognize.py导致评阅者卡在第一步。5. 提交前值得做的 3 个调优技巧与排错路径5.1 光照鲁棒性的通用处理LBPH 对光照极其敏感这是它的已知短板。最便宜的解决办法是在采集和识别两端都做直方图均衡化让图像的灰度分布尽量一致再做识别。加一行命令即可实现# 在采集和训练、识别三个环节统一使用 face_resized cv2.equalizeHist(face_resized)如果均衡化后效果仍不理想可尝试在训练数据中混入高斯噪声或轻微旋转模拟不同环境下的变化。注意cv2.equalizeHist只接受单通道灰度图彩色图需先转换为灰度再均衡化。5.2 置信度阈值与多帧投票的协同单人识别时视频流中某一帧的噪声可能导致瞬间误判。我常用的处理是连续采样 5 帧取出现次数最多的身份作为最终结果同时计算这 5 帧的平均置信度只有当平均置信度低于阈值才输出对应姓名。这个方案既抑制了偶发误判也减少了阈值调优的难度。阈值设定的通用方法针对每个人测 20 帧记录置信度均值和标准差同一个人的置信度均值加上两倍标准差作为该人的个性化阈值陌生人可以直接设为统一值。课程作业不需要做得这么细但报告里如果能放出置信度分布图会让答辩更有说服力。5.3 后端运行报错的常见分支module cv2 has no attribute face是出现频率最高的问题原因是安装的是opencv-python而非opencv-contrib-python或者两个包同时存在。排查命令是pip list | grep opencv卸载非 contrib 包重启解释器。cv2.VideoCapture(0)返回False或画面黑屏摄像头被占用是常见原因关闭 Zoom、腾讯会议里对摄像头的占用后重试。还有一类问题是虚拟机或远程服务器没有摄像头设备需要先用lsusb确认设备存在。detectMultiScale检测不到人脸时优先检查minSize是否过大、图片是否过小、目标人脸是否过于模糊。最后把训练好的face_model.yml和数据集一起打包提交前先换一台电脑完整跑一遍recognize.py确认没有依赖当前机器的路径或硬件。很多课程答辩淘汰不是因为模型不好而是因为现场环境起不来。这套从环境固定、数据集组织到评估打包的流程就是期末项目最常见的工程化交付路径。本文还有配套的精品资源点击获取