1 of 16

1.7.0, 日本語, 1v1

イントロダクション

JCV の SenseID 認証プライベートクラウドサービスをご利用いただき、ありがとうございます。

当マニュアルでは、プライベートクラウドサービスの使用方法の詳細について説明いたします。プライベートクラウドサービスの導入を成功させるために、導入作業を開始する前に、当マニュアルをよくお読みください。

当マニュアルで記載されているプライベートクラウドの展開サービスの使用プロセスについて、次の図で詳細に説明します。

1. UDID 取得ツール

初めに

プライベートクラウドファイルのアクティベーションは、UDID に紐づける形で実行されます。プライベートクラウドサービスの認証を申請する前に、UDID 取得ツールをダウンロードし、指示に従って UDID を取得してください。

UDID取得ツールファイル

デプロイターゲットのデバイスの UDIDを取得します。
UDID取得ツールのファイル名称は、SenseIDPrivateCloud-UDIDGetter-V4.1.0.zipです。

Linux プラットフォーム向け手順

お使いのデバイスに対応するプロセッサープラットフォームのディレクトリへ移動します。
- 例: cd SenseIDPrivateCloud-UDIDGetter-V4.1.0/
標準的な使い方:
- コマンドラインで ./UDIDGetter.sh o を実行します。
- 出力された UDID.txt ファイルをメールで担当者に送付します。

よくあるエラー

Linux で使用する場合は、必ず Linux 上で ZIP ファイルを解凍するようにしてください。Linux 以外で解凍したd場合、ソフトリンクの障害が原因で、プログラムの実行が失敗する可能性があります。
エラー: save udid to file error, code -1の場合， sudo ./UDIDGetter.shを実行してください。

2. プライベートクラウドファイルのライセンスに関する説明

初めに

ライセンスファイルのアクティベーションは、UUID に紐づける形で実行されます。異なるインターフェースを開くように設定している場合、対応するライセンスファイルも異なります。1 つのインターフェースは、1-2 つのライセンスファイルに対応します。プライベートクラウドを展開する前に、ライセンスファイルの名前を変更して、指定ディレクトリに配置する必要があります。

プライベートクラウドライセンスの置き換え例

プライベートクラウドのライセンスファイルは、メールに添付されて提供されます。すべてのインターフェースを開くためには、対応する2つのライセンスファイルをそれぞれアクティベーションする必要があります。詳細については、次の手順を参照してください。

ライセンスの名前変更

SENSEID\_FACE\_xxx.lic ファイルの名前をsenseid\_face.licに変更
SENSEID\_LIVENESS\_xxx.lic ファイルの名前を senseid\_liveness.licに変更

ライセンスの置き換え手順:

ライセンスディレクトリへ移動します。
```
cd go-worker/fixture/license
```
ls licenseを実行します。次の 3つのフォルダーが表示されます。
※本製品ではsenseid_ocrはサポートされておりません。
注意事項: 実際には、このディレクトリのフォルダーに応じて、該当する名前が変更されたライセンスファイルを渡す必要があります。
```
 ├── senseid_face
 └── senseid_liveness
```

指定したディレクトリにライセンスファイルを移動します。

1) senseid_face.lic を senseid_face フォルダーに移動して、以前のライセンスを上書き

2) senseid_liveness.lic を senseid_liveness フォルダーに移動して、以前のライセンスを上書き

上記の手順を実行後、サービスを再起動します (注意事項: サービスの開始後にライセンスを置き換えた場合は、サービスを再起動する必要があります)。
```
最初に実行: ./stop.sh
次に実行: ./start.sh
```

3. プライベートクラウドの展開方法

概要

当マニュアルでは、プライベートクラウドを認証するための展開方法について、主にインストール、設定、重要なサービスの起動、また発生する可能性のある問題とその解決策について詳しく説明しています。
プライベートクラウドを展開する前に、運用および保守担当者はこのマニュアルを注意深くお読みください。

システム環境設定の要件

推奨されるマシン構成は、ubuntu 18.04のOSです。ハードウェアに関しては、クアッドコアまたはそれ以上の CPU、8GM 以上の RAM、そして 100GB 以上のディスク容量があることを推奨します。
注意事項: 命令セットには、AVX が必要です。

サービスについて

ruby-cloud-api: クライアントから呼び出される主要なインタフェースを含むHTTP サービス。
go-workers: バックエンドのコンピューティングサービス。主にアルゴリズムをカプセル化してあり、ruby-cloud-api に対して HTTP 形式で提供されます。

