Skip to content

Commit 7dd0de0

Browse files
VolodymyrBushkoVolodymyrBushko
committed
EFRS-1333: Added the REST API descriptions for endpoints that use embeddings instead of images to perform recognition and verification
1 parent 3754d53 commit 7dd0de0

File tree

2 files changed

+124
-1
lines changed

2 files changed

+124
-1
lines changed

‎docs/Rest-API-description.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -831,3 +831,126 @@ curl -X POST "http://localhost:8000/api/v1/verification/verify?limit=<limit>&pre
831831
-d {"source_image": "<source_image_base64_value>", "target_image": "<target_image_base64_value>"}
832832
```
833833

834+
835+
836+
## Embedding Support
837+
`since 1.2.0 version`
838+
839+
If you already have a computed embedding, you can use it to perform recognition and verification.
840+
The base rule is to use `Content-Type: application/json` header and send JSON in the body.
841+
842+
### Embedding Recognition Service
843+
The service is used to determine similarities between input embeddings and embeddings within the database. An example:
844+
845+
```shell
846+
curl -X POST "http://localhost:8000/api/v1/recognition/embeddings/recognize?prediction_count=<prediction_count>" \
847+
-H "Content-Type: application/json" \
848+
-H "x-api-key: <service_api_key>" \
849+
-d {"embeddings": "<array_of_embeddings>"}
850+
```
851+
852+
| Element | Description | Type | Required | Notes |
853+
|------------------|-------------|---------|----------|-----------------------------------------------------------------------------------------------------------------|
854+
| Content-Type | header | string | required | application/json |
855+
| x-api-key | header | string | required | an api key of the Embedding recognition service, created by the user |
856+
| embeddings | body | array | required | an input embeddings. The length must be 512 for each of them |
857+
| prediction_count | param | integer | optional | the maximum number of subject predictions per embedding. It returns the most similar subjects. Default value: 1 |
858+
859+
Response body on success:
860+
```json
861+
{
862+
"results": [
863+
{
864+
"embedding": [0.0627421774604647, "...", -0.0236684433507126],
865+
"similarities": [
866+
{
867+
"subject": "John",
868+
"similarity": 0.55988
869+
},
870+
"..."
871+
]
872+
},
873+
"..."
874+
]
875+
}
876+
```
877+
878+
| Element | Type | Description |
879+
|--------------|--------|--------------------------------------------------------------------------------------------|
880+
| results | array | an array that contains all the results |
881+
| embedding | array | an embedding that is similar to the input embedding |
882+
| similarities | array | an array that contains results of similarity between the embedding and the input embedding |
883+
| subject | string | a subject in which the similar embedding was found |
884+
| similarity | float | a similarity between the embedding and the input embedding |
885+
886+
### Embedding Verification Service
887+
The service is used to determine similarities between an input source embedding and input target embeddings. An example:
888+
889+
```shell
890+
curl -X POST "http://localhost:8000/api/v1/verification/embeddings/verify" \
891+
-H "Content-Type: application/json" \
892+
-H "x-api-key: <service_api_key>" \
893+
-d {"source": "<source_embedding>"; "targets": "array_of_target_embeddings"}
894+
```
895+
896+
| Element | Description | Type | Required | Notes |
897+
|------------------|-------------|---------|----------|--------------------------------------------------------------------|
898+
| Content-Type | header | string | required | application/json |
899+
| x-api-key | header | string | required | api key of the Embedding verification service, created by the user |
900+
| source | body | array | required | the source embedding. The length must be 512 |
901+
| targets | body | array | required | the target embeddings. The length must be 512 for each of them |
902+
903+
Response body on success:
904+
```json
905+
{
906+
"results": [
907+
{
908+
"embedding": [0.0627421774604647, "...", -0.0236684433507126],
909+
"similarity": 0.55988
910+
},
911+
"..."
912+
]
913+
}
914+
```
915+
916+
| Element | Type | Description |
917+
|--------------|--------|--------------------------------------------------------------------|
918+
| results | array | an array that contains all the results |
919+
| embedding | array | a target embedding that is similar to the source embedding |
920+
| similarity | float | a similarity between the source embedding and the target embedding |
921+
922+
### Verify Embeddings using Given Embedding
923+
The endpoint is used to compare input embeddings to the embedding by its id. An example:
924+
925+
```shell
926+
curl -X POST "http://localhost:8000/api/v1/recognition/embeddings/faces/{embeddingId}/verify" \
927+
-H "Content-Type: application/json" \
928+
-H "x-api-key: <service_api_key>" \
929+
-d {"embeddings": "<array_of_embeddings>"}
930+
```
931+
932+
| Element | Description | Type | Required | Notes |
933+
|--------------|-------------|--------|----------|-------------------------------------------------------------------|
934+
| Content-Type | header | string | required | application/json |
935+
| x-api-key | header | string | required | api key of the Embedding recognition service, created by the user |
936+
| embeddings | body | array | required | input target embeddings. The length must be 512 for each of them |
937+
| embedding_id | variable | UUID | required | an id of the source embedding within the database |
938+
939+
Response body on success:
940+
```json
941+
{
942+
"results": [
943+
{
944+
"embedding": [0.0627421774604647, "...", -0.0236684433507126],
945+
"similarity": 0.55988
946+
},
947+
"..."
948+
]
949+
}
950+
```
951+
952+
| Element | Type | Description |
953+
|--------------|--------|--------------------------------------------------------------------|
954+
| results | array | an array that contains all the results |
955+
| embedding | array | a target embedding that is similar to the source embedding |
956+
| similarity | float | a similarity between the source embedding and the target embedding |

‎java/api/src/main/java/com/exadel/frs/core/trainservice/dto/EmbeddingRecognitionProcessResult.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,5 @@
1313
public class EmbeddingRecognitionProcessResult {
1414

1515
private double[] embedding;
16-
private List<EmbeddingSimilarityResult> results;
16+
private List<EmbeddingSimilarityResult> similarities;
1717
}

0 commit comments

Comments
 (0)