简介这是一套适合Python初学者的入门级人脸识别项目代码包覆盖人脸检测、特征提取、匹配识别三大核心环节。压缩包大小为3.33MB共13个文件包含5个py脚本、6张jpg测试图像和2张png图片脚本与示例图片配套可直接运行观察效果。代码中既能看到基于OpenCV Haar级联分类器的人脸检测实现也涉及PCA/LDA特征提取和余弦相似度匹配等经典方法并配有可用于实验的样例图像便于理解从像素到特征向量的转换过程。Python脚本与示例图片一一对应方便对照输出结果调试参数对于希望结合动手实践掌握计算机视觉基础的中级学习者这套代码能帮助快速建立人脸识别技术框架同时提供了扩展至深度学习模型的参考路径。资源已有160人学习下载文件组织简洁适合自学与课程作业参考。1. 为什么人脸识别代码要从Python入手调试体验与学习曲线在人脸识别项目里选型第一件事不是选算法而是选语言。很多工业项目用C或Java落地但如果你要快速验证“人脸检测-特征提取-身份比对”这条链路Python是最容易跑通的选择。原因很直接OpenCV、dlib、face_recognition、InsightFace这些库都有Python绑定社区示例多到随手可抄。我自己经历过从Java切换到Python做原型的过程原本需要手动管理内存的模型加载在Python里用一个列表就能把多张人脸的特征向量接住。下面我会从零开始写一套可离线运行的人脸识别代码只组合成熟算法把“人传人”式的人脸流转流程跑通既适合在公司内部做门禁机演示也给毕设或边缘设备预研留了可扩展的接口。2. 人脸识别算法选型从Haar、DNN到人脸向量模型2.1 先分清人脸检测和人脸识别别混用很多人说“人脸识别代码”时其实只写了人脸检测——把脸框出来然后程序就不知道是谁了。真正的识别要分两步检测人脸在哪和识别这张脸是谁。检测的输出是人脸框坐标识别的输出是身份ID或置信度。如果你用的是OpenCV自带的Haar级联分类器那只能做检测不能做识别。想识别就得在检测基础上提取人脸特征向量再和一个底库做比对。这里就引出“人脸——特征向量——身份”的传递链条也就是标题里说的“人传人人脸”。2.2 检测模型选型Haar、HOG、DNN与RetinaFace人脸检测的公共参数是速度与召回率。选型时先问三个问题跑在CPU还是GPU侧脸多不多目标人的最小像素尺寸是多少检测方案模型体积CPU实时性抗遮挡/侧脸典型场景Haar Cascades约1MB较好差只吃正脸文档扫描、手机解锁辅助HOG Linear SVM约80MB一般中能接受轻微偏转静态图片、低功耗DSPOpenCV DNN (SSD/RFB)约5-10MB好中上对光照鲁棒摄像头实时、门禁机MTCNN约6MBPNet/RNet/ONet差较好能出5点对齐高精度标注、GPURetinaFace约16MB差好带密集关键点质量要求高的识别链路Haar在2010年前是主力现在只适合做快速预筛。OpenCV DNN的SSD模型是MobileNet-SSD在树莓派上可以跑到15到20帧每秒适合瘦死的边缘设备。MTCNN和RetinaFace会先缩放图像金字塔所以CPU上会掉帧但返回的关键点信息对后续对齐非常关键。我的常见做法是如果只用OpenCV系列就用OpenCV DNN做检测如果后续识别要追求门禁机级别精度检测换成RetinaFace或MTCNN再把检测框传给下一级特征模型。2.3 人脸特征模型dlib、face_recognition与InsightFace检测完人脸后需要把框内图像压缩成一个向量。常见的人脸识别算法有三个层次face_recognition封装了dlib的128维ResNet特征接口只有两行适合入门和内部工具。缺点是模型老对极端光照和儿童脸容易翻车。dlib提供68点关键点检测和128维特征模型训练数据来自LFW精度中等。好处是可离线、跨平台坏处是安装麻烦。InsightFace/ArcFace现在工业界主流用ArcFace损失训练的512维特征在LFW、MegaFace上指标领先且对侧脸、口罩遮挡更稳。如果做人脸识别门禁机这类产品推荐直接用InsightFace的输出做比对。选型时不要迷信越新越好。如果你的底库只有几十人face_recognition完全够用。如果要做大量数据的人群识别ArcFace类模型更合适。后面所有代码都以face_recognition为主因为它的API固定方便你看懂流程换成InsightFace时只需要替换特征提取部分。2.4 特征比对欧氏距离与余弦相似度人脸特征向量的维度常见有128维dlib/face_recognition、256维、512维ArcFace。识别本质是比较两个向量。比对方式一般为欧氏距离越小越像取值范围理论上0到无穷。face_recognition的compare_faces的tolerance参数使用的就是归一化后的欧氏距离。余弦相似度越大越像取值范围-1到1。需要提前对向量做L2归一化再算点积。一个容易被忽略的点不同模型输出的向量空间不同阈值不能通用。dlib的0.6与InsightFace的0.6意义完全不一样。每次更换模型都要重新采集一批底库样本标定阈值否则识别率全是幻觉。3. 用Python跑通最小人脸识别代码安装、依赖与第一个识别结果3.1 环境准备Python版本与依赖清单热词里大量出现python安装、python入门这里直接给出可复制的命令。我通常用Python 3.10或3.11避免3.12下dlib某些旧版本编译失败。装依赖前先建虚拟环境python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install --upgrade pip pip install opencv-python numpy cmake dlib face-recognition参数说明cmake是dlib编译需要Windows用户必须装Visual Studio Build Tools才有C编译环境。如果你不想自己编译dlib可以尝试pip install dlib-bin或者在Anaconda里用conda install -c conda-forge dlib。face_recognition会自动安装dlib但版本可能不是最新的遇到接口报错时先看版本。如果这一步失败最常见的坑是没有安装cmake、没有Python开发头文件、或者pip下载源码超时。建议先装cmake再装dlib最后装face_recognition分开执行。不要盲目信任网上那些一键安装的命令尤其是csdn上转载的老博客很多依赖已经过时。3.2 最小人脸识别代码编码已知人脸并比对先写一个最小可运行脚本。这个脚本解决“这张照片是不是张三”的问题。import face_recognition # 加载已知人脸并计算特征向量 known_image face_recognition.load_image_file(alice.jpg) alice_encoding face_recognition.face_encodings(known_image)[0] # 加载未知图片 unknown_image face_recognition.load_image_file(test.jpg) unknown_encodings face_recognition.face_encodings(unknown_image) # 如果没人脸直接返回不匹配 if not unknown_encodings: print(未检测到人脸) else: results face_recognition.compare_faces([alice_encoding], unknown_encodings[0], tolerance0.6) distance face_recognition.face_distance([alice_encoding], unknown_encodings[0])[0] print(f是否匹配: {results[0]}, 距离: {distance:.4f})逻辑说明load_image_file直接读图返回RGB数组face_encodings内部依次完成检测、对齐、特征提取返回一个list。因为一张图可能有多张脸所以代码里取第一个人的边界框。compare_faces会把tolerance转换成距离阈值小于阈值视为同一人。face_distance给你原始距离方便后续自己定阈值。注意一个问题face_encodings(known_image)[0]如果原图中没有人脸会抛IndexError生产代码里要提前判断长度。3.3 实时摄像头人脸识别代码从图片到视频帧接下来的代码是很多教程都会写的摄像头识别但我会把缩放、多目标匹配、显示三部分的坑直接标出来。import face_recognition import cv2 import numpy as np known_face_encodings [] known_face_names [] def register_face(name, image_path): img face_recognition.load_image_file(image_path) encodings face_recognition.face_encodings(img) if len(encodings) 0: raise ValueError(f{image_path} 中没检测到人脸) known_face_encodings.append(encodings[0]) known_face_names.append(name) register_face(Li, li.jpg) register_face(Chen, chen.jpg) video_capture cv2.VideoCapture(0) if not video_capture.isOpened(): raise RuntimeError(摄像头无法打开可能被占用或驱动有问题) while True: ret, frame video_capture.read() if not ret: break # 缩小帧到1/2提高处理速度 small_frame cv2.resize(frame, (0, 0), fx0.5, fy0.5) rgb_small_frame cv2.cvtColor(small_frame, cv2.COLOR_BGR2RGB) # 当前帧的人脸位置与特征 face_locations face_recognition.face_locations(rgb_small_frame) face_encodings face_recognition.face_encodings(rgb_small_frame, face_locations) # 逐个匹配 for face_encoding, face_location in zip(face_encodings, face_locations): matches face_recognition.compare_faces(known_face_encodings, face_encoding, tolerance0.5) name Unknown if True in matches: distances face_recognition.face_distance(known_face_encodings, face_encoding) best_match_index np.argmin(distances) if matches[best_match_index]: name known_face_names[best_match_index] top, right, bottom, left face_location # 因为缩小过画框要乘2 top * 2; right * 2; bottom * 2; left * 2 cv2.rectangle(frame, (left, top), (right, bottom), (0, 255, 0), 2) cv2.putText(frame, name, (left, top - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2) cv2.imshow(Face Recognition, frame) if cv2.waitKey(1) 0xFF ord(q): break video_capture.release() cv2.destroyAllWindows()这段代码里face_locations返回top、right、bottom、left注意顺序不要记错。face_recognition.face_locations默认使用HOG模型如果想让检测更准可以加参数modelcnn但CPU上帧率会明显下降。cv2.resize缩小操作非常关键——face_recognition对越小的图检测越快但对太小的脸会漏检。一般把短边限制在480到640之间比较合适。3.4 常见坑IndexError、编译失败与接口变化IndexErrorface_encodings返回空列表说明检测漏了。解决办法是换检测模型或检查图片有没有真的加载成功。dlib安装失败最常见是无法找到dlib的C库。在Ubuntu上先sudo apt install build-essential cmakeWindows要安装Visual Studio Build Tools。接口版本face_recognition的老教程使用的内部结构在不同版本中有微调。遇到AttributeError时先print(face_recognition.__version__)确认版本。提示不要在for循环里反复调用load_image_file读取同一个人脸底库图片应该一次性加载并缓存成向量。4. 人脸识别代码的工程化人脸对齐、特征比对与阈值调优4.1 为什么要先做人脸对齐人脸检测框是矩形的但人脸的姿态、拍摄角度会让五官在框内错位。直接把这个框传给特征提取模型同一个人会因为角度差几度而得到差别很大的特征向量。所以正规的人脸识别代码里检测和人脸对齐是紧耦合的。对齐的物理意义是把两只眼睛和鼻子的位置扭到一个标准坐标系让特征模型拿到的输入尽量是正面照。人脸识别门禁机上最常见的现象是同一人正面识别通过低头或侧脸就变成Unknown。答案不是调大阈值而是先检查有没有对齐。如果你用RetinaFace检测它会同时返回5个关键点直接用这些关键点做相似变换即可。如果你用face_recognition它内部已经默认做了对齐但它的对齐依赖68点模型对极端遮挡依然会失效。4.2 用dlib手工做关键点对齐的Python代码一个可靠的对齐实现只需要三组点左眼外角、右眼外角、鼻子。dlib的68点索引中36是左眼外角45是右眼外角30是鼻尖。使用OpenCV的estimateAffinePartial2D可以直接求得相似变换矩阵。下面代码把对齐后的脸统一缩放到200x200。import cv2 import dlib import numpy as np detector dlib.get_frontal_face_detector() predictor dlib.shape_predictor(shape_predictor_68_face_landmarks.dat) def align_face(img, left_eye, right_eye, nose): # 源点左眼、右眼、鼻尖 src_points np.array([left_eye, right_eye, nose], dtypenp.float32) # 目标点标准坐标左眼(0.35,0.25)、右眼(0.65,0.25)、鼻尖(0.5,0.45) dst_points np.array([(0.35, 0.25), (0.65, 0.25), (0.5, 0.45)], dtypenp.float32) transform, _ cv2.estimateAffinePartial2D(src_points, dst_points) aligned cv2.warpAffine(img, transform, (200, 200)) return aligned # 调用示例 img cv2.imread(input.jpg) gray cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) rects detector(gray, 1) if len(rects) 0: landmarks predictor(gray, rects[0]) left_eye (landmarks.part(36).x, landmarks.part(36).y) right_eye (landmarks.part(45).x, landmarks.part(45).y) nose (landmarks.part(30).x, landmarks.part(30).y) aligned_face align_face(img, left_eye, right_eye, nose) cv2.imwrite(aligned.jpg, aligned_face)理解这段代码的关键在于estimateAffinePartial2D它只计算旋转、缩放和平移不计算裁剪和投影正好符合人脸对齐的需求。目标点是相对坐标最终输出被缩放到200x200。如果你要处理非正脸还可以增加两个嘴角点做仿射变换但对大多数门禁场景三点对齐已经够用。4.3 特征比对阈值怎么调tolerance 与验证集很多项目上线后出现问题都在于直接把网上代码里的tolerance0.6拿过来用。不同场景、不同摄像头分辨率、甚至不同年龄段人群合适的阈值都不同。我的标定方法准备三类图片正样本同一个人多角度多天拍摄、负样本不同人、空背景图然后跑一个阈值扫描。import face_recognition import numpy as np def threshold_tuning(known_paths, positive_paths, negative_paths): known [] for path in known_paths: img face_recognition.load_image_file(path) enc face_recognition.face_encodings(img)[0] known.append(enc) pos_dists [] for path in positive_paths: img face_recognition.load_image_file(path) enc face_recognition.face_encodings(img)[0] pos_dists.append(face_recognition.face_distance(known, enc).min()) neg_dists [] for path in negative_paths: img face_recognition.load_image_file(path) enc face_recognition.face_encodings(img)[0] neg_dists.append(face_recognition.face_distance(known, enc).min()) for threshold in np.arange(0.3, 0.8, 0.05): tp sum(1 for d in pos_dists if d threshold) fp sum(1 for d in neg_dists if d threshold) fn len(pos_dists) - tp tn len(neg_dists) - fp acc (tp tn) / (len(pos_dists) len(neg_dists)) print(ftolerance{threshold:.2f}, ACC{acc:.3f}, FP{fp}, FN{fn}) # 示例 threshold_tuning([alice.jpg], [alice_1.jpg, alice_2.jpg], [bob.jpg])注意这段代码直接用全部负样本没做交叉验证。正式标定时要按人分组防止同一人出现在正负样本里。表格式的经验数据如下但不要当标准用。tolerance安全方向误识别率适用场景0.4更严格很低门禁、支付0.5平衡低考勤、单机验证0.6更宽松中快速通行、手机4.4 底库从list到faiss大量数据的比对当底库超过几百个人用list做for循环比对会很慢。这时常见做法是把所有人脸向量全部堆叠成矩阵用faiss做近似最近邻检索。import faiss import numpy as np # 假设 known_face_encodings 是一个list encodings np.array(known_face_encodings, dtypenp.float32) # L2归一化让点积等价于余弦相似度 faiss.normalize_L2(encodings) dim encodings.shape[1] index faiss.IndexFlatIP(dim) index.add(encodings) # 查询时也要归一化 query np.array([face_encoding], dtypenp.float32) faiss.normalize_L2(query) scores, idx index.search(query, k1) if scores[0][0] 0.6: # 余弦阈值需自行标定 print(命中, known_face_names[idx[0][0]]) else: print(Unknown)faiss的IndexFlatIP是暴力内积搜索数据量大时换IndexIVFFlat。但注意faiss索引一旦构建新增人脸需要重建或使用IndexIDMap。而且归一化这一步必须在训练和查询时都用同一套预处理否则阈值会漂移。5. 人脸识别代码在门禁机与边缘设备上的部署验证技巧5.1 先把“摄像头回放”跑通再做真机联调很多项目卡在“摄像头前一站代码就崩”因为摄像头依赖环境难以重复。我的技巧是做成视频文件回放模式代码里用一个参数切换视频源。source test_video.mp4 # 0 表示摄像头 cap cv2.VideoCapture(source) while cap.isOpened(): ret, frame cap.read() if not ret: cap.set(cv2.CAP_PROP_POS_FRAMES, 0) # 循环播放 continue # 复用上一章的识别逻辑帧数据统一走函数接口这样做的好处是能拿着同一段视频在不同机器上对比帧率和准确率还能检查是不是某个特定帧导致检测器崩掉。实际部署到人脸识别门禁机上大多数模块比如tx510人脸识别模块接受的是jpeg流或视频流你仍然可以用这段伪摄像头代码模拟输入避免调试时把人锁在门外。5.2 定量验证帧率、耗时与失败率怎么记录记录识别结果时不要只print用CSV记录每帧的时间戳、检测人数、匹配身份、距离值。用脚本统计平均识别耗时、最大耗时和失败率。下面是一段记录逻辑。import csv from time import time with open(metrics.csv, w, newline) as f: writer csv.writer(f) writer.writerow([ts, face_count, name, distance, duration_ms]) while True: start time() # 处理一帧得到 faces_info这是你识别函数的结构化返回 duration_ms (time() - start) * 1000 for info in faces_info: writer.writerow([info[ts], info[count], info[name], info[distance], duration_ms])最后一条建议在真实代码里关闭cv2.imshow窗口也能省下5%到10%的帧率损失。部署到边缘设备时尽量使用无界面模式运行把识别结果通过MQTT或HTTP发送出去。本文还有配套的精品资源点击获取