プライベートクラウドのアクティベーション

プライベートクラウドのライセンスファイルはメールに添付されて提供されます。プライベートクラウドを展開する前に、ライセンスファイルの名前を変更して、対応するディレクトリに配置する必要があります。

ライセンス数とタイプは、開くように設定されているさまざまなインターフェースによって異なる場合があります。詳細については「プライベートクラウドファイルのライセンスに関する説明」をご参照ください。

プライベートクラウドの展開プロセス

1. 概要

展開パッケージ名: 1v1-private-cloud.tgz

1.1 展開先のマシンにまず展開パッケージをコピーして解凍

$ tar -xvzf 1v1-private-cloud.tgz

o 注意事項: 必ず Linux 上で解凍するようにしてください。Windows 上でパッケージを解凍した場合、動的リンクライブラリのソフトリンク障害が発生します。

1.2. 解凍されたファイルのディレクトリへ移動

$ cd 1v1-private-cloud

1.3 現在のディレクトリにあるファイルを表示

$ ls -a

ストラクチャは次のとおりです。

.
├── .env
├── docker-compose
├── load_image.sh
├── docker-compose.yml
├── docs
├── go-workers
└── ruby-cloud-api.tar

(ライセンスにより) デバイスを紐づけるする必要があるため、go-workers の Dockerイメージは展開に使用できません。
ruby-cloud-api.tar は、対応するサービスの Docker イメージです。展開には、docker-compose を使用できます。

2. go-workers の展開

このサービスは主要なコンピューティングサービスであるため、できれば専用のサーバーリソースを割り当てます。

2.1 go-workers ディレクトリへ移動

$ cd go-workers

2.2 並行数を調整

注意事項: まずは、マシンの物理 CPU コア数を確認する必要があります。物理 CPU コア情報を取得するコマンドは以下のとおりです。

$ echo Cores=$(($(lscpu | awk '/^Socket/{print $2}') * $(lscpu | awk '/^Core/{print $4}')))

env ファイルを開き、CONCURRENT の値を物理 CPU コア数に設定し、保存します。

$ vim .env

注意事項: CONCURRENT には、マシンの物理 CPU コア数を超える値を設定することはできません。CONCURRENT 値が大きいほど、サービスの同時実行数が高くなり、メモリと CPU の消費量が多くなります。

2.3 サービスを開始 (注意: 実行する必要があるのは一度のみです)

開始前に、ライセンスが置き換えられていることを確認します。

$ ./start.sh

なお、展開ディレクトリ内に停止スクリプトも用意されています。

$ ./stop.sh

2.4 サービスが正常に開始したか確認するためにログを参照

$ tail -f tmp/worker.log.0

注意事項: tail コマンドの実行結果にポート番号 50050 の Server Listen が含まれている場合、サービスが正常に開始されたことを示します。

2.5 正常に展開されたか確認

$ curl 127.0.0.1:50050/healthcheck

正常に展開された場合の実行結果の例は以下のとおりです (サービスが正常に開始したことを示しています)。

{"request_id":"07a41c21822e4223a373e77bfc186ed2","status":"ok"}

3. ruby-cloud-apiを展開

以下のサービスのデプロイはDockerに依存しますので、ご自身でDockerをインストールしてください。

3.1 サービスイメージを読み込む

$ ./load_image.sh

実行結果は以下のとおりです。

Loaded image: registry.sensetime.com/senseid-cloudv2/ruby-cloud-api:v1.0.0

3.2 go-workers サービスアドレスを設定

.env ファイルを開きます。

$ vi .env

最終行の WORKER_IP 値を修正し、go-workers サービスが展開されているマシンの IP アドレスを設定します。保存後、ファイルを閉じます。

IP アドレスの取得コマンド:

$ hostname -I | cut -d' ' -f1

3.3 サービスを開始

$ docker-compose up -d

結果は以下のとおりです。

Creating network "senseid-private-cloud-yyyymmdd_default" with the default driver
Creating senseid-private-cloud-yyyymmdd_ruby-cloud-api_1     ... done

3.4 サービスステータスを表示

$ docker-compose ps

結果は以下のとおりです。

                       Name                                      Command                  State                Ports
-----------------------------------------------------------------------------------------------------------------------------
senseid-private-cloud-20191225_ruby-cloud-api_1       ./entrypoint.sh start            Up (healthy)   0.0.0.0:3000->3000/tcp

ここまでにサービスが展開されています。

