PythonによるWeb API入門（2）顔認識の機械学習APIを利用する

*******************************************************

【お得なマガジンもあります】
Pythonを利用した、Web APIを学べるコースです。セット割で、3000円ほどお得になります。現在、3本のチュートリアルが利用できます。一からAPIを学びたい人は、こちらのWeb APIコースがおすすめです！

①PythonによるWeb API入門（1） AKBの画像を5000件API経由でダウンロードする
②PythonによるWeb API入門（2）顔認識の機械学習APIを利用する
③Flaskチュートリアル - Pythonでツイッターの分析ツールを作ってディプロイしよう！（動画つき！）-

Web APIコース｜Dai｜note

*******************************************************

PythonでWeb APIを利用するためのチュートリアルです。前回作成した、

≫PythonによるWeb API入門（1） AKBの画像を5000件API経由でダウンロードする

の続編となります。

このチュートリアルでやること

このチュートリアルでやることは、以下のとおりです。

・AKB48のメンバーの画像を、顔認識のAPIに送信
・顔認識のAPIがAKBメンバーの画像を学習
・画像を送信すると、一番似ているAKBメンバーを抽出して教えてくれる

といったものになっています。

CSVからAKBの画像データを取得して、データをMicrosoft Cognitive Face APIに送信します。

送信すると、Microsoft Face APIが顔と名前を一致して学習してくれるので、次に任意の女性の画像を送信すると、それに似たAKBのメンバーを教えてくれるといったものになります。

このチュートリアルの対象者

このチュートリアルの対象者は以下の通りです。

・ProgateのPython1-3はクリアしている人（※必須）
・ProgateのCommand Lineをクリアしている人（※必須）
・基礎的なWeb APIの知識を理解している人（※任意）
・Pandasの基礎的な利用方法について理解している人（※任意）

となります。できれば、

≫PythonによるWeb API入門（1） AKBの画像を5000件API経由でダウンロードする

を理解したうえで進めていただけると、進めやすいかと思います。

このチュートリアルの流れ

以下の手順で学習を進めていきます。

・Microsoft Cognitive Face APIとは？
・PythonでAKBの画像データのCSVをインポート
・それぞれの顔認識の画像に対して、一人ひとり学習を進めるコードを書く
・画像URLを指定すると、それに似た画像を返してくれるようなコードを書く

Microsoft Cognitive Face APIとは？

今回使う、Microsoft Cognitive Face APIについて解説します。公式はこちらのページをご覧ください。公式サイトはこちらです。

Face API - 顔認識ソフトウェア | Microsoft Azure

Face APIを利用するためには、Microsoftのアカウントを作成する必要があります。アカウントを作成する方法はこちらの記事が詳しいので、ぜひ参考にしてみてください。

Azure Computer Vision APIとFace APIをPythonから利用する | ブログ一覧 | DATUM STUDIO株式会社

Cognitive ServicesのFace APIを登録してみる。|ネスケラボ

さて、アカウントが作成されてから学習するまでの流れはこちらのブログにまとめていますので、ぜひ参照してみてください。

さて、晴れて登録できたら、今度はFace APIを利用するためのサブスクリプションキーを発行します。

発行するとここの上のところからサブスクリプションキーを取得することができます。ここのキーをメモしておきます。

こちらの

・Endpoint
・サブスクリプションID

をメモしておいてください。

Face APIの仕組み

Face APIの仕組み

・Person Group：学習させる人の集合(今回だったらAKBメンバー全体)
・Person：人一人（鳳かなめ、あおいそら等）
・Person Face: Personに紐づく画像（複数）

流れとしては

1. Person Groupの作成
2. Person Groupに、Personを追加
3. Personに、Person Faceを追加
4. Person Groupの学習

となります。

Person Groupの作成

さて、最初にPerson Groupを作成します。APIリファレンスを読んでみましょう。

Microsoft Cognitive Services

以下のように書いてあります。

指定したpersonGroupId、name、およびuser-provided userDataを持つ新しい個人グループを作成します。
userGroupは、顔画像および顔認識機能を含む、アップロードされた人物データのコンテナです。
作成後、PersonGroup Person - Createを使用してPersonをグループに追加し、PersonGroup - Trainを呼び出してこのグループをFace-Identifyの準備が整うようにします。
personGroup Person - DeleteまたはPersonGroup - Deleteが呼び出されるまで、personのface、image、userDataはサーバーに保存されます。

リクエストURL

リクエストURLは以下のとおりです。

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

ＨTTPメソッド

HTTPメソッドはPUT(更新)になります。

リクエストパラメーター

必須のリクエストパラメーターは以下の通りです。

