添加人脸识别API

通过添加人脸识别API，可以为MT Photos服务端提供人脸识别功能；

镜像说明

基于仓库 https://github.com/dev-fox-101/mt-photos-insightface-unofficial 打包

使用insightface模型，它是目前开源中准确率最高的预训练模型，特别是针对亚洲人脸型准确率比别的模型比较高

镜像内已内置 buffalo_l 模型文件，避免因为网络的原因导致下载模型文件失败

使用方法：

一、使用图形化安装的教程

常见NAS内的安装方法：

如果您使用的Nas，不在以上列表中，可以参考群晖的安装方法

使用别的电脑运行API的方法

MT Photos服务端在调用人脸识别API时，识别的数据都保存在服务端内的数据库；API仅负责将图片内识别到的人物数据返回给MT Photos服务端；

因此，可以API可以运行在任何MT Photos服务端可访问到的设备上；

如果有其他性能更强的电脑，可以按下面的步骤来提升第一次处理大量照片时的识别速度：

使用其他电脑运行API的方法

1、在性能强的电脑上安装人脸识别API程序
- Windows系统按这个教程安装 - Windows 添加人脸识别API
- MacOS系统按这个教程安装 - MacOS 添加人脸识别API
- 其他nas或者服务器，按照上方的图形化安装教程，或者直接使用命令行安装人脸识别API
2、人脸识别的api地址，填写 http://192.168.1.108:8060 （192.168.1.108为运行API的电脑ip）（8060需要改为实际运行的api的端口）
3、等识别完成后，把人脸识别的api地址改回nas上运行的mt-photos-insightface服务的地址，用来识别后面新增照片

等完成第一次全部照片的识别后，可以再切换回使用NAS上部署的人脸识别API服务；

注意： 仅支持在 运行着相同的人脸识别模型 API地址之间切换

Insightface模型中的buffalo_l、antelopev2 或者更早的Deepface模型，它们是不同的模型，如果需要切换，请按设置中切换使用API识别模型的步骤 执行

调用外部API的相关说明：

1、在性能更强的电脑安装好人脸识别API的程序或容器；

2、返回人脸识别API配置界面，填写接口地址、API_AUTH_KEY等信息；

3、保存后，在系统配置顶部的后台任务中可以看到运行的任务；此时MT Photos服务端会发送需要识别的照片的缩略图到API，API识别完成后再将识别的结果返回给MT Photos 服务端；

4、MT Photos服务端获取到API识别的结果后，将识别结果保存到内部的数据库中；

5、直到识别完成全部照片，再返回人脸识别API配置界面将接口地址、API_AUTH_KEY 修改为在nas上运行的人脸识别API；

6、后面新增的照片，通过nas上运行的人脸识别API来识别；

二、API配置参数

人脸置信度阈值设置 建议填 0.65

人脸匹配差异度阈值 建议填 0.5

三、API 硬件加速

Intel核显加速

使用 OpenVINO核显加速来处理智能识别和人脸识别

NVIDIA显卡加速

点击这里查看 CUDA版本镜像

RKNN 加速

使用 RKNN NPU加速来处理智能识别和人脸识别

AI识别时，占用的CPU太高

如果文本识别、CLIP识别或者人脸识别时，占用的CPU过高，可以通过下面的方法，限制容器的CPU和内存使用量；

点击这里限制智能识别API的CPU使用量查看

四、使用命令行安装的教程

下载镜像

docker pull devfox101/mt-photos-insightface-unofficial:latest

docker镜像下载失败？使用镜像地址下载

使用命令行创建及运行容器

docker run -i -p 8066:8066 -e API_AUTH_KEY=mt_photos_ai_extra --name mt-photos-insightface-unofficial --restart="unless-stopped" devfox101/mt-photos-insightface-unofficial:latest

默认使用cpu处理人脸识别，如果是arm架构或需要使用cuda加速，可以查看下方的 ARM版本镜像和 CUDA版本镜像

arm版本镜像

如果是m系列芯片的Mac，以及其他armV8架构的处理器，使用这个镜像安装；

#使用命令行下载镜像

docker pull devfox101/mt-photos-insightface-unofficial:arm-latest

#启动容器：

docker run -i -p 8066:8066 -e API_AUTH_KEY=mt_photos_ai_extra --name mt-photos-insightface-unofficial --restart="unless-stopped" devfox101/mt-photos-insightface-unofficial:arm-latest

docker镜像下载失败？使用镜像地址下载

查看arm版本的yaml模板点击这里

CUDA版本镜像

CUDA 版本 12.3.0 以上，显卡驱动版本 >=545.23.06

#下载镜像
docker pull devfox101/mt-photos-insightface-unofficial:cuda-latest

#启动容器：
docker run --gpus all -i -p 8066:8066 -e API_AUTH_KEY=mt_photos_ai_extra --name mt-photos-insightface devfox101/mt-photos-insightface-unofficial:cuda-latest

docker镜像下载失败？使用镜像地址下载

查看CUDA版本的yaml模板点击这里

docker-compose模板

如果需要使用docker compose安装，参考下面的模板；

查看 yaml语法的三大规则

同时安装 MT Photos + 智能识别API + 人脸识别API 的yaml模板

提示：docker compose 和上面 docker run 创建容器的效果是一样的，只需要选择其中一种方法运行；

version: "3"