3.5 展開の成功を確認

$ curl 127.0.0.1:3000/healthcheck

返されるサンプルは次のとおりです。展開が正常である場合（サービスが正常に開始されたことを証明します）：

{"code":1000,"status":"ok"}

サービスについて

こちらの節に記載しているサービスはサーバー内部で動作するものの為、認証情報を変更することはできません。安全に使用して頂けれる為に、安全なAPIメカニズム、認証メカニズム、通信、DNSをSenseID外部に実装することを強く推奨します。

go-workers

サービスポート: 50050

ruby-cloud-api

サービスポート: 3000
インターフェース定義: 詳細については、インターフェースファイルをご参照ください。

4. プライベートクラウドの展開に関する FAQ

Q1.展開先マシンのバージョンが古く、命令セットが低レベル（または対応する命令セットに AVX 命令セットが含まれていない）な状態です。ログを取得し確認するために、”tail -f tmp/worker.log.0” コマンドを実行したところ、ログ内に "SIGILL: illegal instruction” と出てきてしまいました。この問題の解決方法を教えてください。

まず、マシンで対応している命令セットを確認します。

cat /proc/cpuinfo コマンドを実行します。
フラグを確認します。

AVX と AVX2 の組み合わせが含まれていない場合は、CPU 命令セットが AVX 命令セットをサポートしていないことを示します。

解決方法は 2 通りあります。

1) AVX 命令セットが含まれるマシンに変更します。

2) 現在のマシンで、強制的にSSE 命令セットが使用されるようにします。ただし、サービスの性能は低下し、処理スピードは半減します。

強制的に SSE 命令セットが使用されるようにするには、go-workers の env ファイルを開き、FORCE_SET_SSE=false を FORCE_SET_SSE=true に変更します。

注意事項: 変更後、保存してから、go-workers サービスを再起動します。サービスを再起動する方法は以下のとおりです。

まず ./stop/sh を実行してから、./start.sh を実行します。

Q2. go-workers で `./start.sh` を複数回実行するなど、展開中に開始コマンド (`./start.sh`) が繰り返し呼び出される場合、またはポートが使用されている場合、ログを確認すると次のエラーが発生していました。

listen: listen tcp :50050: bind: address already in use

注意事項: go-workers または go-cloud-api を開始する際は、対応する ./start.sh を一度だけ開始してください。

1) 下記のコマンドを実行します。

ps aux | grep supervisord

2) ./tool/supervisord -c config/supervisor.conf -dに対応するプロセス番号を強制終了します。

kill -9 PID

Q3. ライセンスの使用に関するエラータイプのまとめ

弊社が提供する「プライベートクラウドパッケージ」には、デフォルトでライセンスが含まれていませんので、ライセンスの詳細な利用方法については、プライベートクラウドファイルのライセンスの使い方を参照してください。

1）panic: bad license: -1

ライセンスが壊れている（空のライセンスなど）ので、再度ライセンスファイルを差し替えてください。

2) panic: open fixture/license/senseid_ocr/senseid_ocr.lic: no such file or directory

ライセンスがインポートされていないということですので、指定したフォルダにライセンスファイルをインポートしてください。

3）panic: bad license: -16

udid mismatch と表示され、ライセンスにバインドされているハードウェアの指紋と現在のデバイスのハードウェアの指紋が一致していません。
デバイスのハードウェア情報が変更されていないことを確認してください。
デバイスのUUIDが変更されていることを確認したら、新しいライセンスを申請できる事業者に新しいUUIDを提供して、新しいライセンスを忘れずに交換してください。

Q4 error:-8 ？

主にモデルファイルに関連したファイル形式が間違っていることを意味します。

例えば、WINDOWS システムの解凍ソフトを使用して、「プライベートクラウドパッケージ」を解凍してサーバーにアップロードすると、モデルファイルの一部が破損する可能性があります。お客様は、インストールパッケージをサーバに再アップロードし、コマンドラインで解凍することをお勧めします。

5. 個人データの暗号化

ユーザーがアップロードした個人データは暗号化する必要があります。暗号化アルゴリズムは AES-256-CBC を使用します。暗号化に必要なキーおよび IV は、デフォルトの設定では以下のとおりです。

変更する場合は、環境変数 PARAM_DECRYPT_KEY および PARAM_DECRYPT_IV を更新します。キーは 32 文字で、IV は 12 文字です。

具体的な暗号化の方法

人物の画像ファイルまたはその他の個人データを読み取ります。
AES-256-CBC でデータを暗号化します。
Base64 で上記の結果を暗号化します。

