Understanding Jina Executors and How to Use Them ¶

Note

This guide assumes you have a basic understanding of Jina, if you haven’t, please check out Jina 101 first.

Table of Contents

Understanding Jina Executors and How to Use Them

Motivation ¶

In Jina the Executors represent an algorithmic class and they are a key part to take the full potential of Jina. We have several of them and they all live in the Hub, facilitating the work-flow while creating your app. Here we will see what exactly are they and how you can use them.

Before you start ¶

You have installed the latest stable release of Jina Core according to the instructions found here and read Understand Jina Recursive Document Representation guide.

Overview ¶

In Jina we want to facilitate your work while building up a search system by managing a lot of the heavy work on the background, but at the same time we want to maintain Jina Core as light-weight and with the least dependencies as possible. This is usually a difficult trade-off, and for this we wanted to keep that heavy-work separate from the Core. This is where the Executors come into play. Think of them as the ones managing all the algorithmic part, so you can use connect them to your Flow without having to understand everything that is happening under the hood.

Executors¶

In Jina we have several Executors:

Crafter
Segmenter
Encoder
Indexer
Ranker
Classifier
Evaluator

All of them are specialized in one task and take care only of that, isolating the workflow. This is possible because each Executor is wrapped up by a Pea as you can see here:

It can also be the case that you need multiple executors at once, and for that you can use a CompoundExecutor. With this you can chain a pipeline of executors, where the input of the current is the output of the former.

We can see an example to make it more clear:

!CompoundExecutor
components:
  - !NumpyIndexer
    with:
      index_filename: vec.gz
    metas:
      name: vecidx_exec  # a customized name
      workspace: ${{TEST_WORKDIR}}
  - !BinaryPbIndexer
    with:
      index_filename: doc.gz
    metas:
      name: docidx_exec
      workspace: ${{TEST_WORKDIR}}
metas:
  name: doc_compound_indexer
  workspace: ${{TEST_WORKDIR}}
requests:
  on:
    SearchRequest:
      - !VectorSearchDriver
        with:
          executor: vecidx_exec
    IndexRequest:
      - !VectorIndexDriver
        with:
          executor: vecidx_exec
    ControlRequest:
      - !ControlReqDriver {}

In this example we have a CompoundExecutor that chains together a NumpyIndexer and a BinaryPbIndexer.

The problem now is how can they communicate the data they are processing. And this is where we meet the Driver.

Drivers¶

The Driver are the ones that handle the input and output messages from the Executor.

As well as we have different Executors for different tasks, we also need different Drivers for different Executors, and you can find the list here.

Executors in action ¶

Executors can be used in several ways in Jina.

Like we said, we have seven types of Execturos in Jina, so let’s see an example with one of them and how we could see it in action.

Run with Docker (docker run)¶

First Let’s use a Ranker just for this example, but this can be used for any other type of Exectuor that you need.

docker run jinahub/pod.ranker.simpleaggregateranker:MODULE_VERSION-JINA_VERSION --port-in 55555 --port-out 55556

Run with Flow API¶

Another way to use them is directly in your Python file. Let’s use a Crafter this time, for example the Image Normalizer

from jina.flow import Flow

f = (Flow().add(name='my_crafter', uses='docker://jinahub/pod.crafter.imagenormalizer:MODULE_VERSION-JINA_VERSION'))
# Or use YAML file.
#f = (Flow().add(name='my_crafter', uses='imagenormalizer.yml'))

Run with Jina CLI¶

Or directly with Jina CLI. Now let’s use an Indexer, the RedisBDIndexer

jina pod --uses docker://jinahub/pod.indexer.redisdbindexer:MODULE_VERSION-JINA_VERSION

Conclusion ¶

In this guide, we introduced why we need and how to use Executors and how they need Drivers to communicate. Apart from that, we provided some concrete examples of how to use them. Now that you now what they are and how to use them, you might be wondering how to create them, we have a guide on that for Executors and Drivers.

What’s next ¶

If you still have questions, feel free to submit an issue or post a message in our community slack channel .

To gain a deeper knowledge on the implementation of Jina Ranker, you can find the source code here.

Understanding Jina Executors and How to Use Them¶

Motivation¶

Before you start¶

Overview¶