企业官网建设流程全解析

简介：面向Python开发者和计算机视觉学习者，这份人脸识别与专注度检测源码包以OpenCV、dlib与face_recognition为核心技术栈，覆盖人脸考勤打卡和专注度分析两类典型应用场景。压缩包共161个文件、约437.34MB，内含100余张测试图片、22个Python源码、9个级联分类器配置、多个人脸关键点与识别模型，以及可直接运行的GUI演示程序和辅助工具；目录按训练、检测、界面模块分层，便于按需研读。已有662人学习下载。项目完整覆盖摄像头视频流读取、人脸检测与关键点定位、专注度判断、考勤比对、数据记录到通知触发的落地链路，各模块间的调用关系清晰。阅读源码与模型调用代码，可以掌握传统特征和深度学习方法在人脸任务中的工程化实现，理解数据库存储、异常处理与日志记录等细节，适合在此基础上扩展自己的考勤系统或注意力监测原型。

1. 人脸识别与专注度检测：这份 Python 源码能把哪些事落地

拿到这套 python 人脸识别与专注度检测源码时，我的第一反应是"又一个课堂打卡 Demo"。真正跑了两个小时之后我改了判断——它不只有人脸识别，还带完整的专注度打分逻辑，能把"坐在屏幕前的人是否在认真看"量化成 0 到 100 的分数，并实时写入 CSV，直接对接课堂专注度统计、远程办公状态自查这类需求。

这套源码适合两类人：一类是刚学完 Python 基础、想找一个有深度的完整项目练手的人，能从代码里看到图像处理、特征提取、状态机分层的真实工程写法；另一类是想在在线课堂或自习室场景加走神提醒的开发者，不需要懂深度学习理论，能跑通脚本、改参数就能用。它真正解决的不是"算法多先进"，而是"人脸识别加行为状态分析这一整套管道能不能稳定落地"。

2. 系统架构与选型：人脸识别加专注度检测的四层管道

先看整体架构。这套源码的核心不是某个单一算法，而是把视频帧处理拆成一条四层管道：采集层从摄像头或视频文件读取帧，检测层定位人脸并提取 68 点特征点，分析层计算 EAR、头部姿态角等专注度特征并给出 0～100 的分数，输出层负责把结果画在画面上、写入 CSV 或触发提醒。先看懂这条管道，后面调参、排错、扩展才有地方下刀。很多初学者拿到源码就在main.py里逐行死磕，我建议反过来，先画一遍数据流，再按层去读代码。

2.1 技术栈拆解：OpenCV、Dlib 与 face_recognition 的分工

这套项目最常见的实现组合是 OpenCV + Dlib + face_recognition 三个库。OpenCV 负责视频读取、灰度转换、画框和文字叠加，Dlib 负责用 HOG 检测器定位人脸、用 68 点特征点模型标出眼睛、鼻尖、下巴等关键位置，face_recognition 在 Dlib 之上封装了人脸编码与人脸比对，三个库各管一层，职责清楚。人脸识别门禁机、课堂点名系统这类产品用的也是同一套"检测 + 特征点 + 编码比对"的原理，只是换成了工业级模型。

安装命令如下，建议在虚拟环境里执行：

pip install opencv-python pip install dlib pip install face_recognition pip install numpy

提示：face_recognition 会自动拉取 dlib，但 dlib 在 Windows 上经常编译失败，建议先单独装好 dlib 再装 face_recognition，避免装到一半工程翻车。

为什么选这套组合，而不是现在热门的 YOLO v8 或 ArcFace？YOLO v8 做学生专注度检测，检测精度确实更好，还自带目标分类，但推理耗时长，想要实时流畅基本得靠 GPU，对一份面向学习与二次开发的源码来说门槛偏高；ArcFace 人脸识别精度高，但要额外做人脸对齐、模型转换和部署，工程成本大。Dlib 组合的优点足够明显：生态成熟、文档多、不依赖 GPU，普通笔记本 CPU 就能跑到 15～20 FPS。缺点是侧脸、低头角度过大和极端光照下鲁棒性一般，所以它的适用边界是固定摄像头、正脸为主的场景。场景一旦变成无约束的开放式识别，就不该指望这份源码，直接换工业级方案更省时间。

