8 上級者向けのガイダンス

Mercury Cloud OpenAPIの高度な使用法に関するアドバイスとテクニックについて記載しています。

8.1 画像の上級使用方法

通常、画像関連のAPIでは1つの画像から1つの顔だけが使用されますが、Mercury Cloudは様々なユーザーシナリオのニーズに合わせた、より強力な機能を提供しています。

8.1.1 画像内の範囲指定

シナリオによっては画像全体から顔を検出するのではなく、画像の特定の領域を検出したい場合があります（例えば身分証明書など）。そのため一部のAPIでは、長方形の範囲を指定することができます。長方形で範囲を指定すると、APIはその範囲のみ顔をスキャンして結果を返します。長方形の指定がない場合、画像全体がスキャンされます。なお、長方形の領域を指定すると、特にHD画像の場合、指定しないより処理速度が速くなります。

rectangleフィールドは、顔検知API、顔比較API、顔特徴一括追加API、および顔検索APIで同じように動作します。

リクエスト例

{
  "images": [
    {
      "data": "/9j/4AAQSkZJRgA...Tpi3Q1lZTCn//Z",
      "rectangle": {
        "top": 50,
        "left": 100,
        "width": 500,
        "height": 800
      }
    }
  ]
}

8.1.2 複数の顔検知

顔検知機能は、顔検知API、顔比較API、顔特徴一括追加API、および顔検索APIで使用されます。 ただし検出動作は少し異なります。顔検知APIでは画像内の検出可能なすべての顔をスキャンします。画像に複数の顔が含まれている場合、顔検知APIは画像内のすべての顔を検出できます。APIレスポンスのbatchs.facesは、画像で検出されたすべて顔を含むリストです。

顔比較API、品質チェックAPI、顔特徴一括追加API、および顔検索APIでは、画像内の最大の顔のみを使用します。

リクエスト例

{
  "results": [ { "code": 0, "message": "Success.", "internal_code": 0 } ],
  "batches": [
    {
      "faces": [
        {
          "rectangle": { "top": 771, "left": 403, "width": 695, "height": 718 },
          ...
        },
        {
          "rectangle": { "top": 92, "left": 274, "width": 132, "height": 130 },
          ...
        }
      ]
    }
  ]
}

8.1.3 一括画像処理

顔検知APIではリクエストのimages フィールドとレスポンスのresultsフィールド、batchesフィールドはすべてリストタイプです。これらのリストには、複数の画像を含めることができます。リクエスト内のimagesフィールドの順序と応答のresultsフィールド、batchesフィールドの項目の順序は一致しています。同じインデックス値を使用して、画像、検出結果、および検出された顔へのアクセスができます。

顔検知API以外、顔特徴一括追加APIもバッチモードをサポートします。ただしパフォーマンス上の理由から1回のリクエスト内の画像の最大数は16に制限されており、各画像は基準を満たす必要があります。

8.2 KeyとExtra Infoの上級使用方法

特徴データベースに顔特徴を追加するときは、画像と共にkey、またはextra_info値を追加することを推奨します。これにより、追加された顔特徴をfeature_idより可読性が高い方法で管理とアクセスができます。顔特徴を特徴データベースに複数回追加すると複数のfeature_idを受け取り、データベースに重複した顔特徴が存在する可能性があります。keyまたはextra_info値がないと、feature_idが紛失した場合の管理が困難になりますので、ご注意ください。

8.2.1 Key

顔特徴のKeyは、アルファベット、数字、ハイフン（ "-"）、最大半角48文字で構成されるユーザー定義の文字列です。顔特徴を特徴データベース内で人間として扱う場合、keyはその人間のインデックスです。feature_idで顔特徴にアクセスすることで、その顔特徴のkeyとextra_infoを取得することもできます。keyの値は、必ずしもすべての特徴データベースで一意である必要はありません。したがって一連の顔特徴に同じkeyの値を設定することもできます。

ほとんどのお客様システムでは、ユーザーごとに一意のuser_id（たとえば、従業員番号やメンバーシップ番号）を配布します。この一意のuser_idは、顔特徴一括追加APIのリクエストの中、key値として設定することで、ユーザーシステムのuser_idとMercury Cloudの顔特徴をマッピングできます。Mercury Cloudではなく、お客様のユーザーシステムは、特徴データベース全体でkeyの一意性を維持する責任があります。

