1.1 システムについて

SenseIDの利用環境には、Ubuntu Server 18.04 LTSを推奨します。ハードウェア側では、クアッドコアまたはそれ以上のCPU、8GM以上のRAM、100GB以上のディスク容量を推奨します。なお、CPU命令セットにAVXが必要です。

1.2 サービスについて

• Ruby-Cloud-API

  • クライアントから呼び出される主要なインターフェースを含む、HTTP サービス。

  • サービスポート：3000

• Go-Workers

  • バックエンドのコンピューティングサービス。主にアルゴリズムをカプセル化してあり、Ruby-Cloud-APIに対してHTTP形式で提供されます。

  • サービスポート：50050

本マニュアルでは、JCV顔認証サービス「SenseID」のインストール方法について説明します。導入を成功させるために、導入作業を開始する前には、当マニュアルをよくお読みください。

当マニュアルは、主にIT部門に所属するお客様、Linux、Kubernetes、Docker、クラウドなどの利用・運用経験があるお客様を対象にしています。

本マニュアルで記載されているインストールのプロセスについては、次の図で詳細に説明します。

2.1 UDIDとは

UDIDは、サーバーのハードウエア情報から算出したサーバーの識別コードです。SenseIDのアクティベーションは、UDIDに紐づける形で実行されます。SenseIDの認証を申請する前にUDID取得ツールをダウンロードし、指示に従ってUDIDを取得してください。

2.2 UDID取得ツール

デプロイターゲットのサーバーの UDIDを取得します。

UDID取得ツールのファイル名称は、SenseIDPrivateCloud-UDIDGetter-V4.1.0.zipです。

2.3 UDIDを取得

UDID取得ツールをサーバーに配置・解凍してください。

解凍したディレクトリへ移動し、UDIDGetter.shを実行してください。

出力されたUDID.txtファイル、およびお客様の契約番号を、JCV製品提供窓口である、宛にご連絡ください。

2.1 暗号化キーの設定

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

PARAM_DECRYPT_KEY = dcbbad6765e14139a07d34b92292a672
PARAM_DECRYPT_IV = df25d188a061

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

$ cd 1v1-private-cloud-v1.8/
$ vi .env

2.2 暗号化方法

1. 人物の写真ファイルまたは動画ファイルを読み取ります。

2. AES-256-GCMでデータを暗号化します。

3. Base64で上記の結果を暗号化します。

import javax.crypto.Cipher;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.Charset;
import java.util.Base64;


public class AESCipher {
    private String key;
    private String iv;

    public AESCipher(String key, String iv) {
        this.key = key;
        this.iv = iv;
    }

    String encrypt(byte[] data) throws Exception{
        SecretKeySpec keySpec = new SecretKeySpec(key.getBytes(Charset.forName("UTF-8")), "AES");
        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        cipher.init(Cipher.ENCRYPT_MODE, keySpec, new GCMParameterSpec(128, iv.getBytes(Charset.forName("UTF-8"))));
        byte[] result = cipher.doFinal(data);
        return Base64.getEncoder().encodeToString(result);
    }

    byte[] decrypt(String data) throws Exception {
        SecretKeySpec keySpec = new SecretKeySpec(key.getBytes(Charset.forName("UTF-8")), "AES");
        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        cipher.init(Cipher.DECRYPT_MODE, keySpec, new GCMParameterSpec(128, iv.getBytes(Charset.forName("UTF-8"))));
        byte[] result = cipher.doFinal(Base64.getDecoder().decode(data));
        return result;
    }

    public static void main(String[] args) throws Exception{
        String key = "dcbbad6765e14139a07d34b92292a672"; //key 32 bits
        String iv = "df25d188a061"; // iv 12 bits
        String data = "hello world";

        AESCipher cipher = new AESCipher(key, iv);
        String encryptedData = cipher.encrypt(data.getBytes());
        System.out.println("encrypted data: " + encryptedData);

        String decryptedData = new String(cipher.decrypt(encryptedData));
        System.out.println("decrypted data: " + decryptedData);
    }
}

ライセンスファイルを更新するためには、指定のディレクトリに旧ライセンスファイルから新しいライセンスファイルを上書きして配置する必要があります。詳細はインストールマニュアルの3章 ライセンスファイルを配置をご参照ください。

上記の手順を実行後、サービスを再起動してくだい。

$ cd 1v1-private-cloud-v1.8/go-worker
$ sudo ./stop.sh
$ sudo ./start.sh

3.1 入力写真の基準

