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>, <similarity>], ...],
    "error": null
}

e.g.

{
    "luna_request_id": "1659084076,4adbe16d-49e7-4188-8a99-45b94f8ee920",
    "status_code": 201,
    "result": [['691ee8d6-381a-461e-97b8-05f7bf9cb1ad', 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>, <similarity>] is a tuple, first element is a matching candidate ID, second - 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.