Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Failed to load latest commit information.
Latest commit message
Commit time

Jina logo: Build multimodal AI services via cloud native technologies 路 Neural Search 路 Generative AI 路 Cloud Native

Build multimodal AI services with cloud native technologies

PyPI Codecov branch PyPI - Downloads from official pypistats Github CD status

Jina is an MLOps framework to build multimodal AI services and pipelines then serve, scale and deploy them to a production-ready environment like Kubernetes or Jina AI Cloud. Jina handles the infrastructure complexity, making advanced solution engineering and cloud-native technologies accessible to every developer.

Build and deploy a gRPC microserviceBuild and deploy a pipeline

Applications built with Jina enjoy the following features out of the box:

馃寣 Universal

  • Build applications that deliver fresh insights from multiple data types such as text, image, audio, video, 3D mesh, PDF with LF's DocArray.
  • Support for all mainstream deep learning frameworks.
  • Polyglot gateway that supports gRPC, Websockets, HTTP, GraphQL protocols with TLS.


  • Intuitive design pattern for high-performance microservices.
  • Easy scaling: set replicas, sharding in one line.
  • Duplex streaming between client and server.
  • Async and non-blocking data processing over dynamic flows.

鈽侊笍 Cloud native

  • Seamless Docker container integration: sharing, exploring, sandboxing, versioning and dependency control via Executor Hub.
  • Full observability via OpenTelemetry, Prometheus and Grafana.
  • Fast deployment to Kubernetes and Docker Compose.

馃嵄 Ecosystem

  • Improved engineering efficiency thanks to the Jina AI ecosystem, so you can focus on innovating with the data applications you build.
  • Free CPU/GPU hosting via Jina AI Cloud.

Jina in Jina AI neural search ecosystem



pip install jina

Find more install options on Apple Silicon/Windows.

Get Started

Basic Concepts

Jina has three fundamental concepts:

  • A Document (from DocArray) is the input/output format in Jina.
  • An Executor is a Python class that transforms and processes Documents.
  • A Deployment serves a single Executor, while a Flow serves Executors chained into a pipeline.

The full glossary is explained here.

Jina: Streamline AI & ML Product Delivery

Build AI Services

Open In Colab

Let's build a fast, reliable and scalable gRPC-based AI service. In Jina we call this an Executor. Our simple Executor will use Facebook's mBART-50 model to translate French to English. We'll then use a Deployment to serve it.

Note A Deployment serves just one Executor. To combine multiple Executors into a pipeline and serve that, use a Flow.

Note Run the code in Colab to install all dependencies.

Let's implement the service's logic:
from docarray import DocumentArray
from jina import Executor, requests
from transformers import AutoTokenizer, AutoModelForSeq2SeqLM

