> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/backend1n/technical_documentation/performance.md).

# Performance

## Introduction

This document presents the performance test results for **Backend1N Service**. The tests simulate concurrent virtual users (VUs). The test machine and the machine running the service are in different geographic locations (far apart), but belong to the same VPN, with no intermediary tunnel or proxy that could distort latency measurements.

Each row in the performance table corresponds to an **independent scenario**:

1. **Upload media**: uploads the image bank (`POST /assets/upload`) to the same collection (`collectionId`).
2. **Enroll**: registers a specimen (face) (`POST /faces`) for each image uploaded in the previous step, in the same collection (`collectionId`). The generated identifiers are reused in the following scenarios.
3. **Search (image)**: image search (`POST /search/image/{collectionId}`) on the populated collection. **Important:** Image search includes a process for extracting the biometric template from the search image itself.
4. **Search (template)**: biometric template search (`POST /search/template/{collectionId}`), extracted beforehand from each image in the bank (`POST /extract`). Extraction time is excluded from the test metrics.
5. **Delete** (currently no results—see note below the table): deletes the registered specimens (`DELETE /faces/{id}`).

In each scenario involving multiple VUs, the workload is distributed among them **without overlap**: each VU processes its own subset of specimens/searches, with no overlap between them.

## Reference machine

The tests are run against an instance of **AWS EC2 `c5a.8xlarge`**:

| Feature   | Value                                            |
| --------- | ------------------------------------------------ |
| Processor | AMD EPYC (2nd generation, "Rome"), up to 3.3 GHz |
| vCPUs     | 32                                               |
| RAM       | 64 GiB                                           |

## Test configuration

* **5000:** Number of specimens in the database.
* **20000:** Number of searches against the database.
* **PostgreSQL:** Database associated with the service. The service also supports `MongoDB`, but it is outside the scope of this test.
* **FACEPHI\_SELPHID\_FACIALEXTRACTOR\_NUM\_THREADS:8** Number of threads assigned to the facial extraction engine (environment variable).
* **"number\_of\_threads": 4** Value inside `config.json` which indicates the number of concurrent requests the service can handle. Any additional requests will be queued. **Important:** is set to `4` because the machine has `32 vCPUs`. For instances with `16 vCPUs` this value should be `2`. For instances with `8 vCPUs` this value should be `1`.

> For optimal performance, `FACEPHI_SELPHID_FACIALEXTRACTOR_NUM_THREADS * number_of_threads` must equal the number of `vCPUs` on the node.

## Performance

> **Important:** The service does not maintain its own state between requests (state is stored in the PostgreSQL/MongoDB database). This means that each search operation (image or template) rebuilds a 1N gallery in memory from the database. This process always ensures data integrity, but affects performance.

> **Important:** Database access is mutually exclusive among all VUs on the same node. For this reason, we see no improvement in searches with more than 2 VUs.

