人脸识别服务DOCKER安装说明

1. 简介

本项目基于dlib库实现了一个简单的人脸识别服务，使用FastAPI框架构建API接口，支持通过HTTP请求进行人脸注册和识别。
该服务可以部署在Docker容器中，方便用户快速搭建和使用人脸识别功能。

2. 安装部署

在线安装

离线安装

手工部署

3. 使用说明

3.1 启动服务

进入服务部署目录，执行以下命令启动服务：

docker-compose up -d

3.2 停止服务

docker-compose down

3.3 查看日志

docker-compose logs -f facerec

3.4 人脸识别API接口说明

本文档详细描述了人脸识别服务提供的各个API接口，包括接口地址、请求方式、参数说明、返回结果等信息。

3.4.1 人脸识别接口

接口地址

POST /api/identifyFace

功能说明

上传图片进行人脸识别，返回匹配的用户信息。

请求参数

参数名	类型	必填	说明
image	file	是	包含人脸的图片文件

返回结果

{
  "code": 200,
  "data": {
    "msg": "success",
    "errno": 0,
    "data": {
      "result": [
        {
          "score": 95.5,
          "group_id": "group",
          "user_id": "用户名",
          "Uid": "用户编码",
          "Name": "用户姓名",
          "IdNum": "身份证号"
        }
      ],
      "log_id": "时间戳",
      "face_token": "唯一标识符",
      "result_num": 1
    }
  },
  "message": "SUCCESS"
}

示例

curl -X POST "http://localhost:12316/api/identifyFace" \
     -H "Content-Type: multipart/form-data" \
     -F "image=@test.jpg"

3.4.2 添加人脸数据接口

接口地址

POST /api/addFace

功能说明

添加新的人脸数据到系统中，用于后续的人脸识别。

请求参数

参数名	类型	必填	说明
image	file	是	包含人脸的图片文件
userCode	string	是	用户编码
userName	string	否	用户姓名，默认使用userCode
idNum	string	否	身份证号，默认使用userCode

返回结果

{
  "code": 200,
  "data": {
    "msg": "success",
    "errno": 0,
    "data": {
      "log_id": "时间戳",
      "message": "用户数据添加成功",
      "faceUrl": "http://localhost:12316/images/userCode.jpg",
      "faceUrl_Placeholder": "http://^API_BASE_URL^/images/userCode.jpg"
    }
  },
  "message": "SUCCESS"
}

示例

curl -X POST "http://localhost:12316/api/addFace" \
     -H "Content-Type: multipart/form-data" \
     -F "image=@user.jpg" \
     -F "userCode=USER001" \
     -F "userName=张三" \
     -F "idNum=110101199001011234"

3.4.3 人脸检测接口

接口地址

POST /api/detectFace

功能说明

检测图片中的人脸位置信息，不进行身份识别。

请求参数

参数名	类型	必填	说明
image	file	是	图片文件

返回结果

{
  "code": 200,
  "data": {
    "faces": [
      {
        "location": {
          "left": 100,
          "top": 100,
          "width": 200,
          "height": 200
        }
      }
    ],
    "face_num": 1
  },
  "message": "SUCCESS"
}

坐标信息说明：
- left: 人脸框左上角距离图片左边界的像素距离
- top: 人脸框左上角距离图片上边界的像素距离
- width: 人脸框的宽度（像素）
- height: 人脸框的高度（像素）
这些坐标信息基于图片的左上角为原点(0,0)，向右为X轴正方向，向下为Y轴正方向的坐标系。

示例

curl -X POST "http://localhost:12316/api/detectFace" \
     -H "Content-Type: multipart/form-data" \
     -F "image=@test.jpg"

3.4.4 获取用户人脸图像URL接口

接口地址

POST /api/getUserFaceUrl

功能说明

根据用户编码获取用户人脸图像的访问URL。

请求参数

参数名	类型	必填	说明
userCode	string	是	用户编码

返回结果

{
  "code": 200,
  "data": "http://localhost:12316/images/userCode.jpg",
  "message": "SUCCESS"
}

示例

curl -X POST "http://localhost:12316/api/getUserFaceUrl" \
     -d "userCode=USER001"

3.4.5 删除人脸数据接口

接口地址

POST /api/delFace

功能说明

根据用户编码删除指定的人脸数据。

请求参数

参数名	类型	必填	说明
userCode	string	是	用户编码

返回结果

{
  "code": 200,
  "data": {
    "msg": "success",
    "errno": 0,
    "data": {
      "log_id": "时间戳",
      "message": "用户数据删除成功"
    }
  },
  "message": "SUCCESS"
}

示例

curl -X POST "http://localhost:12316/api/delFace" \
     -d "userCode=USER001"

3.4.6 重新加载特征数据接口

接口地址

POST /api/reloadFeatures

功能说明

重新从数据库加载所有人脸特征数据到内存中。

请求参数

无

返回结果

{
  "code": 200,
  "data": {
    "msg": "success",
    "errno": 0,
    "data": {
      "log_id": "时间戳",
      "message": "特征数据重新加载成功",
      "count": 10
    }
  },
  "message": "SUCCESS"
}

示例

curl -X POST "http://localhost:12316/api/reloadFeatures"

3.4.7 查询所有人员数据接口

接口地址

POST /api/getAllUsers

功能说明

获取系统中所有已注册用户的信息。

请求参数

无

返回结果

