简介：这是一套面向高校学生与Python初学者的计算机视觉实践项目源码，以人脸识别为核心功能，适合用作期末大作业、课程设计或自学练手。项目基于Python与OpenCV实现，涵盖人脸检测、特征提取与识别等典型流程，代码经过严格调试，评审得分在95分以上，可直接运行验证效果。压缩包共130个文件，约22.62MB，其中19个py源码文件承载主要逻辑，41个pyc为编译缓存，35张png与30张jpeg提供界面素材与测试人脸图像，另含sqlite3数据库、pb模型文件及TensorFlow变量分片文件，说明项目已集成训练好的模型权重，无需从零训练即可复现识别效果。目前已有988人学习下载，热度较高。读者可获得完整可运行的项目结构、模型文件与配套素材，便于快速理解人脸识别系统的实现思路，并在此基础上修改功能或撰写实验报告。
1. 从一份 95 分大作业说起：Python+OpenCV 人脸识别到底能跑出什么
期末大作业选题里，人脸识别是常年热门，但真正能拿到 95 分以上的，往往不是调了个库就交差的版本，而是把「检测—对齐—识别—界面」这条链路完整跑通、还能讲清楚每一步为什么这么做。这份基于 Python+OpenCV 的人脸识别系统源码，核心就是用 cv2 做图像采集与预处理，配合人脸检测器定位人脸，再接入识别模型完成身份比对，最后套一层可交互的界面。它解决的是「从摄像头到姓名输出」这一整条落地链路，而不是单点演示。
适合谁看：正在做课程设计、想拿高分的学生；想快速搭一个人脸识别门禁机原型的工程师；以及被ModuleNotFoundError: No module named 'opencv'、cv2.error这类报错卡住、想搞清楚环境到底怎么配的人。下面按「环境能跑 → 检测能准 → 识别能认 → 界面能用 → 坑能填」的顺序拆开讲，每一步都给可抄的命令和参数。
2. 环境搭建与依赖选型：别让 cv2 在第一步就翻车
2.1 为什么是 opencv-contrib-python 而不是 opencv-python
很多人pip install opencv-python之后发现cv2.face这个模块根本不存在，于是报AttributeError: module 'cv2' has no attribute 'face'。原因是标准包opencv-python只包含主模块，人脸相关的cv2.face（LBPH 识别器）、cv2.data（级联分类器路径）这些属于 contrib 扩展，必须装opencv-contrib-python。这是新手最容易踩的第一个坑，也是「python 下载 cv2」这类搜索词背后真正的诉求。
选型上，如果你只是做检测和基础图像处理，opencv-python够用且体积小；一旦涉及人脸识别、SIFT、跟踪算法，直接上 contrib 版本，避免后期反复卸载重装。版本上不建议追最新，OpenCV 4.x 系列里 4.5～4.8 的 API 稳定、教程资料多，和 Python 3.8～3.11 兼容性好。Python 版本别用太新的（比如 3.12 早期），部分 contrib 轮子还没跟上，容易在编译阶段卡住。
2.2 一条命令装齐依赖与验证
# 建议先建虚拟环境，避免污染全局 python -m venv face_env # Windows 激活 face_env\Scripts\activate # Linux / macOS 激活 source face_env/bin/activate # 装 contrib 版本，指定较稳的版本区间 pip install opencv-contrib-python==4.8.0.76 pip install numpy==1.24.3 pip install pillow # 验证是否装对 python -c "import cv2; print(cv2.__version__); print(hasattr(cv2, 'face'))"逻辑说明：虚拟环境隔离是为了避免和系统里已有的 opencv 冲突，尤其是 Ubuntu 上用 apt 装过python3-opencv的机器，全局和虚拟环境两套 cv2 混用会出玄学问题。hasattr(cv2, 'face')返回True才说明 contrib 装对了。numpy 锁 1.24 是因为更高版本在某些 OpenCV 轮子上会触发 ABI 不兼容的警告甚至崩溃。
参数说明：opencv-contrib-python==4.8.0.76里的4.8.0是 OpenCV 版本，.76是构建号，不同构建号对应不同 Python 版本轮子，装错会提示找不到匹配版本，这时换4.7.0.72或4.6.0.66试。如果你在 Ubuntu 上遇到cv2.error: OpenCV(4.4.0) ... pip-req-build这类路径报错，基本是系统里旧版和 pip 版打架，先pip uninstall opencv-python opencv-contrib-python清干净再重装。
提示：装完先跑一遍上面的验证命令，确认
cv2.face存在再往下走，能省掉后面一半的排查时间。
3. 人脸检测：Haar 还是 DNN，级联分类器怎么调才不飘
3.1 检测器选型：Haar 级联与 DNN 的取舍
OpenCV 自带的人脸检测主流有两条路。一是 Haar 级联分类器，靠cv2.CascadeClassifier加载haarcascade_frontalface_default.xml，优点是零额外模型文件、CPU 上飞快、代码三行搞定；缺点是侧脸、遮挡、暗光下漏检明显，误检率也高。二是 DNN 模块加载 Caffe 或 ONNX 的人脸检测模型（如 res10_300x300），精度高很多，代价是要额外下载模型文件、推理稍慢。
课程大作业场景，我一般建议：先用 Haar 把整条链路跑通，保证能出结果；如果评分对准确率有要求，再换 DNN 检测器。两者接口不同但下游识别逻辑一致，替换成本低。cv2.data.haarcascades这个路径变量能直接定位到 OpenCV 自带的分类器目录，省得你手动找 xml 文件。
3.2 检测代码与三个必调参数
import cv2 # 加载 OpenCV 自带的正脸级联分类器 face_cascade = cv2.CascadeClassifier( cv2.data.haarcascades + 'haarcascade_frontalface_default.xml' ) def detect_faces(frame): # 转灰度：Haar 只吃单通道，能提速约 3 倍 gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) # 直方图均衡化，缓解暗光下漏检 gray = cv2.equalizeHist(gray) faces = face_cascade.detectMultiScale( gray, scaleFactor=1.1, # 每次缩放比例，越小越慢越准 minNeighbors=5, # 邻域阈值，越大越严越少误检 minSize=(60, 60) # 最小人脸尺寸，过滤噪点 ) return faces cap = cv2.VideoCapture(0) while True: ret, frame = cap.read() if not ret: break for (x, y, w, h) in detect_faces(frame): cv2.rectangle(frame, (x, y), (x + w, y + h), (0, 255, 0), 2) cv2.imshow('face', frame) if cv2.waitKey(1) & 0xFF == ord('q'): break cap.release() cv2.destroyAllWindows()逻辑说明：先转灰度再检测是 Haar 的硬性要求，彩色图直接喂进去会报错或结果异常。equalizeHist做直方图均衡，对背光、室内弱光场景提升明显，是很多人忽略的一步。detectMultiScale返回的是(x, y, w, h)列表，可能为空，画框前不用判断长度，for 循环天然处理空列表。
参数说明：scaleFactor控制图像金字塔每次缩小的比例，1.1 是精度和速度的平衡点，调到 1.05 更准但更慢，1.3 快但容易漏小脸。minNeighbors决定一个候选框周围要有多少个邻居才被保留，默认 3 误检多，5 是常用值，8 以上会开始漏检。minSize一定要设，否则背景纹理会被当成脸，这是「检测框乱飘」最常见的原因。
3.3 检测阶段的两个典型现象
第一个是「框在抖」。视频流里每帧独立检测，人脸稍微一动框就跳，看起来像玄学。解决办法是对检测结果做简单平滑，比如缓存上一帧的框，和当前框做加权平均，或者降低检测频率（每 3 帧检测一次，中间帧沿用上次结果）。第二个是「多人只检到一个」。Haar 对并排人脸的处理依赖minNeighbors，人挨太近时邻居数不够会被合并，适当调低到 4 并配合minSize能缓解。
4. 人脸识别：LBPH 训练、阈值判定与数据采集规范
4.1 识别方案选型：LBPH 与 ArcFace 的边界
OpenCV contrib 里现成能用的是cv2.face.LBPHFaceRecognizer，它基于局部二值模式直方图，优点是训练快、样本需求少（每人 10～20 张就够）、不需要 GPU，非常适合大作业。缺点是跨姿态、跨光照的泛化一般，人脸库一大准确率就掉。工业级方案会用 ArcFace、FaceNet 这类深度模型，精度高但需要额外依赖（如 insightface、onnxruntime）和更多样本。
对期末大作业，LBPH 是性价比最高的选择：代码量小、可解释性强、答辩时能讲清楚原理。如果你想让系统更「高级」，可以在检测阶段用 DNN、识别阶段仍用 LBPH，兼顾精度和实现成本。easyai 人脸识别这类封装库虽然上手快，但黑匣子属性强，答辩被问原理容易卡壳，不太建议直接用。
4.2 数据采集与训练脚本
import cv2 import os import numpy as np # 采集：每人一个 id，存 30 张灰度人脸 def collect(user_id, save_dir='dataset', count=30): os.makedirs(save_dir, exist_ok=True) cascade = cv2.CascadeClassifier( cv2.data.haarcascades + 'haarcascade_frontalface_default.xml') cap = cv2.VideoCapture(0) saved = 0 while saved < count: ret, frame = cap.read() if not ret: break gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces = cascade.detectMultiScale(gray, 1.1, 5, minSize=(80, 80)) for (x, y, w, h) in faces: saved += 1 # 统一缩放到 200x200，保证训练输入一致 face = cv2.resize(gray[y:y+h, x:x+w], (200, 200)) cv2.imwrite(f'{save_dir}/user_{user_id}_{saved}.jpg', face) cv2.rectangle(frame, (x, y), (x+w, y+h), (0, 255, 0), 2) cv2.imshow('collect', frame) if cv2.waitKey(1) & 0xFF == ord('q'): break cap.release() cv2.destroyAllWindows() # 训练：读数据集，训练 LBPH，保存模型 def train(save_dir='dataset', model_path='trainer.yml'): recognizer = cv2.face.LBPHFaceRecognizer_create() faces, ids = [], [] for fname in os.listdir(save_dir): if not fname.endswith('.jpg'): continue img = cv2.imread(os.path.join(save_dir, fname), cv2.IMREAD_GRAYSCALE) uid = int(fname.split('_')[1]) faces.append(img) ids.append(uid) recognizer.train(faces, np.array(ids)) recognizer.save(model_path) print(f'trained on {len(set(ids))} people, {len(faces)} images') collect(user_id=1) train()逻辑说明：采集阶段把每张人脸统一 resize 到 200x200，是因为 LBPH 虽然对尺寸不敏感，但统一尺寸能让直方图分布更稳定，识别率更可复现。文件名里带user_id是为了训练时能反解标签，命名规范一旦定下就别改，否则训练脚本解析会出错。训练时ids必须是 numpy 数组，传 list 会报类型错误。
参数说明：count=30是每人样本数，10 张能跑但容易过拟合，30 张是精度和采集时间的平衡点。minSize=(80, 80)比检测阶段调大，是为了保证采集到的人脸有足够像素，太小的脸训练出来没意义。LBPHFaceRecognizer_create()可以传radius、neighbors、grid_x、grid_y参数，默认值 1、8、8、8 对多数场景够用，样本少时可把grid_x/grid_y调到 6 减少特征维度。
4.3 识别阈值：confidence 到底怎么判
recognizer = cv2.face.LBPHFaceRecognizer_create() recognizer.read('trainer.yml') # 识别时 confidence 越小越可信，不是概率 id_, confidence = recognizer.predict(gray_face) if confidence < 70: name = names[id_] # 认定为已知用户 else: name = 'unknown' # 超过阈值判为陌生人逻辑说明：LBPH 的predict返回的confidence是距离度量，越小表示越像，这和一般分类器的概率正好相反，很多人第一次用会搞反。阈值没有统一标准，取决于你的数据集，常见区间是 50～80。设太低会把本人判成陌生人，设太高会把陌生人认成已知用户。
参数说明：建议先用一批已知人脸和一批陌生人脸各跑一遍，统计两类 confidence 的分布，取中间值作为阈值。如果两类重叠严重，说明样本质量或数量不够，回去补采集，别硬调阈值。names字典要和训练时的 id 对应，id 从 1 开始还是 0 开始要统一，否则会出现「认对人但显示错名字」的诡异现象。
5. 避坑与排查：那些让大作业从 95 掉到 60 的细节
5.1 摄像头打不开或画面全黑
现象：cap.read()一直返回False，或者窗口全黑。原因通常是摄像头被其他程序占用（比如刚关掉的预览窗口没释放），或者VideoCapture(0)的索引不对（多摄像头机器上内置摄像头可能是 1）。解决：先确认没有其他程序占用，再依次试VideoCapture(0)、VideoCapture(1)；Linux 上还要检查当前用户是否在video组里，不在的话sudo usermod -aG video $USER后重新登录。
5.2 训练时报标签类型错误
现象：recognizer.train(faces, ids)抛TypeError或断言失败。原因是ids传了 Python list，OpenCV 的 Python 绑定要求 numpy 数组且类型为 int32。解决：ids = np.array(ids, dtype='int32')。这个坑在样本少时不一定触发，样本一多就暴露，属于典型的「小数据能跑、大数据翻车」。
5.3 识别结果在两个人之间反复横跳
现象：同一个人站在摄像头前，名字一会儿对一会儿错。原因是 LBPH 对光照和角度敏感，加上阈值卡在两类分布的重叠区。解决：采集时尽量覆盖不同角度和光照（但别太极端），识别时对连续多帧结果做投票，取出现次数最多的名字，而不是每帧独立判定。这个「多帧投票」是让演示稳定的关键技巧。
5.4 中文路径导致 imread 返回 None
现象：cv2.imread读一张明明存在的图却返回None，后续resize报错。原因是 OpenCV 的imread在 Windows 上对中文路径支持不好。解决：用cv2.imdecode(np.fromfile(path, dtype=np.uint8), cv2.IMREAD_GRAYSCALE)替代，或者干脆把数据集目录和文件名全用英文数字。这是血泪经验，答辩前一天才发现数据集读不进去，后悔药都没得吃。
5.5 打包成 exe 后模型文件找不到
现象：源码里跑得好好的，用 PyInstaller 打包后提示trainer.yml或级联 xml 找不到。原因是打包后工作目录变了，相对路径失效。解决：用sys._MEIPASS定位资源目录，把模型和 xml 作为--add-data打进去，代码里统一走一个resource_path()函数拼接路径。这个坑不做打包不会遇到，一旦要做可执行文件交付就必须处理。
6. 从能跑到好用：界面封装与识别稳定性的进阶技巧
把命令行版本变成能拿高分的系统，界面是加分项但不是核心，核心是识别稳定性。我一般用 Tkinter 或 PyQt 套一层，左边显示摄像头画面，右边显示识别结果和置信度，再加个「录入新用户」按钮调用采集函数。界面本身不难，难的是别让界面线程和摄像头读取线程互相阻塞——常见做法是摄像头读取放独立线程，通过队列把帧传给主线程渲染，否则界面会卡成幻灯片。
稳定性上，除了前面说的多帧投票，还有两个实用技巧。一是识别前做一次人脸对齐：用眼睛检测器定位双眼，计算旋转角度把脸摆正，LBPH 对正脸最敏感，对齐后准确率能明显提升。二是动态阈值：对每个已注册用户单独统计其历史 confidence 均值，识别时用「均值 + 标准差」作为该用户的判定阈值，比全局固定阈值更贴合个体差异。
| 技巧 | 作用 | 实现成本 |
|---|---|---|
| 多帧投票 | 消除单帧误判抖动 | 低，缓存最近 N 帧结果 |
| 人眼对齐 | 提升跨姿态识别率 | 中，需额外眼睛检测器 |
| 动态阈值 | 适配不同用户特征差异 | 中，需记录历史 confidence |
| 直方图均衡 | 缓解暗光漏检 | 低，一行代码 |
验证方法很简单：找 3～5 个人，每人录 30 张，再让每个人在不同光照、不同距离下各测 20 次，统计正确率和误识率。正确率低于 85% 就回去补样本或调阈值，别急着加功能。我自己的习惯是每改一次参数就重跑一遍这套测试，把结果记在表格里，避免「感觉变好了」这种主观判断——玄学调参最后一定会反噬。
这套方案从环境到识别再到界面，完整跑通大概两三天，难点不在写代码，而在采集规范、阈值判定和那几个路径坑。把检测和识别分开调、每步都验证，比一口气写完再 debug 高效得多。希望帮到你。
本文还有配套的精品资源，点击获取
