EasyFace 项目使用指南：从核心功能到个性化配置

核心功能模块解析：快速定位你需要的工具

当你需要选择合适的人脸检测模型时，了解项目的功能模块分布是第一步。EasyFace 将核心能力分为五大功能集群，每个模块都对应特定的应用场景。

人脸检测引擎：多种算法满足不同精度需求

功能说明：提供从轻量级到高精度的全系列人脸检测解决方案，包含 MTCNN、RetinaFace、MogFace 等主流算法。

应用场景：

• 移动设备部署：选择 ULFD 模型（face_project/face_detection/ulfd_slim/）
• 高精度场景：使用 DamoFD 模型（face_project/face_detection/DamoFD/）
• 实时性要求高的场景：优先考虑 MogFace（face_project/face_detection/MogFace/）

注意事项：不同模型的性能指标差异显著，如 DamoFD 在 WIDER Face 数据集上的 Easy 子集精度可达 95.81%，但参数规模是轻量级模型的 20 倍以上。

人脸特征处理：从识别到活体检测的全流程支持

功能说明：包含人脸关键点检测、特征提取、活体判断等完整处理链，支持戴口罩识别等特殊场景。

应用场景：

• 身份验证系统：使用 arcface 特征提取（modelscope/models/cv/face_recognition/torchkit/backbone/）
• 反欺诈场景：启用红外活体检测（data/test/images/face_liveness_xc.png）
• 公共安全领域：部署口罩识别模型（data/test/images/mask_face_recognition_1.jpg）

模型训练与优化：打造专属人脸AI模型

功能说明：提供完整的训练脚本和优化工具，支持从数据准备到模型部署的全流程。

应用场景：

• 自定义数据集训练：修改 face_project/face_detection/DamoFD/train_damofd_10g.py 配置
• 模型压缩：使用 trainers 模块中的压缩工具（modelscope/trainers/hooks/compression/）
• 性能评估：通过 tests/pipelines/ 下的测试脚本验证模型指标

快速上手流程：5分钟启动你的第一个人脸检测任务

当你拿到一个新的AI项目，最想知道的一定是"如何最快跑通 demo"。以下步骤将帮助你从环境搭建到获得检测结果，全程不超过300秒。

1. 准备工作：克隆代码与安装依赖

首先获取项目源码：

git clone https://gitcode.com/gh_mirrors/eas/EasyFace
cd EasyFace

安装核心依赖：

pip install -r requirements.txt

2. 运行基础人脸检测 demo

执行 RetinaFace 检测示例：

python face_project/face_detection/RetinaFace/test_retina_face_detection.py

查看输出结果：检测后的图片会保存在 data/test/images/ 目录，文件名为原文件名加 _detected 后缀。

3. 常见启动问题排查

问题1：ImportError: No module named 'modelscope' 解决：检查是否已安装所有依赖，执行 pip install -r requirements/cv.txt

问题2：模型文件下载失败 解决：手动下载模型文件并放置到 modelscope/models/ 对应目录，或检查网络连接

问题3：检测速度过慢 解决：降低输入图片分辨率，或切换到轻量级模型（如 ULFD）

个性化配置指南：让模型表现更符合你的需求

当你需要调整检测灵敏度、优化运行速度或适配特定硬件时，合理的配置修改能显著提升系统表现。

定制检测参数：平衡精度与速度

配置文件路径：modelscope/pipelines/cv/retina_face_detection_pipeline.py

关键参数说明：

• confidence_threshold: 检测置信度阈值（默认0.5）
  • 提高到0.7可减少误检，适合背景简单场景
  • 降低到0.3可提高召回率，适合复杂场景
• nms_threshold: 非极大值抑制阈值（默认0.4）
  • 取值越小，保留的边界框越少
• input_size: 输入图片尺寸（默认640x640）
  • 减小尺寸可提升速度，如320x320适合实时场景

选择合适的模型配置：根据硬件条件调整

不同模型性能对比（在WIDER Face数据集上）：

推荐配置方案：

• 高性能GPU环境：选择 SCRFD-34GF，参数9.8M，精度95.81%
• 普通PC环境：选择 SCRFD-2.5GF，参数0.67M，速度提升4倍
• 嵌入式设备：选择 DDSAR-0.5GF，参数0.26M，FLOPs仅0.52G

数据路径配置：使用自定义数据集

修改 modelscope/pipelines/cv/face_detection_pipeline.py 中的：

DATA_CONFIG = {
    'test_path': 'data/test/images',  # 修改为你的图片目录
    'batch_size': 8,                  # 根据内存调整
    'num_workers': 4                  # CPU核心数
}

注意事项：自定义数据集需遵循 VOC 格式，或修改数据加载器适配你的数据格式。

通过以上配置，你可以将EasyFace调整为最适合你应用场景的状态。无论是安防监控、身份验证还是移动应用，合理利用这些配置选项都能让系统发挥最佳性能。