Java サンプル

6. API リファレンス

本章では、必要に応じて参考にできるように、JCV 認証クラウドサービスで提供されるすべての API に関する手順について詳細に説明します。 API の説明には、関数の紹介、パラメーター、出力結果、エラーメッセージなどが含まれます。

6.1. 顔の比較 (ステートレス)

6.1.1 /identity/image_verification/stateless

インターフェースを介してアップロードされた 2 つの顔画像を比較して、2 つの顔が同一人物のものかどうかを判断します。

画像は、以下の要件を満たすものとします。

JPG (JPEG)、BMP、PNG、GIF、TIFF のいずれかの形式
幅と高さは 8 px 以上 5,000 px 以下
ファイルサイズは 5 MB 以下

リクエストモード

POST

リクエスト URL

http://ip:port/identity/image_verification/stateless

リクエストパラメーター

通常のレスポンス

{
  'request_id': 'xxx',
  'code': xxx,
  'verification_score': xxx
}

顔比較スコアの閾値とエラー率との対応関係:

推奨閾値: 0.7 以上

異常なレスポンス

{
  'request_id': 'xxx',
  'code': xxx,
  'message': xxx
}

システムレスポンスコードの説明

可能性のある http ステータスコード:

使用サンプル

curl サンプル

curl -X POST "http://ip:port/identity/image_verification/stateless" \
  -d first_encrypted_image=xxx \
  -d second_encrypted_image=xxx \
  -d auto_rotate=true

java サンプル

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

import org.apache.http.HttpEntity;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

public class HttpClient {
    public static final String POST_URL = "http://127.0.0.1:3000/identity/image_verification/stateless";
    private static AESCipher cipher = new AESCipher("dcbbad6765e14139a07d34b92292a672", "df25d188a061");

    public static void Post() throws Exception {
        CloseableHttpClient httpclient = HttpClients.createDefault();
        HttpPost post = new HttpPost(POST_URL);

        List<NameValuePair> params = new ArrayList<>();

        String firstEncryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_01.jpg")));
        String secondEncryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_02.jpg")));

        params.add(new BasicNameValuePair("first_encrypted_image", firstEncryptedImage));
        params.add(new BasicNameValuePair("second_encrypted_image", secondEncryptedImage));

        post.setEntity(new UrlEncodedFormEntity(params));
        HttpResponse response = httpclient.execute(post);

        if (response.getStatusLine().getStatusCode() == 200) {
            HttpEntity respEntity = response.getEntity();
            BufferedReader reader = new BufferedReader(new InputStreamReader(respEntity.getContent()));
            String line = reader.readLine();
            System.out.println(line);
        } else {
            HttpEntity respEntity = response.getEntity();
            String responseString = EntityUtils.toString(respEntity);
            System.out.println("error:" + response.getStatusLine().getStatusCode()
                    + "  " + response.getStatusLine().getReasonPhrase());
            System.out.println("cause of error:"+responseString);
        }
    }

    public static void main(String[] args) throws Exception {
        Post();
    }
}

6.1.2. /identity/multiface_image_omni_verification/stateless

比較対象の顔画像に複数の顔が含まれる場合に、 2 つの画像に含まれる顔の各グループの類似度スコアを返します。

顔画像は、以下の要件を満たすものとします。

JPG (JPEG)、BMP、PNG、GIF、TIFF のいずれかの形式
幅と高さは 8 px 以上 5,000 px 以下
ファイルサイズは 5 MB 以下

リクエストモード

POST

リクエスト URL

http://ip:port/identity/multiface_image_omni_verification/stateless

リクエストパラメーター

通常のレスポンス

例:

first_image_file に相当する図 A に 2 つの顔 (a1、a2) が含まれていて、second_image_file に相当する図 B にも 2 つの顔 (b1、b2) が含まれているとします。a1b1 などの値は、図 A に含まれる顔 a1 と図 B に含まれる顔 b1 の比較スコアを表します。

{
  'code: Int, # システムレスポンスコード
  'scores': array, # [[a1b1 顔比較スコア, a1b2 顔比較スコア], [a2b1 顔比較スコア, a2b2 顔比較スコア]]
  "face_rects":{ hash,# 各画像の顔枠
                 'first_image_face_rects':[a1 顔枠の座標], [a2 顔枠の座標]],
                 'second_image_face_rects,:[[b1 顔枠の座標],[b2 顔枠の座標]]
               },
  'request_id': string # このリクエストのID
}

