简介这份资源是CVND计算机视觉纳米学位的第一个实战项目——面部关键点检测的完整代码与数据集面向具备Python与深度学习基础、希望掌握CNN回归任务与经典人脸检测流程的学习者。项目围绕眼睛、鼻子、嘴部关键点展开可应用于面部跟踪、姿态识别、滤镜与情感分析等场景。压缩包共约2000个文件整体330.12MB其中5774张jpg图像构成训练与测试样本9个ipynb笔记本对应数据加载可视化、CNN网络定义与训练、Haar级联结合CNN的完整检测管线以及趣味滤镜四个阶段另有xml级联文件、csv关键点标注、py模型脚本与说明文档目录结构清晰。已有200人学习。读者可据此复现从数据探索、网络搭建到端到端检测的全流程理解关键点回归的损失设计与数据增强思路并借助标注文件与预置脚本快速排错、迁移到自有人脸数据上。1. 从一张歪脸说起P1_Facial_Keypoints 到底在练什么很多人第一次跑人脸关键点检测都会遇到一个很玄学的问题明明训练 loss 降得挺漂亮一拿测试图出来左眼的关键点跑到右眼上去了或者整张脸的框歪了 15 度关键点就集体漂移。这不是模型笨而是你喂给它的数据里坐标和图像没对齐。P1_Facial_Keypoints 这个 CVNDComputer Vision Nanodegree的第一个项目练的就是这件事——把「人脸检测」和「关键点回归」拆开用 Jupyter Notebook 一步步把 68 个关键点从原始标注变成可训练、可预测、可可视化的完整链路。它不教你调 SOTA 模型而是逼你把数据清洗、坐标归一化、翻转增强、模型输出反变换这几步亲手写一遍。适合谁刚学完 CNN 想找个能跑通的小项目练手的人以及被「关键点漂移」坑过、想回头补数据对齐基本功的从业者。Jupyter Notebook 在这里不是噱头而是让你每跑一个 cell 就能看到图像和坐标的对应关系翻车当场就能定位。2. 数据管线拆解从标注文件到可训练张量2.1 为什么关键点项目必须先做坐标归一化人脸关键点回归和普通图像分类最大的区别在于分类任务关心「图里有没有猫」关键点任务关心「眼睛在图的哪个像素位置」。像素位置是绝对坐标图像一缩放、一裁剪坐标就全废了。所以这个项目里最核心的一步不是搭模型而是把绝对坐标转成相对坐标。常见做法是先用人脸检测器项目里用的是 OpenCV 的 Haar cascade 或 dlib框出人脸区域然后把 68 个关键点的绝对坐标减去人脸框左上角坐标再除以人脸框的宽和高。这样每个关键点的坐标就被压缩到 [0,1] 区间模型学的是「眼睛在脸框内相对位置」而不是「眼睛在第 237 像素」。这一步不做后面翻转增强、裁剪增强全都会把坐标带偏。我一般会先把标注文件读进 DataFrame检查有没有缺失值、有没有坐标超出图像边界的脏数据。这个项目的数据集里偶尔会出现关键点标到图像外面的情况直接拿去训练就是给模型喂噪声。import pandas as pd import numpy as np # 读取关键点标注文件每行是一张图的 68 个点坐标 df pd.read_csv(keypoints.csv) # 检查坐标是否越界正常像素坐标应该在 [0, 图像宽高] 之间 # 这里假设图像尺寸是 96x96 out_of_bound df[(df.iloc[:, 0::2] 0).any(axis1) | (df.iloc[:, 0::2] 96).any(axis1)] print(f越界样本数: {len(out_of_bound)}) # 丢弃越界样本避免训练时坐标回归目标本身就不合理 df_clean df.drop(out_of_bound.index).reset_index(dropTrue)这段代码做的是数据体检。df.iloc[:, 0::2]取的是所有 x 坐标列因为标注文件通常是 x0,y0,x1,y1… 交替排列。越界样本直接丢不要试图修补修补出来的坐标比丢掉更危险。2.2 翻转增强一行代码让样本翻倍但坐标要跟着翻数据增强里性价比最高的就是水平翻转。一张脸翻转之后还是脸关键点数量不变但每个点的 x 坐标要变成1 - x归一化之后或者width - x绝对坐标。这个项目里很多人翻车就翻在这里图像翻了坐标没翻模型学出来的眼睛位置永远是反的。import cv2 import numpy as np def flip_image_and_keypoints(image, keypoints): image: HxWxC 的 numpy 数组 keypoints: shape (68, 2) 的绝对坐标数组 flipped_image cv2.flip(image, 1) # 1 表示水平翻转 h, w image.shape[:2] flipped_keypoints keypoints.copy() # 水平翻转后 x 坐标变为 w - xy 坐标不变 flipped_keypoints[:, 0] w - flipped_keypoints[:, 0] return flipped_image, flipped_keypoints逻辑说明cv2.flip(image, 1)的第二个参数 1 代表绕 y 轴翻转也就是左右镜像。坐标变换只动 x 列w - x是绝对坐标下的正确映射。如果你已经做了归一化那就用1 - x。参数上唯一要注意的是翻转后的坐标可能因为浮点误差略微超出 [0,1]训练前 clip 一下就行。2.3 把人脸检测和关键点回归串成推理管线这个项目的完整推理流程是两段式的先用检测器框人脸再把框出来的区域送进关键点模型。很多人只训了关键点模型忘了检测器结果拿一张全图去预测模型直接懵掉。import cv2 import torch # 加载人脸检测器项目里常用 Haar cascade face_cascade cv2.CascadeClassifier(haarcascade_frontalface_default.xml) def predict_keypoints(image_path, keypoint_model): img cv2.imread(image_path) gray cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) faces face_cascade.detectMultiScale(gray, 1.1, 4) results [] for (x, y, w, h) in faces: # 裁剪人脸区域并缩放到模型输入尺寸 face_roi img[y:yh, x:xw] face_resized cv2.resize(face_roi, (96, 96)) # 转 tensor 并归一化 tensor torch.from_numpy(face_resized).permute(2,0,1).float() / 255.0 tensor tensor.unsqueeze(0) with torch.no_grad(): pred keypoint_model(tensor).squeeze().numpy() # pred 是归一化坐标还原到原图绝对坐标 pred pred.reshape(-1, 2) pred[:, 0] pred[:, 0] * w x pred[:, 1] pred[:, 1] * h y results.append(pred) return results这里的关键参数是detectMultiScale的scaleFactor1.1和minNeighbors4。scaleFactor 越小检测越慢但越不容易漏minNeighbors 越大误检越少但可能漏掉侧脸。我一般先用默认值跑一遍看漏检多还是误检多再调。坐标还原那两行是必须的模型输出的是相对坐标不还原回原图坐标系画出来的点全是错的。3. 模型搭建与训练别急着上 ResNet3.1 关键点回归网络的输出层该怎么设计关键点回归本质是回归问题不是分类。输出层不能用 softmax要用线性输出。68 个关键点每个点两个坐标所以输出维度是 136。这个项目里常见做法是卷积层堆几层后面接全连接最后一层不加激活函数。import torch.nn as nn class KeypointNet(nn.Module): def __init__(self): super(KeypointNet, self).__init__() self.conv nn.Sequential( nn.Conv2d(3, 32, 3, padding1), nn.ReLU(), nn.MaxPool2d(2), nn.Conv2d(32, 64, 3, padding1), nn.ReLU(), nn.MaxPool2d(2), nn.Conv2d(64, 128, 3, padding1), nn.ReLU(), nn.MaxPool2d(2), ) self.fc nn.Sequential( nn.Linear(128*12*12, 512), nn.ReLU(), nn.Dropout(0.3), nn.Linear(512, 136) # 68 个点 * 2 个坐标 ) def forward(self, x): x self.conv(x) x x.view(x.size(0), -1) return self.fc(x)输出层 136 维不加激活是因为坐标可以是任意实数归一化后在 0 到 1 之间但训练初期可能超出。损失函数用 MSELoss优化器用 Adam学习率 1e-3 起步。Dropout 加在 fc 层前面防止过拟合这个项目数据量不大不加 Dropout 很容易训练集 loss 降到 0.001 但验证集不降。3.2 训练循环里必须监控的两个量训练关键点模型光看 loss 不够。loss 是平均像素误差但平均误差小不代表每个点都对。我一般会在验证集上额外算一个「关键点命中率」预测点和真实点距离小于某个阈值比如 5 像素就算命中。def train_one_epoch(model, loader, criterion, optimizer, device): model.train() total_loss 0 for images, keypoints in loader: images images.to(device) keypoints keypoints.to(device).view(keypoints.size(0), -1) optimizer.zero_grad() outputs model(images) loss criterion(outputs, keypoints) loss.backward() optimizer.step() total_loss loss.item() return total_loss / len(loader) def evaluate(model, loader, device, threshold5.0): model.eval() hit, total 0, 0 with torch.no_grad(): for images, keypoints in loader: images images.to(device) outputs model(images).cpu().numpy() gt keypoints.numpy().reshape(-1, 68, 2) pred outputs.reshape(-1, 68, 2) # 计算每个点的欧氏距离 dist np.linalg.norm(pred - gt, axis2) hit (dist threshold).sum() total dist.size return hit / totalthreshold5.0是像素单位如果你的图像是 96x965 像素大概是脸宽的 5%这个阈值下命中率能到 80% 以上就算这个项目跑通了。注意keypoints.view(keypoints.size(0), -1)这一步把 (batch, 68, 2) 展平成 (batch, 136)和模型输出对齐。3.3 学习率调度什么时候该降降多少这个项目里我见过太多人用固定学习率跑到底loss 卡在 0.01 就不动了。常见做法是加一个ReduceLROnPlateau验证 loss 连续 5 个 epoch 不降就把学习率乘 0.1。scheduler torch.optim.lr_scheduler.ReduceLROnPlateau( optimizer, modemin, factor0.1, patience5, verboseTrue ) # 在每个 epoch 结束后调用 val_loss evaluate_loss(model, val_loader, criterion, device) scheduler.step(val_loss)patience5意味着给模型 5 次机会5 次还没进步才降。factor0.1是降幅不要设太小比如 0.5降了跟没降一样。这个调度器监控的是验证 loss不是训练 loss别传错。4. 避坑与排查那些让关键点集体漂移的坑4.1 现象训练 loss 正常但预测点全部偏向图像中心原因坐标归一化时用了整张图的宽高而不是人脸框的宽高。模型学到的是「点在图中心附近」因为大部分脸都在图像中间。解决归一化必须用人脸框的 w 和 h推理时还原也要用同一个框的 w 和 h。检查方法很简单随便取一张训练图把归一化坐标画回去看和原标注是否重合。4.2 现象翻转增强后模型对左右脸预测不对称原因翻转时只翻了图像没翻坐标或者翻了坐标但左右眼的索引没对应上。68 点标注里左眼和右眼的点索引是固定的翻转后索引不变但位置变了模型会学到矛盾的目标。解决翻转后不要交换索引只做坐标变换。因为翻转后的图像里原来的左眼点现在在右边但它的索引还是左眼索引模型学的是「这个索引对应的位置」不是「解剖学上的左眼」。如果你要交换索引那就要同时交换图像等于没翻。4.3 现象验证集 loss 比训练集低原因验证集没有做增强而训练集做了翻转增强增强后的样本分布和原始分布有差异模型在原始分布上反而表现更好。解决这不是 bug是正常现象。但如果你发现验证 loss 低得离谱检查一下验证集是不是太小或者验证集和训练集有重叠。这个项目数据量不大我一般会确保验证集至少占 20%并且和训练集完全隔离。4.4 现象推理时关键点画出来是乱的但模型输出数值看着正常原因模型输出是归一化坐标画图时忘了乘回人脸框的宽高或者乘了但忘了加框的左上角偏移。解决还原公式是x_abs x_norm * w x_toplefty_abs y_norm * h y_topleft。两步都不能少。我习惯在画图函数里强制断言坐标在图像范围内超出就报错这样能第一时间发现还原错误。4.5 现象换一张新图预测关键点全挤在一起原因新图的人脸尺寸和训练集差异太大模型没有见过这种尺度。这个项目训练集里的人脸基本都是 96x96 裁剪好的你拿一张 500x500 的全图直接送进去模型输出必然崩。解决推理前必须做和训练时一样的预处理检测人脸、裁剪、缩放到 96x96、归一化。少一步都不行。我一般会把预处理写成一个函数训练和推理共用避免不一致。5. 进阶技巧用可视化反推数据质量5.1 把关键点画回原图一眼看出标注问题这个项目最值钱的地方不是模型是 Jupyter Notebook 里那套可视化。我习惯在训练前先随机抽 20 张图把标注点画上去肉眼过一遍。很多标注错误比如点标到背景上、左右眼标反在数值上看不出来一画图就露馅。import matplotlib.pyplot as plt import cv2 def visualize_keypoints(image, keypoints, title): plt.figure(figsize(6,6)) plt.imshow(cv2.cvtColor(image, cv2.COLOR_BGR2RGB)) plt.scatter(keypoints[:,0], keypoints[:,1], s8, cr, marker.) plt.title(title) plt.axis(off) plt.show() # 随机抽 5 张检查 for idx in np.random.choice(len(df_clean), 5): img cv2.imread(df_clean.iloc[idx][image_path]) kp df_clean.iloc[idx].values[1:].reshape(-1,2).astype(float) visualize_keypoints(img, kp, fsample {idx})marker.和s8是为了让点足够小不遮挡人脸细节。画的时候注意 OpenCV 读进来是 BGRmatplotlib 显示要转 RGB不然人脸颜色是蓝的看着别扭但坐标是对的。5.2 用误差热力图定位模型弱项训练完之后不要只看一个平均命中率。把验证集所有样本的每个关键点误差算出来画成热力图你能清楚看到模型在哪个部位最差。通常嘴角、下巴这些纹理少、遮挡多的点误差最大。# 假设 all_dist 是 (N, 68) 的误差矩阵 mean_dist_per_kp all_dist.mean(axis0) plt.figure(figsize(12,4)) plt.bar(range(68), mean_dist_per_kp) plt.xlabel(keypoint index) plt.ylabel(mean pixel error) plt.title(per-keypoint error distribution) plt.show()如果发现某几个点的误差明显高于其他点回去检查这些点的标注一致性。我遇到过下巴点标注在轮廓内外跳的情况模型学不准是正常的这种数据要么修要么丢。5.3 一个我每次都会走的验证习惯从那以后我每次跑完关键点项目都会强制走一遍「单图全流程」拿一张从来没进过训练集的图从检测、裁剪、归一化、模型推理、坐标还原到画图完整跑一遍中间不跳任何一步。这一步能暴露 90% 的预处理不一致问题。很多人训练指标好看一上真实图就崩就是因为训练和推理的预处理是两套代码。希望帮到你。本文还有配套的精品资源点击获取