Face Recognition Operations - Identify From Dynamic Person Group
1 對多識別,從動態人員群組尋找特定查詢人員臉部最接近的相符專案。
針對faceIds陣列中的每個臉部,臉部識別會計算查詢臉部與 dynamicPersonGroupId) 所指定動態人員群組 (中所有臉部的相似度,並傳回候選人員 (依相似度信賴排名的臉部) 。
注意
-
- 演演算法允許在同一個要求中獨立識別多個臉部,但不超過10個臉部。
- 每個人可以有一個以上的臉部,但不超過 248 個臉部。
- 較高的臉部影像品質表示更好的識別精確度。 請考慮高品質的臉部:正面、清楚和臉部大小為 200x200 像素, (100 像素在眼睛之間) 或更大。
- 傳回的候選項目數目受限於 maxNumOfCandidatesReturned 和 confidenceThreshold。 如果未識別任何人員,傳回的候選專案將會是空陣列。
- 識別作業只能比對與查詢臉部相關聯的相同辨識模型取得的臉部。
POST {endpoint}/face/{apiVersion}/identify
URI 參數
名稱 | 位於 | 必要 | 類型 | Description |
---|---|---|---|---|
api
|
path | True |
string |
API 版本 |
endpoint
|
path | True |
string uri |
支持的認知服務端點 (通訊協定和主機名,例如:https://{resource-name}.cognitiveservices.azure.com) 。 |
要求本文
名稱 | 必要 | 類型 | Description |
---|---|---|---|
dynamicPersonGroupId | True |
string |
要比對的目標 PersonDirectory DynamicPersonGroup 的 DynamicPersonGroupId。 |
faceIds | True |
string[] |
查詢臉部 faceId 的陣列,由 「Detect」 所建立。 每個臉部都會獨立識別。 faceIds 的有效數目介於 [1, 10] 之間。 |
confidenceThreshold |
number |
自定義識別信賴閾值,範圍為 [0, 1]。 進階使用者可以調整此值,以覆寫預設內部閾值,以取得其案例數據更好的精確度。 請注意,此臨界值無法保證會在其他數據和演算法更新之後運作。 |
|
maxNumOfCandidatesReturned |
integer |
maxNumOfCandidatesReturned 的範圍介於 1 到 100 之間。 預設值為 10。 |
回應
名稱 | 類型 | Description |
---|---|---|
200 OK |
成功的呼叫會針對每個查詢臉部傳回識別的候選人員 () 。 |
|
Other Status Codes |
未預期的錯誤回應。 Headers x-ms-error-code: string |
安全性
Ocp-Apim-Subscription-Key
Azure AI 臉部訂用帳戶的秘密密鑰。
Type:
apiKey
In:
header
AADToken
Azure Active Directory OAuth2 流程
Type:
oauth2
Flow:
accessCode
Authorization URL:
https://api.example.com/oauth2/authorize
Token URL:
https://api.example.com/oauth2/token
Scopes
名稱 | Description |
---|---|
https://cognitiveservices.azure.com/.default |
範例
Identify from DynamicPersonGroup
Sample Request
POST {endpoint}/face/v1.1-preview.1/identify
{
"faceIds": [
"c5c24a82-6845-4031-9d5d-978df9175426"
],
"dynamicPersonGroupId": "your_dynamic_person_group_id",
"maxNumOfCandidatesReturned": 9,
"confidenceThreshold": 0.7
}
Sample Response
[
{
"faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
"candidates": [
{
"personId": "85c0c630-c9c9-40f8-8a4e-f9ae4f926ea5",
"confidence": 0.8
}
]
}
]
定義
名稱 | Description |
---|---|
Face |
錯誤物件。 如需臉部服務所傳回錯誤碼和訊息的完整詳細數據,請參閱下列連結: https://aka.ms/face-error-codes-and-messages。 |
Face |
包含錯誤詳細數據的回應。 |
Identification |
識別通話的候選專案。 |
Identification |
識別結果。 |
FaceError
錯誤物件。 如需臉部服務所傳回錯誤碼和訊息的完整詳細數據,請參閱下列連結: https://aka.ms/face-error-codes-and-messages。
名稱 | 類型 | Description |
---|---|---|
code |
string |
其中一組伺服器定義的錯誤碼。 |
message |
string |
人類看得懂的錯誤表示法。 |
FaceErrorResponse
包含錯誤詳細數據的回應。
名稱 | 類型 | Description |
---|---|---|
error |
錯誤物件。 |
IdentificationCandidate
識別通話的候選專案。
名稱 | 類型 | Description |
---|---|---|
confidence |
number |
候選專案的信賴值。 信賴度越高,比較類似。 介於 [0,1] 之間的範圍。 |
personId |
string |
候選人員的personId。 |
IdentificationResult
識別結果。
名稱 | 類型 | Description |
---|---|---|
candidates |
識別出該臉部的人員候選專案 (依信賴) 排名。 陣列大小不應大於輸入 maxNumOfCandidatesReturned。 如果未識別任何人員,則會傳回空陣列。 |
|
faceId |
string |
查詢臉部的faceId。 |