顔比較スコアの閾値とエラー率との対応関係:

推奨閾値: 0.7 以上

異常なレスポンス

{
  'request_id': string,
  'code': int,
  'message': string
}

システムレスポンスコードの説明

可能性のある http ステータスコード:

使用サンプル

Curl サンプル

curl -X POST "http://ip:port/identity/multiface_image_omni_verification/stateless" \
  -d first_encrypted_image=xxx \
  -d second_encrypted_image=xxx \
  -d auto_rotate=true

Java サンプル

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

import org.apache.http.HttpEntity;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

public class HttpClient {
    public static final String POST_URL = "http://127.0.0.1:3000/identity/multiface_image_omni_verification/stateless";
    private static AESCipher cipher = new AESCipher("dcbbad6765e14139a07d34b92292a672", "df25d188a061");

    public static void Post() throws Exception {
        CloseableHttpClient httpclient = HttpClients.createDefault();
        HttpPost post = new HttpPost(POST_URL);

        List<NameValuePair> params = new ArrayList<>();

        String firstEncryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_01.jpg")));
        String secondEncryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_02.jpg")));

        params.add(new BasicNameValuePair("first_encrypted_image", firstEncryptedImage));
        params.add(new BasicNameValuePair("second_encrypted_image", secondEncryptedImage));

        post.setEntity(new UrlEncodedFormEntity(params));
        HttpResponse response = httpclient.execute(post);

        if (response.getStatusLine().getStatusCode() == 200) {
            HttpEntity respEntity = response.getEntity();
            BufferedReader reader = new BufferedReader(new InputStreamReader(respEntity.getContent()));
            String line = reader.readLine();
            System.out.println(line);
        } else {
            HttpEntity respEntity = response.getEntity();
            String responseString = EntityUtils.toString(respEntity);
            System.out.println("error:" + response.getStatusLine().getStatusCode()
                    + "  " + response.getStatusLine().getReasonPhrase());
            System.out.println("cause of error:" +responseString);
        }
    }

    public static void main(String[] args) throws Exception {
        Post();
    }
}

6.1.3. /identity/liveness_image_verification/stateless

インターフェースを介してアップロードされた顔画像と生体認証データを比較して、画像内の顔が同一人物のものであるかどうかを判断します。

画像は、以下の要件を満たすものとします。

JPG (JPEG)、BMP、PNG、GIF、TIFF のいずれかの形式
幅と高さは 8 px 以上 5,000 px 以下
ファイルサイズは 5 MB 以下

リクエストモード

POST

リクエスト URL

http://ip:port/identity/liveness_image_verification/stateless

リクエストパラメーター

通常のレスポンス

{
  'request_id': 'xxx',
  'code': xxx,
  'verification_score': xxx
}

顔比較スコアの閾値とエラー率との対応関係:

推奨閾値: 0.7 以上

異常なレスポンス

{
  'request_id': 'xxx',
  'code': xxx,
  'message': xxx
}

システムレスポンスコードの説明

可能性のある http ステータスコード:

使用サンプル

curl サンプル

curl -X POST "http://ip:port/identity/liveness_image_verification/stateless" \
  -F liveness_file=@/PATH/TO/FILE \
  -d encrypted_image=xxx \
  -d auto_rotate=true

Java サンプル

import java.io.BufferedReader;
import java.io.File;
import java.io.InputStreamReader;
import java.nio.file.Files;
import java.nio.file.Paths;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.mime.MultipartEntityBuilder;
import org.apache.http.entity.mime.content.FileBody;
import org.apache.http.entity.mime.content.StringBody;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class HttpClient {
    public static final String POST_URL = "http://127.0.0.1:3000/identity/liveness_image_verification/stateless";
    private static AESCipher cipher = new AESCipher("dcbbad6765e14139a07d34b92292a672", "df25d188a061");

    public static void Post() throws Exception {
        CloseableHttpClient httpclient = HttpClients.createDefault();
        HttpPost post = new HttpPost(POST_URL);

        MultipartEntityBuilder entity = MultipartEntityBuilder.create();
        String encryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_01.jpg")));

        entity.addPart("liveness_file", new FileBody(new File("src/main/resources/mobile.protobuf")));
        entity.addPart("encrypted_image", new StringBody(encryptedImage));
        entity.addPart("auto_rotate", new StringBody("true"));

        post.setEntity(entity.build());
        HttpResponse response = httpclient.execute(post);

        if (response.getStatusLine().getStatusCode() == 200) {
            HttpEntity respEntity = response.getEntity();
            BufferedReader reader = new BufferedReader(new InputStreamReader(respEntity.getContent()));
            String line = reader.readLine();
            System.out.println(line);
        } else {
            HttpEntity respEntity = response.getEntity();
            String responseString = EntityUtils.toString(respEntity);
            System.out.println("error:" + response.getStatusLine().getStatusCode()
                    + "  " + response.getStatusLine().getReasonPhrase());
            System.out.println("cause of error:"+responseString);
        }
    }

    public static void main(String[] args) throws Exception {
        Post();
    }
}

