Azure Cognitive ServicesのPerson Group構造を使ってみる #azure #faceapi #persongroup

構造の包含関係としては以下の感じ
Person Group > Person Group Person > PersistedFace

顔があって、人がいて、人の集まりをグループと呼んでいる感じ。

学習～推論の操作順は以下の通り。

#	構造	操作	内容
1	Person Group	Create	Person Groupを作成
2	Person Group Person	Create	Personを作成
3	Person Group Person	Add Face	Personに顔を追加
4	Person Group	Train	Person Groupに追加されたPersonを学習する
5	Person Group	Get Training Status	学習状況を取得する
-	学習ここまで	-	-
6	Face	Detect	推論したい顔を検出する
7	Face	Identify	検出した顔がどのPersonかを推論する

光岡高宏

Person Group - Createのサンドボックス

光岡高宏

パラメータ一覧

クエリパラメータ
- personGroupId: 任意のグループID
ヘッダー
- Ocp-Apim-Subscription-Key: APIキー
リクエストボディ
- name: グループ名
- userData: グループの説明/メタデータ
- recognitionModel: 利用するモデル。recognition_04が一番新しく、03と比べてマスク着用時の精度が向上しているらしい。

リクエスト例

PUT https://japaneast.api.cognitive.microsoft.com/face/v1.0/persongroups/sample-group-1 HTTP/1.1
Host: japaneast.api.cognitive.microsoft.com
Content-Type: application/json
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••

{
    "name": "テストグループ1",
    "userData": "user-provided data attached to the person group.",
    "recognitionModel": "recognition_04"
}

レスポンス例

x-envoy-upstream-service-time: 226
apim-request-id: d42ec460-e5a0-4679-940c-41ccd199653f
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
CSP-Billing-Usage: CognitiveServices.Face.Transaction=1
Date: Wed, 25 Aug 2021 14:58:39 GMT
Content-Length: 0

光岡高宏

PersonGroup Person - Create のサンドボックス

光岡高宏

クエリパラメータ
- personGroupId: Person Group - Createで作成したPerson GroupのID
ヘッダー
- Ocp-Apim-Subscription-Key: APIキー
リクエストボディ
- name: グループ名
- userData: グループの説明/メタデータ

リクエスト例

POST https://japaneast.api.cognitive.microsoft.com/face/v1.0/persongroups/sample-group-1/persons HTTP/1.1
Host: japaneast.api.cognitive.microsoft.com
Content-Type: application/json
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••

{
    "name": "ueshima",
    "userData": "ueshima"
}

レスポンス例

x-envoy-upstream-service-time: 89
apim-request-id: 97bf955c-22eb-4b37-b2c7-87ebf46583ad
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
CSP-Billing-Usage: CognitiveServices.Face.Transaction=1
Date: Wed, 25 Aug 2021 16:47:08 GMT
Content-Length: 51
Content-Type: application/json; charset=utf-8

{
  "personId": "b41a314a-b830-4d7c-8400-d2de1d4b5eb3"
}

光岡高宏

試しにダチョウ倶楽部の顔認識してみよう。

[memo]

ueshima: b41a314a-b830-4d7c-8400-d2de1d4b5eb3
terakado: 6a5b8e4b-4dd7-42ca-bcc0-b5a993adf5ef
higo: 1f5e9f88-b23b-4a2b-b317-b423e7271dca

光岡高宏

#	構造	操作	内容	今
1	Person Group	Create	Person Groupを作成
2	Person Group Person	Create	Personを作成
3	Person Group Person	Add Face	Personに顔を追加	<--
4	Person Group	Train	Person Groupに追加されたPersonを学習する
5	Person Group	Get Training Status	学習状況を取得する
-	学習ここまで	-	-
6	Face	Detect	推論したい顔を検出する
7	Face	Identify	検出した顔がどのPersonかを推論する

光岡高宏

PersonGroup Person - Add Face のサンドボックス

光岡高宏

クエリパラメータ
- personGroupId: Person Group - Createで作成したPerson GroupのID
- personId: PersonGroup Person - Createで作成したPersonのID
- userData: おそらくユーザーのメタデータを設定できる
- targetFace: おそらく画像に写っている顔の座標を指定するもの？
- detectionModel: 顔検出に使用するモデル。detection_03が一番新しく2021/02にリリースされた。小さく写っている顔に対する精度が改善されているそう。
ヘッダー
- Ocp-Apim-Subscription-Key: APIキー
リクエストボディ
- url: 顔が写っている画像のURL

リクエスト例

