你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Face Recognition Operations - Find Similar From Face List

服务:

Azure AI Services

API 版本:

v1.2-preview.1

给定查询人脸的 faceId，以便从人脸列表中搜索类似外观的人脸。 创建人脸列表创建“faceListId”。
根据返回的类似人脸列表的输入，返回的相似人脸列表包含 faceId 或 persistedFaceIds，按相似性排名。

查找类似的模式有两种工作模式：“matchPerson”和“matchFace”。 “matchPerson”是默认模式，它尝试通过使用内部同一人员阈值来查找同一人脸。 查找已知人员的其他照片非常有用。 请注意，如果没有人脸通过内部阈值，将返回空列表。 “matchFace”模式忽略同一人员阈值，并返回排名相似的人脸，即使相似性较低。 它可用于搜索名人脸等情况。

与查询 faceId 关联的“recognitionModel”应与目标人脸列表使用的“recognitionModel”相同。

POST {endpoint}/face/{apiVersion}/findsimilars

URI 参数

名称	在	必需	类型	说明
apiVersion	path	True	string	API 版本
endpoint	path	True	string uri	支持的认知服务终结点（协议和主机名，例如：https://{resource-name}.cognitiveservices.azure.com）。

请求正文

名称	必需	类型	说明
faceId	True	string	查询人脸的 faceId。 用户需要先调用“检测”才能获取有效的 faceId。 请注意，此 faceId 不会持久化，将在检测调用后 24 小时过期。
faceListId	True	string	在“创建人脸列表”中创建的现有用户指定的唯一候选人脸列表。 人脸列表包含一组持久化且永不过期的 persistedFaceId。
maxNumOfCandidatesReturned		integer	返回的前相似人脸数。 有效范围为 [1， 1000]。 默认值为 20。
mode		FindSimilarMatchMode	类似的人脸搜索模式。 可以是“matchPerson”或“matchFace”。 默认值为“matchPerson”。

响应

名称	类型	说明
200 OK	FindSimilarResult[]	如果输入参数为 faceId，或者如果输入参数为 faceListId 或 largeFaceListId，则成功调用将返回 faceId 中表示的最相似人脸的数组。
Other Status Codes	FaceErrorResponse	意外的错误响应。 标头 x-ms-error-code: string

安全性

Ocp-Apim-Subscription-Key

Azure AI 人脸订阅的密钥。

类型: apiKey
在: header

AADToken

Azure Active Directory OAuth2 流

类型: oauth2
流向: accessCode
授权 URL: https://api.example.com/oauth2/authorize
令牌 URL: https://api.example.com/oauth2/token

作用域

名称	说明
https://cognitiveservices.azure.com/.default

示例

Find Similar from FaceList

示例请求

HTTP

POST {endpoint}/face/v1.2-preview.1/findsimilars

{
  "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
  "maxNumOfCandidatesReturned": 3,
  "mode": "matchPerson",
  "faceListId": "your_face_list_id"
}

示例响应

状态代码:

200

[
  {
    "confidence": 0.8,
    "faceId": "015839fb-fbd9-4f79-ace9-7675fc2f1dd9"
  }
]

定义

名称	说明
FaceError	错误对象。 有关人脸服务返回的错误代码和消息的综合详细信息，请参阅以下链接：https://aka.ms/face-error-codes-and-messages。
FaceErrorResponse	包含错误详细信息的响应。
FindSimilarResult	用于查找类似人脸操作的响应正文。

FaceError

错误对象。 有关人脸服务返回的错误代码和消息的综合详细信息，请参阅以下链接：https://aka.ms/face-error-codes-and-messages。

名称	类型	说明
code	string	服务器定义的错误代码集之一。
message	string	错误的人工可读表示形式。

FaceErrorResponse

包含错误详细信息的响应。

名称	类型	说明
error	FaceError	错误对象。

FindSimilarResult

用于查找类似人脸操作的响应正文。

名称	类型	说明
confidence	number	候选项的置信度值。 置信度越高，越相似。 介于 [0,1] 之间。
faceId	string	通过 faceIds 查找时，候选人脸的 faceId。 faceId 由“Detect”创建，将在检测调用后 24 小时过期。
persistedFaceId	string	当通过 faceListId 或 largeFaceListId 查找时，候选人脸的 persistedFaceId。 人脸列表/大型人脸列表中的 persistedFaceId 将持久化，不会过期。