From v5.2 to v6.1

This migration guide outlines the recent changes made in the Face SDK v6.1. Refer to the following information to ensure a smooth transition and update your implementation accordingly.

Warning

The Web Component and Mobile SDK v6.1 are only compatible with the Web Service v6.1. Make sure to update the Web Service first and only after that update client applications.

Web Service

Updated Milvus to v2.3.8

As Milvus was updated v2.3.8, you need to migrate to version 2.3.8. Migration from v2.2.2 to v2.3.8 involves creating a backup using milvus-backup 0.2.2 and restoring it with 0.4.0.

Info

For more details, see the Milvus guides:

This migration guide outlines prerequisites and the necessary steps for a smooth transition.

Prerequisites

GO: Install GO from https://go.dev/doc/install
git: Installation guide can be found at https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

git clone git@github.com:zilliztech/milvus-backup.git
cd milvus-backup

git checkout v0.2.2
go get
go build

The connection to Milvus is set via configs/backup.yaml.

Warning

Note that bucketName and backupBucketName should match the Milvus bucket name (milvus-bucket). Ensure consistency between these settings for proper configuration.

Migration Steps

1. Create a backup:

./milvus-backup create -n milvus_2_2_2

You should receive a success message.

2. Restore data:

git checkout v0.4.0
go get
go build

You should see a success message.

Post-Migration

Right after migration, collections will be without indexes. To get indexes created and collections loaded into memory automatically, restart the FaceAPI service.

YAML Configuration

We have significantly redesigned the Web Service configuration to simplify it and reduce confusion with environment variables. Now, the Face SDK Web Service can be configured via a YAML file. In this new structure, we've dedicated a separate section for each module, consolidating all module-specific settings in one place. The only settings that should be configured using environment variables are the System Settings that are listed separately.

To enable YAML configuration, in the Face SDK Web Service installation folder, you need to find the config.yaml.example file and rename it to config.yaml. Make sure not to move the file to other folders, it should be located in the root directory of the Web Service.

For a quick and painless migration, you can use the guide below and see how the new YAML parameters correspond to the deprecated environment variables.

To study the structure and parameters of the YAML file in details, visit the Configuration page.

General

Environment variable	YAML parameter
FACEAPI_BIND	`webServer.port`
FACEAPI_WORKERS	`webServer.workers`
FACEAPI_TIMEOUT	`webServer.timeout`
FACEAPI_ENABLE_DEMO_WEB_APP	`webServer.demoApp.enabled`
HTTPS_PROXY	not used
REGULA_RETURN_SYSTEMINFO	should be configured at the system level

HTTPS and CORS

Environment variable	YAML parameter
FACEAPI_CORS_ORIGINS	`webServer.cors.origins`
FACEAPI_CORS_METHODS	`webServer.cors.methods`
FACEAPI_CORS_HEADERS	`webServer.cors.headers`
FACEAPI_HTTPS	`webServer.ssl.enabled`
FACEAPI_CERT_FILE	`webServer.ssl.cert`
FACEAPI_KEY_FILE	`webServer.ssl.key`
FACEAPI_TLS_VERSION	`webServer.ssl.tlsVersion`

Monitoring

Environment variable	YAML parameter
FACEAPI_ENABLE_PROMETHEUS_METRICS	`webServer.metrics.enabled`

Logging

Access logs are configured in the service.webServer.logging.access section.

Application logs are configured in service.webServer.logging.app.

The location for the processing result logs is set separately for the modules:

service.detectMatch.results.location for the Detection and Comparison modules
service.liveness.sessions.location for the Liveness module
service.search.persons.location for the Identification module

Liveness Module

For the Liveness module settings, see the Liveness section.

Identification Module

For the Identification module settings, see the Search section.

Storage

Storage is now configured in two steps:

1. Set the credentials for the storage type in service.storage.

2. Configure storage buckets separately within each feature section:

For Face Detection and Comparison, see service.detectMatch.results.location
For Liveness Assessment, see service.liveness.sessions.location
For Identification, see service.search.persons.location

Database

Environment variable	YAML parameter
FACEAPI_SQL_URL	`service.database.connectionString`

Milvus

Environment variable	YAML parameter
FACEAPI_MILVUS_HOST	`service.search.vectorDatabase.milvus.endpoint`
FACEAPI_MILVUS_PORT	`service.search.vectorDatabase.milvus.endpoint`

Scenarios

Face Detection scenarios are now set up in the sdk.detect.scenarios field of the config.yaml file.

Deprecated `thumbnails`

For the Face Detection and Face Comparison features, the thumbnails request parameter is deprecated and will be removed in future releases. Instead, to get thumbnails with the detected faces, utilize the crop field within outputImageParams.

In the 6.1 release, both thumbnails and outputImageParams are still available. They work the following way:

If only thumbnails is set to true, it will be used.
When both outputImageParams and thumbnails are present, thumbnails will be disregarded, and the image processing method will be determined by the crop parameters.

To obtain a thumbnail using outputImageParams with the same dimensions as you did with thumbnails, set the type parameter to 0.

Mobile

The Face SDK now includes two Core framework types:

Core Basic supports only server-side face comparison.
Core Match lets you perform a client-side face comparison.

You can learn more about the available Core types on the Installation page.

As usage of the Core framework has been updated, you need to update your dependencies as described below.

Android

1. To use Core Basic, in your project's build.gradle file, replace

implementation 'com.regula.face:core:5.2.+@aar'

with

implementation 'com.regula.face.core:basic:6.1.+@aar'

To use the new Core Match type, which works in the offline mode, add:

implementation 'com.regula.face.core:match:6.1.+@aar'

2. Now, to use FaceSDK, it's necessary to include the uncompressed faceSdkResource.dat file in the APK. See the updated Installation guide for details, step 3.

iOS

To use Core Basic, in your project's Podfile file, replace

pod 'FaceSDK'
pod 'FaceCore'