文档

人脸特征算法上云

更新时间:
一键部署

本文档用来指导厂商提供特征算法上云服务镜像,在保持算法独立性的前提下实现人脸特征下发。

IoT门禁服务向设备下发人脸权限时默认使用图片的方式,核心原因是为了更好的兼容性,下发图片后由端侧设备计算人脸特征值。之所以采用这种方式,是因为云、端算法不容易统一。

直接下发图片的方式由于需要多次网络交互和本地计算,部署性能较低,影响实施效率。长时间下发容易受到网络状态影响导致下发失败。

厂商根据本文档提供的服务规范,实现托管服务镜像。IoT集成托管服务完成云端部署服务集群,就可以实现特征下发,提高人脸权限的下发性能和成功率。

与人脸图片下发对比,特征下发可以提高10倍的部署性能,部署时间缩短为1/10。

重要

人脸特征算法上云能力只面向人脸1.0 SDK。

1. 架构

image

流程:

  • 厂商按服务规范提供服务镜像;

  • IoT负责部署在云端;

  • 下发权限时,IoT根据服务提供的业务参数路由到对应的服务计算特征;

2. 服务定义

2.1. 通用定义

docker镜像,提供HTTP标准服务

服务日志写到标准输出 stdout, stderror

协议:HTTP | HTTPS

端口:8080

方法:POST

路径:见接口定义

例:

http://10.1.2.3:8080/device/face/features/get

IoT分配 appKey, appSecret

String appKey = "xxx";
String appSecret = "xxx";
long ts = System.currentTimeMillis();
String str = appKey + "." + appSecret + "." + ts;
String sign = md5(str);

ts校验:

assert( Math.abs( currentTime - ${ts} ) < 3600000 )

字段名

类型

非空

说明

sign

String

签名

appKey

String

IoT颁发的appKey,用于验证签名

ts

Long

时间戳,毫秒

requestId

String

请求ID,回填给响应。

params

Array|Object

请求参数,可以为空、数组或对象。具体见接口定义。

示例

{
  "sign": "32fvdsazxxr4234rdxfsdasdfsda",
  "appKey": "xxxx",
  "ts": 1604494967,
  "requestId": "xxxxxxx",
  "params": {
    ...
  }
}

字段名

类型

非空

说明

requestId

String

请求ID,回填给响应。

code

Integer

响应码,200成功

message

String

非成功时的错误消息,成功时为空。非成功时说明错误原因。

data

Array|Object

成功时的数据部,可以为空、对象或数组。

正常响应

{
    "requestId": "32fvdsazxxr4234rdxfsdasdfsda",
    "code": 200,
    "data": {
        ...
    }
}

错误响应

{
    "requestId":"JymsEenXhMQwMaDb2L68WFFFO3bkyAb7",
    "code":500,
    "message":"服务不可用"
}

错误码

说明

200

成功

401

签名错误

403

参数错误

500

系统错误

单服务节点性能基本要求

  • 人脸提取特征

    服务的性能指标:CPU架构不低于5 QPS,GPU架构不低于30 QPS;支持并行处理,并发限制由厂商提供;

  • 人脸质量检查

    服务的性能指标:不低于10 QPS,支持并行处理,并发限制由厂商提供;

  • 其它服务请求rt不大于100ms;

厂商提供:

  • 人脸提取特征

    服务的性能指标(qps)和并发数限制;

  • 人脸质量检查

    服务的性能指标(qps)和并发数限制;

  • 提供托管服务配置要求,CPU、GPU、存储、网络等;

2.2. 计算人脸特征

根据输入的固件和算法版本,计算人脸特征值,批量接口。

/device/face/features/get

请求参数的数据部为JSON对象

字段名

类型

非空

说明

productKey

String

IoT productKey

firmwareVersion

String

固件版本

algorithmVersion

String

算法版本

faces

Array<Object>

人脸信息,最大长度100

faceId

String

人脸ID

faceImageUrl

String

人脸下载URL

faceImageMd5

String

人脸文件MD5值

响应参数的数据部为JSON对象数组

字段名

类型

非空

说明

faceId

String

人脸ID

faceFeatures

Array<String>

人脸特征,或其它特征预处理结果。

如果返回内容是JSON,需要的前处理JSON转义。

该字段会直接透传给设备端,由厂商保证每个特征的顺序和含义。云端不会改变特征字段的值和编码。

code

Integer

异常时的错误码

message

String

异常时的报错信息

请求