2.2 专注度评分算法：EAR、头部姿态角与注意力窗口三类特征

专注度判定是这份源码最有价值的部分，它不靠"猜"，而是把三类可计算的指标喂给一个状态机。第一类是 EAR（Eye Aspect Ratio，眼部纵横比），用 68 点特征点中的眼睛关键点坐标计算。人清醒注视时眼睛睁开，EAR 值在 0.25～0.35 之间；打瞌睡或走神低头时眼皮下垂，EAR 会明显掉到 0.1 以下。代码对左右眼各算一次取平均，降低单眼的定位误差。

第二类是头部姿态角。通过鼻尖、下巴、左右眼外角等 6 个特征点，配合标准 3D 人脸模型做 PnP 解算，得到 yaw、pitch、roll 三个欧拉角。其中 pitch 角（低头角度）是判断"低头看手机、趴桌"的关键特征，也是一堆误报的来源——很多人习惯把手撑在下巴上，pitch 角会周期性抖动，单帧判定很容易被带偏。简化实现大致是这样：

# 标准 3D 人脸点与当前图像 2D 点做 PnP 解算 object_pts = np.float32([[6.8, -7.2, 0], [6.2, 7.2, 0], ...]) image_pts = np.float32([[nose_x, nose_y], [chin_x, chin_y], ...]) _, rvec, tvec = cv2.solvePnP(object_pts, image_pts, camera_matrix, dist_coeffs) pitch = np.degrees(np.arctan2(rvec[0][0], rvec[2][0]))

第三类是注意力窗口。单帧的 EAR 和姿态角都有噪声，代码里维护一个默认 30 帧（约 1 秒）的滑动窗口，统计窗口内低关注帧的占比，再映射成 0～100 的专注度分数。窗口参数直接决定系统性格：窗口越大分数越平滑但响应越迟钝，窗口越小反应越快但容易被单帧抖动骗到。实际项目中我建议窗口放在 15～45 这个区间，具体值取决于摄像头帧率，帧率越高越可以放心用大窗口。

这套"指标 + 状态机"的方案，和直接把视频帧扔给 CNN 做专注/走神二分类的方案相比，最大差别是有明确的物理含义。出问题时，你能从 EAR 原始值、pitch 角数值直接定位是哪一环坏了，而不是对着一个黑匣子干瞪眼。这也是源码类资源比"开箱即用 API"更适合学习的原因——你能看到分数背后的每一个特征是怎么算出来的。

2.3 源码目录与核心模块的对应关系

拿到源码先别急着装依赖，花两三分钟把目录结构过一遍。规范的人脸识别项目通常会按职责拆成下面这些模块：

我每次拿到新项目，都习惯先打开config.py把所有参数读一遍，再按main.py→face_detector.py→focus_engine.py→recognizer.py的顺序读代码。因为大部分运行期问题都藏在参数和路径配置里，而不是藏在算法逻辑里。这张表可以存下来，后面读代码和排错时对照着看，能省不少时间。尤其是config.py，我见过太多人改参数直接改在main.py里，最后代码改得乱七八糟，还不如老老实实走配置文件。

3. 从零跑通：Python 环境、模型文件与首次运行的三步走

这一章解决"怎么让它跑起来"。我假设你的系统是 Windows 10/11，Python 版本 3.8～3.10，这个组合是 dlib 和 face_recognition 兼容性最稳的区间。Python 3.11 以上装 dlib 基本要自己编译，新手别碰，原因在第 5 章的避坑第一条里会展开。如果你的机器是 macOS 或 Linux，安装命令里把venv\Scripts\activate换成source venv/bin/activate即可，依赖逻辑完全一样。

3.1 环境准备：Python 3.10 虚拟环境与依赖安装

先建虚拟环境，把项目依赖和系统环境隔离开，免得以后装别的项目时把包搞乱。虚拟环境是 Python 项目的基本功，这里不展开讲，按命令走就行：