POST https://japaneast.api.cognitive.microsoft.com/face/v1.0/persongroups/sample-group-1/persons/b41a314a-b830-4d7c-8400-d2de1d4b5eb3/persistedFaces?userData=ueshima_01&detectionModel=detection_03 HTTP/1.1
Host: japaneast.api.cognitive.microsoft.com
Content-Type: application/json
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••

{
    "url": "https://i.gyazo.com/037c32e3c019de5533a405308925dfba.jpg"
}

レスポンス例

x-envoy-upstream-service-time: 788
apim-request-id: 6b1dca45-6064-4c09-9e1d-667e509f4a64
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
CSP-Billing-Usage: CognitiveServices.Face.Transaction=1
Date: Wed, 25 Aug 2021 17:00:16 GMT
Content-Length: 58
Content-Type: application/json; charset=utf-8

{
  "persistedFaceId": "6953481a-3278-4bf0-a364-8515390a0f1d"
}

光岡高宏

一人5枚ずつくらい画像を追加しておく

光岡高宏

PersonGroup - Train のサンドボックス

光岡高宏

クエリパラメータ
- personGroupId: Person Group - Createで作成したPerson GroupのID
ヘッダー
- Ocp-Apim-Subscription-Key: APIキー

リクエスト例

POST https://japaneast.api.cognitive.microsoft.com/face/v1.0/persongroups/sample-group-1/train HTTP/1.1
Host: japaneast.api.cognitive.microsoft.com
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••

レスポンス例

Operation-Location: https://japaneast.api.cognitive.microsoft.com/face/v1.0/persongroups/sample-group-1/training
x-envoy-upstream-service-time: 31
apim-request-id: 886a39d1-63d9-4b0b-b62e-c214c4efb260
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
CSP-Billing-Usage: CognitiveServices.Face.Transaction=1
Access-Control-Expose-Headers: Operation-Location
Date: Wed, 25 Aug 2021 17:07:55 GMT
Content-Length: 0

光岡高宏

PersonGroup - Get Training Status のサンドボックス

こちらを使って、学習状況を見守ることができます。

光岡高宏

リクエストは、PersonGroup - Train と同じなので省略。

レスポンス例

x-envoy-upstream-service-time: 12
apim-request-id: dd710b0d-646b-47c6-9f92-b77e72150054
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
CSP-Billing-Usage: CognitiveServices.Face.Transaction=1
Date: Wed, 25 Aug 2021 17:09:13 GMT
Content-Length: 251
Content-Type: application/json; charset=utf-8

{
  "status": "succeeded",
  "createdDateTime": "2021-08-25T17:07:56.3214291Z",
  "lastActionDateTime": "2021-08-25T17:07:56.634359Z",
  "lastSuccessfulTrainingId": "10ce24c3-b677-4260-bc67-9c755c3c8aa5",
  "lastSuccessfulTrainingDateTime": "2021-08-25T17:07:56.634359Z"
}

光岡高宏

1分以内に学習終わった。結構早い。

光岡高宏

#	構造	操作	内容	今
1	Person Group	Create	Person Groupを作成
2	Person Group Person	Create	Personを作成
3	Person Group Person	Add Face	Personに顔を追加
4	Person Group	Train	Person Groupに追加されたPersonを学習する
5	Person Group	Get Training Status	学習状況を取得する
-	学習ここまで	-	-
6	Face	Detect	推論したい顔を検出する	<--
7	Face	Identify	検出した顔がどのPersonかを推論する

光岡高宏

学習に使用していないこちらの画像で推論してみます。

光岡高宏

Face - Detect のサンドボックス

光岡高宏

クエリパラメータ
- returnFaceId: 検出した顔のIDをレスポンスに載せるか。後で使うのでtrueにしておきます。
- returnFaceLandmarks: 顔の特徴点をレスポンスに載せるか。今回はfalseでOK。
- returnFaceAttributes: レスポンスに載せる顔の属性。今回は使わない。
- recognitionModel: 顔認識モデル。Person Group - Createで指定したものと同じモデルを指定しないといけない。
- returnRecognitionModel: 顔認識モデルをレスポンスに載せるか。いらない。
- detectionModel: 顔検出モデル。PersonGroup Person - Add Face で使用したものに一応合わせておく。
- faceIdTimeToLive: FaceIDの有効期限。
ヘッダー
- Ocp-Apim-Subscription-Key: APIキー
リクエストボディ
- url: 顔認識したい画像のURL

リクエスト例

POST https://japaneast.api.cognitive.microsoft.com/face/v1.0/detect?returnFaceId=true&returnFaceLandmarks=false&recognitionModel=recognition_04&returnRecognitionModel=false&detectionModel=detection_03&faceIdTimeToLive=86400 HTTP/1.1
Host: japaneast.api.cognitive.microsoft.com
Content-Type: application/json
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••

