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.

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

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:

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.

1:N Search¶

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):