6.1.4. /identity/silent_image_verification/stateless

このAPIは、サイレント生体認証結果と自撮りの顔写真を比較に利用されています。

リクエストモード

POST

リクエスト URL

http://ip:port/identity/silent_image_verification/stateless

リクエストパラメーター

一般的なビデオフォーマットはサポートされています。例えば： .mp4, .avi, .flv, .wmv, .mov, .rm
顔画像は、以下の要件を満たすものとします。
JPG (JPEG)、BMP、PNG、GIF、TIFF のいずれかの形式
幅と高さは 8 px 以上 5,000 px 以下
ファイルサイズは 5 MB 以下

通常のレスポンス

ここで、liveness_statusの結果は以下のようになる:

{
  "request_id": string,
  "code": int,
  "passed": boolean,
  "liveness_score": float,
  "liveness_status": string,
  "verification_score": float,
  "image_timestamp": float,
  "base64_image": string,
  "base64_face_image": string,
}

顔比較スコアの閾値とエラー率との対応関係:

推奨閾値: 0.7 以上

異常なレスポンス

{
  'request_id': 'xxx',
  'code': xxx,
  'message': xxx
}

システムレスポンスコードの説明

可能性のある http ステータスコード:

使用サンプル

curl サンプル

curl -X POST "http://ip:port/identity/silent_image_verification/stateless" \
  -d encrypted_video=xxx \
  -d encrypted_image=xxx \
  -d auto_rotate=true

Java サンプル

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

import org.apache.http.HttpEntity;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

public class HttpClient {
    public static final String POST_URL = "http://127.0.0.1:3000/identity/silent_image_verification/stateless";
    private static AESCipher cipher = new AESCipher("dcbbad6765e14139a07d34b92292a672", "df25d188a061");

    public static void Post() throws Exception {
        CloseableHttpClient httpclient = HttpClients.createDefault();
        HttpPost post = new HttpPost(POST_URL);

        List<NameValuePair> params = new ArrayList<>();

        String encryptedVideo = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/video_01.mp4")));
        String encryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_01.jpg")));

        params.add(new BasicNameValuePair("encrypted_video", encryptedVideo));
        params.add(new BasicNameValuePair("encrypted_image", encryptedImage));
        params.add(new BasicNameValuePair("auto_rotate", "true"));
        params.add(new BasicNameValuePair("return_image", "true"));
        params.add(new BasicNameValuePair("return_face_image", "true"));
        params.add(new BasicNameValuePair("return_status", "true"));

        post.setEntity(new UrlEncodedFormEntity(params));
        HttpResponse response = httpclient.execute(post);

        if (response.getStatusLine().getStatusCode() == 200) {
            HttpEntity respEntity = response.getEntity();
            BufferedReader reader = new BufferedReader(new InputStreamReader(respEntity.getContent()));
            String line = reader.readLine();
            System.out.println(line);
        } else {
            HttpEntity respEntity = response.getEntity();
            String responseString = EntityUtils.toString(respEntity);
            System.out.println("error:" + response.getStatusLine().getStatusCode()
                    + "  " + response.getStatusLine().getReasonPhrase());
            System.out.println("cause of error:" +responseString);
        }
    }

    public static void main(String[] args) throws Exception {
        Post();
    }
}

6.2. 画像品質チェック

6.2.1. /quality/face/stateless

顔画像品質チェックのインターフェースです。

注意：画像ファイルには複数の顔が含まれることは可能

顔画像は、以下の要件を満たすものとします。

JPG (JPEG)、BMP、PNG、GIF、TIFF のいずれかの形式
幅と高さは 8 px 以上 5,000 px 以下
ファイルサイズは 5 MB 以下

リクエストモード

POST

リクエスト URL

リクエストパラメーター

通常のレスポンス

異常なレスポンス

システムレスポンスコードの説明

