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

Face Recognition Operations - Find Similar

  • 参考
服务:
Azure AI Services
API 版本:
v1.2-preview.1

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

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

与查询 faceId 关联的“recognitionModel”应与目标 faceId 数组使用的“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 小时过期。
faceIds True

string[]

候选 faceIds 数组。 所有这些操作都是由“检测”创建的，faceId 将在检测调用后 24 小时过期。 faceId 的数量限制为 1000。
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 among Face IDs

示例请求

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

{
  "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
  "maxNumOfCandidatesReturned": 3,
  "mode": "matchPerson",
  "faceIds": [
    "015839fb-fbd9-4f79-ace9-7675fc2f1dd9",
    "be386ab3-af91-4104-9e6d-4dae4c9fddb7"
  ]
}

示例响应

状态代码:
200 
[
  {
    "confidence": 0.9,
    "persistedFaceId": "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 将持久化，不会过期。