1. 写真のフォーマットは以下のいずれかであること。推奨フォーマットはJPG（JPEG）はです。 フォーマット：JPG（JPEG）、BMP、PNG、GIF、TIFF

2. 写真の幅と高さは32ピクセル以上、かつ5,000px以下であること。推奨サイズは640✕480ピクセルです。

3. 写真ファイルのサイズは5MB以下であること。サイズが大きいほど、処理性能に影響があります。100KBまで圧縮することを推奨します。

3.2 入力動画の基準

1. 一般的な動画フォーマットをサポートしています。推奨フォーマットはmp4です。 対応フォーマット：mp4、avi、flv、wmv、mov、rm

2. 動画の幅と高さは8ピクセル以上、かつ5,000px以下であること。推奨サイズは640✕480ピクセルです。

3. 動画ファイルのサイズは16MB以下であること。サイズが大きいほど、処理性能に影響があります。約500KB〜1MB程度に圧縮することを推奨します。

3.1 ライセンスとは

SenseIDのGo-Workersサービスを使用するには、ライセンスファイルが必要です。ライセンスファイルのアクティベーションは、UDIDに紐づける形で実行されます。異なるサービスを使用する場合、対応するライセンスファイルも異なります。1つのSenseIDサーバーには、1〜3つのライセンスファイルに対応します。SenseIDを展開する前に、ライセンスファイルの名前を変更して、指定のディレクトリに配置する必要があります。

SenseIDのライセンスファイルは、JCV製品窓口より提供されます。アクティベーションの詳細については、次の手順を参照してください。

3.2 ライセンスの名前変更

• SENSEID_FACE_xxx.licファイルの名前を、senseid_face.licに変更

• SENSEID_KESTREL_xxx.licファイルの名前を、senseid_kestrel.licに変更

• SENSEID_LIVENESS_xxx.licファイルの名前を、senseid_liveness.licに変更

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

3.3.1 インストールパッケージ展開

パッケージ名：1v1-private-cloud-v1.8.tgz

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

3.3.2 ライセンスファイル配置

SenseIDのインストールパッケージの解凍先にある、ライセンスディレクトリへ移動します。

$ cd 1v1-private-cloud-v1.8/go-workers/fixture/license

以下の命令を実施し、次の3つのフォルダーが表示されることを確認できます。

$ ls -1

senseid_face
senseid_kestrel
senseid_liveness

指定したディレクトリにライセンスファイルをコピーし、元のファイルを上書きします。

#1) senseid_face.licをsenseid_faceフォルダーに移動し、以前のライセンスを上書き
$ cp {ファイル先}/senseid_face.lic {インストール先}/1v1-private-cloud-v1.8/go-workers/fixture/license/senseid_face

#2) senseid_kestrel.licをsenseid_kestrelフォルダーに移動し、以前のライセンスを上書き
$ cp {ファイル先}/senseid_kestrel.lic {インストール先}/1v1-private-cloud-v1.8/go-workers/fixture/license/senseid_kestrel

#3) senseid_liveness.licをsenseid_livenessフォルダーに移動し、以前のライセンスを上書き
$ cp {ファイル先}/senseid_liveness.lic {インストール先}/1v1-private-cloud-v1.8/go-workers/fixture/license/senseid_liveness

本マニュアルでは、SenseIDのV1.7.0からV1.8.0へのアップデートを例にして、アップデート手順を案内します。

事前準備として、V1.8.0のパッケージ1v1-private-cloud-v1.8.tgzをV1.7.0がインストールした同じディレクトリに解凍・配置してください。

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

1v1-private-cloud-v1.7/
1v1-private-cloud-v1.8/

4.1 旧バージョンのRuby-Cloud-APIサービスを停止

旧バージョンのフォルダーに移動し、Ruby-Cloud-APIサービスを停止します。

$ cd 1v1-private-cloud-v1.7
$ sudo ./docker-compose stop

4.2 新バージョンの設定ファイルを更新

インストールマニュアルの4.2.1節 並行CPU数を調整、4.3.2節 Go-Workersサービスアドレスを設定、4.3.3節 並行CPU数を調整を参照し、CPU数とGo-Workersのアドレスを、旧バージョンと同様に新バージョンの設定ファイルで設定します。

4.3 新バージョンのサービスイメージを読み込む

新バージョンのディレクトリに移動し、イメージファイルを読み込みます。

$ cd 1v1-private-cloud-v1.8
$ sudo ./load_image.sh

4.4 新バージョンのRuby-Cloud-APIサービスを開始

