docs/PROJECT_README.md

深度学习人脸识别实践作业

本项目按 design/大作业.pptx 完成人脸验证大作业：读取作业给定 LFW 6000 对，使用 CASIA-WebFace 训练人脸特征模型，并输出准确率、ROC、混淆矩阵、训练记录和报告。

主结果不使用他人的人脸识别预训练权重。当前最终权重由本机从 pretrained=None 的 IR-ResNet18 开始，在可下载 CASIA-WebFace 镜像上训练，并用我们自己的 IR-ResNet18 checkpoint 做 hard-example self-distillation 微调得到。

进阶实验前的可复现基线见 baseline.md。该 baseline 使用第 21 轮本地 scratch InceptionResnetV1 权重、MTCNN margin=0，LFW 10 折准确率为 84.8500%。课程要求进阶见 advanced.md，使用从头训练的 IR-ResNet18 + ArcFace，LFW 10 折准确率为 94.1167%。自选进阶见 self_advanced.md，最终 LFW 10 折准确率为 94.7167%。

环境

工作目录固定为 /home/data1/data_mining。已创建 conda 环境：

conda activate data_mining

复现环境：

bash setup_env.sh
conda activate data_mining

关键配置：

• GPU：NVIDIA RTX PRO 6000 Blackwell Workstation Edition，约 96GB 显存
• PyTorch：torch==2.11.0+cu128
• torchvision：0.26.0+cu128
• Python：3.10
• facenet-pytorch==2.6.0 --no-deps

说明：早期尝试过旧版 CUDA wheel，但 torch 2.2.2+cu121 不支持 Blackwell sm_120；当前环境使用 cu128 GPU 版并已通过 CUDA 张量运算测试。

数据

CASIA-WebFace 训练集

PPT 标称 CASIA-WebFace 为 10,575 个身份、494,414 张图像。官方数据集需要申请，当前环境使用 Hugging Face 镜像 SaffalPoosh/casia_web_face 的 20 个 parquet 分片：

• 本地目录：data/raw/casia_webface_parquet
• 可下载镜像总量：490,592 张
• 镜像身份类别：10,572 类，label 范围覆盖 0..10571
• 图像格式：parquet 内 PNG bytes，RGB，112x112 对齐图

差额说明：镜像比 PPT 官方数字少 3,822 张和 3 个身份标签，推测来自镜像清洗或转换；本项目已训练当前可下载镜像的全部 490,592 张。

下载命令：

python src/download_casia_webface.py

LFW 测试集

• 测试对文件：design/lfw_test_pair.txt
• 图像目录：data/raw/lfw-deepfunneled
• 图像数量：13,233
• 测试对数量：6,000，其中同人 3,000 对、异人 3,000 对
• 唯一测试图片：7,701 张

官方 UMass LFW 地址在当前环境 DNS 解析失败，scikit-learn/Figshare 镜像返回 403，因此使用 Hugging Face 镜像 DerrickUnleashed/LFW 的 lfw-deepfunneled.zip。测试协议仍使用作业提供的 6000 对文件。

下载命令：

python src/download_lfw.py

预处理

训练阶段按 PPT “数据预处理”要求实现：

• 从 parquet 解码 RGB 图片并构建 DataLoader
• RandomResizedCrop(112, scale=(0.86, 1.0))
• RandomHorizontalFlip
• RandomRotation(10)
• ColorJitter
• fixed_image_standardization
• 分片、row group、样本级随机打乱

测试阶段使用 MTCNN 人脸检测对齐，输出 112x112；最终设置为 --mtcnn-margin 16，比 margin=0 保留更多脸部边界，更接近 CASIA 镜像的 112x112 对齐分布。

模型与训练

Baseline 模型：

• Backbone：InceptionResnetV1(pretrained=None, classify=False)
• Head：ArcFace ArcMarginProduct(512, 10572)
• Loss：ArcFace logits + cross entropy
• Optimizer：SGD + momentum + Nesterov
• Scheduler：CosineAnnealingLR
• Mixed precision：torch.amp.autocast + GradScaler
• Batch size：512
• Workers：12
• Device：CUDA

课程进阶模型：

• Backbone：IR-ResNet18(pretrained=None)
• Head：ArcFace ArcMarginProduct(512, 10572)
• Loss/optimizer/scheduler/AMP：同 baseline
• Batch size：512
• Workers：12
• Device：CUDA

自选进阶模型：

• Backbone：IR-ResNet18
• Teacher：models/advanced_ir18_arcface/epoch_020.pth，由本项目本地训练得到
• Student：从同一 checkpoint 初始化
• Loss：hard-example weighted ArcFace CE + embedding self-distillation
• 推理结构：仍为单个 IR-ResNet18 backbone

Baseline 训练命令：

TORCH_HOME=/home/data1/data_mining/models/torch \
python src/train_casia_parquet_arcface.py \
  --epochs 10 \
  --batch-size 512 \
  --num-workers 8 \
  --output-dir models/scratch_casia_arcface \
  --device cuda

TORCH_HOME=/home/data1/data_mining/models/torch \
python src/train_casia_parquet_arcface.py \
  --epochs 10 \
  --resume models/scratch_casia_arcface/latest.pth \
  --batch-size 512 \
  --num-workers 12 \
  --output-dir models/scratch_casia_arcface \
  --arc-margin 0.35 \
  --lr 0.02 \
  --device cuda

