Python+dlib人脸识别课设源码详解：从HOG检测到128维特征比对

简介：这是一份基于Python与dlib实现的人脸识别系统课程设计完整源码包，并配有使用说明，面向计算机相关专业正在完成课设的学生。项目难度适中，源码均已在本地编译并成功运行，评审分达95分以上，内容经助教审定，既能满足课程设计学习与直接使用需求，也可作为人脸识别入门到进阶的实战范例。压缩包共37个文件，约93.29MB，主要包含4个Python核心源文件（涉及人脸数据采集、128维特征提取、实时识别等模块）、dlib所需的shape_predictor与face_recognition模型dat文件、csv特征数据文件、jpg/png人脸样本图片、xml配置文件、iml项目文件及README说明文档，目录结构清晰，便于按模块阅读与二次开发。目前已有145人学习浏览，对计划高效完成人脸识别课设的同学而言，这份资料提供了从数据准备、模型调用到结果展示的完整实现思路，参考价值较高。

1. 不交“静态图糊弄版”：这套 dlib 人脸识别课设源码的底子在哪

如果你也是那个被课程设计逼到「先跑通再美化」的人，大概率已经看过一圈 faceswap、LBPH 或者 OpenCV 自带的人脸识别 Demo。它们要么识别率感人，要么只能对着一张提前存好的照片做比对，答辩时老师一句「现场换个人试试」就能把你打回原形。这套基于 Python + dlib 的人脸识别课设源码，走的是另一条路：它把「人脸检测 → 关键点定位 → 128 维特征编码 → 欧氏距离比对 → 界面展示 → 签到记录」串成了一条完整可跑的链路，不是那种只检测不识别、或者是把训练好的麻省理工模型当黑匣子调一调的半成品。

我要先把这个项目的真实能力边界说清楚：它不是一个从零训练人脸识别模型的教学代码库，而是一个把 dlib 的 HOG 检测器、68 点关键点模型、人脸编码模型、OpenCV 摄像头采集和 Python 图形界面组装成型的课程设计工程。你拿到手能直接产生「摄像头一开，识别到人，界面显示姓名，并把记录写进 CSV」的可演示结果。适合三类人：被 Python 课程设计卡住、想要高分呈现的在读学生；想搞懂 dlib 人脸识别工程链路、而不是停留在 pip install 层面的初学者；以及需要用一套干净代码做二次开发的从业者。下面我从环境、代码骨架、参数调优一路拆到避坑，都是照着课设验收标准来的拆解，不是泛泛而谈。

2. 环境搭建与依赖版本：为什么报错全出在 dlib，而不是你自己的代码

2.1 为什么选 dlib：把 HOG 检测器和 128 维特征向量讲明白

课设选型是答辩时最常被问的问题，很多同学答不上来。OpenCV 自带的 LBPH 人脸识别训练速度不算慢，但对姿态、光照、遮挡的容错率低，课设场景里应用效果很难说服老师。dlib 的方案是「检测 + 编码」两步走的成熟架构：先用get_frontal_face_detector()拿到一个 HOG + 线性 SVM 的人脸检测器，快速框出人脸区域；然后用shape_predictor_68_face_landmarks.dat定位眼睛、鼻子、嘴角等 68 个关键点，再把这些关键点对齐后输入face_recognition_model_v1.dat，得到一个 128 维的人脸特征向量。比对时算两个向量的欧氏距离，距离越小越像。

这就是 dlib 方案比 LBPH 更稳的原因：它不直接比像素，而是比「人脸的本质特征」。像素受光照影响大，128 维编码受光照影响相对小。课设答辩时你能讲出这一层，比单纯说「我用的是 dlib」要有说服力得多。当然 dlib 也有代价，它更吃计算资源，这在后面避坑章里我会单独提。

2.2 Python 版本、dlib 安装与模型文件放置：一套能一次装通的操作

资源压缩包里一般会带完整说明文档，但环境这块我建议你自己重新过一遍，因为最常翻车的不是代码逻辑，而是 dlib 装不上。我测过的稳定组合是这样：Python 3.8 或 3.9，dlib 19.24.x，OpenCV-Python 4.5.x。Python 版本如果超过 3.10，Windows 下 pip 直装 dlib 的概率会下降，要么去找预编译 whl，要么本地编译。别用 3.12，省得折腾。

# 1. 创建虚拟环境，避免污染全局 Python 解释器 conda create -n face_project python=3.8 # 2. 激活环境 conda activate face_project # 3. 安装 dlib，Windows 下若没有预编译 wheel 会触发源码编译 pip install dlib==19.24.0 # 4. 安装 OpenCV、NumPy、Pillow pip install opencv-python==4.5.5.64 numpy pillow # 5. 安装 PyQt5 或 tkinter 视源码界面而定，本项目桌面端用 PyQt5 pip install PyQt5