| Phase                                              | 1 VU                                                                                                     | 2 VUs                                                                                                     | 4 VUs                                                                                                    | 8 VUs                                                                                                     | 16 VUs                                                                                                     |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| <p><strong>Upload media</strong><br>(5000)</p>     | <p>Total: 933.96 s<br>TPS: 5.35 req/s<br>mean: 0.19 s<br>max: 2.28 s<br>p50: 0.18 s<br>p95: 0.20 s</p>   | <p>Total: 452.96 s<br>TPS: 11.04 req/s<br>mean: 0.18 s<br>max: 1.15 s<br>p50: 0.17 s<br>p95: 0.19 s</p>   | <p>Total: 245.42 s<br>TPS: 20.37 req/s<br>mean: 0.19 s<br>max: 2.14 s<br>p50: 0.18 s<br>p95: 0.21 s</p>  | <p>Total: 121.66 s<br>TPS: 41.10 req/s<br>mean: 0.19 s<br>max: 1.86 s<br>p50: 0.18 s<br>p95: 0.22 s</p>   | <p>Total: 78.53 s<br>TPS: 63.67 req/s<br>mean: 0.23 s<br>max: 1.72 s<br>p50: 0.22 s<br>p95: 0.33 s</p>     |
| <p><strong>Enroll</strong><br>(5000)</p>           | <p>Total: 1129.45 s<br>TPS: 4.43 req/s<br>mean: 0.23 s<br>max: 0.84 s<br>p50: 0.22 s<br>p95: 0.24 s</p>  | <p>Total: 601.71 s<br>TPS: 8.31 req/s<br>mean: 0.24 s<br>max: 0.66 s<br>p50: 0.23 s<br>p95: 0.28 s</p>    | <p>Total: 408.89 s<br>TPS: 12.23 req/s<br>mean: 0.33 s<br>max: 0.71 s<br>p50: 0.32 s<br>p95: 0.37 s</p>  | <p>Total: 454.16 s<br>TPS: 11.01 req/s<br>mean: 0.62 s<br>max: 1.66 s<br>p50: 0.59 s<br>p95: 1.24 s</p>   | <p>Total: 415.09 s<br>TPS: 12.05 req/s<br>mean: 1.04 s<br>max: 5.19 s<br>p50: 0.66 s<br>p95: 1.94 s</p>    |
| <p><strong>Search (image)</strong><br>20000</p>    | <p>Total: 44366.13 s<br>TPS: 0.45 req/s<br>mean: 2.22 s<br>max: 2.93 s<br>p50: 2.20 s<br>p95: 2.51 s</p> | <p>Total: 22340.71 s<br>TPS: 0.90 req/s<br>mean: 2.23 s<br>max: 47.16 s<br>p50: 2.21 s<br>p95: 2.52 s</p> | <p>Total: 20072.42 s<br>TPS: 1.00 req/s<br>mean: 3.13 s<br>max: 6.17 s<br>p50: 2.74 s<br>p95: 4.29 s</p> | <p>Total: 19892.78 s<br>TPS: 1.01 req/s<br>mean: 6.41 s<br>max: 13.93 s<br>p50: 6.47 s<br>p95: 9.27 s</p> | <p>Total: 15662.86 s<br>TPS: 1.28 req/s<br>mean: 9.00 s<br>max: 22.94 s<br>p50: 8.43 s<br>p95: 15.40 s</p> |
| <p><strong>Search (template)</strong><br>20000</p> | <p>Total: 41182.27 s<br>TPS: 0.49 req/s<br>mean: 2.06 s<br>max: 3.68 s<br>p50: 2.03 s<br>p95: 2.34 s</p> | <p>Total: 19870.45 s<br>TPS: 1.01 req/s<br>mean: 1.99 s<br>max: 4.19 s<br>p50: 1.96 s<br>p95: 2.25 s</p>  | <p>Total: 19220.16 s<br>TPS: 1.04 req/s<br>mean: 2.97 s<br>max: 4.59 s<br>p50: 2.77 s<br>p95: 4.10 s</p> | <p>Total: 19379.94 s<br>TPS: 1.03 req/s<br>mean: 5.35 s<br>max: 12.05 s<br>p50: 4.22 s<br>p95: 9.39 s</p> | <p>Total: 9553.79 s<br>TPS: 2.09 req/s<br>mean: 7.53 s<br>max: 12.17 s<br>p50: 7.56 s<br>p95: 9.76 s</p>   |
| <p><strong>Delete</strong><br>5000</p>             | <p>Total: 635.79 s<br>TPS: 7.83 req/s<br>mean: 0.13 s<br>max: 0.38 s<br>p50: 0.13 s<br>p95: 0.14 s</p>   | <p>Total: 334.56 s<br>TPS: 14.89 req/s<br>mean: 0.13 s<br>max: 0.36 s<br>p50: 0.13 s<br>p95: 0.15 s</p>   | <p>Total: 163.46 s<br>TPS: 30.47 req/s<br>mean: 0.13 s<br>max: 0.36 s<br>p50: 0.13 s<br>p95: 0.14 s</p>  | <p>Total: 82.87 s<br>TPS: 60.09 req/s<br>mean: 0.13 s<br>max: 0.50 s<br>p50: 0.13 s<br>p95: 0.15 s</p>    | <p>Total: 42.74 s<br>TPS: 116.51 req/s<br>mean: 0.13 s<br>max: 1.14 s<br>p50: 0.13 s<br>p95: 0.15 s</p>    |

## Database sizing

After completing the registration of images and specimens (faces), the database status is as follows:

**PostgreSQL (db\_backend)**

| Table       | Items | Data     | Indexes  | Total    |
| ----------- | ----- | -------- | -------- | -------- |
| collections | 1     | 16.0 KB  | 16.0 KB  | 32.0 KB  |
| media       | 5000  | 683.6 MB | 336.0 KB | 683.9 MB |
| patterns    | 4980  | 94.0 MB  | 400.0 KB | 94.4 MB  |

## Scaling

The TPS figures collected in the previous table are the performance ceiling for **a single instance** deployed on the reference machine. If higher performance is needed, the solution is not to scale that same machine vertically (add more vCPUs/memory to a single instance), but to scale horizontally: deploy a **cluster of multiple instances** of the service, managed by a cloud orchestration technology (Kubernetes or an equivalent), distributing the load across all of them through a load balancer.

The service does not maintain its own state between requests (the state resides in the PostgreSQL/MongoDB database), so adding replicas behind a load balancer is straightforward, provided that all replicas point to the same shared database.