personGroupId： ユーザー指定のpersonGroupIdを文字列として返します。有効な文字には、数字、英字（小文字）、 ' - '、 '_'が含まれます。 personGroupIdの最大長は64です。

リクエストヘッダー

必須のリクエストヘッダーは以下の通りです。

Ocp-Apim-Subscription-Key：このAPIへのアクセスを提供するサブスクリプションキー。あなたのCognitive サービスアカウントにあります。

リクエストボディ

必須のリクエストヘッダーは以下の通りです。

name： Person group の表示名.最大文字数は128字です.

コーディング

のちほどコードの解説はしますが、以下のように実装することになります。こちらはのちほど変わるコードなので、「こういう構造になるんだ～」くらいで理解しておいてください。

def makeGroup():
  end_point = BASE_URL + "persongroups/" + GROUP_NAME
  payload = { # ここがリクエストボディになります。
      "name": GROUP_NAME
  }
  headers = { # ここがヘッダーになります
      "Ocp-Apim-Subscription-Key" :SUBSCRIPTION_KEY 
  }
  r = requests.put(
      end_point, # URL 
      headers = headers, # ヘッダー
      json = payload # リクエスト墓碑
  )
  print (r.text)

Person Groupに、Personを追加

次に、Personを追加します。リファレンスはこちらになります。

Microsoft Cognitive Services

さきほどと同じようにリファレンスを読んでいきましょう。

リクエストURL

リクエストURLは以下のとおりです。

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

リクエストパラメーター

必須のリクエストパラメーターは以下の通りです。

personGroupId: 先ほど指定したperronGroupIdを指定します

リクエストヘッダー

必須のリクエストヘッダーは以下の通りです。

Ocp-Apim-Subscription-Key：このAPIへのアクセスを提供するサブスクリプションキー。あなたのCognitive サービスアカウントにあります。

リクエストボディ

必須のリクエストボディは以下の通りです。

name：人間の名前です。今後AKBの各女優に名前を付けていく場合はここになります。

コーディング

のちほどコードの解説はしますが、以下のように実装することになります。こちらはのちほど変わるコードなので、「こういう構造になるんだ～」くらいで理解しておいてください。

def makePerson(personName):
 """
 makeGroupで作成したgroupにpersonを追加することができます。
 """
 end_point = BASE_URL + "persongroups/" + GROUP_NAME + "/persons"
 headers = {
     "Ocp-Apim-Subscription-Key" :SUBSCRIPTION_KEY
 }
 payload = {
     "name": name
 }
 r = requests.post(
     end_point,
     headers = headers,
     json = payload
 )
 try:
     personId = r.json()["personId"]
 except Exception as e:
     personId = None
     print(r.json()["error"])
 return personId

Person Face: Personに紐づく画像を追加

次に Person Groupの中のPersonの中に、取得した顔の画像を紐づけます。

また同じようにリファレンスを見ていきましょう。こちらがリファレンスになります。

Microsoft Cognitive Services

HTTPメソッド

HTTPメソッドは以下のようになります。

・POST

リクエストURL

リクエストURLは以下の通りです。

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

リクエストパラメーター

必須のリクエストパラメーターは、以下の通りです。

・personGroupId：さきほど説明したpersonGroupIdを指定します。
・personId：personGroupIdの中のpersonの値を指定します。

リクエストヘッダー

ヘッダーも先ほどと同じで、以下の値になります。

・Ocp-Apim-Subscription-Key：このAPIへのアクセスを提供するサブスクリプションキー。あなたのCognitive サービスアカウントにあります。

リクエストボディ

リクエストボディは以下のようになります。

url：画像のURLです。1KBから6MBでが許容範囲です。複数の顔がある画像は使えません

コーディング

これらの値を利用してコーディングを行うと、以下のようになります。

def addFaceToPerson(personId, imageUrl):
  end_point = BASE_URL + "persongroups/" + GROUP_NAME + "/persons/" + personId  + "/persistedFaces"
  print(end_point)
  headers = {
      "Ocp-Apim-Subscription-Key" :SUBSCRIPTION_KEY
  }
  payload = {
      "url": imageUrl
  }
  r = requests.post(
      end_point,
      headers = headers,
      json = payload
  )
  print(r.text)

実装編

さて、APIリファレンスを軽くさらったところで、さっそく試していきましょう。

ライブラリのインポート

まずは必要なライブラリをインポートします。

・requests: HTTPの通信を行うためのライブラリ
・json：データをjson形式で使うためのライブラリ
・pandas: CSVデータを使うためのライブラリ

# ライブラリのインポート
import requests
import json
import pandas as pd