逻辑说明：先建虚拟环境是为了把项目依赖隔离，课设机器上往往装了一堆matplotlib、pandas，版本互相干扰是家常便饭。dlib 指定 19.24 是因为较新版本在 Windows 上的源码编译默认启用 AVX 指令集，老 CPU 反而可能跑不起来。OpenCV 4.5 系列的cv2.VideoCapture在 USB 摄像头兼容性上表现比较稳。

模型文件是整套源码的另一半。dlib 官网提供两个已训练好的模型：shape_predictor_68_face_landmarks.dat约 99MB，dlib_face_recognition_model_v1.dat约 60MB。下载后要放在项目根目录的models/文件夹下，标准目录结构如下。注意这份资源的压缩包里通常已经附带完整模型，没有的话才需要自己另找渠道。

face_recognition_project/ ├── main.py # 程序入口：启动界面与主循环 ├── face_utils.py # 人脸检测、编码、比对工具函数 ├── models/ │ ├── shape_predictor_68_face_landmarks.dat │ └── dlib_face_recognition_model_v1.dat ├── data/ │ ├── known_faces/ # 按人存放照片，一人一个子文件夹 │ └── attendance_records/ # 识别签到记录输出目录 ├── gui/ │ └── main_window.py # PyQt5 界面文件 └── requirements.txt

参数说明：known_faces/目录的命名规则决定了识别程序的遍历方式，一般是一个文件夹对应一个人，文件夹名就是显示在界面上的姓名。比如data/known_faces/张三/下放几张不同角度的生活照。这个命名规范是源码里写死的约定，改代码反而容易出错，实际使用中保持这个结构最稳。

3. 五段式代码骨架：从摄像头画面到「识别出你是谁」到底走了几步

3.1 检测、编码、比对、界面、记录：主流程的设计逻辑

整套源码的核心模块是face_utils.py和main.py。前者管算法链路，后者管界面和业务流程。两者分离是课设源码里比较难得的做法，答辩时老师问「业务逻辑和算法怎么解耦的」，你可以直接指着这两个文件回答。整个识别主流程可以拆成五步：打开摄像头取帧 → 用 HOG 检测器框人脸 → 关键点对齐 → 提取 128 维特征 → 与已知人脸库逐人比对，取最近距离。全程不用训练自己的模型，这是 dlib 预训练模型的优势，也是它能作为「课设源码」而不是「训练工程」存在的原因。

# face_utils.py 核心代码骨架 import dlib import numpy as np class FaceProcessor: def __init__(self, predictor_path, model_path, detection_method="hog"): self.detector = dlib.get_frontal_face_detector() self.predictor = dlib.shape_predictor(predictor_path) self.face_model = dlib.face_recognition_model_v1(model_path) self.detection_method = detection_method # "hog" 或 "cnn" def detect_face(self, rgb_image): """检测一张图中最大的人脸区域，返回矩形对象""" # upsample=1 对较小的图做一次金字塔放大，提升小脸召回率 faces = self.detector(rgb_image, 1) if len(faces) == 0: return None # 取面积最大的人脸，避免多人场景下框错目标 return max(faces, key=lambda rect: rect.width() * rect.height()) def encode_face(self, rgb_image, face_rect): """提取一个人脸的128维特征向量""" shape = self.predictor(rgb_image, face_rect) # 返回的就是dlib里所谓的"128维描述子" descriptor = self.face_model.compute_face_descriptor(rgb_image, shape, num_jitters=1) return np.array(descriptor)

逻辑说明：detect_face里max(faces, key=lambda rect: rect.width() * rect.height())这行是课设场景下的取舍——老师不会同时把两个人的脸塞满镜头，取最大人脸能避免误识别，代价是多人场景会忽略其他人，但课程设计够用。compute_face_descriptor的num_jitters=1表示对同一张脸只做一次特征提取，设为 10 会对人脸图像做扰动后多次提取再取均值，识别更稳但更慢。

3.2 已知人脸库怎样生成特征并落盘

拿到 128 维向量后需要一个「注册」过程：遍历data/known_faces/下每个人的照片，提取特征并保存成.npy文件或直接存在内存字典里。缓存到本地的好处是下次启动程序不用重新逐张提取，课设演示时等待时间越短，老师脸色越好。

