基于 Python + OpenCV 的人脸识别项目实战（SFaceEmbedding + GUI 一键训练 + 测试评估）
基于 Python + OpenCV 的人脸识别项目实战（SFaceEmbedding + GUI 一键训练 + 测试评估）
目录
- 基于 Python + OpenCV 的人脸识别项目实战（SFaceEmbedding + GUI 一键训练 + 测试评估）
1. 项目简介
这是一个本地可运行的人脸识别 Python 项目，完整实现了从训练集准备到图形界面识别的全流程，适合课程设计、毕业设计、OpenCV 学习、Python 实战项目展示。
项目主要能力：
- 训练集管理（按“姓名/图片”目录组织）
- 自动划分训练集 / 测试集（
split） - 人脸预处理（
prepare，支持检测/裁剪/统一尺寸） - 模型训练（默认
SFaceEmbedding，兼容LBPH） - 单张图片识别（GUI / 命令行）
- 批量评估测试集准确率
- 图形界面（支持一键训练、选图识别、进度条）
- 图片抓取下载 GUI（按关键词下载训练图）
- 中文路径 / 中文姓名标签支持（Windows 场景）
2. 项目效果展示（可放截图）
2.1 主识别 GUI（训练 + 测试 + 识别）
- 一键训练（
split -> prepare -> train） - 测试集目录切换
- 识别结果预览
- 日志与 JSON 结果展示
2.2 图片抓取下载 GUI（补充训练集）
- 输入关键词（如：薛之谦、胡歌）
- 指定保存目录（如
dataset/raw_lfw/人物名） - 指定下载数量
- 支持原图优先、缩略图回退
- 支持下载日志与进度条
3. 技术方案说明（核心原理）
本项目支持两种识别后端：
3.1 默认方案：SFaceEmbedding（推荐）
当前默认使用 SFaceEmbedding 路线，整体流程如下：
- 使用
YuNet进行人脸检测（DNN） - 使用
SFace提取人脸 embedding（特征向量） - 将新图的人脸向量与训练库中的向量做相似度匹配（cosine distance）
- 根据阈值判断是否为已知人物或
unknown
特点：
- 对彩色自然照片更稳
- 比传统 LBPH 更适合真实场景（网络图片、手机照片）
- 不需要从零训练神经网络（使用预训练模型做特征提取）
3.2 兼容方案：LBPH（传统方法）
项目中也保留了 LBPH 路线，适合作为传统方法对照学习。
特点：
- 实现简单
- 对规整、已裁剪人脸图可用
- 对真实场景图片的鲁棒性通常不如 SFace
4. 项目目录结构
view/ artifacts/ # 模型、标签映射、报告、ONNX 模型缓存 face_embedding_gallery.npz # 默认 SFace 特征库模型 lbph_face_model.yml # LBPH 模型（备用） label_map.json # 标签映射（id -> 姓名） model_meta.json # 模型元信息（后端、阈值、尺寸等） dataset_summary.json # 预处理统计 eval_report.json # 批量评估报告 models/ face_detection_yunet_*.onnx # YuNet 模型（自动下载） face_recognition_sface_*.onnx # SFace 模型（自动下载） dataset/ raw/ # 原始数据集（按姓名分目录） raw_lfw/ # LFW 彩色样例数据（推荐） processed/ # 预处理后人脸图（LBPH 使用） splits/ train_raw/ # 划分后的训练集原图 test_raw/ # 划分后的测试集原图 train_processed/ # 划分后训练集预处理结果（LBPH） outputs/ gui/ # GUI 识别结果图 eval/ # 批量评估标注图 scripts/ download_sample_dataset.py # 下载样例数据集（LFW/Olivetti） download_images_gui.py # 图片抓取下载 GUI（新增） split_dataset.py # 划分训练集/测试集 prepare_dataset.py # 预处理（检测/裁剪/缩放） train_model.py # 训练（默认 SFace，兼容 LBPH） recognize_image.py # 单图识别 evaluate_testset.py # 批量评估 gui_app.py # 主识别 GUI src/face_pipeline/ # 核心逻辑 requirements.txt # 依赖 README.md # 项目说明 5. 环境安装（Windows / PowerShell）
建议使用虚拟环境：
python -m venv .venv .\.venv\Scripts\activate python -m pip install -r requirements.txt 5.1 国内镜像（清华源）
如果网络较慢，可以使用清华源安装依赖：
python -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt 6. 样例数据集（推荐使用 LFW 彩色数据）
项目提供了样例数据集下载脚本，支持：
LFW（彩色，推荐）Olivetti（灰度，较老，仅做流程验证）
6.1 下载 LFW 到新目录（不覆盖自己的数据）
.\.venv\Scripts\python scripts\download_sample_dataset.py --dataset lfw --output-dir dataset\raw_lfw --clean --lfw-min-faces 20 --per-person 10 --shuffle --seed 42 下载后目录名会是：
Angelina_JolieGeorge_W_BushColin_Powell- …
7. 使用自己的图片训练（重点）
7.1 数据集组织方式
按“人名目录”组织图片，文件夹名就是标签名：
dataset/ raw/ 邓紫棋/ 001.jpg 002.png 003.jpg 胡歌/ 001.jpg 002.jpg 支持格式：
.jpg.jpeg.png.bmp.webp
7.2 是否需要手动改成 200x200？
不需要。
对普通原图，项目会自动完成：
- 人脸检测
- 人脸裁剪
- 尺寸归一化（LBPH 路线需要）
8. 主 GUI 使用方法（推荐）
启动 GUI：
.\.venv\Scripts\python scripts\gui_app.py 8.1 一键训练（GUI）
GUI 左侧已按流程调整顺序：
- 一键训练（
split + prepare + train） - 测试集目录与识别设置
- 测试图片列表
- 日志区域
训练步骤：
- 设置“训练原图目录”
- 设置每人训练/测试张数（例如
8 / 2） - 根据数据类型决定是否勾选
训练预处理跳过检测 - 点击
一键训练（split + prepare + train） - 等待进度条完成（支持
split / prepare / train步骤状态显示）
8.2 识别单张图片（GUI）
- 从左侧测试集列表双击图片
- 或点击“浏览文件”选择任意本地图片
- 点击“识别当前图片”
当前 GUI 识别结果展示方式：
- 图片中只画人脸框（避免小图文字过小/截断）
- 识别文本固定显示在结果图下方（固定字号）
- 日志区域显示完整 JSON 结果（含 bbox、name、confidence、unknown）
9. 图片抓取下载 GUI（新增功能）
为了方便补充训练集，我额外做了一个独立界面：
.\.venv\Scripts\python scripts\download_images_gui.py 9.1 功能说明
- 输入关键词（如：
薛之谦/胡歌） - 自动生成人物子目录名
- 下载指定数量图片到
dataset/raw_lfw/人物名 - 支持尺寸过滤、字节数过滤
- 支持“下载前清空目标目录”
- 支持“缩略图回退”（仅在原图失败时回退，不再重复保存缩略图）
9.2 关于重复图片问题（踩坑记录）
初版实现中会出现“大图 + 474x 缩略图”成对重复，原因是每条结果同时下载了：
- 原图链接（
murl） - 缩略图链接（
turl）
当前已修复为：
- 优先下载原图
- 原图失败时才回退缩略图
- 日志显示来源标记（
[orig]/[thumb]）
10. 命令行方式（CLI）完整流程
10.1 划分训练集 / 测试集
.\.venv\Scripts\python scripts\split_dataset.py --clean --source-dir dataset\raw_lfw --train-per-person 8 --test-per-person 2 --shuffle --seed 42 10.2 预处理（已裁剪人脸图可跳过检测）
.\.venv\Scripts\python scripts\prepare_dataset.py --clean --skip-detect--raw-dir dataset\splits\train_raw --processed-dir dataset\splits\train_processed 10.3 训练模型（默认 SFaceEmbedding）
.\.venv\Scripts\python scripts\train_model.py --backend sface --raw-dir dataset\splits\train_raw 10.4 单图识别
.\.venv\Scripts\python scripts\recognize_image.py --image path\to\photo.jpg 10.5 批量评估测试集
.\.venv\Scripts\python scripts\evaluate_testset.py --test-dir dataset\splits\test_raw 11. 多人脸图片是否支持分别识别？
支持。
前提：
- 识别时不要勾选
跳过检测（已裁剪人脸图） - 使用普通照片进行识别
- 图片中的人脸不要太小、太模糊
程序会：
- 检测图中多张人脸
- 对每张人脸分别提取特征并匹配
- 返回多个结果（
results列表）
12. 阈值说明（SFace 和 LBPH 不能混用）
12.1 SFaceEmbedding（默认）
confidence表示 cosine distance（距离）- 数值越小越像
- 默认阈值
0.62 - 常见调参范围
0.55 ~ 0.75
12.2 LBPH
confidence表示 LBPH 距离- 数值越小越像
- 默认阈值
70 - 常见调参范围
50 ~ 120
13. 典型问题与解决方案（实战踩坑）
13.1 cv2.face 不存在（module 'cv2' has no attribute 'face'）
原因：
- 安装了
opencv-python而不是opencv-contrib-python - IDE 运行按钮使用了错误解释器（不是
.venv）
解决：
.\.venv\Scripts\python -m pip uninstall -y opencv-python opencv-contrib-python .\.venv\Scripts\python -m pip install -r requirements.txt 并确认 IDE 解释器为：
...\view\.venv\Scripts\python.exe
13.2 中文路径图片读取/写入失败（Windows）
例如微信截图名、中文人物名目录。
项目已做兼容处理：
- 中文路径读图（
imdecode+ Python 文件 IO） - 中文路径写图（
imencode+ Python 文件 IO） - 中文姓名标签绘制（Pillow）
13.3 识别成功但结果图预览空白
原因通常是：
- 结果图刚写完就读取失败
- 中文路径导致旧版写盘路径异常
当前 GUI 已处理：
- 结果图预览重试
- 失败时回退显示原图并记录日志
- 识别结果本身仍有效（名字和 bbox 已算出）
14. 项目亮点总结
这个项目完整做成了一个可操作、可展示、可扩展的小型人脸识别系统，包含：
- GUI 一键训练流程
- 彩色样例数据集支持（LFW）
- 自定义数据集训练
- 中文路径/中文标签兼容
- 批量评估与结果输出
- 独立图片抓取下载工具
- 多后端（SFaceEmbedding / LBPH）对比学习
15. 注意事项
- 本项目仅用于学习与技术交流
- 使用他人照片请注意授权与隐私
- 图片抓取结果建议人工筛选，避免误抓、重复图、多人图影响训练效果
