功能描述
人脸搜索能力可以根据输入图片，在数据库中搜索并返回相似的人脸图片数据。单次搜索最多可支持10个人脸数据库的同时搜索（跨库搜索）。该能力根据人脸特征来进行识别，通过把人脸图像特征化，然后比较人脸特征的相似程度。
前提条件：
已通过创建人脸数据库（CreateFaceDb）接口创建了数据库名称（DbName）。
已通过添加人脸样本（AddFaceEntity）接口创建了实体ID（EntityId）。
已通过添加人脸数据（AddFace）接口给数据库（DbName）下的实体ID（EntityId）添加了人脸图片。
输入限制
图像格式：JPG、JPEG、PNG。
图像大小：不超过5 MB。
图像分辨率：大于32×32像素，小于4096×4096像素。人脸占比不低于64×64像素。
URL地址中不能包含中文字符。
支持图片中包含最多10个人脸，超过部分会被忽略。
请求参数
SearchFaceAdvanceRequest
| 名称 | 类型 | 是否必选 | 示例值 | 描述 |
|---|---|---|---|---|
| db_name | String | 否 | default | 数据库名称。 |
| image_url_object | String | 是 | 图像二进制数据。 | |
| limit | Integer | 是 | 2 | 单个人脸列表中搜索人脸结果数量限制，取值范围 1~100。 |
| db_names | String | 否 | test1,test2,test3 | 数据库名称列表，以英文逗号 (,) 分割，可以实现跨库查询，最大支持 10 个数据库。 |
| quality_score_threshold | Float | 否 | 50.0 | 质量分阈值。对人脸图片进行质量分析判断，得到的质量分小于该阈值则表示人脸图片质量不符合要求，比对失败。取值范围[0.0,100.0]。0.0 或空则表示不做质量分判断逻辑。 |
| max_face_num | Long | 否 | 5 | 对输入图像中多少个人脸进行检索比对，控制人脸样本列表个数，取值范围 1~10，默认为 5。 |
返回数据
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| RequestId | String | 4159ee4a-0fe8-438c-a8de-ee531555b3c | 请求 ID。 |
| Data | Object | - | 返回的结果数据内容。 |
| MatchList | Array of MatchList | - | 匹配的结果列表，如果输入图像中多个人脸，则这里会返回多个数据。 |
| FaceItems | Array of FaceItems | - | 匹配的人脸数据列表。 |
| EntityId | String | U1 | 实体 ID，用来标识用户的唯一性，如用户 ID、员工 ID 等。每个实体可包含多张人脸图片。支持大小写字母、数字、下划线和减号的组合，长度为 2~64。 |
| FaceId | String | 001 | 人脸图片数据 ID，需要全局唯一，不可重复。支持小写字母、数字和下划线的组合。长度为 1~64。 |
| Score | Float | 0.892133 | 人脸的相似度，取值范围-1.0~1.0，取小数点后 6 位，数值越大相似度越高，建议的三个参考阈值为 0.35，0.45 和 0.6，分别对应千分之一，万分之一和十万分之一的误识率。阈值设置越高，误识率越低，通过率也越低，对安全性要求越高的场合，可以设置越高的阈值。 |
| ExtraData | String | 王小二 | 自定义信息（字符串）。支持字母、数字、标点符号和汉字。不超过 512 个字符。 |
| DbName | String | default | 数据库名称。 |
| Confidence | Float | 36.820168 | 转换后的置信度，取值范围 0.0~100.0，数值越大相似度越高，建议的三个参考阈值为 60.48，67.87 和 72.62，分别对应千分之一，万分之一和十万分之一的误识率。阈值设置越高，误识率越低，通过率也越低，对安全性要求越高的场合，可以设置越高的阈值。 |
| Location | Object | - | 输入图像中的人脸坐标信息。 |
| Width | Integer | 200 | 宽度，单位像素。 |
| Height | Integer | 200 | 高度，单位像素。 |
| Y | Integer | 6 | 左上角 y 坐标。 |
| X | Integer | 5 | 左上角 x 坐标。 |
| QualityScore | Float | 71.7349 | 输入图像中的人脸质量分。 |
HTTP/1.1 200 OK
Content-Type:application/json
{
"RequestId" : "4159e64a-0fe8-436c-a8de-ee531555db3c",
"Data" : {
"MatchList" : [ {
"FaceItems" : [ {
"EntityId" : "U1",
"FaceId" : "001",
"Score" : 0.892133,
"ExtraData" : "王小二",
"DbName" : "default",
"Confidence" : 36.820168
} ],
"Location" : {
"Width" : 200,
"Height" : 200,
"Y" : 6,
"X" : 5
},
"QualitieScore" : 71.7349
} ]
}
} def search_face_advanced(self, db_name, limit=5, local_image_path=None, image_url=None):
"""
人脸搜索
:param db_name: 数据库名称
:param limit: 返回结果的数量限制
:param local_image_path: 本地图片文件路径
:param image_url: 网络图片的 URL
:return: 响应结果或异常信息
"""
try:
if local_image_path:
if not os.path.exists(local_image_path):
raise FileNotFoundError(f"文件 {local_image_path} 不存在。")
with open(local_image_path, 'rb') as stream:
image_data = stream.read()
image_obj = io.BytesIO(image_data)
elif image_url:
img = urlopen(image_url).read()
image_obj = io.BytesIO(img)
else:
raise ValueError("请提供本地图片路径或网络图片 URL")
request = SearchFaceAdvanceRequest(
db_name=db_name,
limit=limit,
image_url_object=image_obj
)
response = self.client.search_face_advance(request, self.runtime_option)
return response.body
except Exception as error:
print(error)
if hasattr(error, 'code'):
print(error.code)
return error
评论 (0)