{
    "sign":"MczHCDuwnfLdOuIWSgSHwby9bLRadLul",
    "appKey":"xxx",
    "ts":1234567890,
    "requestId":"JymsEenXhMQwMaDb2L68WFFFO3bkyAb7",
    "params":{
        "productKey":"XXXX",
        "firmwareVersion":"1.2.3",
        "algorithmVersions":"1.3.2",
        "faces":[
            {
                "faceId":"xxx1",
                "faceImageUrl":"http://xxxx",
                "faceImageMd5":"xxxxxxx"
            },{
                "faceId":"xxx2",
                "faceImageUrl":"http://xxxx",
                "faceImageMd5":"xxxxxxx"
            }
        ]
    }
}

响应

{
    "requestId":"JymsEenXhMQwMaDb2L68WFFFO3bkyAb7",
    "code":200,
    "message":"xxxx",
    "data":[
        {
            "faceId":"xxx1",
            "faceFeatures":["0.342,343243,243243,432","xxx"]
        },
        {
            "faceId":"xxx2",
            "code":204,
            "msg":"人脸质量低"
        }
    ]
}

2.3. 人脸质量检查

人脸图质量检查,批量接口。

这个接口会开放给项目ISV,当项目有人脸检测需求时可以使用云端服务,避免厂商重复部署。ISV使用服务时,可以向厂商咨询使用的算法版本。也可以支持无版本的请求,使用默认的检查算法。

/device/face/quality/check

请求参数的数据部为JSON对象

字段名

类型

非空

说明

algorithmVersion

String

算法版本,如果没有版本号可以不填

faces

Array<Object>

人脸信息。最大长度100

faceId

String

人脸ID

faceImageUrl

String

人脸下载URL

faceImageMd5

String

人脸文件MD5值

响应参数的数据部为JSON对象数组

字段名

类型

非空

说明

faceId

String

人脸ID

status

String

状态,字符串枚举 ACCEPT 接受REJECT 拒绝

message

String

REJECT状态时的错误消息

  • Low quality. 质量低

  • No face found. 没找到人脸

  • More faces. 

存在多张人脸厂商可自定义

请求

{
    "sign":"MczHCDuwnfLdOuIWSgSHwby9bLRadLul",
    "appKey":"xxx",
    "ts":1234567890,
    "requestId":"JymsEenXhMQwMaDb2L68WFFFO3bkyAb7",
    "params":{
        "faces":[
            {
                "faceId":"xxx1",
                "faceImageUrl":"http://xxxx",
                "faceImageMd5":"xxxxxxx"
            },{
                "faceId":"xxx2",
                "faceImageUrl":"http://xxxx",
                "faceImageMd5":"xxxxxxx"
            }
        ]
    }
}

响应

{
    "requestId":"JymsEenXhMQwMaDb2L68WFFFO3bkyAb7",
    "code":200,
    "message":"xxxx",
    "data":[
        {
            "faceId":"xxx1",
            "status":"ACCEPT"
        },
        {
            "faceId":"xxx2",
            "status":"REJECT",
            "message":"More faces."
        }
    ]
}

2.4.查询服务信息

获取厂商托管服务的基本信息.

/service/info/get

请求参数的数据部为空。

响应参数的数据部为JSON对象

字段名

类型

非空

说明

manufacturerName

String

厂商名称(注册服务用)

支持汉字、字母、数字、横线和下划线,必须由汉字、字母开头,长度不超过64

serviceReleaseTime

String

服务发布日期(注册服务的标识信息)

version

String

服务版本号(注册服务的标识信息)

qpsLimit

Integer

服务的秒级限流

https

Boolean

是否支持HTTPS,默认为否 false

请求

{
    "sign":"MczHCDuwnfLdOuIWSgSHwby9bLRadLul",
    "appKey":"xxx",
    "ts":1234567890,
    "requestId":"JymsEenXhMQwMaDb2L68WFFFO3bkyAb7"
}

响应

{
    "requestId":"JymsEenXhMQwMaDb2L68WFFFO3bkyAb7",
    "code":200,
    "data":{
        "manufacturerName":"XX公司",
        "serviceReleaseTime":"2020-10-31",
        "version":"1.0.0",
        "qpsLimit":30,
        "https: false
    }
}

2.5.查询算法版本列表

查询托管服务支持的算法版本信息。支持配置多个产品的可用算法。

云端缓存算法关系时,忽略固件版本。固件版本信息会作为参数输入给人脸特征服务,具体适配由厂商处理。

/service/algorithmversions/supports/get

请求参数的数据部为空

响应参数的数据部为JSON对象数组。

字段名

类型

非空

说明

productKey

String

IoT productKey

algorithmVersions

Array<String>

支持版本列表

请求

{
    "sign":"MczHCDuwnfLdOuIWSgSHwby9bLRadLul",
    "appKey":"xxx",
    "ts":1234567890,
    "requestId":"JymsEenXhMQwMaDb2L68WFFFO3bkyAb7"
}