TORCH_HOME=/home/data1/data_mining/models/torch \
python src/train_casia_parquet_arcface.py \
  --epochs 1 \
  --resume models/scratch_casia_arcface/latest.pth \
  --batch-size 512 \
  --num-workers 12 \
  --output-dir models/scratch_casia_arcface \
  --arc-margin 0.35 \
  --lr 0.002 \
  --device cuda

第 21 轮训练日志明确记录：

samples_seen: 490592

即当前 CASIA-WebFace 镜像的全部样本已在训练中被读取。第 22-26 轮用于 margin 调参探索，也均覆盖 490,592 张，但 LFW 最佳 checkpoint 为第 21 轮。

课程进阶训练命令：

TORCH_HOME=/home/data1/data_mining/models/torch \
python src/train_casia_parquet_arcface.py \
  --backbone ir_resnet18 \
  --epochs 20 \
  --batch-size 512 \
  --num-workers 12 \
  --output-dir models/advanced_ir18_arcface \
  --arc-margin 0.35 \
  --lr 0.05 \
  --device cuda

第 20 轮训练日志记录 samples_seen: 490592，同样覆盖当前可下载 CASIA-WebFace 镜像的全部样本。训练期间 RTX PRO 6000 利用率可到约 99%，显存约 20GB，功耗约 474W。

自选进阶训练命令：

TORCH_HOME=/home/data1/data_mining/models/torch \
python src/train_casia_hsd_arcface.py \
  --epochs 5 \
  --batch-size 512 \
  --num-workers 12 \
  --output-dir models/self_hsd_ir18_arcface \
  --lr 0.003 \
  --distill-weight 1.0 \
  --hard-weight 1.0 \
  --hard-gamma 2.0 \
  --device cuda

自选进阶第 24 轮作为最佳 checkpoint，该轮 samples_seen: 490592，训练期间 GPU 利用率约 94%-99%，功耗约 484W-502W。

最终评测

自选进阶最终命令：

TORCH_HOME=/home/data1/data_mining/models/torch \
python src/evaluate_lfw.py \
  --lfw-root data/raw/lfw-deepfunneled \
  --pairs-file design/lfw_test_pair.txt \
  --checkpoint models/self_hsd_ir18_arcface/epoch_024.pth \
  --preprocess mtcnn \
  --mtcnn-margin 16 \
  --image-size 112 \
  --batch-size 512 \
  --num-workers 0 \
  --device cuda \
  --output-dir results/self_hsd_ir18_lfw_epoch24_margin16

评测协议：

• 对 7,701 张唯一图片提取 512 维 L2 归一化 embedding
• 对每对图片计算 cosine similarity
• 按作业 6000 对重组 10 折：每折 300 个同人对 + 300 个异人对
• 每折用其余 9 折选择阈值，在当前折测试

自选进阶最终结果：

指标	数值
LFW 10 折准确率	94.7167% ± 0.7819%
ROC AUC	0.974148
全局最优阈值	0.270818
全局最优准确率	94.8000%
10 折混淆矩阵 [[TN, FP], [FN, TP]]	[[2921, 79], [238, 2762]]
MTCNN 检测成功率	99.9870%

输出文件：

• results/self_hsd_ir18_lfw_epoch24_margin16/metrics.json
• results/self_hsd_ir18_lfw_epoch24_margin16/fold_metrics.csv
• results/self_hsd_ir18_lfw_epoch24_margin16/pair_scores.csv
• results/self_hsd_ir18_lfw_epoch24_margin16/roc_curve.png
• results/self_hsd_ir18_lfw_epoch24_margin16/confusion_matrix.png
• results/self_hsd_ir18_lfw_epoch24_margin16/score_histogram.png

最佳本地权重：

• models/self_hsd_ir18_arcface/epoch_024.pth
• models/self_hsd_ir18_arcface/best_lfw.pth 指向第 24 轮

对照实验

这些结果不作为主结果，只用于验证工程选择：

实验	LFW 10 折准确率
scratch epoch 10，MTCNN margin 0	83.4167%
baseline scratch epoch 21，MTCNN margin 0	84.8500%
baseline scratch epoch 21，MTCNN margin 16	86.4833%
scratch epoch 21，直接 resize 112	65.2333%
scratch epoch 22，MTCNN margin 0	84.7000%
scratch epoch 26，MTCNN margin 0 + flip TTA	84.6833%
课程进阶 IR-ResNet18 epoch 20，MTCNN margin 0	92.4333%
课程进阶 IR-ResNet18 epoch 20，MTCNN margin 16	94.1167%
自选进阶 HSD IR-ResNet18 epoch 24，MTCNN margin 0	93.4833%
自选进阶 HSD IR-ResNet18 epoch 24，MTCNN margin 16	94.7167%
外部 CASIA 预训练 FaceNet，MTCNN margin 0	95.8167%

报告

• 项目报告：reports/project_report.md
• 实验总报告：reports/final_experiment_report.md
• Baseline 说明：baseline.md
• 课程进阶说明：advanced.md
• 自选进阶说明：self_advanced.md
• 汇报提纲：reports/presentation_outline.md
• 执行状态：STATUS.md
• 自我任务提示：prompts/self_prompts.md