指定臉部偵測模式

發行項
10/16/2024

本指南說明如何為 Azure AI 臉部服務指定臉部偵測模型。

臉部服務使用機器學習模型，對影像中的人臉執行作業。我們會根據客戶的意見反應和研究的進展，持續改善這些模型的精確度，並透過更新模型來提供這些改善措施。開發人員可以指定要使用的臉部偵測模型版本；他們可以選擇最適合其使用案例的模型。

請繼續閱讀，以了解如何在特定臉部作業中指定臉部偵測模型。臉部服務在將臉部的影像轉換成其他形式的資料時，都會用到臉部偵測。

如果您不確定是否應使用最新的模型，請跳到評估不同模型章節，以評估新的模型，並使用您目前的資料集來比較結果。

必要條件

您應熟悉 AI 臉部偵測的概念。如果不熟悉，請參閱臉部偵測概念性指南或操作指南：

評估不同模型

不同的臉部偵測模型適用於不同工作。請參閱下表以簡要了解其差異。

模型	描述	效能注意事項	地標
detection_01	所有臉部偵測作業的預設選項。	不適合很小、側面或模糊的臉部。	如果在偵測呼叫中指定了臉部關鍵點，會將其傳回。
detection_02	於 2019 年 5 月發行，且在所有臉部偵測作業中均可選擇使用。	提升了很小、側面和模糊臉部的精確度。	不會傳回臉部地標。
detection_03	於 2021 年 2 月發行，且在所有臉部偵測作業中均可選擇使用。	進一步提升精確度，包括較小的臉部 (64x64 像素) 和旋轉的臉部方向。	如果在偵測呼叫中指定了臉部關鍵點，會將其傳回。

屬性是一組特徵，若在偵測呼叫中指定了特徵，可選擇性地偵測這些特徵：

Model	配件	模糊	曝光	眼鏡	headPose	mask	雜訊	occlusion	qualityForRecognition
detection_01	✔️	✔️	✔️	✔️	✔️		✔️	✔️	✔️ (適用於 recognition_03 或 04)
detection_02
detection_03		✔️	✔️	✔️	✔️	✔️		✔️	✔️ (適用於 recognition_03 或 04)

比較偵測模型效能的最佳方式，就是在範例資料集加以使用。建議您使用每個偵測模型，對各種影像呼叫偵測 API，尤其是有許多臉部或難以看清臉部的影像。請注意每個模型傳回的臉部數目。

使用指定的模型偵測臉部

臉部偵測會尋找人臉的周框方塊位置，並識別其視覺關鍵點。該功能會擷取臉部的特徵，並加以儲存，以供之後在辨識作業中使用。

當您使用偵測 API 時，可以使用 detectionModel 參數指派模型版本。可用的值為：

detection_01
detection_02
detection_03

偵測 REST API 的要求 URL 看起來如下所示：

https://westus.api.cognitive.microsoft.com/face/v1.0/detect?detectionModel={detectionModel}&recognitionModel={recognitionModel}&returnFaceId={returnFaceId}&returnFaceAttributes={returnFaceAttributes}&returnFaceLandmarks={returnFaceLandmarks}&returnRecognitionModel={returnRecognitionModel}&faceIdTimeToLive={faceIdTimeToLive}

如果您使用的是用戶端程式庫，您可以傳遞適當的字串來指派 detectionModel 的值。如果您維持未指派，則 API 會使用預設的模型版本 (detection_01)。請參閱 .NET 用戶端程式庫的下列程式碼範例。

string imageUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/detection1.jpg";
var response = await faceClient.DetectAsync(new Uri(imageUrl), FaceDetectionModel.Detection03, FaceRecognitionModel.Recognition04, returnFaceId: false, returnFaceLandmarks: false);
var faces = response.Value;

使用指定的模型將臉部新增到 Person

臉部辨識服務可以從影像中擷取臉部資料，並透過新增人員群組人員臉部 API 將其與 Person 物件建立關聯。在此 API 呼叫中，您可以用與偵測相同的方式來指定偵測模型。

請參閱下列 .NET 程式碼範例。

// Create a PersonGroup and add a person with face detected by "detection_03" model
string personGroupId = "mypersongroupid";
using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["name"] = "My Person Group Name", ["recognitionModel"] = "recognition_04" }))))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    await httpClient.PutAsync($"{ENDPOINT}/face/v1.0/persongroups/{personGroupId}", content);
}

string? personId = null;
using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["name"] = "My Person Name" }))))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    using (var response = await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/persongroups/{personGroupId}/persons", content))
    {
        string contentString = await response.Content.ReadAsStringAsync();
        personId = (string?)(JsonConvert.DeserializeObject<Dictionary<string, object>>(contentString)?["personId"]);
    }
}

string imageUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/detection1.jpg";
using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["url"] = imageUrl }))))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/persongroups/{personGroupId}/persons/{personId}/persistedfaces?detectionModel=detection_03", content);
}

此程式碼會建立識別碼為 mypersongroupid 的 PersonGroup，並在其中新增 Person。接著會使用 detection_03 模型將臉部新增到這個 Person。如果您未指定 detectionModel 參數，則 API 會使用預設模型 detection_01。

注意

您不需要對 Person 物件中的所有臉部使用相同偵測模型，而且在偵測新臉部以與 Person 物件 (例如在識別人員群組 API 中) 比較時，也不需要使用相同的偵測模型。

使用指定的模型將臉部新增到 FaceList

當您將臉部新增到現有的 FaceList 物件時，也可以指定偵測模型。請參閱下列 .NET 程式碼範例。

using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["name"] = "My face collection", ["recognitionModel"] = "recognition_04" }))))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    await httpClient.PutAsync($"{ENDPOINT}/face/v1.0/facelists/{faceListId}", content);
}

string imageUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/detection1.jpg";
using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["url"] = imageUrl }))))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/facelists/{faceListId}/persistedfaces?detectionModel=detection_03", content);
}

這段程式碼會建立名為 My face collection 的 FaceList，並使用 detection_03 模型將臉部新增到其中。如果您未指定 detectionModel 參數，則 API 會使用預設模型 detection_01。

注意

您不需要對 FaceList 物件中的所有臉部使用相同偵測模型，而且在偵測新臉部以與 FaceList 物件比較時，也不需要使用相同的偵測模型。

下一步

在本文中，您已了解如何指定要搭配不同 Face API 使用的辨識模型。接下來，可以透過快速入門開始進行臉部偵測和分析。

共用方式為