Matching requests¶

Matching request format¶

LIM Matcher accepts matching requests via Redis streams. For requests for each matching label there is the stream with the name of the label. Multiple running matcher instances with loaded index are consumer group for this stream. Stream messages to be properly processed by matchers should have the following format:

{
    "descriptor": <descriptor>,
    "label": <label>,
    "limit": <limit>,
    "response_channel": <response_channel>,
    "luna_request_id": <luna_request_id>,
    "rid": <rid>
}

e.g.

{
    "descriptor": b"dp\x00\x00;\x00\x00\x0011111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111",
    "label": "17cdbe41-c7f1-440b-b9ad-aad93c7176ee",
    "limit": 1,
    "response_channel": "indexed_matcher_channel:5eab97d0-a9b7-4887-b718-e2de8fb73944",
    "luna_request_id": "1659084076,4adbe16d-49e7-4188-8a99-45b94f8ee920",
    "rid": "757ddeaa-bf21-4916-891a-7ab1e175e5c6"
}

where

<descriptor> is an SDK binary descriptor, in bytes;
<label> is a matching label UUID (i.g. list ID);
<limit> is a limit of the number of matching candidates;
<response_channel> is a name of the channel to send the response;
<luna_request_id> is external matching request ID (helps to identify messages in system logs that correspond to particular requests);
<rid> is unique matching request ID.

Matching response format¶

LIM Matcher sends matching result to the Redis channel specified in the request. Matching response, depending on whether it was successful, has one of the following formats:

{
    "luna_request_id": <luna_request_id>,
    "status_code": <status_code>,
    "result": [{"face_id": <face_id>, "similarity": <similarity>}, ...],
    "error": null
}

e.g.

{
    "luna_request_id": "1659084076,4adbe16d-49e7-4188-8a99-45b94f8ee920",
    "status_code": 201,
    "result": [{'face_id': '691ee8d6-381a-461e-97b8-05f7bf9cb1ad', 'similarity': 0.997}],
    "error": null
}

where

<luna_request_id> is external matching request ID specified in the request;
<status_code> is response status code (mimic an HTTP status code);
<face_id> is a matching candidate ID;
<similarity> is a reference vs candidate similarity score.

{
    "luna_request_id": <luna_request_id>,
    "status_code": <status_code>,
    "result": null,
    "error": {"error_code": <error_code>, "desc": <desc>, "detail": <detail>, "link": <link>}
}

e.g.

{
    "luna_request_id": "1659084076,4adbe16d-49e7-4188-8a99-45b94f8ee920",
    "status_code": 400,
    "result": null,
    "error": {"error_code": 26305, "desc": "Descriptor version mismatch", "detail": "Descriptor of version 0 cannot be searched in index of version 59", "link": "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-26305"}
}

where

<luna_request_id> is external matching request ID specified in the request;
<status_code> is response status code (mimic an HTTP status code);
<error_code> is Luna Platform error code;
<desc> is some error description;
<detail> is some error details;
<link> is a link to the documentation website with the error description.

Matching label synchronization¶

In the background, the matcher synchronizes in-memory index labels with Redis keys. For all the in-memory index labels, the matcher sets keys in the following format: matching_label:<label>, e.g. matching_label:17cdbe41-c7f1-440b-b9ad-aad93c7176ee. Label keys being set have a TTL and will expire if no matcher update this key again. The presence of such a key in Redis means that at least one of the running matcher instances can process matching requests on the label.