# 生成已知人脸特征库 import os import cv2 from face_utils import FaceProcessor def build_known_database(folder_path, processor): """遍历文件夹，生成 {人名: 特征矩阵}""" known_names = [] known_vectors = [] for person_name in os.listdir(folder_path): person_dir = os.path.join(folder_path, person_name) if not os.path.isdir(person_dir): continue vectors_for_person = [] for img_file in os.listdir(person_dir): img_path = os.path.join(person_dir, img_file) # OpenCV 默认读入 BGR，dlib 内部基于 RGB，这里必须转换 bgr_img = cv2.imread(img_path) if bgr_img is None: continue rgb_img = cv2.cvtColor(bgr_img, cv2.COLOR_BGR2RGB) face_rect = processor.detect_face(rgb_img) if face_rect is None: continue vector = processor.encode_face(rgb_img, face_rect) vectors_for_person.append(vector) if len(vectors_for_person) > 0: # 一个人可有多张注册照，特征取均值后更鲁棒 mean_vector = np.mean(vectors_for_person, axis=0) known_names.append(person_name) known_vectors.append(mean_vector) # 保存到本地，下次启动免提取 np.savez("known_faces.npz", names=known_names, vectors=known_vectors)

逻辑说明：cv2.imread读出来是 BGR 排序，而 dlib 期望的是 RGB，这个转换漏掉的话识别率会断崖式下跌，属于这个项目里最经典的「代码没报错但就是认不出人」的原因，后面避坑章我还会再强调一次。np.savez把名单和特征矩阵压缩成单文件，二次启动时直接np.load即可，跳过图片遍历和特征提取环节。

3.3 相似度比对：欧氏距离阈值怎么卡到 0.36

比对环节是整个工程里最值得写进课设报告的部分。两个 128 维向量的相似度用欧氏距离表示，距离小代表特征接近。dlib 官方经验值里，同一个人不同照片的特征距离通常在 0.36 以下，不同人的距离往往在 0.6 以上。0.36 到 0.6 之间是模糊地带，可以按课设场景调。

def match_face(query_vector, known_names, known_vectors, threshold=0.36): """ 返回匹配到的人名和最小距离，距离大于 threshold 则返回 "未知" """ distances = np.linalg.norm(known_vectors - query_vector, axis=1) min_idx = np.argmin(distances) min_distance = distances[min_idx] if min_distance < threshold: return known_names[min_idx], min_distance return "陌生人", min_distance

逻辑说明：np.linalg.norm(known_vectors - query_vector, axis=1)一行算出了测试向量与所有已知向量的欧氏距离，比 for 循环写逐条距离快得多，也简洁。argmin找出最小距离对应的索引，工夫全在阈值上。阈值调大写容易把不同人误判成同一人，调小写容易把本人认成陌生人。课设调试阶段我建议做一个快速自检脚本：把注册照片和几张陌生人照片混在一起跑一遍，统计比对距离分布，再定阈值。0.36 只是起点，不是标准答案。

4. 从「能跑」到「能答辩」：把核心链路改造成你自己的课设亮点

4.1 摄像头实时识别循环：别再对着静态图按回车了

默认源码里main.py的识别循环一般是这样设计的：启动 PyQt5 界面，打开摄像头，按「开始识别」按钮后进入while True循环，每帧执行一次检测和比对，并把结果画在视频画面上。很多同学改的第一个地方就是这里——为了省 CPU，把「每帧识别」改成「每 3 帧识别一次」，否则笔记本风扇会起飞。

# main.py 中摄像头识别循环的核心片段 import cv2 from face_utils import FaceProcessor def start_recognition(processor, known_names, known_vectors): cap = cv2.VideoCapture(0) # 0 表示默认摄像头，外接摄像头常为 1 # 强制设定读取分辨率，减少逐帧传输压力 cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640) cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480) cap.set(cv2.CAP_PROP_FPS, 30) frame_skip = 3 # 每 3 帧识别一次 frame_count = 0 while True: ret, frame = cap.read() if not ret: break frame_count += 1 if frame_count % frame_skip != 0: # 未到识别帧时直接显示上一帧结果，并继续读取 cv2.imshow("Face Recognition", frame) if cv2.waitKey(1) & 0xFF == ord("q"): break continue rgb_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) face_rect = processor.detect_face(rgb_frame) if face_rect is not None: query_vector = processor.encode_face(rgb_frame, face_rect) name, distance = match_face(query_vector, known_names, known_vectors) # 在原始 BGR 帧上画框，坐标直接从 dlib 矩形对象读取 x, y, w, h = face_rect.left(), face_rect.top(), face_rect.width(), face_rect.height() cv2.rectangle(frame, (x, y), (x + w, y + h), (0, 255, 0), 2) cv2.putText(frame, f"{name} {distance:.2f}", (x, y - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2) cv2.imshow("Face Recognition", frame) if cv2.waitKey(1) & 0xFF == ord("q"): break cap.release() cv2.destroyAllWindows()

