Python 機械学習のためのMicrosoft Azure Face API活用① Microsoft Azure Face APIに、AV女優を学習させるためにAPIドキュメントを読む

Microsoft Azure Face APIを利用して、スクレイピングで取得したAV女優の画像を学習させる。

#TODO

• この記事を参考にして、Microsoft Face APIにAV女優の画像を学習させる
• 今回はMicrosoft Azure Face APIを利用してみたいので、そのドキュメントを読んでまとめてみる

Face APIで登録した顔の人物情報を取得する

• Pythonのrequestsを利用して、Web APIを利用する
• 具体的な処理の流れ
• Person Groupを作成する
• Personを作成する
• 顔を登録する
• 最後にPerson Groupを学習させる

Person Groupを作成する

Web APIドキュメントを読むと、こう書いてある。

PersonGroup - Create
Create a new person group with specified personGroupId, name, and user-provided userData.
A person group is the container of the uploaded person data, including face images and face recognition features.
After creation, use PersonGroup Person - Create to add persons into the group, and then call PersonGroup - Train to get this group ready for Face - Identify.
The person's face, image, and userData will be stored on server until PersonGroup Person - Delete or PersonGroup - Delete is called. 

各種パラメーターは以下の通り。
リクエストヘッダーに、サブスクリプションキーを入れて、リクエストボディにはグループ名を入れればよさそうである。

personGroupIdには、英数字小文字、-, _が利用できて、最大文字数は64文字とのこと。

Request URL

https://[location].api.cognitive.microsoft.com/face/v1.0/persongroups/{personGroupId}

Request parameters

personGroupId

string

User-provided personGroupId as a string. The valid characters include numbers, English letters in lower case, '-' and '_'. The maximum length of the personGroupId is 64.

Request headers

Content-Type (optional)

string

Media type of the body sent to the API.

Ocp-Apim-Subscription-Key

string

Subscription key which provides access to this API. Found in your Cognitive Services accounts.

Request body

JSON fields in request body:

Fields	Type	Description
name	String	Person group display name. The maximum length is 128.
userData (optional)	String	User-provided data attached to the person group. The size limit is 16KB.

Pythonのサンプルコードもあったので、こちらにメモしておく。

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.parse.urlencode({
})

try:
    conn = http.client.HTTPSConnection('westus.api.cognitive.microsoft.com')
    conn.request("POST", "/face/v1.0/persongroups/{personGroupId}/train?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

Personを作成する

作成したグループの中に、一人ひとりの画像を作成する。公式ドキュメントにはこのように書いてある。無料のものだと、1000人が限界とのこと。

PersonGroup Person - Create

Create a new person in a specified person group. To add face to this person, please call PersonGroup PersonFace - Add. 

• Free-tier subscription quota:
  • 1,000 persons in all person groups.
• S0-tier subscription quota:
  • 10,000 persons per person group.
  • 1,000,000 person groups.
  • 100,000,000 persons in all person groups.

各種パラメーターは以下の通り。URLには、パラメータに先ほど作成したpersonGroupIdを入れてあげるとよいらしい。
ヘッダーにサブスクリプションキーを入れて、ボディに名前を入れるらしい。

Request URL

https://[location].api.cognitive.microsoft.com/face/v1.0/persongroups/{personGroupId}/persons

Request parameters

personGroupId

string

Specifying the target person group to create the person.

Request headers

Content-Type (optional)

string

Media type of the body sent to the API.

Ocp-Apim-Subscription-Key

string

Subscription key which provides access to this API. Found in your Cognitive Services accounts.

Request body

JSON fields in request body:

Fields	Type	Description
name	String	Display name of the target person. The maximum length is 128.
userData (optional)	String	Optional fields for user-provided data attached to a person. Size limit is 16KB.

リクエストが返ってくると、個人のIDが返ってくるみたいだ。

{
    "personId": "25985303-c537-4467-b41d-bdb45cd95ca1"
}

Pythonのサンプルコードはこれ。

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Content-Type': 'application/json',
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.parse.urlencode({
})

try:
    conn = http.client.HTTPSConnection('westus.api.cognitive.microsoft.com')
    conn.request("POST", "/face/v1.0/persongroups/{personGroupId}/persons?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

顔を登録する

公式ドキュメントを読む。

登録する場合に注意することは、

• 四角形の画像を選択すること
• 248枚の画像を上限に学習できる
• ファイルサイズは4MBまで
• 複数の顔が入っている画像はエラーが起こる

PersonGroup Person - Add Face
Add a face image to a person into a person group for face identification or verification. To deal with the image of multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. The face image and related info will be stored on server until PersonGroup PersonFace - Delete, PersonGroup Person - Delete or PersonGroup - Delete is called.
Note persistedFaceId is different from faceId generated by Face - Detect.
Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger.
Each person entry can hold up to 248 faces.
JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 4MB.
"targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from Face - Detect, there’s no guarantee to detect and add the face successfully.
Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures.
Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel.

URLのパラメーターには、さきほど取得したpersonIdを入れておいてあげればよいらしい。リクエストパラメーターには、personGroupIdを、ボディには画像のURLを入れてあげれば、画像を追加することができるようですね。

Request URL

https://[location].api.cognitive.microsoft.com/face/v1.0/persongroups/{personGroupId}/persons/{personId}/persistedFaces[?userData][&targetFace]

Request parameters

personGroupId

string

Specifying the person group containing the target person.

personId

string

Target person that the face is added to.

userData (optional)

string

User-specified data about the target face to add for any purpose. The maximum length is 1KB.

targetFace (optional)

string

A face rectangle to specify the target face to be added to a person, in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image.

Request headers

Content-Type (optional)

string

Media type of the body sent to the API.

Ocp-Apim-Subscription-Key

string

Subscription key which provides access to this API. Found in your Cognitive Services accounts.

Request body

JSON fields in request body:

Fields	Type	Description
url	String	Face image URL. Valid image size is from 1KB to 4MB. Only one face is allowed per image.

Pythonのサンプルコードはこちら

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Content-Type': 'application/json',
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.parse.urlencode({
    # Request parameters
    'userData': '{string}',
    'targetFace': '{string}',
})

try:
    conn = http.client.HTTPSConnection('westus.api.cognitive.microsoft.com')
    conn.request("POST", "/face/v1.0/persongroups/{personGroupId}/persons/{personId}/persistedFaces?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))




最後にPerson Groupを学習させる

学習させます。

• PersonGroupを見ると、学習が完了したかどうかを確認することができるらしい。

PersonGroup - Train
Submit a person group training task. Training is a crucial step that only a trained person group can be used by Face - Identify.
The training task is an asynchronous task. Training time depends on the number of person entries, and their faces in a person group. It could be several seconds to minutes. To check training status, please use PersonGroup - Get Training Status.

パラメーターはpersonGroupIdを指定してあげて、ヘッダーにはSubscription-Keyを入れてあげればよいみたいですね。

Request URL

https://[location].api.cognitive.microsoft.com/face/v1.0/persongroups/{personGroupId}/train

Request parameters

personGroupId

string

Target person group to be trained.

Request headers

Ocp-Apim-Subscription-Key

string

Subscription key which provides access to this API. Found in your Cognitive Services accounts.

Pythonのサンプルコードがこちら。

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.parse.urlencode({
})

try:
    conn = http.client.HTTPSConnection('westus.api.cognitive.microsoft.com')
    conn.request("POST", "/face/v1.0/persongroups/{personGroupId}/train?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################