{
    "url": "https://i.gyazo.com/4e59cd046449277d37d3a45c877c3c03.jpg"
}

レスポンス例

x-envoy-upstream-service-time: 659
apim-request-id: c36638ba-a374-431e-b50f-f8b1faa94166
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
CSP-Billing-Usage: CognitiveServices.Face.Transaction=1
Date: Wed, 25 Aug 2021 17:20:32 GMT
Content-Length: 113
Content-Type: application/json; charset=utf-8

[{
  "faceId": "65b09cb1-85c2-449b-926f-dfc0339d8b8d",
  "faceRectangle": {
    "top": 67,
    "left": 55,
    "width": 150,
    "height": 195
  }
}]

光岡高宏

Face - Identify のサンドボックス

光岡高宏

ヘッダー
- Ocp-Apim-Subscription-Key: APIキー
リクエストボディ
- personGroupId: Person Group - Createで作成したPerson GroupのID
- faceIds: 顔認識したいFaceIDの配列。Face - Detect で取得したFace IDを使う。
- maxNumOfCandidatesReturned: (オプション)推論結果をいくつまで表示するか。1~100の範囲で選択可能。
- confidenceThreshold: (オプション)顔一致度のしきい値の設定。0~1の範囲で設定可能。説明を読んでる限り、初心者はいじらないほうが良い。

リクエスト例

POST https://japaneast.api.cognitive.microsoft.com/face/v1.0/identify HTTP/1.1
Host: japaneast.api.cognitive.microsoft.com
Content-Type: application/json
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••

{
    "personGroupId": "sample-group-1",
    "faceIds": [
        "65b09cb1-85c2-449b-926f-dfc0339d8b8d"
    ],
}

レスポンス例

x-envoy-upstream-service-time: 362
apim-request-id: 33512658-5113-424c-a950-62c14b9ea9a0
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
CSP-Billing-Usage: CognitiveServices.Face.Transaction=1
Date: Wed, 25 Aug 2021 17:27:21 GMT
Content-Length: 139
Content-Type: application/json; charset=utf-8

[{
  "faceId": "65b09cb1-85c2-449b-926f-dfc0339d8b8d",
  "candidates": [{
    "personId": "b41a314a-b830-4d7c-8400-d2de1d4b5eb3",
    "confidence": 0.93884
  }]
}]

光岡高宏

Person IDがb41a314a-b830-4d7c-8400-d2de1d4b5eb3の人と93.884%と同一人物という推論結果が出ました。

を見ると、b41a314a-b830-4d7c-8400-d2de1d4b5ebはueshimaなので合っていますね！

光岡高宏

Person IDだけでは誰かわからないので、メタデータを取得して誰か調べてみます。

光岡高宏

PersonGroup Person - Get のサンドボックス

光岡高宏

クエリパラメータ
- personGroupId: Person Group - Createで作成したPerson GroupのID
- personId: Face - Identifyで取得したPerson Group PersonのID
ヘッダー
- Ocp-Apim-Subscription-Key: APIキー

リクエスト例

GET https://japaneast.api.cognitive.microsoft.com/face/v1.0/persongroups/sample-group-1/persons/b41a314a-b830-4d7c-8400-d2de1d4b5eb3 HTTP/1.1
Host: japaneast.api.cognitive.microsoft.com
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••

レスポンス例

x-envoy-upstream-service-time: 21
apim-request-id: 81dba5f6-102f-4666-8a64-cd9e995342ce
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
CSP-Billing-Usage: CognitiveServices.Face.Transaction=1
Date: Wed, 25 Aug 2021 17:33:29 GMT
Content-Length: 305
Content-Type: application/json; charset=utf-8

{
  "personId": "b41a314a-b830-4d7c-8400-d2de1d4b5eb3",
  "persistedFaceIds": ["08627e7e-c58a-4bea-a011-6ff87f0748c2", "6953481a-3278-4bf0-a364-8515390a0f1d", "a82473a5-cda2-4dff-94f7-7c80b3c5b543", "be4433b3-6ce4-4c67-b626-e01d9a705b3d", "de2f3062-966a-4a56-90c7-937e307630c5"],
  "name": "ueshima",
  "userData": "ueshima"
}

光岡高宏

これでueshimaを取得することができました。

光岡高宏

構造化されていてわかりやすいですが、たくさん操作しないといけないので大変ですね。

光岡高宏

ちなみに最近Person Directoryという新機能が追加されて、現在パプリックプレビュー中だそうです。

PersonDirectory と以前のデータ構造のもう 1 つの大きな違いは、顔を Person オブジェクトに追加した後にトレーニングの呼び出しを行う必要がなくなったことです。

これは便利ですね。正式リリースに期待。