顔検索（1：N）APIのレスポンスには、検索画像の顔特徴と比較して最も類似性の高い上位の結果が含まれます。結果のKeyは、最も類似した顔特徴の所有者をすばやく特定することに役立ちます。そして、その登録者に対して、更なるビジネスロジックの実装と処理を俊敏的に実行できます。

8.2.2 Extra Info

Mercury Cloudは、登録者情報を格納するための専用のカラムを提供していません。かわりに、より柔軟で高度なソリューションを提供します。extra_infoフィールドはユーザー定義の文字列であり、最大半角1,024文字を格納できます。シリアル化されたJSONオブジェクト、Base64でエンコードされたバイナリ、画像のURLなど、任意の文字列タイプを含めることができます。例えば1つのメンバーシップサービスの情報は、次のように構成できます。

{
  "customer_info": {
    "id": 1000000,
    "first_name": "foo",
    "last_name": "bar",
    "create_at": "2021-01-01 15:00:00",
    "avatar": "base_url/2021/1000000_foo_bar.jpg"
  },
  "point_info": {
    "normal_points": {
      "card_no": 000011112222,
      "point": 100.00,
      "enabled": true,
      "expiration": "2022-01-01 00:00:00"
    },
    "2021_bonus_points": {
      "card_no": 000033334444,
      "point": 50.00,
      "enabled": false,
      "expiration": "2021-01-31 23:59:59"
    }
  }
}

この例では名前と画像のURLがextra_infoに含まれているため、お客様システムのデータベースでクエリを実行しなくても、登録済みの名前と登録画像をすばやく抽出できます。

頻繁に使用する情報のみ、extra_infoとMercuryCloudに保存することを強く推奨します。Mercury Cloudはテナントの分離とデータセキュリティを確保するための高レベルなセキュリティ対策を提供していますが、ベストプラクティスとしては機密性の高い個人情報の保存は控えるようにしてください。

V1.5.0から、extra_info は特徴の追加情報を更新APIで更新できます。

8.3 顔検索の上級使用方法

顔検索APIは、1：Nの顔検索シナリオで最も重要なAPIです。カメラで撮影した写真と一致する人物の結果を見つけるために、特徴データベースに登録されている顔検索と比較されます。

8.3.1 検索スコアについて

顔特徴は多次元ベクトルです。顔検索シナリオではAPIは特定の顔特徴を特徴データベース内の登録済みの顔特徴と比較し、それぞれがどれほど近いかを計算します。0〜1の範囲のAPI応答のスコアは、それらの間の類似性を示します。様々な条件、画像、角度、明るさ、撮影した日付などが検証スコアに影響します。2つ同じの画像を比較しても、スコアは1に非常に近いものの、類似性スコアに1にはなりません。

8.3.2 Min scoreとTop K

顔検索APIリクエストを送信する場合、min_scoreフィールドをしきい値として使用して、レスポンス応答の最低スコアを制限できます。min_score以上の結果のみが返されます。ただしお客様がご自身でmin_scoreを決定する必要があります。一般的なしきい値は、FARをできるだけ回避する観点で、0.94から0.96に設定されますので、ご自身のビジネス要件とテスト結果に基づいて、調整およびシステム構成をしてください。

もう1つのフィールドtop_kは、APIによって返される結果の数を制限するために使用されます。ほとんどの場合、上位1つの結果のみが必要です。ただし一部の場合では、より多くの上位結果を取得するとする必要があります。min_score設定の優先度はtop_kよりも高いことに注意してください。つまり、上位k個の顔特徴のいずれかがmin_score要件を満たしていない場合、APIレスポンスには含まれません。

8.3.3 複数特徴DBの検索

一部のシナリオでは、複数の機能データベースに顔特徴を保存したい場合があります。例えば、地域ごとに仕分ける場合などです。

通常、顔検索APIは単一の特徴データベースで実行されます。ただし特殊な場合には、すべての特徴データベースを検索する必要があります。Mercury Cloudの顔検索APIは、複数のdb_idをサポートすることでこの機能を提供できます。APIは複数の特徴データベースにわたって顔特徴を検索し、上位の結果をレスポンスします。

APIリクエストのdb_id数がNに設定されている場合、単一データベースに対する顔検索をN回実行することと同等のため、複数データベースでの顔検索はネットワーク遅延を増加させることにご注意してください。