python -m venv venv venv\Scripts\activate pip install --upgrade pip pip install opencv-python numpy

如果你连 Python 还没装，先去 python.org 下载 3.10 版本安装包，安装时勾选 Add Python to PATH，这一步不勾，以后命令行里找不到 python 命令，又得折腾半天。装完在终端输入python --version确认版本号，再去建虚拟环境，顺序不要反。

dlib 单独装。Windows 下最快的路径是找对应 Python 版本的预编译 wheel，比如dlib-19.24.2-cp310-cp310-win_amd64.whl，直接指定文件安装。装完先验证再继续：

python -c "import dlib; print(dlib.__version__)"

能输出版本号说明 dlib 装好了。如果输出报错，要么是装到了错误的虚拟环境，要么是 Python 版本跟 wheel 不匹配。这一步验证非常关键，我见过不少人跳过验证直接装 face_recognition，装完才发现 dlib 根本没装上，后面所有报错都找不到源头，白白浪费一下午。

3.2 首次运行：模型文件、人脸注册与最小复现

依赖装好后，先检查models/目录。里面必须有两个文件：shape_predictor_68_face_landmarks.dat（约 99MB）和dlib_face_recognition_resnet_model_v1.dat（约 24MB）。这两个是 dlib 官方训练的模型，源码包通常会附带，但如果是从网上下载的裁剪版，经常会把模型文件拆出去单独发。缺失时程序会直接抛异常退出，这也是"明明装好了依赖却跑不起来"的第一大原因。

模型就位后，启动摄像头检测：

python main.py --camera 0 --config config.py

看到实时画面、人脸被框住、框上方显示名字和分数，就算最小复现成功。首次运行建议先拍一张正面清晰的照片放到data/known_faces/目录做注册，这样识别结果才能显示具体人名而不是 Unknown。注意注册照片最好直接从摄像头截一帧，而不是用一张完全不同的证件照，光照和角度差异会影响比对通过率。

如果启动后画面是黑的，先检查摄像头索引是否正确，再用系统自带的相机应用确认摄像头没被别的程序占用。Windows 下摄像头被占用时 OpenCV 会返回全黑帧，程序不报错但画面是黑的，这个现象特别容易误导人。另外，项目一般也支持--video test.mp4指定视频文件，这给后面的离线回归验证留了后路。

3.3 参数调优：五个核心阈值怎么设才不误判

config.py里的参数决定了系统的性格，核心参数就五个：

调参是这门项目里最像"玄学"的阶段，因为每个阈值都和环境强相关，换一个摄像头、换一种光照，最优值就变了。正确的做法是：固定摄像头位置和光照，录一段 3 分钟正常工作的视频和一段 3 分钟的走神视频，然后用--video离线跑两段视频，对比分数曲线去调阈值。别一边看直播画面一边盲改，那样你根本分不清是参数问题还是光线问题。

我自己的流程是：先调RECOGNITION_TOLERANCE让人脸识别稳定，再调EAR_THRESHOLD和PITCH_THRESHOLD让单帧状态合理，最后动窗口参数控制平滑度，一层一层来。调参过程中强烈建议每改一个参数就记录一次结果，我当时用一张表格维护参数组合和对应的误报、漏报次数，比自己凭感觉调靠谱得多。

4. 核心代码走读：EAR、头部姿态与专注度状态机怎么串

跑通之后就该读代码了。这一章挑三个最关键的函数走读，让你明白分数是怎么算出来的，出问题也知道去哪看。注意，所有特征点计算都依赖 dlib 的 68 点索引约定，索引写错一个，算出来的分数就全是错的。

4.1 人脸检测与 68 点特征点提取的封装

face_detector.py里的核心封装是这样：

import dlib import cv2 class FaceDetector: def __init__(self, shape_predictor_path: str): self.detector = dlib.get_frontal_face_detector() self.predictor = dlib.shape_predictor(shape_predictor_path) def get_landmarks(self, frame): """返回人脸框和 68 点特征点，没有人脸时返回 None""" gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) rects = self.detector(gray, 1) # 上采样 1 次，提升小脸检测率 if len(rects) == 0: return None, None rect = rects[0] # 只取最大人脸，适合单人专注度场景 landmarks = self.predictor(gray, rect) return rect, landmarks

