serengil/deepface

Docker化的DeepFace：容器化人脸识别与面部属性分析服务

项目地址：https://github.com/serengil/deepface
视频教程：[***]

概述

Docker化的DeepFace是一个基于开源项目DeepFace构建的容器化服务，提供人脸识别与面部属性分析功能。该服务封装了DeepFace的核心能力，通过RESTful API接口提供人脸验证、年龄/性别/情绪/种族预测及人脸特征向量生成等功能，支持多种预训练模型和人脸检测后端，便于快速集成到各类应用系统中。

核心功能与特性

• 人脸验证：判断两张人脸图像是否属于同一人，支持VGG-Face等多种预训练模型、OpenCV等检测后端及余弦距离等相似度度量
• 面部属性分析：预测人脸的年龄、性别（男/女）、情绪（愤怒/厌恶/恐惧/快乐/中性/悲伤/惊讶）及种族/ethnicity（亚洲人/黑人/印度人/拉丁裔/中东人/白人），返回主导属性及各属性概率
• 人脸特征向量生成：提取人脸的高维特征向量，用于人脸识别、聚类或检索任务
• 灵活输入方式：支持通过URL或Base64编码字符串传入图像
• 容器化部署：简化依赖管理与环境配置，支持跨平台快速部署

使用方法

1. 拉取镜像

首先，拉取最新的DeepFace镜像：

shell
docker pull docker.xuanyuan.run/serengil/deepface

2. 启动服务

运行容器以启动DeepFace服务：

shell
docker run -p 5005:5000 docker.xuanyuan.run/deepface

服务将在 http://localhost:5005 启动。可通过浏览器访问该地址确认服务是否正常运行。

3. API接口使用

服务提供以下API接口，可通过HTTP POST请求调用。https://github.com/serengil/deepface/blob/master/deepface/api/postman/deepface-api.postman_collection.json%E6%8F%90%E4%BE%9B%E8%AF%A6%E7%BB%86%E8%B0%83%E7%94%A8%E7%A4%BA%E4%BE%8B%E3%80%82

3.1 人脸验证

通过 http://localhost:5005/verify 端点验证两张人脸是否相似。

请求体：

json
{
  "img1_path": "https://raw.githubusercontent.com/serengil/deepface/master/tests/dataset/img1.jpg",
  "img2_path": "https://raw.githubusercontent.com/serengil/deepface/master/tests/dataset/img2.jpg",
  "model_name": "VGG-Face",
  "detector_backend": "opencv",
  "distance_metric": "cosine"
}

响应示例：

json
{
  "detector_backend": "opencv",
  "distance": 0.42272907319751785,
  "facial_areas": {
    "img1": {
      "h": 768,
      "left_eye": [850, 524],
      "right_eye": [571, 517],
      "w": 768,
      "x": 339,
      "y": 218
    },
    "img2": {
      "h": 491,
      "left_eye": [858, 388],
      "right_eye": [663, 390],
      "w": 491,
      "x": 524,
      "y": 201
    }
  },
  "model": "VGG-Face",
  "similarity_metric": "cosine",
  "threshold": 0.68,
  "time": 3.39,
  "verified": true
}

说明：响应中的 verified 字段指示验证结果（true 为相似，false 为不相似）。支持使用Base64编码字符串替代URL作为图像输入。

3.2 面部属性分析

通过 http://127.0.0.1:5005/analyze 端点分析人脸的年龄、性别、情绪及种族。

请求体：

json
{
  "img_path": "https://raw.githubusercontent.com/serengil/deepface/master/tests/dataset/img1.jpg",
  "actions": ["age", "gender", "emotion", "race"]
}

响应示例：

json
{
  "results": [
    {
      "age": 31,
      "dominant_emotion": "sad",
      "dominant_gender": "Man",
      "dominant_race": "white",
      "emotion": {
        "angry": 10.380517944035775,
        "disgust": 0.34448695919073113,
        "fear": 41.99173247912735,
        "happy": 0.031012031045239443,
        "neutral": 2.4377143829805394,
        "sad": 44.47406298231328,
        "surprise": 0.34046527596231985
      },
      "face_confidence": 0.89,
      "gender": {
        "Man": 99.99207258224487,
        "Woman": 0.007924179953988642
      },
      "race": {
        "asian": 1.6582146286964417,
        "black": 0.2634486649185419,
        "indian": 1.1727581731975079,
        "latino hispanic": 41.77250564098358,
        "middle eastern": 10.031893849372864,
        "white": 45.10117769241333
      },
      "region": {
        "h": 681,
        "left_eye": null,
        "right_eye": null,
        "w": 681,
        "x": 1436,
        "y": 336
      }
    }
  ]
}

说明：actions 字段指定需要分析的属性（可选值：age、gender、emotion、race），响应返回各属性的预测结果及主导属性。支持Base64编码图像输入。

3.3 人脸特征向量生成

通过 http://127.0.0.1:5005/represent 端点生成人脸的特征向量。

请求体：

json
{
  "model_name": "VGG-Face",
  "detector_backend": "opencv",
  "img": "https://raw.githubusercontent.com/serengil/deepface/master/tests/dataset/img1.jpg"
}

响应示例：

json
{
  "results": [
    {
      "embedding": [
        0.013881363057331663,
        0.0865466348140943,
        0.00843181578293164,
        0.08922029773772754,
        0.009442750920063645,
        0.0585725425777175,
        0.010859464741657977,
        // ...（省略部分向量元素）
      ],
      "face_confidence": 0.92,
      "facial_area": {
        "h": 768,
        "left_eye": [850, 524],
        "right_eye": [571, 517],
        "w": 768,
        "x": 339,
        "y": 218
      }
    }
  ]
}

说明：响应中的 embedding 字段为高维特征向量，可用于人脸识别、相似度计算或聚类任务。

引用

如果在研究中使用DeepFace，请引用以下文献：

BibTeX
@article{serengil2024lightface,
  title     = {A Benchmark of Facial Recognition Pipelines and Co-Usability Performances of Modules},
  author    = {Serengil, Sefik and Ozpinar, Alper},
  journal   = {Bilisim Teknolojileri Dergisi},
  volume    = {17},
  number    = {2},
  pages     = {95-107},
  year      = {2024},
  doi       = {10.***/gazibtd.***},
  url       = {[***]},
  publisher = {Gazi University}
}