简介：面向Python与OpenCV初学者及人脸识别应用开发者，这份源码包提供一个可直接参考的轻量级人脸识别系统。包内共14个文件，涵盖主程序、配置文件、说明文档、10个识别器模型（yml）以及1个Haar级联分类器（xml），结构分层清晰：配置入口可调整识别参数，说明文档辅助理解调用流程，已生成的模型文件则能直接参与识别。整体压缩包仅148KB，部署成本低，适合快速在本地环境运行验证。目前已有1082人学习下载，适合作为课程设计、算法演示或二次开发的基础模板。通过阅读与运行源码，读者可以掌握OpenCV人脸检测与识别的实现思路、模型文件与级联分类器的配合方式，以及从配置加载到输出结果的完整项目组织方法。
1. 从零跑通人脸识别：这套 OpenCV 源码包值得直接落地
拿到压缩包的人，大多数是想在最短时间内跑通一套能用的完整人脸识别流程，而不是从卷积网络开始啃论文。这套 Python 基于 OpenCV 的人脸识别系统源码，走的是传统视觉最稳的路线：Haar 级联负责检测人脸，LBPH 负责身份比对，config.txt 管参数、main.py 跑主循环，1.yml 到 10.yml 是预训练好的十人模型，haarcascade_frontalface_default.xml 是官方正脸检测器。它不依赖 GPU，普通笔记本摄像头就能跑，适合课程设计、毕设二开和门禁 Demo 起步。接下来先把文件结构和原理拆开讲清楚，再带你跑通 main.py，最后把采集、训练、调阈值这一套补成完整闭环。
2. 核心原理与文件拆解：Haar 检测、LBPH 识别与 config.txt 的配置逻辑
2.1 Haar 级联：haarcascade_frontalface_default.xml 是怎么把人脸框出来的
先看检测层。haarcascade_frontalface_default.xml 是 OpenCV 官方训练好的 Haar 级联分类器，底层是 Viola-Jones 框架：用几百个矩形特征（Haar 特征）在滑动窗口上做弱分类器级联，前几层用极少量特征快速排除明显不是脸的区域，越往后特征越多、判定越严格。正因为有这种"先粗筛再细判"的结构，它才能在 640×480 的视频里每帧跑几十次检测还扛得住。注意它是正脸检测器，侧脸、低头超过一定角度就框不出来，这是所有 Haar 方案的共性，不是 bug。
代码里加载和检测就两行：
face_cascade = cv2.CascadeClassifier('haarcascade_frontalface_default.xml') faces = face_cascade.detectMultiScale(gray, scaleFactor=1.1, minNeighbors=5, minSize=(80, 80))detectMultiScale 的三个参数直接决定误检率和速度。scaleFactor=1.1 表示每轮检测把图像缩小 10%，值越小缩放步长越细、检测越慢也越准，1.05 在低配机器上会明显掉帧；minNeighbors=5 表示候选区域至少被临近的 5 个窗口共同确认才算数，调大误检减少但会漏掉部分小脸；minSize=(80, 80) 过滤掉小于该尺寸的区域，门禁这类固定距离场景建议不低于 80，否则梳妆镜、海报上的脸都会被当成目标。实践里我很少把 scaleFactor 放到 1.05 以下，收益小、代价大，1.1～1.2 是速度和召回率的黄金区间。
2.2 LBPH 识别器：1.yml 到 10.yml 到底存了什么
检测层输出人脸框后，识别层要回答"这是谁"。这套资源用的是 LBPH（Local Binary Pattern Histograms，局部二值模式直方图），也是 OpenCV 里最适合小样本的经典人脸识别算法。核心思路一句话：把灰度图切成网格，每个像素和周围邻居比较大小得到一串 0/1 编码，统计每个网格的直方图并拼接成整张脸的特征，最后用卡方距离做直方图相似度比对。它对光照、表情变化的容忍度比 EigenFace、FisherFace 好，十几张样本就能训出一个能用的模型，这是它在传统方案里长期胜出的原因。
这也解释了压缩包里为什么是 1.yml 到 10.yml 十个独立文件——每个 yml 对应一个人的模型。训练时把这个人所有样本打上统一标签存进去，predict 返回的 label 恒为那个标签，真正的判定依据是第二个返回值 confidence：confidence 越小，说明当前人脸直方图和该模型历史直方图越接近。同一张脸，用属于他的 yml 预测，confidence 会明显低；用别人的预测，会明显高。所以 main.py 的判定逻辑必然是"十个模型挨个 predict，取 confidence 最小者再和阈值比"，而不是只调某一个模型读 label——后者是很多人改这套资源时翻车的第一现场。
选型时可以按这个表快速定位：
| 识别器 | 特征思路 | 小样本表现 | 光照敏感度 | OpenCV 接口 |
|---|---|---|---|---|
| EigenFace | PCA 降维 | 差，样本少易崩 | 高 | cv2.face.EigenFaceRecognizer_create |
| FisherFace | LDA 降维 | 中，要求多类样本均衡 | 中 | cv2.face.FisherFaceRecognizer_create |
| LBPH | 局部二值直方图 | 好，十几张可训 | 中低 | cv2.face.LBPHFaceRecognizer_create |
实操里我一般直接选 LBPH，尤其是每类只有几十张图的小项目。EigenFace、FisherFace 在样本不均衡时经常直接抛异常，调试成本远大于收益。
2.3 config.txt 的配置项解析
config.txt 是这套资源的"总开关"，main.py 启动时按行解析它。按这套资源常见的组织方式，配置大概是这样的结构：
# 人脸检测器路径 cascade_path = haarcascade_frontalface_default.xml # 模型目录，yml 所在位置 model_dir = . # 摄像头编号，0 为内置摄像头 camera_index = 0 # 置信度阈值，confidence 小于该值才显示 ID confidence_threshold = 80逐项说明。cascade_path 是相对 main.py 的路径，换机器目录变了最容易在这出错，报"CascadeClassifier 加载为空"十有八九是路径不对；model_dir = . 表示 yml 和主程序同目录，符合压缩包的文件布局，如果把模型收进子目录，这里要同步改；camera_index 笔记本上通常为 0，插入 USB 摄像头后可能是 1 或 2，运行黑屏或报摄像头打开失败优先检查这里；confidence_threshold 是核心参数，LBPH 的 confidence 越小越像，80 是实践里比较中庸的起点，具体定值方法放在第 6 章。
解析时有个易踩的细节：config.txt 不要用带 BOM 的 UTF-8 保存，否则第一行 key 会带 \ufeff 前缀，代码里匹配不上直接跳过。main.py 一般会跳过 # 注释行，但不会帮你处理 BOM，保存时选 UTF-8 无 BOM 即可。为什么要把参数外置成 config.txt 而不是写死在 main.py 里？因为这十个 yml 和检测器 xml 在不同机器上的相对位置、摄像头编号、光线条件都不一样，写死意味着每换一台机器都得改代码。外置之后，现场部署只需要改一个文本文件，这也是这类毕业设计和门禁 Demo 最常见的交付形态。
3. 环境搭建与首跑：让 main.py 在你的机器上把摄像头画面跑起来
3.1 Python 环境与 OpenCV 安装：两条 pip 命令解决
先交代版本。我建议用 Python 3.9～3.11，这个区间内 opencv-contrib-python 的轮子最全，装完即用。Python 3.12 之后的版本偶尔会遇到某个 OpenCV 版本还没有对应 wheel，需要锁版本号，反而增加不确定性。装依赖只需要两条命令：
python -m pip install opencv-python opencv-contrib-python numpy -i https://pypi.tuna.tsinghua.edu.cn/simple或
conda install -c conda-forge opencv numpy核心是第一条。opencv-python 提供基础 cv2 模块、图像接口和 Haar 级联读取；opencv-contrib-python 补上 cv2.face 人脸识别子模块，LBPH 就在这里面；NumPy 是 yml 模型读写和数组运算的底层依赖。用 python -m pip 而不是裸 pip，是为了避开系统里有多个 Python 解释器时装错环境的经典问题——这是"装完还报 No module named"最常见的根源。用 VS Code 的话，装完在右下角确认当前解释器，别让调试器偷偷切到另一个环境。
装完验证：
python -c "import cv2, numpy; print(cv2.__version__); print(cv2.face.LBPHFaceRecognizer_create)"能打印版本号和 LBPH 识别器类，说明环境齐了。如果 cv2.face 这一行 AttributeError，说明 contrib 包没生效，卸载重装 opencv-contrib-python 即可。这套源码不依赖 GPU，不用碰 CUDA，也不需要额外装深度学习框架，传统视觉方案的优势就在这里。
3.2 首次运行 main.py：核心逻辑与预期画面
环境就绪后，把压缩包解压，保持 config.txt、main.py、十个 yml 和 xml 在同一目录，直接运行：
python main.pymain.py 的核心流程一般是：读配置 → 加载检测器 → 遍历 model_dir 加载全部 yml → 打开摄像头 → 循环检测识别。对应代码结构大致是这样：
import cv2 import os cfg = {} with open('config.txt', 'r', encoding='utf-8') as f: for line in f: line = line.strip() if not line or line.startswith('#'): continue key, _, value = line.partition('=') cfg[key.strip()] = value.strip() face_cascade = cv2.CascadeClassifier(cfg['cascade_path']) threshold = float(cfg.get('confidence_threshold', 80)) models = [] for name in os.listdir(cfg.get('model_dir', '.')): if name.endswith('.yml'): rec = cv2.face.LBPHFaceRecognizer_create() rec.read(os.path.join(cfg['model_dir'], name)) models.append((name[:-4], rec)) # 去掉 .yml 就是人员编号 cap = cv2.VideoCapture(int(cfg.get('camera_index', 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, minSize=(80, 80)) for (x, y, w, h) in faces: roi = gray[y:y + h, x:x + w] best_id, best_conf = None, 999.0 for person_id, rec in models: _, conf = rec.predict(roi) if conf < best_conf: best_conf, best_id = conf, person_id if best_conf < threshold: cv2.rectangle(frame, (x, y), (x + w, y + h), (0, 255, 0), 2) cv2.putText(frame, f'ID:{best_id} conf:{best_conf:.0f}', (x, y - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2) else: cv2.rectangle(frame, (x, y), (x + w, y + h), (0, 0, 255), 2) cv2.putText(frame, 'unknown', (x, y - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 0, 255), 2) cv2.imshow('face recognition', frame) if cv2.waitKey(1) & 0xFF == ord('q'): break cap.release() cv2.destroyAllWindows()这段代码有三个关键点。第一，yml 文件名直接当人员编号，1.yml 就是 1 号，下载后别乱改名；第二，识别判定是"十个模型取最小 confidence"而不是读单个模型 label，前面讲过单人模型 label 恒定，直接读没意义；第三，只有最小 confidence 低于阈值才画绿框显示 ID，否则一律红框 unknown，这是防误识别的底线。跑起来后，画面里出现人脸框并带 ID 数字，就是一次完整识别的正常输出。想退出按 q 键，waitKey 每秒检查一次键盘输入，不会卡死。
补充一个高频问题：运行起来后如果一直只有红框 unknown，先别怀疑代码，打开 config.txt 确认 model_dir 指向的目录里确实有 yml 文件，且 main.py 启动时没有打印"模型加载 0 个"之类的信息。模型没加载进来，后面全是白搭。
3.3 验证识别效果：同一人、不同人、陌生人三种测试
首跑通过不代表系统真能用，我一般按三组测试判断模型可信度：
| 测试组 | 期望行为 | 不通过时的调整方向 |
|---|---|---|
| 模型对应人员 | 稳定显示 ID，confidence 在 30～60 | 检查样本质量，重训 |
| 没入模的同事 | 多数显示 unknown，偶尔误认但 conf 高于 70 | 降低阈值或补样本 |
| 光线、眼镜、侧脸变化 | confidence 波动在可接受范围 | 扩充多光照样本，加均衡化 |
如果第二组经常以低 confidence 把陌生人认成某个 ID，说明阈值设高了或训练样本太单一，第 4、6 章就是解决这两个问题的。测试时建议把每组的 confidence 记录到表格里，十个样本为一轮，比"感觉挺准"可靠得多。
4. 自训模型：从摄像头采集人脸到生成 yml 识别器的完整流程
4.1 采集人脸样本：一个带预处理的采集脚本
这套资源自带的模型是提供者的人脸，想真正用起来必须训自己的模型。第一步是采集干净样本。我一般用这个脚本，让摄像头自动抓脸并保存：
import os import cv2 def collect(person_id, save_dir='samples', target=60): os.makedirs(save_dir, exist_ok=True) cap = cv2.VideoCapture(0) cascade = cv2.CascadeClassifier('haarcascade_frontalface_default.xml') saved = 0 while saved < target: 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: roi = gray[y:y + h, x:x + w] roi = cv2.resize(roi, (200, 200)) cv2.imwrite(f'{save_dir}/person{person_id}_{saved}.jpg', roi) saved += 1 if saved >= target: break cv2.imshow('collect', frame) if cv2.waitKey(1) & 0xFF == ord('q'): break cap.release() cv2.destroyAllWindows()采集脚本里有几个细节要注意。先转灰度再检测识别，因为 Haar 和 LBPH 只吃灰度；roi resize 到 200×200 统一尺寸，保证每个网格的直方图对应相同尺度的纹理，特征才稳定；文件名带 person_id 前缀，训练脚本靠它归类。采集时头轻微转动、左右侧脸各留一点，我还会故意开关一次灯，让样本覆盖不同亮度区间。默认 60 张，抓拍过程中偶尔会有模糊帧，训练前扫一眼样本目录，明显糊的删掉即可。
样本质量优先于数量。60 张里如果有三分之一是低头、闭眼、过曝的，训练出来的模型比 30 张干净的还差。宁可放慢采集速度，让每张脸都处于正对镜头、双眼可见的状态。另外采集时建议把摄像头垫到与视线平齐的高度，仰拍和俯拍都会让 LBPH 的特征分布产生明显偏移。
提示：Windows 下工程路径含中文时，cv2.imread 会静默返回 None，样本等于白采。解决方式是先用 np.fromfile 读字节再走 cv2.imdecode，或者干脆把工程放到纯英文路径。
4.2 LBPH 训练参数：radius、neighbors 与网格大小怎么选
样本够了就可以训，沿用"一人一模型"的思路，每个人员生成一个 yml：
import os import numpy as np import cv2 def train_one(person_id, sample_dir='samples'): faces = [] for f in os.listdir(sample_dir): if f.startswith(f'person{person_id}_'): img = cv2.imread(os.path.join(sample_dir, f), cv2.IMREAD_GRAYSCALE) if img is not None: faces.append(img) if len(faces) < 20: raise ValueError(f'person{person_id} 样本不足，只有 {len(faces)} 张') rec = cv2.face.LBPHFaceRecognizer_create( radius=1, neighbors=8, grid_x=8, grid_y=8) rec.train(faces, np.full(len(faces), person_id, dtype=np.int32)) rec.save(f'{person_id}.yml') print(f'person{person_id} 训练完成，样本数 {len(faces)}')train 的两个参数必须等长：faces 是图像列表，labels 是等量标签数组。这里刻意把所有样本标签设为同一个 person_id，和原资源 1.yml～10.yml 的组织方式一致。识别时再靠多模型比较来归属身份，而不是靠 label 区分。
LBPH 构造参数按场景调。radius=1 是比较半径，1 是默认，半径大特征更粗、抗噪声好但丢细节，小尺寸图建议维持 1；neighbors=8 是采样邻居数，8 是 OpenCV 默认，太小直方图过疏、太大计算量上去，新手不建议动；grid_x=8、grid_y=8 把图切成 8×8 网格，网格越多空间细节越强，但对人脸对齐误差越敏感——采集时如果人脸位置经常偏移，过细的网格反而让同一人两次识别差异变大。这几个参数出问题的典型表现是识别率不升反降，此时先恢复默认再逐项试。极老版本的 OpenCV 在 create 时不接受关键字参数，可以先 create() 再通过 setRadius、setGridX 这类 setter 逐个设置。
4.3 把新模型接回 main.py：文件命名与标签对应关系
训练产物是 {person_id}.yml，放进 model_dir 指向的目录，main.py 下次启动自动加载。它按文件名把 ID 映射到识别结果，所以命名规则就是规范本身：1.yml 对应 1 号，10.yml 对应 10 号；想替换某个人，直接覆盖对应 yml，不用改代码。人数超过十个就新增 yml 文件，加载逻辑遍历目录，不受 1～10 限制。多人的流程就是循环执行 collect 和 train_one，person_id 从 1 递增。替换后务必重跑 3.3 的三组验证，重点看新人员的 confidence 分布和旧模型有没有重叠，重叠严重说明两个人的样本太像或采集姿态太单一。
另外注意一点：yml 是 OpenCV 的 FileStorage 格式，二进制或 XML 取决于保存方式，跨机器拷贝时别用文本编辑器打开修改，改坏了 recognizer.read 会直接加载失败。备份模型文件也建议按人员编号归档，方便回滚。
5. 避坑与排查：人脸识别系统最常见的五个翻车现场
5.1 现象：ModuleNotFoundError: No module named 'cv2'，重装也没用
现象：命令行运行 python main.py 直接报 No module named 'cv2'，pip install 之后再跑仍然报同样的错。
原因：环境串了。最常见的是 VS Code 里选的解释器和 pip 所属的解释器不是同一个，或者 conda 基础环境与项目环境混用。pip 装到了 A 环境，运行用的 B 环境，自然找不到。
解决：统一用 python -m pip install 安装，让 pip 和运行解释器强制绑定到同一个；VS Code 装完依赖后在右下角重新选择解释器；最后用 python -c "import cv2; print(cv2.version)" 做一次现场验证。这一步做完，一半的环境玄学当场消失。
5.2 现象：AttributeError: module 'cv2' has no attribute 'face'
现象：import cv2 成功，cv2.CascadeClassifier 也正常，但跑到 cv2.face.LBPHFaceRecognizer_create 一行报 AttributeError。
原因：装的是精简版 opencv-python。LBPH 这类人脸识别算法在 opencv-contrib-python 扩展包里，基础包没有 face 子模块。
解决：先 pip uninstall opencv-python，再 pip install opencv-contrib-python，两个包同时存在时会互相覆盖文件。装完重新执行 3.1 的验证命令，确认 cv2.face 存在。另外 Python 版本太新（3.12+）时 contrib 轮子可能滞后，锁一个 OpenCV 版本号即可。
5.3 现象：换个人站到摄像头前，依然显示某个 ID，陌生人被认成熟人
现象：识别结果基本固定成某个人，换谁上去都是这个 ID，甚至拿手机里的照片也能认出来。
原因：主循环只调了一个 yml 做 predict，或者没做阈值判断。单人模型的 predict 返回 label 恒为这个人的编号，不看 confidence 就直接显示 ID，等于逢脸必认。还有人把 confidence_threshold 设成 200，形同虚设。
解决：改成 3.2 的多模型遍历逻辑，十个模型全部 predict，取 confidence 最小者，再加置信度阈值兜底。改完找没入模的人测十次，出现误认就把阈值往下调，直到陌生人的 confidence 全部高于阈值。
5.4 现象：检测框乱跳、忽大忽小，帧率掉到个位数
现象：画面像幻灯片，人脸框在脸上来回缩放，人一转头框就消失再出现，CPU 占用接近满核。
原因：每帧都在全分辨率上跑 detectMultiScale，外接摄像头 1080P 输入时计算量直接爆掉；scaleFactor 设成 1.01 这类过小值也会让级联多算几十层。框跳是因为相邻帧检测窗口不稳定，属于 Haar 的固有抖动。
解决：采集端把分辨率压到 640×480：
cap = cv2.VideoCapture(0) cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640) cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)scaleFactor 提到 1.1～1.2，minNeighbors 提到 5～6。720P 以上输入建议隔帧检测，拿上一帧的人脸框位置做简单跟踪，帧率能翻倍，框也稳定很多。
5.5 现象：白天能认，晚上或侧光频繁 unknown
现象：同样的代码，白天识别正常，晚上开灯或侧光照射时连续 unknown，偶尔还认错人。
原因：LBPH 对光照敏感，训练样本的亮度分布只覆盖了一个区间。侧光会让半边脸的局部二值模式完全改变，直方图距离被拉大，confidence 飙高。笔记本电脑摄像头的自动曝光也会让亮度忽高忽低。
解决：采集阶段覆盖多光照，开灯、关灯、侧光各采一部分；预测前对 roi 做直方图均衡化：
roi = cv2.equalizeHist(gray[y:y + h, x:x + w])把灰度分布拉平，相当于把不同光照映射到同一亮度区间。注意训练样本和预测输入要做同一种预处理，否则模型学的分布和线上看到的不一致，又会出现新的偏移。
6. 进阶调优：先用数据把置信度阈值定死在合理区间
阈值是这套系统里唯一值得认真调的参数。直接拍一个 80 不一定适合你的摄像头，我的做法是先量化再定值：分别收集本人和陌生人各 50 次预测的 confidence，看两组分布的边界。用下面这个函数收集：
import cv2 import numpy as np def collect_confs(rec, cascade, total=50): confs, cap = [], cv2.VideoCapture(0) while len(confs) < total: ret, frame = cap.read() gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) for (x, y, w, h) in cascade.detectMultiScale(gray, 1.1, 5, minSize=(80, 80)): roi = cv2.equalizeHist(gray[y:y + h, x:x + w]) _, conf = rec.predict(roi) confs.append(conf) cap.release() return np.array(confs)把两组数据打印出来后，取本人置信度最大值和陌生人置信度最小值的中间点作为阈值，通常就能得到陌生人进不来、本人也丢不了的操作区间。如果两组分布重叠严重，别调阈值，回头补样本和预处理才是正路。
人员变多时全量重训太慢，LBPH 支持增量更新：rec.update(新脸列表, 新标签数组) 在原有模型上追加样本，适合门禁这类定期加人的场景。从那以后，我每次给这类系统换场景，都会强制先跑一遍上述阈值采集流程，再谈调参，而不是拍脑袋改配置。这套流程也希望能帮到你。
本文还有配套的精品资源，点击获取
高可用数据库集群部署指南)