可能性のある http ステータスコード:

使用サンプル

curl サンプル

Java サンプル

6.3. なりすまし防止

6.3.1. /liveness/silent_detection/stateless

サイレント生体検知のインターフェースです。

リクエストモード

POST

リクエスト URL

リクエストパラメーター

一般的なビデオフォーマットはサポートされています。例えば： .mp4, .avi, .flv, .wmv, .mov, .rm

通常のレスポンス

ここで、liveness_statusの結果は以下のようになる:

異常なレスポンス

システムレスポンスコードの説明

可能性のある http ステータスコード:

使用サンプル

curl サンプル

Java サンプル

3. プライベートクラウドの展開方法

概要

当マニュアルでは、プライベートクラウドを認証するための展開方法について、主にインストール、設定、重要なサービスの起動、また発生する可能性のある問題とその解決策について詳しく説明しています。
プライベートクラウドを展開する前に、運用および保守担当者はこのマニュアルを注意深くお読みください。

システム環境設定の要件

推奨されるマシン構成は、ubuntu 18.04のOSです。ハードウェアに関しては、クアッドコアまたはそれ以上の CPU、8GM 以上の RAM、そして 100GB 以上のディスク容量があることを推奨します。
注意事項: 命令セットには、AVX が必要です。

サービスについて

ruby-cloud-api: クライアントから呼び出される主要なインタフェースを含むHTTP サービス。
go-workers: バックエンドのコンピューティングサービス。主にアルゴリズムをカプセル化してあり、ruby-cloud-api に対して HTTP 形式で提供されます。

プライベートクラウドのアクティベーション

プライベートクラウドの展開プロセス

1. 概要

展開パッケージ名: 1v1-private-cloud.tgz

1.1 展開先のマシンにまず展開パッケージをコピーして解凍

$ tar -xvzf 1v1-private-cloud.tgz

1.2. 解凍されたファイルのディレクトリへ移動

$ cd 1v1-private-cloud

1.3 現在のディレクトリにあるファイルを表示

$ ls -a

ストラクチャは次のとおりです。

.
├── .env
├── docker-compose
├── load_image.sh
├── docker-compose.yml
├── docs
├── go-workers
└── ruby-cloud-api.tar

(ライセンスにより) デバイスを紐づけるする必要があるため、go-workers の Dockerイメージは展開に使用できません。
ruby-cloud-api.tar は、対応するサービスの Docker イメージです。展開には、docker-compose を使用できます。

2. go-workers の展開

このサービスは主要なコンピューティングサービスであるため、できれば専用のサーバーリソースを割り当てます。

2.1 go-workers ディレクトリへ移動

$ cd go-workers

2.2 並行数を調整

注意事項: まずは、マシンの物理 CPU コア数を確認する必要があります。物理 CPU コア情報を取得するコマンドは以下のとおりです。

$ echo Cores=$(($(lscpu | awk '/^Socket/{print $2}') * $(lscpu | awk '/^Core/{print $4}')))

env ファイルを開き、CONCURRENT の値を物理 CPU コア数に設定し、保存します。

$ vim .env

注意事項: CONCURRENT には、マシンの物理 CPU コア数を超える値を設定することはできません。CONCURRENT 値が大きいほど、サービスの同時実行数が高くなり、メモリと CPU の消費量が多くなります。

2.3 サービスを開始 (注意: 実行する必要があるのは一度のみです)

開始前に、ライセンスが置き換えられていることを確認します。

$ ./start.sh

なお、展開ディレクトリ内に停止スクリプトも用意されています。

$ ./stop.sh

2.4 サービスが正常に開始したか確認するためにログを参照

$ tail -f tmp/worker.log.0

注意事項: tail コマンドの実行結果にポート番号 50050 の Server Listen が含まれている場合、サービスが正常に開始されたことを示します。

2.5 正常に展開されたか確認

$ curl 127.0.0.1:50050/healthcheck

正常に展開された場合の実行結果の例は以下のとおりです (サービスが正常に開始したことを示しています)。

{"request_id":"07a41c21822e4223a373e77bfc186ed2","status":"ok"}

3. ruby-cloud-apiを展開

以下のサービスのデプロイはDockerに依存しますので、ご自身でDockerをインストールしてください。

3.1 サービスイメージを読み込む

$ ./load_image.sh

実行結果は以下のとおりです。

Loaded image: registry.sensetime.com/senseid-cloudv2/ruby-cloud-api:v1.0.0

3.2 go-workers サービスアドレスを設定

