简介本资源为本科毕业设计项目源码主题是结合知识蒸馏训练人脸关键点检测的极小模型面向计算机、人工智能、通信工程、自动化等专业的在校学生与教师也适合作为课程设计、作业或项目立项演示的参考。项目代码经过完整测试运行成功后才上传答辩评审平均分达到96分适合希望学习模型压缩与轻量化部署的读者。压缩包共约2000个文件包含997个png图像、987个pts关键点标注、11个py源码脚本以及csv、json配置与md说明文档整体约408.9MB覆盖数据集、标注、训练与配置等环节。目前已有76人学习。读者可从中获取知识蒸馏训练极小模型的完整实现思路、人脸关键点检测的数据组织方式与代码结构并在此基础上修改扩展功能用于毕设、课设或进一步研究。1. 从 96 分毕设拆起这套知识蒸馏人脸关键点源码到底能跑出什么答辩能拿 96 分的本科毕设通常不是靠堆模型参数量而是靠一个说得清、跑得动、指标还过得去的小模型。这套源码的核心思路很直接用一个大的教师网络去教一个极小的人脸关键点检测学生模型让学生模型在参数量压到很低的情况下仍然能输出稳定的五官坐标。人脸关键点检测本身是很多下游任务的前置环节比如疲劳检测、表情识别、虚拟试妆、活体检测这些场景对模型体积和推理速度都很敏感所以「极小模型 知识蒸馏」这个组合在工程上是站得住脚的。这份资源适合三类人一是计算机、人工智能、通信、自动化等专业正在做毕设或课程设计的在校学生想找一个结构完整、能跑通、有答辩背书的项目二是刚入门 Python 和深度学习、想通过一个真实项目把训练流程走一遍的新手三是手上已经有业务场景、想拿一个小模型做人脸关键点 baseline 的从业者。它不是一个只放几张图的花架子annotation.csv和annotation_test.csv说明数据标注和划分是齐的README.md负责交代运行方式settings.json和c_cpp_properties.json说明工程配置也一并给了。接下来我按「这是什么 → 怎么用 → 坑在哪」的顺序把这份源码拆到能照着复现的程度。2. 知识蒸馏 人脸关键点先搞懂教师学生怎么分工2.1 为什么关键点检测适合做蒸馏人脸关键点检测本质是一个回归任务输入一张人脸图输出 N 个关键点的坐标常见的是 68 点或 5 点。回归任务和分类任务不一样它没有 softmax 输出的类别概率分布所以经典的知识蒸馏Hinton 那套用温度 T 软化 logits不能直接照搬。工程上更常用的是特征蒸馏和响应蒸馏教师网络中间层输出的特征图或者教师网络最终回归出的坐标作为学生网络的额外监督信号。这么做的理由是教师网络见过更多数据、容量更大它输出的坐标本身就带有「先验」——比如眼角应该在哪、嘴角的弧度大概是什么样。学生网络如果只学 ground truth容易在遮挡、大角度、低分辨率这些困难样本上抖得厉害加上教师的输出作为软目标相当于多了一个稳定的参照。常见做法是损失函数写成L L_gt λ * L_distillL_gt是学生预测和真实标注的 L1/L2 损失L_distill是学生和教师输出的距离λ控制蒸馏强度一般从 0.1 到 1.0 之间调。2.2 极小模型的「小」体现在哪「极小模型」不是随口说的它通常意味着几件事同时成立主干网络用深度可分离卷积或者 MobileNet 系列的倒残差结构通道数被压到很窄全连接层换成全局池化加一个小回归头。这样做的代价是表达能力下降收益是参数量可能只有教师网络的几十分之一推理时延能压到毫秒级方便部署到端侧。这份源码里settings.json一般就是放这类超参的地方——教师模型路径、学生模型通道配置、蒸馏温度或权重、训练轮数、学习率。c_cpp_properties.json是 VS Code 的 C/C 插件配置说明作者可能用到了某些需要编译的依赖或者只是编辑器环境配置不影响 Python 主流程。真正跑训练的时候重点看的是数据加载、模型定义、蒸馏损失这三块。2.3 数据标注格式先对齐annotation.csv和annotation_test.csv是训练集和测试集的标注文件。人脸关键点项目里CSV 的常见格式是第一列图片文件名后面每两个数字是一组(x, y)坐标按关键点顺序排列。比如 68 点就是 1 列文件名 136 列坐标。在动手之前先确认列数和关键点数量对得上否则后面 loss 会直接报维度不匹配。import pandas as pd # 读取标注文件先看结构 train_df pd.read_csv(annotation.csv) test_df pd.read_csv(annotation_test.csv) print(训练集样本数:, len(train_df)) print(测试集样本数:, len(test_df)) print(列名前 5 个:, list(train_df.columns[:5])) print(总列数:, train_df.shape[1]) # 假设第一列是文件名其余是坐标 coord_cols train_df.columns[1:] assert len(coord_cols) % 2 0, 坐标列数必须是偶数 num_points len(coord_cols) // 2 print(关键点数量:, num_points)这段代码的作用是先做一次数据体检。len(coord_cols) % 2 0这个断言很关键因为坐标一定是成对出现的如果列数是奇数说明 CSV 里混进了别的字段或者分隔符有问题。num_points算出来之后要和模型回归头的输出维度对上——如果模型输出 136 维关键点就是 68 个输出 10 维就是 5 个点。这一步不做后面训练报错会很难定位。3. 把源码跑起来环境、配置、训练三步走3.1 环境依赖与 Python 版本这类毕设源码通常基于 PyTorch因为知识蒸馏和自定义损失用 PyTorch 写起来最顺手。先确认 Python 版本建议 3.8 到 3.10 之间太新的版本有些老依赖会装不上。README.md里一般会写依赖清单如果没有按下面这套常见组合装。# 建议先建虚拟环境避免污染全局 python -m venv venv # Windows venv\Scripts\activate # Linux / macOS source venv/bin/activate # 安装核心依赖 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu pip install numpy pandas opencv-python pillow matplotlib tqdm这里把 torch 的安装源指向了官方 CPU 版本如果你有 NVIDIA 显卡并且装了 CUDA把cpu换成对应的cu118或cu121。opencv-python用来读图和画关键点pandas读 CSVtqdm看训练进度。装完之后用python -c import torch; print(torch.__version__)验证一下能打印出版本号就说明环境通了。3.2 settings.json 里的参数怎么读settings.json是这份源码的配置中心不同项目字段名可能不一样但核心就那么几类。下面给一个典型的字段映射表你对照自己下载的版本改。字段名常见含义建议值改动影响teacher_path教师模型权重路径源码自带或需自行训练路径错直接加载失败student_channels学生网络通道基数16 或 32越小模型越小精度越低distill_weight蒸馏损失权重 λ0.3 ~ 0.7太大压制 gt 学习太小蒸馏无效temperature蒸馏温度 T2 ~ 5只影响软目标平滑程度batch_size批大小16 ~ 64受显存限制lr学习率1e-3 ~ 1e-4太大不收敛太小训练慢epochs训练轮数50 ~ 200看早停和验证集曲线改参数的原则是先跑通默认配置确认 loss 能下降、验证集指标能涨再动distill_weight和student_channels做对比实验。很多新手一上来就把学生通道砍到 8结果模型根本学不动还以为是代码有问题。3.3 训练脚本的调用与日志观察源码里一般会有一个train.py或者类似的入口文件。运行之前先确认当前目录下有annotation.csv和图片文件夹路径不对是最常见的翻车点。# 典型训练入口具体文件名以 README 为准 python train.py --config settings.json # 如果脚本用 argparse 传参可能是这种形式 python train.py --train_csv annotation.csv --test_csv annotation_test.csv --epochs 100 --batch_size 32跑起来之后重点盯三个东西训练 loss 是否稳定下降、验证集的关键点误差通常用 NME归一化平均误差是否下降、显存占用是否爆掉。如果 loss 在前几个 epoch 就变成 NaN八成是学习率太大或者坐标没有归一化。如果 loss 下降但验证集不降说明过拟合可以加数据增强或者减小模型。如果显存不够先把batch_size减半再考虑把学生通道数调小。提示训练前把图片路径和 CSV 里的文件名对一遍Windows 下路径分隔符和大小写敏感问题经常导致读图失败。4. 蒸馏损失与关键点回归代码层面的关键改动点4.1 蒸馏损失函数怎么写知识蒸馏在人脸关键点任务里最直接的实现是让学生网络的输出逼近教师网络的输出。下面是一个可抄的损失组合L1 用于 gt 监督MSE 用于蒸馏监督两者加权求和。import torch import torch.nn as nn class DistillLandmarkLoss(nn.Module): def __init__(self, distill_weight0.5): super().__init__() self.distill_weight distill_weight self.l1 nn.L1Loss() # 对 ground truth 用 L1对异常值更鲁棒 self.mse nn.MSELoss() # 对教师输出用 MSE梯度更平滑 def forward(self, student_out, teacher_out, gt): # student_out / teacher_out: (B, 2*N) # gt: (B, 2*N) loss_gt self.l1(student_out, gt) loss_distill self.mse(student_out, teacher_out.detach()) total loss_gt self.distill_weight * loss_distill return total, loss_gt, loss_distillteacher_out.detach()这一步不能省它把教师网络的输出从计算图里摘出来避免梯度回传到教师网络。distill_weight就是前面说的 λ建议先用 0.5 跑一轮看loss_gt和loss_distill两条曲线的比例关系。如果loss_distill一直远大于loss_gt说明蒸馏项在主导训练学生可能被教师带偏这时候把 λ 调小。4.2 坐标归一化与反归一化关键点坐标的数值范围取决于图片分辨率直接拿像素值做回归loss 会很大训练不稳定。常见做法是把坐标除以图片宽高归一化到[0, 1]模型输出后再乘回去。def normalize_coords(coords, width, height): # coords: (B, 2N)偶数索引是 x奇数索引是 y coords coords.clone().float() coords[:, 0::2] / width coords[:, 1::2] / height return coords def denormalize_coords(coords, width, height): coords coords.clone().float() coords[:, 0::2] * width coords[:, 1::2] * height return coords0::2是 Python 切片表示从第 0 个元素开始每隔一个取一个正好拿到所有 x 坐标1::2拿到所有 y 坐标。归一化之后不同分辨率的图片就统一到同一个尺度模型学起来更稳。评估的时候记得反归一化回像素坐标否则算出来的 NME 没有意义。4.3 教师模型和学生模型的加载顺序蒸馏训练需要同时加载两个模型。教师模型只做前向不更新参数所以要设成eval()并且关闭梯度学生模型正常训练。teacher build_teacher_model() teacher.load_state_dict(torch.load(teacher.pth, map_locationcpu)) teacher.eval() for p in teacher.parameters(): p.requires_grad False student build_student_model() student.train() optimizer torch.optim.Adam(student.parameters(), lr1e-3) criterion DistillLandmarkLoss(distill_weight0.5)map_locationcpu是为了在没有 GPU 的机器上也能加载权重避免设备不匹配报错。requires_grad False关掉教师网络的梯度能省显存也能加快训练。如果源码里教师权重是分开给的确认路径写对如果没给教师权重就得先用大模型在训练集上训一个出来这一步不能省。5. 避坑与排查跑这套源码最容易翻车的五个地方5.1 现象读图报 None训练直接崩原因CSV 里的文件名和实际图片文件夹对不上或者图片路径拼接时少了目录层级。Windows 下反斜杠和正斜杠混用也会导致 OpenCV 读不到。解决在读图函数里加一层判断读不到就打印路径并跳过而不是让None进入后续流程。import cv2 import os def safe_read_image(img_dir, filename): path os.path.join(img_dir, filename) img cv2.imread(path) if img is None: print(f[警告] 读图失败: {path}) return None return img5.2 现象loss 变成 NaN原因学习率太大、坐标没归一化、或者蒸馏权重 λ 过大导致梯度爆炸。解决先把学习率降到 1e-4确认坐标已经归一化到[0, 1]再把distill_weight从 0.5 降到 0.1 试一轮。如果还是 NaN检查输入图片是否做了归一化除以 255。5.3 现象验证集指标不涨训练集 loss 一直降原因过拟合。毕设数据集通常不大学生模型虽然小但如果没有数据增强很容易记住训练集。解决加随机水平翻转、随机裁剪、亮度抖动。注意水平翻转时关键点的 x 坐标要同步镜像否则标注就错了。def flip_coords(coords, width): # 水平翻转后x 坐标变成 width - x coords coords.clone() coords[:, 0::2] width - coords[:, 0::2] return coords5.4 现象教师模型加载报 key 不匹配原因保存权重时用了DataParallel或者保存了整个模型而不是state_dict导致 key 里多了module.前缀。解决加载时做一次 key 清洗。state_dict torch.load(teacher.pth, map_locationcpu) new_state {k.replace(module., ): v for k, v in state_dict.items()} teacher.load_state_dict(new_state)5.5 现象推理速度没有想象中快原因学生模型虽然小但输入分辨率没降或者推理时没开torch.no_grad()白白算了梯度。解决推理阶段固定用with torch.no_grad():并且把输入尺寸对齐到模型设计的分辨率。如果部署到端侧还要考虑把模型导出成 ONNX 再做量化。注意改任何参数之前先把原始配置备份一份出问题能快速回退。6. 进阶玩法把蒸馏权重当调参旋钮用 NME 验证学生模型跑通之后真正决定这套毕设能不能拿高分的是你能不能拿出对比实验。我一般会固定学生模型结构只调distill_weight跑三组0.1、0.5、1.0然后统一用 NME 评估。NME 的计算方式是预测点和真实点的欧氏距离除以两眼间距或者人脸框对角线做归一化数值越小越好。import torch def compute_nme(pred, gt, norm_factor): # pred / gt: (B, 2N) pred pred.view(pred.size(0), -1, 2) gt gt.view(gt.size(0), -1, 2) dist torch.norm(pred - gt, dim2) # (B, N) nme dist.mean(dim1) / norm_factor return nme.mean().item()norm_factor通常用两眼之间的距离或者人脸框的宽高。用同一个 norm_factor 去比较不同配置结论才可信。如果 λ0.5 的 NME 比 λ0.1 低说明蒸馏确实起了作用如果三组差不多可能是教师模型本身不够强或者学生容量太小接不住教师的输出。另一个进阶方向是把教师模型换成更大的 backbone或者用多教师蒸馏。但毕设场景下我建议先把单教师这套跑透把训练曲线、NME 对比表、几张可视化结果图整理进论文这比堆新概念更稳。从那以后我每次拿到这类蒸馏源码都强制先跑一遍默认配置、记录 baseline NME再动任何参数——没有 baseline 的调参都是玄学。希望帮到你。本文还有配套的精品资源点击获取