注意两个细节。一是detector(gray, 1)的第二个参数 1 是图像上采样次数，上采样能从灰度图里多捞到一些小尺寸人脸，但耗时接近翻倍；如果要检测画面里的全部人脸，改成遍历rects而不是只读rects[0]。二是先转灰度再检测，dlib 的 HOG 检测器基于灰度特征，直接传彩色图反而多一次无意义的转换。

68 点特征点的索引是 dlib 模型的固定约定：0～16 是下巴轮廓，17～21 是左眉，22～26 是右眉，27～35 是鼻梁和鼻翼，36～41 是左眼，42～47 是右眼，48～67 是嘴部轮廓。后面所有 EAR、姿态角计算都依赖这套索引，我见过有人把左眼索引写成 42～47，导致闭眼识别完全不生效，查了整整一个下午才发现是索引抄反了。如果要做课堂后排的多人专注度统计，需要把"只取最大人脸"改成"遍历全部人脸并逐个算 EAR"，代价是 CPU 占用明显上升，帧率可能掉到 8～10 FPS，这是单人场景和多人场景最本质的差别。

4.2 EAR 分值与专注度状态机的实现

focus_engine.py里的 EAR 计算是这条管道最核心的一块：

def eye_aspect_ratio(landmarks): """计算眼部纵横比，返回左右眼的平均值""" # dlib 68 点模型中，左眼索引 36-41，右眼索引 42-47 left_eye = landmarks[36:42] right_eye = landmarks[42:48] def ear(eye): # 垂直距离两段，水平距离一段 v1 = dist(eye[1], eye[5]) v2 = dist(eye[2], eye[4]) h = dist(eye[0], eye[3]) return (v1 + v2) / (2.0 * h) return (ear(left_eye) + ear(right_eye)) / 2.0

EAR 是一个归一化比值，跟相机距离无关、跟人脸大小无关，所以天生适合做阈值判断。正常的睁眼 EAR 在 0.25～0.35 之间，闭眼能掉到 0.1 以下。如果你发现分数一直偏低，先打印几帧 EAR 原始值看看是不是落在这个区间，这是排查的第一步。注意这里的dist是欧氏距离函数，实现就是np.sqrt((x1-x2)**2 + (y1-y2)**2)，不要自己再造轮子。

如果对 EAR 的分布心里没底，建议先跑一段 10 秒的睁眼视频和一段 10 秒的闭眼视频，把 EAR 均值打印出来，用自己的数据确定阈值，而不是照抄默认值。默认值是基于欧美人脸统计出来的，亚洲人脸型的眼皮褶皱、内眼角结构有差异，实际阈值和默认值偏差 0.03～0.05 都很正常。

分数不是单帧 EAR 直接给的，而是经过一个滑动窗口状态机：

from collections import deque class FocusEngine: def __init__(self, window_size=30, low_ratio=0.5): self.window = deque(maxlen=window_size) self.low_ratio = low_ratio def update(self, is_low): """每帧调用，推入本帧状态，返回 0~100 专注度分数""" self.window.append(0 if is_low else 1) if len(self.window) < self.window.maxlen: return 100 # 窗口未满时不打分，避免启动阶段误报 focus_ratio = sum(self.window) / len(self.window) return int(focus_ratio * 100)

窗口未满返回 100 的设计是故意为之：程序刚启动时人脸可能还没锁稳，强行打分只会产生一堆无意义的低分。窗口大小决定平滑度和灵敏度的取舍，我在部署到自习室场景时把窗口调到 45，让分数更稳定，不容易被一两次低头动作打断；在需要快速报警的监考场景则调回 15，宁可偶尔误报也不能漏掉一次长时间走神。这个取舍没有标准答案，完全取决于业务容忍度。

4.3 主循环、数据落盘与实时可视化

main.py里最核心的是主循环，它把前面几层串起来，典型写法是这样：

