# 目录
<!-- TOC -->
- [目录 ](#目录 )
- [RetinaFace描述 ](#retinaface描述 )
- [预训练模型 ](#预训练模型 )
- [模型架构 ](#模型架构 )
- [数据集 ](#数据集 )
- [环境要求 ](#环境要求 )
- [快速入门 ](#快速入门 )
- [脚本说明 ](#脚本说明 )
- [脚本及样例代码 ](#脚本及样例代码 )
- [脚本参数 ](#脚本参数 )
- [训练过程 ](#训练过程 )
- [用法 ](#用法 )
- [分布式训练 ](#分布式训练 )
- [评估过程 ](#评估过程 )
- [评估 ](#评估 )
- [模型描述 ](#模型描述 )
- [性能 ](#性能 )
- [评估性能 ](#评估性能 )
- [用法 ](#用法-1 )
- [继续训练预训练模型 ](#继续训练预训练模型 )
- [随机情况说明 ](#随机情况说明 )
- [ModelZoo主页 ](#modelzoo主页 )
<!-- /TOC -->
# RetinaFace描述
Retinaface人脸检测模型于2019年提出， ： ， ， ， ，
[论文 ](https://arxiv.org/abs/1905.00641v2 )：
# 预训练模型
RetinaFace使用ResNet50骨干提取图像特征进行检测。从ModelZoo获取ResNet50训练脚本， ，
操作步骤：
1. 从ModelZoo获取ResNet50训练脚本。
2. 根据```./src/network.py```中的ResNet修改ResNet50架构（ ， ）
3. 在ImageNet2012上训练ResNet50。
# 模型架构
具体来说， ， ， ， ，
# 数据集
使用的数据集： [WIDERFACE ](<http://mmlab.ie.cuhk.edu.hk/projects/WIDERFace/WiderFace_Results.html> )
获取数据集：
1. 点击[此处](< https: // github . com / peteryuX / retinaface-tf2 > )获取数据集和标注。
2. 点击[此处](< https: // github . com / peteryuX / retinaface-tf2 / tree / master / widerface_evaluate / ground_truth > )获取评估地面真值标签。
- 数据集大小： ，
- 训练集： ，
- 验证集： ，
- 测试集： ，
# 环境要求
- 硬件（ ）
- 准备GPU处理器搭建硬件环境。
- 框架
- [MindSpore ](https://www.mindspore.cn/install )
- 如需查看详情，请参见如下资源：
- [MindSpore教程 ](https://www.mindspore.cn/tutorial/training/zh-CN/master/index.html )
- [MindSpore Python API ](https://www.mindspore.cn/doc/api_python/zh-CN/master/index.html )
# 快速入门
通过官方网站安装MindSpore后， ：
- GPU处理器环境运行
```python
# 训练示例
export CUDA_VISIBLE_DEVICES=0
python train.py > train.log 2>& 1 &
# 分布式训练示例
bash scripts/run_distribute_gpu_train.sh 3 0,1,2
# 评估示例
export CUDA_VISIBLE_DEVICES=0
python eval.py > eval.log 2>& 1 &
OR
bash run_standalone_gpu_eval.sh 0
```
# 脚本说明
## 脚本及样例代码
```python
├── model_zoo
├── README.md // 所有模型的说明
├── retinaface
├── README.md // GoogLeNet相关说明
├── scripts
│ ├──run_distribute_gpu_train.sh // GPU分布式shell脚本
│ ├──run_standalone_gpu_eval.sh // GPU评估shell脚本
├── src
│ ├──dataset.py // 创建数据集
│ ├──network.py // RetinaFace架构
│ ├──config.py // 参数配置
│ ├──augmentation.py // 数据增强方法
│ ├──loss.py // 损失函数
│ ├──utils.py // 数据预处理
├── data
│ ├──widerface // 数据集
│ ├──resnet50_pretrain.ckpt // ResNet50 ImageNet预训练模型
│ ├──ground_truth // 评估标签
├── train.py // 训练脚本
├── eval.py // 评估脚本
```
## 脚本参数
在config.py中可以同时配置训练参数和评估参数。
- 配置RetinaFace和WIDER FACE数据集
```python
'name': 'Resnet50', # 骨干名称
'min_sizes': [[16, 32], [64, 128], [256, 512]], # 大小分布
'steps': [8, 16, 32], # 各特征图迭代
'variance': [0.1, 0.2], # 方差
'clip': False, # 裁剪
'loc_weight': 2.0, # Bbox回归损失权重
'class_weight': 1.0, # 置信度/类回归损失权重
'landm_weight': 1.0, # 地标回归损失权重
'batch_size': 8, # 训练批次大小
'num_workers': 8, # 数据集加载数据的线程数量
'num_anchor': 29126, # 矩形框数量，取决于图片大小
'ngpu': 3, # 训练的GPU数量
'epoch': 100, # 训练轮次数量
'decay1': 70, # 首次权重衰减的轮次数
'decay2': 90, # 二次权重衰减的轮次数
'image_size': 840, # 训练图像大小
'return_layers': {'layer2': 1, 'layer3': 2, 'layer4': 3}, # 输入特征金字塔的层名
'in_channel': 256, # DetectionHead输入通道
'out_channel': 256, # DetectionHead输出通道
'match_thresh': 0.35, # 匹配框阈值
'optim': 'sgd', # 优化器类型
'warmup_epoch': -1, # 热身大小，-1表示无热身
'initial_lr': 0.001, # 学习率
'network': 'resnet50', # 骨干名称
'momentum': 0.9, # 优化器动量
'weight_decay': 5e-4, # 优化器权重衰减
'gamma': 0.1, # 学习率衰减比
'ckpt_path': './checkpoint/', # 模型保存路径
'save_checkpoint_steps': 1000, # 保存检查点迭代
'keep_checkpoint_max': 1, # 预留检查点数量
'resume_net': None, # 重启网络，
'training_dataset': '', # 训练数据集标签路径，
'pretrain': True, # 是否基于预训练骨干进行训练
'pretrain_path': './data/res50_pretrain.ckpt', # 预训练的骨干检查点路径
# 验证
'val_model': './checkpoint/ckpt_0/RetinaFace-100_536.ckpt', # 验证模型路径
'val_dataset_folder': './data/widerface/val/', # 验证数据集路径
'val_origin_size': False, # 是否使用全尺寸验证
'val_confidence_threshold': 0.02, # 验证置信度阈值
'val_nms_threshold': 0.4, # 验证NMS阈值
'val_iou_threshold': 0.5, # 验证IOU阈值
'val_save_result': False, # 是否保存结果
'val_predict_save_folder': './widerface_result', # 结果保存路径
'val_gt_dir': './data/ground_truth/', # 验证集ground_truth路径
```
## 训练过程
### 用法
- GPU处理器环境运行
```bash
export CUDA_VISIBLE_DEVICES=0
python train.py > train.log 2>& 1 &
```
上述python命令在后台运行，
训练结束后，可在默认文件夹`./checkpoint/`中找到检查点文件。
### 分布式训练
- GPU处理器环境运行
```bash
bash scripts/run_distribute_gpu_train.sh 3 0,1,2
```
上述shell脚本在后台运行分布式训练，
训练结束后，可在默认文件夹`./checkpoint/ckpt_0/`中找到检查点文件。
## 评估过程
### 评估
- GPU处理器环境运行评估WIDER FACE数据集
在运行以下命令之前， ，
```bash
export CUDA_VISIBLE_DEVICES=0
python eval.py > eval.log 2>& 1 &
```
上述python命令在后台运行，
```python
# grep "Val AP" eval.log
Easy Val AP : 0.9437
Medium Val AP : 0.9334
Hard Val AP : 0.8904
```
或，
```bash
bash run_standalone_gpu_eval.sh 0
```
上述python命令在后台运行，
```python
# grep "Val AP" eval.log
Easy Val AP : 0.9437
Medium Val AP : 0.9334
Hard Val AP : 0.8904
```
# 模型描述
## 性能
### 评估性能
| 参数 | GPU |
| -------------------------- | -------------------------------------------------------------|
| 模型版本 | RetinaFace + Resnet50 |
| 资源 | NV SMX2 V100-16G |
| 上传日期 | 2020-10-16 |
| MindSpore版本 | 1.0.0 |
| 数据集 | WIDERFACE |
| 训练参数 | epoch=100, steps=536, batch_size=8, lr=0.001 |
| 优化器 | SGD |
| 损失函数 | MultiBoxLoss + Softmax交叉熵 |
| 输出 |边界框 + 置信度 + 地标 |
| 损失 | 1.200 |
| 速度 | 3卡：
| 总时长 | 3卡：
| 参数 (M) | 27.29M |
| 调优检查点 | 336.3M （
| 脚本 | [RetinaFace脚本 ](https://gitee.com/mindspore/mindspore/tree/master/model_zoo/official/cv/retinaface_resnet50 ) |
## 用法
### 继续训练预训练模型
- GPU处理器环境运行
```python
# 加载数据集
ds_train = create_dataset(training_dataset, cfg, batch_size, multiprocessing=True, num_worker=cfg['num_workers'])
# 定义模型
multibox_loss = MultiBoxLoss(num_classes, cfg['num_anchor'], negative_ratio, cfg['batch_size'])
lr = adjust_learning_rate(initial_lr, gamma, stepvalues, steps_per_epoch, max_epoch, warmup_epoch=cfg['warmup_epoch'])
opt = nn.SGD(params=net.trainable_params(), learning_rate=lr, momentum=momentum,
weight_decay=weight_decay, loss_scale=1)
backbone = resnet50(1001)
net = RetinaFace(phase='train', backbone=backbone)
# 如果resume_net不为None，
pretrain_model_path = cfg['resume_net']
param_dict_retinaface = load_checkpoint(pretrain_model_path)
load_param_into_net(net, param_dict_retinaface)
net = RetinaFaceWithLossCell(net, multibox_loss, cfg)
net = TrainingWrapper(net, opt)
model = Model(net)
# 设置回调
config_ck = CheckpointConfig(save_checkpoint_steps=cfg['save_checkpoint_steps'],
keep_checkpoint_max=cfg['keep_checkpoint_max'])
ckpoint_cb = ModelCheckpoint(prefix="RetinaFace", directory=cfg['ckpt_path'], config=config_ck)
time_cb = TimeMonitor(data_size=ds_train.get_dataset_size())
callback_list = [LossMonitor(), time_cb, ckpoint_cb]
# 开始训练
model.train(max_epoch, ds_train, callbacks=callback_list,
dataset_sink_mode=False)
```
# 随机情况说明
在train.py中使用mindspore.common.seed.set_seed()函数设置种子。
# ModelZoo主页
请浏览官网[主页](https://gitee.com/mindspore/mindspore/tree/master/model_zoo)。