逻辑说明：cap.set三行是保证演示流畅的关键，不设分辨率时摄像头默认可能有 1280×720，每帧做 HOG 检测耗时明显。降到 640×480 后人脸检测速度能提升一倍左右。frame_skip = 3的写法本质是拿识别实时性换 CPU 占用率，课设演示场景下 1 秒识别 10 次已经足够。外接摄像头索引从 0 改成 1 这个细节，几乎是每次演示现场翻车的根源。

4.2 识别结果落盘成签到表：把数据写进 CSV 才算项目闭环

只显示名字的课设太单薄，「识别 + 记录」才有信息系统的味道。源码里通常会带一个「签到记录」功能，把每次识别成功的人名、时间、置信度写入attendance_records/下的 CSV 文件。这一步让整个项目的完成度立刻高出同龄人一截，答辩展示时打开 CSV 给老师看，比任何界面截图都有说服力。

# 记录识别结果到 CSV import csv from datetime import datetime def write_attendance_record(person_name, distance): record_path = f"data/attendance_records/{datetime.now().strftime('%Y-%m-%d')}.csv" with open(record_path, "a", newline="", encoding="utf-8") as f: writer = csv.writer(f) # 每次追加一条识别记录，不覆盖历史数据 writer.writerow([ person_name, datetime.now().strftime("%H:%M:%S"), f"{distance:.4f}" ])

逻辑说明：按天生成 CSV 文件，一天一个文件名，用于后续统计某人在某天的出现时间。newline=""是 Windows 下防止写出的 CSV 隔行空行的小细节，很多初学者在这吃暗亏。encoding="utf-8"是为了让人名写入后不乱码，Windows 的 Excel 打开时建议用 UTF-8 编码读取，否则中文列头会显示成乱码。

4.3 参数调优：upsample、threshold、jitters 一张表说清

拿到源码想调出「最高识别结果」时，主要改三个参数。我把它们的效果和推荐值列在下面，方便写进课设报告里的「参数选择」章节。

调参的血泪经验是：不要在演示前几小时猛调 threshold，而要提前把「本人照片 + 室友照片 + 陌生人照片」混在一个文件夹里，跑一遍输出所有距离，看分布区间。分布区间稳定在 0.25～0.32 之间时阈值设 0.36 才安全。如果自己照片和别人照片的距离都挤在 0.4～0.5，那说明问题不在阈值，而在注册照片质量。有人把模糊的、戴帽子的、逆光的照片塞进 known_faces，特征向量几乎全被噪声带偏，怎么调阈值都救不回来。

5. 避坑记录：dlib 人脸识别课设里我踩过的六个大坑

5.1 摄像头画面空白但程序没报错

现象：VideoCapture(0)正常返回True，但窗口画面是全黑或空白。

原因：笔记本内置摄像头在被占用，或者虚拟机的摄像头映射没开启；还有一种情况是cap.read()读取时摄像头没有完成自动曝光初始化，前几帧是空数据。

解决：先确认设备索引。把VideoCapture(0)改为VideoCapture(1)试试，外接 USB 摄像头很多时候索引是 1。再不行就加一段cap.isOpened()判断，并打印frame.shape，如果读到(0, 0, 3)说明分辨率配置失败。最笨但有效的办法是换一个摄像头在别的软件里试通，排除硬件问题再说代码。

5.2 程序识别不到人脸，但图片里人明明很大

现象：摄像头画面里人正对镜头，控制台却一直输出no face detected。

原因：检测器输入的是灰度图或者通道顺序不对。dlib 的get_frontal_face_detector()接受 RGB 输入，但如果直接从cv2.imread读图后不转通道或转灰度再传入，会在特征提取阶段挂掉。另外距离太近或太远也会导致人脸超出检测框。

解决：统一在传入前执行cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)，不要在多个函数里各转各的，最后把自己绕晕。距离保持 40cm～100cm 之间，脸占画面高度的 1/4 到 1/2 时命中率最高。写一个测试脚本只检测不识别，输出框坐标，确认框准了再走下一步识别。

5.3 dlib 安装报 CMake 错误

现象：pip install dlib时报Could not find CMake或error: command 'cl.exe' failed。

原因：Windows 下 dlib 源码编译需要 CMake 和 Visual Studio 的 C++ 构建工具。pip 安装时如果检测不到cl.exe就直接编译失败，很多人的 Python 环境里根本没装过 VS。