新バージョンでのRuby-Cloud-APIサービスを開始します。

$ sudo ./docker-compose up -d

4.5 旧バージョンのGo-Workersサービスを停止

旧バージョンのフォルダーに移動し、Go-Workersサービスを停止します。

$ cd 1v1-private-cloud-v1.7/go-workers
$ sudo ./stop.sh

4.6 ライセンスファイルをコピー

旧バージョンから、ライセンスファイルを新バージョンのGo-Workersの指定フォルダにコピーします。

$ cp 1v1-private-cloud-v1.7/go-workers/fixture/lisense/senseid_face/senseid_face.lic 1v1-private-cloud-v1.8/go-workers/fixture/lisense/senseid_face
$ cp 1v1-private-cloud-v1.7/go-workers/fixture/lisense/senseid_liveness/senseid_liveness.lic 1v1-private-cloud-v1.8/go-workers/fixture/lisense/senseid_liveness

V1.8.0からsenseid_kestrel.licが必要となります。予めUDID.txtファイル、およびお客様の契約番号を、JCV製品提供窓口（usercenter@japancv.jp）までご連絡ください。詳細はインストールマニュアルの2章 UDID取得をご参照ください。

senseid_kestrel.licを取得後、以下の命令で新バージョンの指定フォルダにコピーしてください。

$ cp {ファイル先}/senseid_liveness.lic {インストール先}/1v1-private-cloud-v1.8/go-worker/fixture/license/senseid_liveness

4.7 新バージョンのGo-Workersサービスを開始

新バージョンのフォルダーに移動し、Go-Workersサービスを開始します。

$ cd 1v1-private-cloud-v1.8/go-workers
$ sudo ./start.sh

4.8 新サービス開始の確認

サービスが正常に開始したか確認します。

• Ruby-Cloud-API

$ sudo ./docker-compose ps

• Go-Workers

$ tail -f tmp/worker.log.0

JCV顔認証サービス「SenseID」をご利用いただき、ありがとうございます。

SenseIDは、使いやすいAI顔認証サービスを提供します。オンラインビジネスのセキュリティとコンプライアンスを確保するためのあらゆる種類のオンライン認証シナリオに対応できるよう作られており、写真品質チェックをはじめ、顔比較や生体検知などの機能を提供し、サーバーとエッジの組み合わせに基づくサービスとなっております。

SenseIDサーバー（プライベートクラウド）では、1v1（顔比較）と1vN（顔検索）の2つのモデルを提供しています。ここでは、各モデルでご利用いただくマニュアルを提供しています。なお、本マニュアルは「SenseID 1v1 V1.8.0」向けの内容です。他のモデルやバージョンの切り替えについては、画面左上をクリックして対象のモデルとバージョンを選択してください。

SenseID専用生体検知SDKのマニュアルはこちらからアクセスできます。

• https://docs.japancv.co.jp/senseid-silent-liveness-detection-sdk/

マニュアルは改訂される場合があります。詳細は各マニュアルの改訂履歴ページを参照してください。　

本マニュアルでは、JCV顔認証サービスSenseIDの運用中に必要な各運用手順について記載しています。

当マニュアルはIT部門に所属するお客様、Linux、Kubernetes、Docker、クラウドなどの利用・運用経験があるお客様を対象にしています。

SenseIDを認証するための展開方法について、主にインストール、設定、重要なサービスの起動、また発生する可能性のある問題とその解決策について詳しく説明しています。

4.1 インストールパッケージの展開確認

ライセンスファイルファイルを配置する為に、パッケージを解凍します。手順は3.3.1節をご参照ください。

解凍されたファイルのディレクトリへ移動し、現在のディレクトリにあるファイルを表示します。

$ cd 1v1-private-cloud-v1.8
$ ls -1

構造は次のとおりです。

api.tar
docker-compose
docker-compose.yml
go-workers
load_image.sh
package.toml
product.toml

4.2 Go-Workersの展開

このサービスは主要なコンピューティングサービスであるため、できれば専用のサーバーリソースを割り当てるようにしてください。

4.2.1 並行CPU数を調整

Go-Workersを配置する前に、サーバーの物理CPUコア数を確認する必要があります。物理CPUコア情報を取得するコマンドは以下のとおりです。

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

Go-Workersディレクトリへ移動して.envファイルを開き、専用サーバーを利用する場合、HANDLERSの値を先程確認した物理CPUコア数に設定してください。それ以外の場合は、コア数を指定してください。編集後、.envファイルを保存してください。

