人脸特征算法,如何上云_物联网应用服务（文档停止维护）-阿里云帮助中心

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

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状态时的错误消息 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