{
  "code": 200,
  "data": {
    "msg": "success",
    "errno": 0,
    "data": {
      "users": [
        {
          "userCode": "USER001",
          "userName": "张三",
          "idNum": "110101199001011234",
          "faceUrl": "http://localhost:12316/images/USER001.jpg",
          "faceUrl_Placeholder": "http://^API_BASE_URL^/images/USER001.jpg"
        }
      ],
      "count": 1
    }
  },
  "message": "SUCCESS"
}

示例

curl -X POST "http://localhost:12316/api/getAllUsers"

3.4.8 静态图像文件服务

接口地址

GET /images/{filename}

功能说明

提供用户人脸图像的静态文件访问服务。

请求参数

参数名	类型	必填	说明
filename	string	是	图像文件名

返回结果

图像文件二进制数据

示例

curl -X GET "http://localhost:12316/images/USER001.jpg" -o user_image.jpg

3.5 简要使用说明

本服务是使用DLIB本的模型进行人脸识别的，精度和速度都比较适中，适合一般的应用场景。使用sqlite数据库存储人脸特征数据，方便部署和维护。
在使用过程中，请注意以下几点：
- 确保上传的图片质量较好，避免模糊或遮挡严重的图片。
- 人脸识别的准确率受多种因素影响，如光照、角度、表情等，建议在多种条件下测试和优化。
- 定期备份数据库文件，防止数据丢失。
- 如果需要更高的识别精度，可以考虑使用更复杂的模型或增加训练数据。

服务在启动时，先把数据库中所有的人脸特征数据加载到内存中，识别时直接在内存中进行比对，速度较快。如果添加或删除了人脸数据，需要调用/api/reloadFeatures接口重新加载特征数据。人脸特征数据存储在rec.db文件中，位于服务的工作目录下data/db。如需导出，可以直接找到容器的挂载目录下的该文件进行备份或导出。

人脸特征，采用了采集128个特征点保存，即128维的浮点数数组，存储在数据库中。识别时，计算上传图片的人脸特征与数据库中所有特征的欧氏距离，距离越小表示相似度越高。可以根据实际需求调整识别阈值。

人脸特征库表每个记录约131个字段，其不适合存储大量人脸数据。如果需要存储更多人脸数据，建议使用更专业的数据库系统，如MySQL、PostgreSQL等。因为本项目就动时需要据有的人脸数据加载到内存中，所以，人脸数据量不宜过大，建议控制在几千人以内。

3.6 人脸识别服务简要测试办法

本人脸识别服务，提供了一个简单的HTML页面用于测试人脸识别功能。可以通过浏览器访问该页面，上传图片进行测试。

下载地址:

[测试网页压缩包](https://datacdn.data-it.tech/faceRec/face-dt/face-test.zip)

[测试网页-未压缩](https://datacdn.data-it.tech/faceRec/face-dt/face-test.html)

解压后，将face-test.html文件放在任意目录下，使用浏览器打开该文件。页面中有一个文件上传控件，可以选择包含人脸的图片进行测试。上传后，页面会调用人脸识别服务的API接口，显示识别结果。

如果需要把网页部署到nginx等web服务器上，可以将face-test.html文件放在服务器的指定目录下，然后通过浏览器访问服务器的地址即可。
但时要注意，因为网页中调用了摄像头视频，在没有https证书的情况下，只有localhost可开启了权限白名单的情况下，才能正常使用摄像头功能。

本地测试如何开启权限

Edge
edge://flags/#unsafely-treat-insecure-origin-as-secure
Chrome
chrome://flags/#unsafely-treat-insecure-origin-as-secure
将 Insecure origins treated as secure 设置为 Enabled

如果不想开启权限白名单，可以把网页放在nginx等web服务器上，并配置https证书，这样浏览器会认为是安全的来源，就可以正常使用摄像头功能。

3.7 常见问题

• 问题1: 上传图片后，识别结果为空或不准确。
• 解决办法: 确保上传的图片质量较好，避免模糊或遮挡严重的图片。可以尝试不同的图片进行测试。
• 问题2: 添加人脸数据时，提示用户已存在。
  • 解决办法: 确认用户编码是否唯一，如果需要更新用户信息，可以先删除旧数据，再添加新数据。
• 问题3: 服务启动失败或无法访问。
• 解决办法: 检查Docker容器是否正常运行，确认端口是否被正确映射。查看日志获取更多信息。
• 问题4: 数据库文件损坏或丢失。
• 解决办法: 如果有备份，可以恢复备份文件。否则需要重新添加人脸数据。
• 问题5: 识别速度较慢。
• 解决办法: 确认服务器性能是否足够，减少人脸数据量，或优化图片大小和质量。
• 问题6: 如何调整识别阈值？
• 解决办法: 目前代码中没有提供直接调整阈值的接口，可以在代码中修改识别逻辑，调整欧氏距离的阈值。

3.8 性能测试报告

上图为配笔记本电脑环境测

下图为公司的前置工控机环境测试

经过反复测试，平均响应时间在200-300ms之间，峰值时段也能保持在500ms以内，满足一般应用需求。
同时并发要控制在4个以内，同一时间进行识别请求，超过4个时，响应时间会明显增加，延迟响应，响应时间有可能超过秒。如果需要更高的并发处理能力，可以考虑增加服务器资源，部署多个服务做负载均衡。，但对同一个中心，一般一个服务就足够了，毕竟同时识可的可能性太少了。

3.9 总结

本项目提供了一个基于DLIB的人脸识别服务，使用FastAPI框架，支持Docker部署。通过RESTful API接口，用户可以方便地进行人脸注册和识别操作。服务性能良好，适合一般应用场景。用户可以根据实际需求进行扩展和优化。