$ cd go-workers
$ vi .env

4.2.2 Go-Workersサービスを開始

Go-Workersサービスを開始します。

$ sudo ./start.sh

なお、展開ディレクトリ内に停止スクリプトも用意されています。停止したい場合、以下の命令を実行してください。

$ sudo ./stop.sh

4.2.3 Go-Workersサービス開始の確認

サービスが正常に開始したかを確認するために、以下の命令でログを参照します。

$ tail -f tmp/worker.log.0

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

また、以下の命令でヘルスチェックを実施してください。

$ curl 127.0.0.1:50050/healthcheck

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

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

4.3 Ruby-Cloud-APIを展開

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

Ruby-Cloud-APIのイメージファイルを読み込みます。

$ cd 1v1-private-cloud-v1.8
$ sudo ./load_image.sh

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

Loaded image: registry.sensetime.com/senseid-cloudv2/api-1v1:xxx

4.3.2 Go-Workersサービスアドレスを設定

Go-WorkersサーバーのIPアドレスを取得してください。

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

SenseIDインストールパッケージのルートフォルダにある.envファイルを開きます。

$ vi .env

最終行の WORKER_IP 値を、Go-Workersサービスが展開されているサーバーの IP アドレスで設定します。

4.3.3 並行CPU数を調整

Go-Workersと同様に、サーバーの物理CPUコア数を設定します。

$ vi .env

.envファイルを開き、専用サーバーを利用する場合、API_HANDLESの値を先程確認した物理CPUコア数に設定してください。それ以外の場合は、コア数を指定してください。編集後、.envファイルを保存してください。

4.3.4 Ruby-Cloud-APIサービス開始

Ruby-Cloud-APIサービスを開始します。

$ sudo ./docker-compose up -d

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

Creating network "1v1-private-cloud-yyyymmdd_default" with the default driver
Creating 1v1-private-cloud-yyyymmdd_api_1 ... done

Dockerが起動していることを確認します。

$ sudo ./docker-compose ps

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

         Name                    Command             State               Ports
---------------------------------------------------------------------------------------
1v1-private-cloud_api_1   ./entrypoint.sh start   Up (healthy)   0.0.0.0:3000->3000/tcp

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

4.3.5 Ruby-Cloud-APIサービス開始を確認

以下の命令で、ヘルスチェックを実施してください。

$ curl 127.0.0.1:3000/healthcheck

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

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

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

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

写真の規格は、運用マニュアルの3章 写真と動画の規格をご参照ください。

リクエストモード

POST

リクエスト URL

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

リクエストパラメーター

通常のレスポンス

{
    "code": 1000,
    "verification_score": float,
    "request_id": string
}

顔比較スコアのしきい値とエラー率との対応関係

推奨しきい値：0.7以上

異常なレスポンス

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

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

可能な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();
    }
}

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

写真と動画の規格は、のをご参照ください。

リクエストモード

POST

リクエスト URL

リクエストパラメーター

通常のレスポンス

ここで、liveness_statusの結果は以下のようになります。

顔比較スコアのしきい値とエラー率との対応関係

推奨しきい値：0.7 以上

異常なレスポンス

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

可能なHTTPステータスコード

使用サンプル

Curl

Java

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

写真の規格は、のをご参照ください。

リクエストモード

POST

リクエスト URL

リクエストパラメーター

通常のレスポンス

顔比較スコアのしきい値とエラー率との対応関係

推奨しきい値：0.7 以上

異常なレスポンス

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

可能なHTTPステータスコード

使用サンプル

Curl

Java

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

顔写真の規格は、のをご参照ください。

リクエストモード

POST

リクエスト URL

リクエストパラメーター

通常のレスポンス

異常なレスポンス

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

可能なHTTPステータスコード

サンプル

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

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

1. cat /proc/cpuinfo コマンドを実行します。

2. フラグを確認します。

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

この場合、解決方法は2通りあります。

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

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

強制的にSSE命令セットを使用できるようにするには、go-workersのenvファイルを開き、FORCE_SET_SSE=falseをFORCE_SET_SSE=trueに変更します。変更後、保存してから、go-workers サービスを再起動します。

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

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

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

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 ？

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

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

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

写真の規格は、のをご参照ください。

リクエストモード

POST

リクエスト URL

リクエストパラメーター

通常のレスポンス

例:

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

顔比較スコアのしきい値とエラー率との対応関係

推奨しきい値：0.7以上

異常なレスポンス

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

可能なHTTPステータスコード

使用サンプル

Curl

Java