.env ファイルを開きます。

$ vi .env

最終行の WORKER_IP 値を修正し、go-workers サービスが展開されているマシンの IP アドレスを設定します。保存後、ファイルを閉じます。

IP アドレスの取得コマンド:

$ hostname -I | cut -d' ' -f1

3.3 サービスを開始

$ docker-compose up -d

結果は以下のとおりです。

Creating network "senseid-private-cloud-yyyymmdd_default" with the default driver
Creating senseid-private-cloud-yyyymmdd_ruby-cloud-api_1     ... done

3.4 サービスステータスを表示

$ docker-compose ps

結果は以下のとおりです。

                       Name                                      Command                  State                Ports
-----------------------------------------------------------------------------------------------------------------------------
senseid-private-cloud-20191225_ruby-cloud-api_1       ./entrypoint.sh start            Up (healthy)   0.0.0.0:3000->3000/tcp

ここまでにサービスが展開されています。

3.5 展開の成功を確認

$ curl 127.0.0.1:3000/healthcheck

返されるサンプルは次のとおりです。展開が正常である場合（サービスが正常に開始されたことを証明します）：

{"code":1000,"status":"ok"}

サービスについて

go-workers

サービスポート: 50050

ruby-cloud-api

サービスポート: 3000
インターフェース定義: 詳細については、インターフェースファイルをご参照ください。

1.7.0, 日本語, 1v1

イントロダクション

1. UDID 取得ツール

初めに

UDID取得ツールファイル

Linux プラットフォーム向け手順

よくあるエラー

2. プライベートクラウドファイルのライセンスに関する説明

初めに

プライベートクラウドライセンスの置き換え例

ライセンスの名前変更

ライセンスの置き換え手順:

3. プライベートクラウドの展開方法

概要

システム環境設定の要件

サービスについて

プライベートクラウドのアクティベーション

プライベートクラウドの展開プロセス

1. 概要

1.1 展開先のマシンにまず展開パッケージをコピーして解凍

1.2. 解凍されたファイルのディレクトリへ移動

1.3 現在のディレクトリにあるファイルを表示

2. go-workers の展開

2.1 go-workers ディレクトリへ移動

2.2 並行数を調整

2.3 サービスを開始 (注意: 実行する必要があるのは一度のみです)

2.4 サービスが正常に開始したか確認するためにログを参照

2.5 正常に展開されたか確認

3. ruby-cloud-apiを展開

3.1 サービスイメージを読み込む

3.2 go-workers サービスアドレスを設定

3.3 サービスを開始

3.4 サービスステータスを表示

3.5 展開の成功を確認

サービスについて

go-workers

ruby-cloud-api

4. プライベートクラウドの展開に関する FAQ

Q2. go-workers で ./start.sh を複数回実行するなど、展開中に開始コマンド (./start.sh) が繰り返し呼び出される場合、またはポートが使用されている場合、ログを確認すると次のエラーが発生していました。

Q3. ライセンスの使用に関するエラータイプのまとめ

Q4 error:-8 ？

5. 個人データの暗号化

具体的な暗号化の方法

Java サンプル

6. API リファレンス

6.1. 顔の比較 (ステートレス)

6.1.1 /identity/image_verification/stateless

リクエストモード

リクエスト URL

リクエストパラメーター

通常のレスポンス

異常なレスポンス

使用サンプル

curl サンプル

java サンプル

6.1.2. /identity/multiface_image_omni_verification/stateless

リクエストモード

リクエスト URL

リクエストパラメーター

通常のレスポンス

異常なレスポンス

使用サンプル

Curl サンプル

Java サンプル

6.1.3. /identity/liveness_image_verification/stateless

リクエストモード

リクエスト URL

リクエストパラメーター

通常のレスポンス

異常なレスポンス

使用サンプル

curl サンプル

Java サンプル

6.1.4. /identity/silent_image_verification/stateless

リクエストモード

リクエスト URL

リクエストパラメーター

通常のレスポンス

異常なレスポンス

使用サンプル

Q2. go-workers で `./start.sh` を複数回実行するなど、展開中に開始コマンド (`./start.sh`) が繰り返し呼び出される場合、またはポートが使用されている場合、ログを確認すると次のエラーが発生していました。

Q2. go-workers で `./start.sh` を複数回実行するなど、展開中に開始コマンド (`./start.sh`) が繰り返し呼び出される場合、またはポートが使用されている場合、ログを確認すると次のエラーが発生していました。