基于OpenCV与LBPH的机器学习人脸识别期末项目实践指南

简介：这是一套基于机器学习的人脸识别系统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，而是 LBPH（Local 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 版本。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-python==4.8.1.78 pip install numpy matplotlib scikit-learn

代码逻辑说明：第一行创建独立虚拟环境，避免污染全局 Python。后续所有依赖装在这个环境里，打包时只需要把环境目录从项目结构里剔除即可。固定opencv-contrib-python版本号，是为了防止最新版接口变动导致课程代码执行到一半报错。

参数说明：opencv-contrib-python是带扩展模块的 OpenCV，cv2.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_ok=True) 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, scaleFactor=1.1, minNeighbors=5, minSize=(100, 100)) for (x, y, w, h) in faces: face_roi = gray[y:y+h, x:x+w] 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), (x+w, y+h), (0, 255, 0), 2) cv2.imshow("collect", frame) if cv2.waitKey(100) & 0xFF == ord('q'): break cap.release() cv2.destroyAllWindows()

代码逻辑说明：detectMultiScale返回所有人脸框的坐标、宽高，循环里把每个框对应的灰度区域裁剪出来，resize统一尺寸后写入硬盘。采集 20 张的目的是覆盖不同角度和表情变化，太少会导致 LBPH 对光照过于敏感。

关键参数说明：scaleFactor=1.1表示检测窗口每次缩小 10%，值越小检测越慢但更精确；minNeighbors=5表示一个区域至少被 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(radius=1, neighbors=8, grid_x=8, grid_y=8) recognizer.train(images, np.array(labels)) recognizer.save("face_model.yml") print("训练完成，模型已保存为 face_model.yml")

代码逻辑说明：os.listdir按目录读取所有样本，label_map维护数字标签与姓名的对应关系，因为 LBPH 只接受连续的整数标签。recognizer.save把训练结果写到磁盘，识别阶段直接加载。

LBPH 核心参数表：

需要注意，grid_x和grid_y增大时，直方图拼接后的特征维度会显著提升，训练集样本数不变的情况下容易过拟合。我一般建议课程作业直接保留默认值，除非识别效果明显差再调整为grid_x=12, grid_y=12。

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, scaleFactor=1.1, minNeighbors=5, minSize=(100, 100)) for (x, y, w, h) in faces: face_roi = gray[y:y+h, x:x+w] 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), (x+w, y+h), (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 报告文档的结构与内容建议

报告文档是期末大作业的评分主体，代码只是佐证。一份能拿高分的报告，不是把代码注释抄一遍，而是让读者在不看代码的情况下理解你的设计思路、实现过程和实验结果。

推荐结构：

写文档时几个容易踩的坑：一是"总结与展望"写得太假，动辄"深度学习将极大提升准确率"，却没有对应实验；二是不写环境版本，导致别人无法复现；三是图片不编号不引用，正文和图表脱节。注意不要编造实验数据，基础不牢的时候宁可只测 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，确认没有依赖当前机器的路径或硬件。很多课程答辩淘汰，不是因为模型不好，而是因为现场环境起不来。这套从环境固定、数据集组织到评估打包的流程，就是期末项目最常见的工程化交付路径。

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