解决：按顺序装 Visual Studio Build Tools 2022，勾选「使用 C++ 的桌面开发」，再重装 dlib。不想折腾的就找 Python 3.8/3.9 对应的预编译 whl 文件，路径里含win_amd64字样的直接 pip 安装，能省半小时。这条虽说是环境问题，但课设现场十有八九栽在这，宁可提前装好。

5.4 模型文件路径写死，换机器就崩

现象：在自己电脑上跑得好好的，拷到演示机器上启动报Unable to open shape_predictor_68_face_landmarks.dat。

原因：源码里有绝对路径，比如C:/Users/名字/Desktop/.../models/shape_predictor_68_face_landmarks.dat。换机器后用户名、路径层级变了，自然打不开。课程设计的代码里看到绝对路径要直接警醒。

解决：改成相对路径，用os.path.join(os.path.dirname(__file__), "models", "shape_predictor_68_face_landmarks.dat")，这样无论项目摆在哪个盘符都能找到模型文件。顺带检查模板里所有模型引用，统一走models/目录。我把这个作为固定习惯：每份课设代码交出去前，全局搜索盘符路径。

5.5 识别结果反复横跳，同一个人一会认识一会不认识

现象：同一张脸，距离有时 0.3 有时 0.5，识别结果不稳定。

原因：实时识别每帧画面有轻微模糊，num_jitters=1时特征提取对噪声敏感，加上摄像头自动曝光不断变化，特征向量会抖动。

解决：注册照片用num_jitters=10，实时识别用num_jitters=1，再在比对前把连续 3 帧的识别结果做投票。窗口内至少 2 帧判成同一人，才显示最终姓名。这个「平滑」逻辑课设报告里可以写成一节「提高系统鲁棒性的策略」，十分加分。也可以把采集到的识别帧保存下来，事后检查是画面质量问题还是特征问题，避免闭眼瞎调。

5.6 中文路径导致 CV2 读不出图片

现象：known_faces目录里放的是data/known_faces/张三/，但程序打印cv2.imread返回None。

原因：OpenCV 的imread在 Windows 下对中文路径支持不好，路径里含中文时读不出图片且不报错。这是 OpenCV 多年来的老毛病，不是你的代码逻辑问题。

解决：把known_faces的父目录全部改为英文路径，比如D:/face_proj，只保留人名文件夹的中文。人名放在文件夹名层显示，路径层不经过中文就不会触发问题。如果非要在代码里处理，可以改用np.fromfile读二进制再cv2.imdecode解码，但课设没必要绕这个弯，改名最稳。

6. 交付演示前的一套自检技巧：让 dlib 人脸识别课设现场不翻车

答辩和演示是课设的最后一步，也是翻车高发区。我自己经历过「界面打不开、摄像头被占用、光线太暗认不出人」三重打击之后，养成了一套演示前的固定自检流程，正好可以借这个项目讲一下具体怎么操作。

第一项是「离线自检脚本」。启动 GUI 前，先用命令行跑一遍核心链路：读入一张本人照片，提取特征，与 known_faces 里所有注册人脸比对，打印相似度矩阵。这一步能验证模型路径、特征库、比对函数全部正常，排除 80% 的启动期事故。脚本很短，十几行，但要确保它能在演示机器上独立运行。第二项是「阈值回退」。演示现场灯光和摄像头通常跟开发环境不一样，为了降低「误把本人认成陌生人」的风险，我一般会在正式演示前把阈值从 0.36 放宽到 0.42。注意这里有个分寸：放宽太多会导致冒充者也能通过，0.42 是课设场景里我能接受的平衡点。第三项是「外接摄像头优先」。笔记本内置摄像头在答辩室容易被其他进程占用，带上一个 USB 摄像头，索引设为 1，比现场跟设备较劲可靠得多。

还有一个必须验证的点是「连续运行稳定性」。我会让程序跑 20 分钟不关机、不间断识别人脸，观察内存增长和帧率下降情况。某次课设演示前，程序跑了 15 分钟之后识别延迟从 0.3 秒涨到 3 秒，原因是识别循环里每帧都在往attendance_records.csv写入数据且未关闭文件句柄，积累大量磁盘 IO。加一个「距上次写入超过 5 秒才落盘」的判断后解决。从那以后，我每次做这类实时识别项目都会强制走一遍长时运行测试，不只看功能通不通，还要看能不能持久稳定地通。希望这个习惯也能帮你在答辩现场少一点心跳加速，多一点从容操作。

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