services:
  mtphotos:
    image: registry.cn-hangzhou.aliyuncs.com/mtphotos/mt-photos:latest
    container_name: mtphotos
    restart: always
    ports:
      - 8063:8063
    volumes:
      - /volume1/docker/mt_photos/config:/config
      - /volume1/photos/mt_photos_upload:/upload
      - /volume1/xxx/其他需要映射的目录:/photos #提示：下面这2行是其他需要映射给容器的文件夹，如果没有可以删除这2行
      - /volume1/xxx/xxx/share_photos:/share_photos #提示：目录映射必须要用 : 分隔开，左边填写nas中的文件路径， 右边添加映射到容器内的路径， 也就是添加图库时选择的文件夹路径
      #- /etc/localtime:/etc/localtime:ro  # 如果服务器时区不是UTC+8，需要添加这行来覆盖镜像内部的时区
    environment:
      - TZ=Asia/Shanghai
      - LANG=C.UTF-8
    dns:
      - 114.114.114.114
    depends_on:
      - mtphotos_ai
      - mtphotos_face_api
  mtphotos_ai:
    image: registry.cn-hangzhou.aliyuncs.com/mtphotos/mt-photos-ai:onnx-latest
    container_name: mtphotos_ai
    restart: always
    ports:
      - 8060:8060
    environment:
      - API_AUTH_KEY=mt_photos_ai_extra
  mtphotos_face_api:
    image: crpi-gcuyquw9co62xzjn.cn-guangzhou.personal.cr.aliyuncs.com/devfox101/mt-photos-insightface-unofficial:latest
    container_name: mtphotos_face_api
    restart: always
    ports:
      - 8066:8066
    environment:
      - API_AUTH_KEY=mt_photos_ai_extra

五、常见问题

无法下载镜像

可以使用这个国内的地址拉取镜像

docker pull crpi-gcuyquw9co62xzjn.cn-guangzhou.personal.cr.aliyuncs.com/devfox101/mt-photos-insightface-unofficial:latest
docker tag crpi-gcuyquw9co62xzjn.cn-guangzhou.personal.cr.aliyuncs.com/devfox101/mt-photos-insightface-unofficial:latest  devfox101/mt-photos-insightface-unofficial:latest

第1条命令为拉取镜像
第2条命令为将镜像标记为Docker hub源，这样可以在图形化创建容器时使用

armV8版本国内镜像地址

docker pull crpi-gcuyquw9co62xzjn.cn-guangzhou.personal.cr.aliyuncs.com/devfox101/mt-photos-insightface-unofficial:arm-latest
docker tag crpi-gcuyquw9co62xzjn.cn-guangzhou.personal.cr.aliyuncs.com/devfox101/mt-photos-insightface-unofficial:arm-latest  devfox101/mt-photos-insightface-unofficial:arm-latest

cuda版本国内镜像地址

docker pull crpi-gcuyquw9co62xzjn.cn-guangzhou.personal.cr.aliyuncs.com/devfox101/mt-photos-insightface-unofficial:cuda-latest
docker tag crpi-gcuyquw9co62xzjn.cn-guangzhou.personal.cr.aliyuncs.com/devfox101/mt-photos-insightface-unofficial:cuda-latest devfox101/mt-photos-insightface-unofficial:cuda-latest

#启动容器：
docker run --gpus all -i -p 8066:8066 -e API_AUTH_KEY=mt_photos_ai_extra --name mt-photos-insightface devfox101/mt-photos-insightface-unofficial:cuda-latest

自定义识别的模型

以上docker镜像内置的模型均为 buffalo_l，如果需要使用其他模型，需要给容器增加环境变量 RECOGNITION_MODEL ,值填写 antelopev2

也就是增加 -e RECOGNITION_MODEL=antelopev2

第一次识别时，需要下载模型，如果因为网络原因，下载较慢或失败，请参考下方 下载模型后目录映射给容器 中的方法；

根据测试，antelopev2模型识别的准确率与buffalo_l 并没有明显的提升，识别速度更慢，因此推荐使用默认的 buffalo_l 模型；

启动容器后，测试api提示不是人脸识别API

如果使用了未内置模型的镜像，第一次启动容器后需要等待下载模型完成才能使用；
如果由于网络问题，下载失败，可以按下面的方法手动下载镜像：

创建容器时，要映射 /root/.insightface/models 这个目录 不能直接映射/root目录
下载模型文件 buffalo_l.zip 或者 antelopev2.zip 并解压到映射的目录中；模型文件下载地址：https://github.com/kqstone/mt-photos-insightface-unofficial/releases/tag/models
或者百度网盘：https://pan.baidu.com/s/1SsY7_2t7aORh2jCvGWtD1A?pwd=1234

下载模型后目录映射给容器

比如容器的目录映射为： -v /mnt/docker/insightface/models:/root/.insightface/models

需要把buffalo_l.zip的文件解压到 /mnt/docker/insightface/models/buffalo_l 这个目录

解压完成后，在 /mnt/docker/insightface/models/buffalo_l目录下，可以看到 1k3d68.onnx、2d106det.onnx、det_10g.onnx、genderage.onnx、w600k_r50.onnx 5个文件

创建容器的完整命令：

docker run -d \
  --name="mt-photos-insightface" \ 
  -p 8066:8066 \
  -e API_AUTH_KEY=mt_photos_ai_extra \ 
  -v /mnt/docker/insightface/models:/root/.insightface/models \ 
  --restart="unless-stopped" \
  devfox101/mt-photos-insightface-unofficial:latest

旧版本人脸识别API模型：Deepface模型

点击这里查看如何配置人脸识别 - deepface API

不推荐使用这个模型，识别的准确率比 insightface 模型低；

自定义向量长度

如果人脸特征提取模型返回的向量长度不是512，可以在API配置中点击 自定义向量长度 设置数据库中存储人脸特征字段的长度

API默认返回的向量长度都是512，如果没有自定义使用其他的模型，不需要自定义向量长度