while cap.isOpened(): ret, frame = cap.read() if not ret: break rect, landmarks = detector.get_landmarks(frame) if landmarks is not None: ear = eye_aspect_ratio(landmarks) pitch = get_head_pitch(landmarks) is_low = (ear < config.EAR_THRESHOLD) or (abs(pitch) > config.PITCH_THRESHOLD) score = focus_engine.update(is_low) name = recognizer.identify(frame, rect) draw_ui(frame, name, score, rect) with open(focus_log, 'a', encoding='utf-8') as f: f.write(f"{timestamp},{person_name},{score:.1f}\n")

这个循环每秒执行 10～20 次，每一帧依次走完检测、打分、识别、绘制、落盘。需要留意的点是：识别（identify）是最耗时的操作，如果不需要每帧都识别，可以改成每 5 帧做一次，或者只在人脸刚出现时识别一次，能省下不少 CPU。CSV 落盘频率和帧率相同，1 分钟视频会生成 900～1200 行记录，长期跑一周会积累几十万行，所以做报表前要先按分钟或小时聚合，不能直接把原始 CSV 丢给 Excel。timestamp 建议直接用 ISO 格式字符串，比如2024-06-10 14:30:00，不要用纯数字时间戳，后面 pandas 解析日期还得再转换一次。

提示：CSV 路径建议用绝对路径或基于项目根目录拼接的相对路径，否则换目录运行后日志会写到找不到的地方。这个坑我踩过一次，数据全丢了才意识到。

5. 避坑指南：跑这套源码绕不开的五个现场问题

这一章是血泪经验，五条全部来自我实际运行时的现场问题，每条按现象、原因、解决来写，你遇到可以直接对照。

5.1 现象：pip install dlib报一堆 C++ 编译错误

原因：Windows 下没有预装的 C++ 编译器，pip 尝试从源码编译 dlib，而 dlib 的 CMake 构建依赖 Visual Studio Build Tools，环境里没有就整体失败，报错日志里全是error C++之类的片段，很多新手看到日志直接懵了。

解决：不跟它硬刚。先把 Python 版本固定到 3.10，然后从 pypi 或 GitHub Releases 找对应版本的预编译 wheel 直接安装，两分钟搞定。如果必须自己编译，先装cmake和visualcppbuildtools再pip install dlib，耗时 20 分钟以上，而且中间任何一步版本不对都会再来一轮。我现在统一 Python 3.10 + 预编译 wheel，这个坑再也没出现过。顺带说一句，pip install dlib之前先跑一下python --version确认当前终端用的是哪个解释器，避免装到全局环境去了。

5.2 现象：画面里没人脸，但专注度分数一直在 60～80 之间波动

原因：检测不到人脸时，不同版本的代码处理方式不一样——有些返回默认高分，有些把"没人脸"当作低关注帧推进窗口，后者就会导致分数乱跳，人离开座位后分数反而在中位波动，看起来很"玄学"。

解决：在focus_engine.py里加一行日志打印rect is None的频率，确认是不是检测丢帧。人离开座位理应是明确的低关注状态，正确做法是在主循环里把人脸缺失帧直接记为低关注，而不是跳过打分。另外 HOG 检测在纯 CPU 下通常只有 10～15 FPS，窗口 30 帧相当于 2～3 秒的跨度，分数更新会明显滞后，帧率不够就先缩小窗口到 15，再配合姿态角判定，效果会稳定很多。

5.3 现象：暗光环境下分数忽高忽低，帧间波动剧烈

原因：EAR 和姿态角都依赖特征点定位精度，暗光下灰度对比度低，dlib 的 68 点定位会抖动，EAR 单帧值噪声很大，阈值判定就跟着抖动，分数自然呈现明显的锯齿状。

解决：在进入检测前加一步自适应直方图均衡化cv2.equalizeHist，能显著提升暗光下特征点稳定性。再把 EAR 和阈值比较之前先做 5 帧滑动平均，相当于给输入加了一个小低通滤波器，抖动基本能消掉八成。这两个改动都非常小，但对暗光教室这类场景改善明显。注意equalizeHist只接受灰度图输入，所以在转灰度之后、检测之前调用，顺序不能反。