class Translator(Executor):
    def __init__(self, **kwargs):
        self.tokenizer = AutoTokenizer.from_pretrained(
            "facebook/mbart-large-50-many-to-many-mmt", src_lang="fr_XX"
        self.model = AutoModelForSeq2SeqLM.from_pretrained(

    def translate(self, docs: DocumentArray, **kwargs):
        for doc in docs:
            doc.text = self._translate(doc.text)

    def _translate(self, text):
        encoded_en = self.tokenizer(text, return_tensors="pt")
        generated_tokens = self.model.generate(
            **encoded_en, forced_bos_token_id=self.tokenizer.lang_code_to_id["en_XX"]
        return self.tokenizer.batch_decode(generated_tokens, skip_special_tokens=True)[

Then we deploy it with either the Python API or YAML:

Python API: YAML: deployment.yml
from jina import Deployment

with Deployment(uses=Translator, timeout_ready=-1) as dep:
jtype: Deployment
  uses: Translator
    - # name of the module containing Translator
  timeout_ready: -1

And run the YAML Deployment with the CLI: jina deployment --uses deployment.yml

鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹 馃帀 Deployment is ready to serve! 鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹
鈺攢鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹 馃敆 Endpoint 鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈺
鈹  鉀      Protocol                   GRPC 鈹
鈹  馃彔        Local  鈹
鈹  馃敀      Private  鈹
鈹  馃實       Public  鈹

Use Jina Client to make requests to the service:

from docarray import Document
from jina import Client

french_text = Document(
    text='un astronaut est en train de faire une promenade dans un parc'

client = Client(port=12345)  # use port from output above
response ='/', inputs=[french_text])

an astronaut is walking in a park

Note In a notebook, one cannot use deployment.block() and then make requests to the client. Please refer to the colab link above for reproducible Jupyter Notebook code snippets.

Build a pipeline

Open In Colab

Sometimes you want to chain microservices together into a pipeline. That's where a Flow comes in.

A Flow is a DAG pipeline, composed of a set of steps, It orchestrates a set of Executors and a Gateway to offer an end-to-end service.

Note If you just want to serve a single Executor, you can use a Deployment.

For instance, let's combine our French translation service with a Stable Diffusion image generation service from Jina AI's Executor Hub. Chaining these services together into a Flow will give us a multilingual image generation service.

Build the Flow with either Python or YAML:

Python API: YAML: flow.yml
from jina import Flow

flow = (
    .add(uses=Translator, timeout_ready=-1)
)  # use the Executor from Executor hub

with flow:
jtype: Flow
  - uses: Translator
    timeout_ready: -1
  - uses: jinaai://jina-ai/TextToImage
    timeout_ready: -1
    install_requirements: true

Then run the YAML Flow with the CLI: jina flow --uses flow.yml

鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹 馃帀 Flow is ready to serve! 鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹
鈺攢鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹 馃敆 Endpoint 鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈹鈺
鈹  鉀      Protocol                   GRPC  鈹
鈹  馃彔        Local  鈹
鈹  馃敀      Private  鈹
鈹  馃實       Public  鈹

Then, use Jina Client to make requests to the Flow:

from jina import Client, Document

client = Client(port=12345)  # use port from output above

french_text = Document(
    text='un astronaut est en train de faire une promenade dans un parc'

response ='/', inputs=[french_text])



You can also deploy a Flow to JCloud.

First, turn the flow.yml file into a JCloud-compatible YAML by specifying resource requirements and using containerized Hub Executors.

Then, use jina cloud deploy command to deploy to the cloud:

jina cloud deploy jcloud-flow.yml

鈿狅笍 Caution: Make sure to delete/clean up the Flow once you are done with this tutorial to save resources and credits.

Read more about deploying Flows to JCloud.

Check the getting-started project source code.

Jina: No Infrastructure Complexity, High Engineering Efficiency

Why not just use standard Python to build that microservice and pipeline? Jina accelerates time to market of your application by making it more scalable and cloud-native. Jina also handles the infrastructure complexity in production and other Day-2 operations so that you can focus on the data application itself.

Jina: Scalability and concurrency with ease

Easy scalability and concurrency

Jina comes with scalability features out of the box like replicas, shards and dynamic batching. This lets you easily increase your application's throughput.

Let's scale a Stable Diffusion Executor deployment with replicas and dynamic batching:

  • Create two replicas, with a GPU assigned for each.
  • Enable dynamic batching to process incoming parallel requests together with the same model inference.
Normal Deployment Scaled Deployment
jtype: Deployment
  timeout_ready: -1
  uses: jinaai://jina-ai/TextToImage
  install_requirements: true
jtype: Deployment
  timeout_ready: -1
  uses: jinaai://jina-ai/TextToImage
  install_requirements: true
  replicas: 2
  uses_dynamic_batching: # configure dynamic batching
      preferred_batch_size: 10
      timeout: 200

Assuming your machine has two GPUs, using the scaled deployment YAML will give better throughput compared to the normal deployment.

These features apply to both Deployment YAML and Flow YAML. Thanks to the YAML syntax, you can inject deployment configurations regardless of Executor code.

Jina: Seamless Container Integration

Seamless container integration

Use Executor Hub to share your Executors or use public/private Executors, with no need to worry about dependencies.

To create an Executor:

jina hub new 

To push it to Executor Hub:

jina hub push .

To use a Hub Executor in your Flow:

Docker container Sandbox Source
YAML uses: jinaai+docker://<username>/MyExecutor uses: jinaai+sandbox://<username>/MyExecutor uses: jinaai://<username>/MyExecutor
Python .add(uses='jinaai+docker://<username>/MyExecutor') .add(uses='jinaai+sandbox://<username>/MyExecutor') .add(uses='jinaai://<username>/MyExecutor')

Executor Hub manages everything on the backend:

  • Automated builds on the cloud
  • Store, deploy, and deliver Executors cost-efficiently;
  • Automatically resolve version conflicts and dependencies;
  • Instant delivery of any Executor via Sandbox without pulling anything to local.

Jina: Seamless Container Integration

Get on the fast lane to cloud-native

Using Kubernetes with Jina is easy:

jina export kubernetes flow.yml ./my-k8s
kubectl apply -R -f my-k8s

And so is Docker Compose:

jina export docker-compose flow.yml docker-compose.yml
docker-compose up

Note You can also export Deployment YAML to Kubernetes and Docker Compose.

Likewise, tracing and monitoring with OpenTelemetry is straightforward:

from docarray import DocumentArray
from jina import Executor, requests

class Encoder(Executor):
    def encode(self, docs: DocumentArray, **kwargs):
        with self.tracer.start_as_current_span(
            'encode', context=tracing_context
        ) as span:
            with self.monitor(
                'preprocessing_seconds', 'Time preprocessing the requests'
                docs.tensors = preprocessing(docs)
            with self.monitor(
                'model_inference_seconds', 'Time doing inference the requests'
                docs.embedding = model_inference(docs.tensors)

You can integrate Jaeger or any other distributed tracing tools to collect and visualize request-level and application level service operation attributes. This helps you analyze request-response lifecycle, application behavior and performance.

To use Grafana, download this JSON and import it into Grafana:

Jina: Seamless Container Integration

To trace requests with Jaeger:

Jina: Seamless Container Integration

What cloud-native technology is still challenging to you? Tell us and we'll handle the complexity and make it easy for you.


Join Us

Jina is backed by Jina AI and licensed under Apache-2.0.