Service interaction#

Below is a diagram of the interaction of the index module services.

In the Index Manager service, a task is created to build an index (in automatic or one-time modes). If automatic indexing is specified in the Index Manager settings, the service interacts with the Faces database to track changes in the lists (IMan1).

All information about matching tasks is stored in the Redis (IMan2) database. It also uses the RedLock mechanism, which provides work with multiple instances of the Index Manager service.

After creation, the tasks are sent to the Indexer (In1) service. After receiving the task, the Indexer service extracts the descriptors from the Faces database (In2) and starts generating the index. The generated index is stored in storage (In3). Indexed Matcher caches indexes (IMat1) and waits for a matching request. The Index Manager service interacts with the repository by sending requests related to the created indexes (IMan3).

The API service sends the matching request to the Python Matcher Proxy service (A1), which determines where to send the request. If the Python Matcher (MP1), then the matching will be performed in this service. If the list is too large, a matching request will be sent to the Indexed Matcher (MP2) service.

See description of the principle of distribution of matching requests between the Python Matcher or Indexed Matcher service in the section "Matching plugin for Python Matcher Proxy".

The Indexed Matcher service checks for a matching license by interacting with the Licenses (IMat2) service. During and after the matching, the Indexed Matcher service interacts with Redis (IMat3). After the end of the matching, its result is sent to the Python Matcher Proxy service (IMat4), and then to the API service (MP3).

To perform a matching request in the Indexed Matcher service, indexes must be created in advance.

Matching plugin for Python Matcher Proxy#

There are three types of plugins in LUNA PLATFORM:

Event plugins. Intended to monitor and send events.
Background plugins. Intended to implement individual requests for a specific resource, background monitoring of resources, etc.
Matching plugins. Intended to improve the matching process.

For user interaction with the Indexed Matcher service, you should use a special matching plugin located in the Python Matcher Proxy service container.

This section describes how matching plugins work. See the "Plugins" section of the LUNA PLATFORM 5 administrator manual for detailed information on event plugins and background plugins.

Matching plugin description#

Each matching request is presented in the form of all possible combinations of candidates and references, then each such combination is processed as a separate sub-request as follows (further sub-request means combination of reference and candidates):

Get the sub-request matching cost (see "Matching cost").
Choose the way for the sub-request processing using the lowest estimated matching cost: matching plugin or Python Matcher service.
- If in the previous step Python Matcher service was selected, it will process sub-request, returns the response to the Python Matcher Proxy service.
- If in the previous step matching plugin was selected, it will process sub-request. If sub-request was successfully processed, the response returns to the Python Matcher Proxy service. If a sub-request was not successfully processed, it will try to process by Python Matcher service.
If the request was successfully processed by matching plugin and plugin does not have access to all matching targets which specified in sub-request, then Python Matcher Proxy service will enrich data before next step, see matching targets for details.
The Python Matcher Proxy service collects results from all sub-requests, sorts them in the right order, and replies to the user.

Matching cost#

Matching cost is a float numeric expression of matching request process complexity using a plugin. Matching cost is necessary to choose the best way to process a matching request: Python Matcher service or one or more plugins.

The matching cost value for the Python Matcher service is 100. If there are several plugins, then the matching cost value will be calculated for each plugin. The matching plugin with the lowest matching cost will be used if its matching cost is lower than the Python Matcher matching cost. All requests with matching costs greater than 100 will be processed in the Python Matcher service. If there are no plugins, Python Matcher will be used for the request processing.

Matching targets#

The Python Matcher service has access to all data of matching entities, so it can process matching requests with all targets. Matching plugins may not have access to data, which is specified in request targets. In this case, Python Matcher Proxy service will enrich response of plugin with missing targets data, e.g.:

matching response contains next targets: face_id, user_data and similarity and the chosen matching plugin does not have access to user_data field:
- matching plugin match reference with specified face_ids and return the matching response to the Luna-Python-Matcher-Proxy, which contains only pairs of face_id and similarity;
- for every match candidate in result, Python Matcher Proxy service will get user_data from the main database by face_id and merge face_id and similarity with user_data;
- return enriched response with specified targets to the user.
matching response contains next targets: age, gender (all candidates are events’ faces) and the chosen matching plugin have access only to event_id, descriptor, and age fields:
- matching plugin match reference and return the matching response to the Luna-Python-Matcher-Proxy, which contains only pairs of event_id, age and similarity;
- for every match candidate in result, Python Matcher Proxy service will get gender from the main database by event_id and merge event_id with gender, also after that it drops non-required event_id and similarity from the response
- return a prepared response with specified targets to the user.

Several matching plugins can be used in LUNA PLATFORM. See the "Matching plugins" section of the LUNA PLATFORM administrator manuals for details.