顔検出モデルを指定する

このガイドでは、Azure AI Face サービスの顔検出モデルを指定する方法を示します。

Face サービスでは、機械学習モデルを使用して、画像内の人間の顔に対して操作を実行します。 お客様からのフィードバックや研究の進展に基づいてモデル精度の改善を続けており、これらの改善をモデルの更新として提供します。 開発者は、使う顔検出モデルのバージョンを指定でき、ユース ケースに最適なモデルを選択できます。

特定の顔操作での顔検出モデルの指定方法について、後続の説明をお読みください。 Face サービスは、顔の画像を他の形式のデータに変換するときは常に、顔検出を使用します。

最新モデルを使用すべきかどうかわからない場合は、「さまざまなモデルを評価する」のセクションに進み、新しいモデルを評価したり、現在のデータセットを使用して結果を比較したりしてください。

前提条件

AI による顔検出の概念を理解している必要があります。 そうでない場合は、顔検出に関する概念ガイドまたはハウツー ガイドを参照してください。

• 顔検出の概念
• 検出 API を呼び出す

さまざまなモデルを評価する

各顔検出モデルは、異なるタスクに合わせて最適化されています。 相違点の概要については、次の表を参照してください。

属性は、検出呼び出しで指定されている場合に必要に応じて検出できる一連の機能です。

検出モデルのパフォーマンスを比較する最良の方法は、それらをサンプル データセットで使用することです。 さまざまな画像、特に多数の顔や識別しづらい顔の画像に対して、それぞれの検出モデルを使用して Detect API を呼び出すことをお勧めします。 各モデルによって返される顔の数に注意してください。

指定されたモデルで顔を検出する

顔検出では、人間の顔の境界ボックス位置を見つけ、それらの視覚的な目印を識別します。 顔の特徴を抽出し、後で認識操作で使用するために保存します。

Detect API を使用するときは、detectionModel パラメーターを使用してモデルのバージョンを割り当てることができます。 使用できる値は次のとおりです。

• detection_01
• detection_02
• detection_03

Detect 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 に顔を追加する

Face サービスでは画像から顔データを抽出し、Add Person Group Person Face API によってそれを Person オブジェクトに関連付けることができます。 この API 呼び出しでは、Detect と同じ方法で検出モデルを指定できます。

次の .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);
}

このコードは、ID mypersongroupid を持つ PersonGroup を作成し、それに Person を追加します。 次に、detection_03 モデルを使用して、この Person に顔を追加します。 detectionModel パラメーターを指定しない場合、API は既定のモデルである detection_01 を使います。

指定したモデルを使用して 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 を使います。

次のステップ

この記事では、さまざまな Face API で使用する検出モデルを指定する方法について説明しました。 次は、クイック スタートに従って顔検出と分析を開始します。

• Face .NET SDK
• Face Python SDK
• Face Java SDK
• Face JavaScript SDK