响应

{
    "requestId":"JymsEenXhMQwMaDb2L68WFFFO3bkyAb7",
    "code":200,
    "data":[
        {
            "productKey":"iLxhvTig",
            "algorithmVersions":[
                "v1.xx.xx",
                "v2.xx.xx",
                "v3.xx.xx",
                "v4.xx.xx"
            ]
        },
        {
            "productKey":"3rb5apOH",
            "algorithmVersions":[
                "v1.xx.xx",
                "v2.xx.xx",
                "v3.xx.xx"
            ]
        }
    ]
}

2.6.健康检查

查询服务的健康状态。

由K8s集群检查服务状态。

/service/health

请求参数的数据部为空

响应参数的数据部为JSON对象。

字段名

类型

非空

说明

status

String

健康状态,字符串枚举

  • UP 健康

  • DOWN 故障

请求

{
    "sign":"MczHCDuwnfLdOuIWSgSHwby9bLRadLul",
    "appKey":"xxx",
    "ts":1234567890,
    "requestId":"JymsEenXhMQwMaDb2L68WFFFO3bkyAb7"
}

响应

{
    "requestId":"JymsEenXhMQwMaDb2L68WFFFO3bkyAb7",
    "code":200,
    "data":{
        "status":"UP"
    }
}

3. 设备物模型

3.1. 物模型 - 属性

属性定义,上报设备端版本号

  • 人脸算法版本(新增) 

    • FaceAlgorithmVersion

  • 设备固件版本(新增)

    • FirmwareVersion

{
    "properties":[
        {
            "identifier":"FaceAlgorithmVersion",
            "dataType":{
                "specs":{
                    "length":"65"
                },
                "type":"text"
            },
            "name":"人脸库算法版本",
            "accessMode":"rw",
            "required":true
        },
        {
            "identifier":"FirmwareVersion",
            "dataType":{
                "specs":{
                    "length":"65"
                },
                "type":"text"
            },
            "name":"设备固件版本",
            "accessMode":"rw",
            "required":true
        }
    ]
}

增加设备支持特征下发开关属性

  • SupportFaceFeature

{
    "properties":[
        {
            "identifier":"SupportFaceFeature",
            "dataType":{
                "specs":{
                    "0":"支持",
                    "1":"不支持"
                },
                "type":"bool"
            },
            "name":"设备是否支持人脸特征下发"
        }
    ]
}

3.2. 物模型 - 服务

人脸特征下发

新增人脸特征下发服务

{
    "services":[
        {
            "name":"同步人脸库特征",
            "identifier":"SyncFaceFeatures",
            "method":"thing.service.SyncFaceFeatures",
            "required":false,
            "callType":"sync",
            "inputData":[
                {
                    "identifier":"FacePicFeaturesURL",
                    "dataType":{
                        "specs":{
                            "length":"1024"
                        },
                        "type":"text"
                    },
                    "name":"同步特征文件URL地址"
                }
            ],
            "outputData":[
                {
                    "identifier":"SyncPicStatus",
                    "dataType":{
                        "specs":{
                            "0":"成功",
                            "1":"布控中",
                            "2":"下载文件失败",
                            "3":"解析文件失败"
                        },
                        "type":"enum"
                    },
                    "name":"设备同步图片状态值"
                }
            ]
        }
    ]
}

参数示例:

{"FacePicFeaturesURL":"http://xxxxxx"}

特征文件

新增人脸特信息,增加人脸特征字段,类型为字符串数组。

features: ["xxxxxxxxxxxxxxxxxx"]

完整示例:

{
    "groupId":"egqQkuFBPgh8pltWiw1S000100",
    "addFaceInfos":[
        {
            "faceId":"552f3570-4717-4a39-910b-d72542552d89",
            "faceMd5":"36c36fa96920e45ca5f00334675484bc",
            "faceUrl":"http://xxx",
            "userInfo":"{"userName": "Xiao Wang", "expire": "2020-12-31 23:59:59", "policy": "DENY", "userExtInfo": "BLACKLIST"}",
            "features":[
                "xxxxxxxxxxxxxxxxxx"
            ],
            "index":0,
            "clientTag":""
        }
    ],
    "deleteFaceInfos":[
        {
            "faceId":"xxxx"
        },
        {
            "faceId":"yyyy"
        }
    ],
    "isCleanAll":false,
    "isCleanAllGroup":false
}

3.3. SDK

见SDK文档《LinkFace C SDK Linux设备端V1版开发指南》

3.4. 适配品类

人脸特征支持的品类:

  • 智能城市 -> 公共服务 -> 人脸识别门禁/FaceRecognition

  • 智慧园区 -> 多功能门禁/MultiAccessControl