5.4 现象：注册了人脸照片，但识别结果一直显示 Unknown

原因：RECOGNITION_TOLERANCE阈值设得太严格，或者注册照片和实际运行画面的光照、角度差异太大，导致人脸编码的欧氏距离超过了阈值，比对不通过。

解决：先把阈值从 0.45 放宽到 0.55 测试，确认能稳定认出人之后再逐步收紧到 0.45 左右。注册照片尽量从摄像头直接截一帧，和运行时保持同域——同样的分辨率、光照方向、姿态。这是人脸识别里最容易被忽视的"同域注册"原则，用它替换掉随手上网找的证件照，识别率会有质的提升。如果换了多张照片还是认不出，打印一下比对距离的数值，看看实际距离离阈值有多远，距离太近说明照片太像，太远说明选错人了。

5.5 现象：启动报RuntimeError: Unable to load或直接闪退

原因：shape_predictor_68_face_landmarks.dat和dlib_face_recognition_resnet_model_v1.dat缺失或损坏。这两个模型不随 pip 安装自动下载，必须手动放进models/目录，很多裁剪版源码包把它们单独拆出来发布，下载漏了就会这样。

解决：先检查文件是否存在、大小是否跟官方一致，然后从 dlib 官方模型库重新下载放回models/。路径的话，我统一在config.py里用os.path.join(os.path.dirname(__file__), 'models', 'xxx.dat')拼接，避免项目被整体复制换目录后相对路径失效。这个习惯让我少踩了好几次"换机器就跑不起来"的坑。另外注意模型文件有几百 MB，下载完成后检查一下哈希或大小，避免下载中断产生半截文件。

6. 进阶玩法：把专注度检测从调试 Demo 变成可用小工具

项目稳定跑通后，这套源码真正的价值在于能低成本扩展成生产用途的小工具。我的建议是先不要急着改算法，先把"能不能稳定产出可信数据"这个地基打牢，再谈扩展。

6.1 分钟级聚合与报表输出

CSV 是逐帧写的，直接看没法得出结论。用 pandas 做分钟级聚合，一行脚本就能产出可读报表：

import pandas as pd df = pd.read_csv('focus_log.csv', names=['ts', 'name', 'score']) df['ts'] = pd.to_datetime(df['ts']) df['minute'] = df['ts'].dt.floor('min') report = df.groupby('minute')['score'].mean().reset_index() report.to_csv('focus_report.csv', index=False)

这样生成的报表每一行是一分钟的平均专注度，直接导入 Excel 或接 Grafana 画曲线都行。聚合粒度可以按需改，看长时段趋势就按 5 分钟聚合，看单次任务内的波动就按 30 秒聚合。

6.2 低专注度实时告警

默认只画框写 CSV 不够醒目，加一个告警层，连续 10 帧均值低于 40 才触发，避免每帧报警造成轰炸：

def check_alert(score_queue, last_alert_time): if len(score_queue) >= 10 and sum(score_queue) / 10 < 40: if time.time() - last_alert_time > 60: trigger_alert() # 提示音或 webhook 通知 return True return False

这里做了两级过滤：窗口内平均分数低才进入告警判断，两次告警间隔至少 60 秒，防止同一段走神被反复提醒。Webhook 通知用requests.post推到企业微信或钉钉机器人，代码量不超过 20 行，这个扩展让项目从"事后看日志"变成"实时提醒"。

6.3 用录制视频做回归验证

改完代码最怕"之前能跑现在不能跑"。我的习惯是把一段 5 分钟的摄像头录像存成 mp4，每次改动后都跑一遍python main.py --video test.mp4，对比输出 CSV 里分数超过 70 的帧占比，保证在可控误差范围内才算通过。这个回归流程看起来原始，但能拦住九成的低级回归问题。

从那以后，我每次拿到类似的人脸识别源码，都会强制自己先走一遍"环境安装 → 最小复现 → 参数扫描 → 录制回归"的流程，而不是急着改代码。很多看着像算法问题的现象，最后都只是环境或参数问题。希望这一步一坑的经验能帮到你，少走几步我当初走过的弯路。

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