FaceX-Zoo

FaceX-Zoo 是一个用于人脸识别的 PyTorch 工具箱。它提供了一个包含多种监督头和骨干网络的训练模块，能够实现当前最先进的人脸识别性能；同时，还配备了一个标准化的评估模块，只需简单修改配置文件，即可在大多数常用基准上对模型进行评估。此外，我们还提供了一个简单但功能完善的面部 SDK，用于验证和初步应用训练好的模型。与尽可能多地集成现有技术不同，FaceX-Zoo 的设计旨在随着人脸相关领域的不断发展而轻松升级和扩展。有关该项目的更多详细信息，请参阅 技术报告。

关于名称：

• “Face”——本仓库主要用于人脸识别。
• “X”——我们也致力于提供超越人脸识别的功能，例如人脸解析、人脸增强等。
• “Zoo”——该仓库包含了大量算法和模型。

最新动态

• [2021年10月] 现已支持 Swin Transformer！我们使用 Swin-S 在 MegaFace rank1 协议中取得了 98.17% 的优异成绩。更多结果、预训练模型及日志请参阅 3.1 SOTA 骨干网络实验。如需使用 Swin Transformer 训练人脸识别模型，请参考 swin_training。请注意，输入尺寸为 224×224，而非 112×112，并且我们采用 AdamW + CosineLRScheduler 进行优化，而非 SGD + MultiStepLR。
• [2021年9月] 我们提供了 Dockerfile，用于构建该项目的 Docker 镜像。
• [2021年8月] RepVGG 已被添加到人脸识别的骨干网络中，RepVGG_A0、B0、B1 的性能可在 3.1 SOTA 骨干网络实验 中找到。
• [2021年7月] 一种名为 DMUE 的表情识别方法已被 CVPR 2021 接受，所有代码已在 addition_module/DMUE 中发布。
• [2021年6月] 我们在人脸识别任务上评估了一些知识蒸馏方法，相关结果和代码可在 face_lightning 模块中找到。
• [2021年5月] 用于将训练好的模型转换为 ONNX 格式以及提供的 SDK 格式的工具，可在 model_convertor 模块中找到。
• [2021年4月] IJB-C 1:1 协议已被添加到 evaluation module 中。
• [2021年3月] ResNeSt 和 ReXNet 已被加入骨干网络，MagFace 则被添加到分类头中。
• [2021年2月] 支持分布式训练以及通过 apex 实现的混合精度训练。请查看 distributed_training 和 train_amp.py。
• [2021年1月] 我们提交了 FaceX-Zoo 的初始版本。

系统要求

• python >= 3.7.1
• pytorch >= 1.1.0
• torchvision >= 0.3.0

模型训练

详情请参阅 training_mode 中的 README.md，目前支持常规训练和 半双生训练。

模型评估

详情请参阅 test_protocol 中的 README.md，目前支持 LFW、CPLFW、CALFW、RFW、AgeDB30、IJB-C、MegaFace 以及 MegaFace-mask。

面部 SDK

详情请参阅 face_sdk 中的 README.md，目前支持人脸检测、人脸对齐和人脸识别。

添加口罩功能

详情请参阅 FMA-3D 中的 README.md。

许可证

FaceX-Zoo 采用 Apache License, Version 2.0 许可证进行发布。

致谢

本仓库主要受到 InsightFace、InsightFace_Pytorch 和 face.evoLVe 的启发。我们衷心感谢这些项目作者所做出的宝贵贡献。

引用

如果本项目对您的研究有所帮助，请在您的出版物中引用我们的论文。BibTeX 引用如下：

@inproceedings{wang2021facex,
  author = {Jun Wang, Yinglu Liu, Yibo Hu, Hailin Shi and Tao Mei},
  title = {FaceX-Zoo: A PyTorh Toolbox for Face Recognition},
  journal = {Proceedings of the 29th ACM international conference on Multimedia},
  year = {2021}
}

如有任何问题，请联系 Jun Wang (wangjun492@jd.com)、Yinglu Liu (liuyinglu1@jd.com)、Yibo Hu (huyibo6@jd.com)、Hailin Shi (shihailin@jd.com) 和 Wu Liu (liuwu1@jd.com)。

FaceX-Zoo 快速上手指南

FaceX-Zoo 是一个基于 PyTorch 的人脸识别工具箱，提供多种先进的监督头（Supervisory Heads）和骨干网络（Backbones），支持标准化评估及人脸 SDK 应用。

环境准备

在开始之前，请确保您的系统满足以下最低要求：

• 操作系统: Linux (推荐 Ubuntu)
• Python: >= 3.7.1
• PyTorch: >= 1.1.0
• TorchVision: >= 0.3.0
• GPU: 推荐使用 NVIDIA GPU 以加速训练和推理

依赖安装建议： 建议使用 pip 并配置国内镜像源（如清华源）以加快下载速度。

pip install torch torchvision -i https://pypi.tuna.tsinghua.edu.cn/simple

若需使用混合精度训练或分布式训练，还需安装 apex：

git clone https://github.com/NVIDIA/apex
cd apex
pip install -v --no-cache-dir ./

安装步骤

1. 克隆仓库 从 GitHub 克隆项目代码到本地：

   git clone https://github.com/JDAI-CV/FaceX-Zoo.git
   cd FaceX-Zoo
   

2. 安装项目依赖 进入项目目录并安装所需的 Python 包：

   pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   

   (注：如果根目录下没有 requirements.txt，请根据 training_mode 或 face_sdk 下的具体需求手动安装常见库如 opencv-python, scikit-learn, tensorboard 等)

3. 可选：Docker 部署 项目提供了 Dockerfile，可直接构建环境：

   docker build -t facex-zoo -f docker/Dockerfile .
   

基本使用

FaceX-Zoo 主要包含模型训练、评估和 SDK 推理三个核心功能。以下是极简使用示例。

1. 模型训练 (Model Training)

支持常规训练和半孪生训练。以下是一个使用默认配置进行常规训练的示例命令（需自行准备数据集并修改配置文件）：

# 进入训练模块目录
cd training_mode/conventional_training

# 运行训练脚本 (示例：使用 SGD 优化器)
python train.py --config_file config/resnet50_ms1m.yaml

• 新特性支持：若使用 Swin Transformer，请参考 training_mode/swin_training，注意输入尺寸需调整为 224*224，并使用 AdamW + CosineLRScheduler。
• 分布式训练：

  python -m torch.distributed.launch --nproc_per_node=8 train_amp.py --config_file config/resnet50_ms1m.yaml
  

2. 模型评估 (Model Evaluation)

支持 LFW, IJB-C, MegaFace 等主流基准测试。只需编辑配置文件即可运行评估。

# 进入评估协议目录
cd test_protocol

# 运行评估脚本 (示例：运行 LFW 测试)
bash test_lfw.sh

• 对于 IJB-C 1:1 协议，可运行 bash test_ijbc.sh。
• 具体配置请在脚本中指定模型路径和数据集路径。

3. 人脸 SDK 推理 (Face SDK)

SDK 模块提供了人脸检测、对齐和识别的一站式功能，适用于验证和初级应用。

# 进入 SDK 目录
cd face_sdk

# 运行演示脚本 (需准备一张测试图片)
python demo.py --image_path ../data/images/test.jpg --model_path ../pretrained_models/ms1m_resnet50.pth

• 模型转换：如需将训练好的模型转换为 ONNX 格式或 SDK 专用格式，请使用 addition_module/model_convertor 中的工具。

---

更多详细算法实现、预训练模型及实验结果，请参阅项目各子模块下的 README.md 文件或官方技术报告。