人脸特征算法上云
本文档用来指导厂商提供特征算法上云服务镜像,在保持算法独立性的前提下实现人脸特征下发。
IoT门禁服务向设备下发人脸权限时默认使用图片的方式,核心原因是为了更好的兼容性,下发图片后由端侧设备计算人脸特征值。之所以采用这种方式,是因为云、端算法不容易统一。
直接下发图片的方式由于需要多次网络交互和本地计算,部署性能较低,影响实施效率。长时间下发容易受到网络状态影响导致下发失败。
厂商根据本文档提供的服务规范,实现托管服务镜像。IoT集成托管服务完成云端部署服务集群,就可以实现特征下发,提高人脸权限的下发性能和成功率。
与人脸图片下发对比,特征下发可以提高10倍的部署性能,部署时间缩短为1/10。
人脸特征算法上云能力只面向人脸1.0 SDK。
1. 架构
流程:
厂商按服务规范提供服务镜像;
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状态时的错误消息
存在多张人脸厂商可自定义 |
请求
{
"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 | 是 | 健康状态,字符串枚举
|
请求
{
"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