Skip to content

Using IDLive Face Match Server

Start container

To run the application, start the Docker container:

docker run --name idfacematch-server -d -p 8080:8080 idfacematch-server-eval:1.3.0

The application is ready once it prints Ready into the log stream. You can also call the /info endpoint. Once it returns 200 OK, the application has started.

The OpenAPI specification is available at http://localhost:8080/openapi.json. You can use Postman or Swagger UI to explore it. Online Swagger UI is available at https://petstore.swagger.io.

Running Qdrant

Qdrant is a vector search engine that allows efficient similarity search. It is required for 1:N face search in IDLive Face Match Server. To start Qdrant using Docker, run the following command:

docker run --name qdrant -d -p 6334:6334 \
  -e QDRANT__STORAGE__HNSW_INDEX__M=64 \
  -e QDRANT__STORAGE__HNSW_INDEX__EF_CONSTRUCT=600 \
  -e QDRANT__SEARCH__HNSW_INDEX__EF=600 \
  qdrant/qdrant:latest

This command pulls and runs the latest Qdrant image, exposing it on port 6334.

The parameters QDRANT__STORAGE__HNSW_INDEX__M=64, QDRANT__STORAGE__HNSW_INDEX__EF_CONSTRUCT=600 and QDRANT__SEARCH__HNSW_INDEX__EF=600 provide an optimal balance between search quality and speed.

Warning

It is crucial to start Qdrant with the recommended parameters above to ensure the best search quality and performance.

Persistent Storage in Qdrant

To ensure that Qdrant retains data between restarts, you can use a persistent volume:

docker run --name qdrant -d -p 6334:6334 \
  -e QDRANT__STORAGE__HNSW_INDEX__M=64 \
  -e QDRANT__STORAGE__HNSW_INDEX__EF_CONSTRUCT=600 \
  -e QDRANT__SEARCH__HNSW_INDEX__EF=600 \
  -v qdrant_storage:/qdrant/storage \
  qdrant/qdrant:latest

For more information on running and configuring Qdrant, refer to the official documentation: Qdrant Documentation.

Start server with 1:N search support

To enable 1:N search functionality using Qdrant, start the server with the IDFM_SERVER_QDRANT_HOST environment variable set to the Qdrant host:

docker run --name idfacematch-server -d -p 8080:8080 \
  -e IDFM_SERVER_QDRANT_HOST=QDRANT_HOST \
  idfacematch-server-eval:1.3.0

By default, the server expects Qdrant to be running on port 6334. If you use a different port, specify it explicitly:

docker run --name idfacematch-server -d -p 8080:8080 \
  -e IDFM_SERVER_QDRANT_HOST=QDRANT_HOST \
  -e IDFM_SERVER_QDRANT_PORT=QDRANT_PORT \
  idfacematch-server-eval:1.3.0

Info

If you are running both idfacematch-server and qdrant on your local machine, ensure proper connectivity between the Docker containers. It can be achieved by creating a docker network and assigning both containers to it:

docker network create idfm-qdrant

docker run --name qdrant -d \
  --network idfm-qdrant \
  -e QDRANT__STORAGE__HNSW_INDEX__M=64 \
  -e QDRANT__STORAGE__HNSW_INDEX__EF_CONSTRUCT=600 \
  -e QDRANT__SEARCH__HNSW_INDEX__EF=600 \
  -v qdrant_storage:/qdrant/storage \
  qdrant/qdrant:latest

docker run --name idfacematch-server -d -p 8080:8080 \
  --network idfm-qdrant \
  -e IDFM_SERVER_QDRANT_HOST=qdrant \
  idfacematch-server-eval:1.3.0

The OpenAPI specification contains a list of endpoints related to 1:N search.

Generate a face template

To generate a face template, send an image to the /detect endpoint. The content type does not matter, but make sure it is not a multipart request:

curl -s --data-binary @image.jpg  http://localhost:8080/detect

Image can be in JPG or PNG format. The response will contain information about all faces on the image, including a face box and a template:

{
  "faces": [
    {
      "box": {
        "x": 967,
        "y": 124,
        "width": 183,
        "height": 254
      },
      "template": "wRkUy8zdCs.."
    }
  ]
}

The coordinates start from the top-left corner of the image. The faces list will be empty if no faces were detected.

The /detect endpoint supports these optional query parameters:

Name Description
max-faces Maximum number of faces that can be on the image. If there are more, an error will be returned.

Match templates

To match two templates, prepare this JSON file:

{
  "source": "wRkUy8zdCs...",
  "target": "32k3vAHk6T..."
}

And send it to the /match endpoint:

curl -s --header "Content-Type: application/json" \
        --data-binary @templates.json http://localhost:8080/match

Example of a response:

{ "probability": 0.83 }

The matching result contains the probability field which is the main factor in determining whether two biometric templates belong to the same identity or different ones. It ranges from 0 (different identities) to 1 (same identity) and the threshold for the decision is 0.5.

Additionaly you can select a calibration:

{
  "source": "wRkUy8zdCs...",
  "target": "32k3vAHk6T...",
  "calibration": "SOFT"
}

Calibration allows you to set the desired FNMR/FMR balance.

Available values for calibration:

  • REGULAR (the default) targets low FMR (0.00001).
  • SOFT achieves lower FNMR while still having acceptable FMR (0.0001).
  • HARD targets extra low FMR (0.000001) with possibly higher FNMR.

When Qdrant is enabled, you can perform 1:N searches. The relevant API endpoints are:

Create a collection

To create a face template collection:

curl -s -XPOST http://localhost:8080/database/collection-name

Add face templates to a collection

To add face templates to a collection:

curl -s --header "Content-Type: application/json" \
        --data-binary '{"templates": ["wRkUy8zdCs..."]}' \
        http://localhost:8080/database/collection-name/records

Search for a face in a collection

To find similar faces in the specified collection based on the provided image:

curl -s --data-binary @image.jpg \
        http://localhost:8080/search/collection-name?limit=5

The response will contain a list of matched records, including their IDs and similarity probabilities.

Query parameters (all optional):

Name Description
max-faces Maximum allowed number of faces in the image. If more faces are detected, an error will be returned.
limit Number of matched records to return for each face detected. Default is 5.
calibration Calibration setting for adjusting the probability based on FNMR and FMR. Available values: REGULAR (default), SOFT, HARD.