#
YAML specificationThis page outlines the specification for valid Executor
YAML files.
Such YAML configurations can be used to generate a Executor
object via load_config()
.
To generate a YAML configuration from a Flow
Python object, use save_config()
.
YAML completion in IDE#
We provide a JSON Schema for your IDE to enable code completion, syntax validation, members listing and displaying help text. Here is a video tutorial to walk you through the setup.
PyCharm users#
Click menu
Preferences
->JSON Schema mappings
;Add a new schema, in the
Schema File or URL
writehttps://api.jina.ai/schemas/latest.json
; selectJSON Schema Version 7
;Add a file path pattern and link it to
*.jaml
or*.jina.yml
or any suffix you commonly used for Jina Flow’s YAML.
VSCode users#
Install the extension:
YAML Language Support by Red Hat
;In IDE-level
settings.json
add:
"yaml.schemas": {
"https://api.jina.ai/schemas/latest.json": ["/*.jina.yml", "/*.jaml"],
}
You can bind Schema to any file suffix you commonly used for Jina Flow’s YAML.
Example YAML#
The following constitutes an example Flow YAML:
jtype: Flow
version: '1'
with:
protocol: http
executors:
# inline Executor YAML
- name: firstexec
uses:
jtype: MyExec
py_modules:
- executor.py
# reference to Executor YAML
- name: secondexec
uses: indexer.yml
workspace: /home/my/workspace
# reference to Executor Python class
- name: thirdexec
uses: CustomExec # located in executor.py
Fields#
jtype
#
String that is always set to “Flow”, indicating the corresponding Python class.
version
#
String indicating the version of the Flow.
with
#
Keyword arguments passed to Flow __init__()
method. You can set Flow-specific arguments and Gateway-specific arguments here:
Flow arguments#
Name |
Description |
Type |
Default |
---|---|---|---|
|
The name of this object. |
|
|
|
The working directory for any IO operations in this object. If not set, then derive from its parent |
|
|
|
The YAML config of the logger used in this object. |
|
|
|
If set, then no log will be emitted from this object. |
|
|
|
If set, then exception stack information will not be added to the log |
|
|
|
The YAML path represents a flow. It can be either a local file path or a URL. |
|
|
|
The map of environment variables that are available inside runtime |
|
|
|
The strategy on those inspect deployments in the flow. |
|
|
Gateway arguments#
Name |
Description |
Type |
Default |
---|---|---|---|
|
The name of this object. |
|
|
|
The working directory for any IO operations in this object. If not set, then derive from its parent |
|
|
|
The YAML config of the logger used in this object. |
|
|
|
If set, then no log will be emitted from this object. |
|
|
|
If set, then exception stack information will not be added to the log |
|
|
|
The timeout in milliseconds of the control request, -1 for waiting forever |
|
|
|
The polling strategy of the Deployment and its endpoints (when |
|
|
|
The config of the executor, it could be one of the followings: |
|
|
|
Dictionary of keyword arguments that will override the |
|
|
|
Dictionary of keyword arguments that will override the |
|
|
|
Dictionary of keyword arguments that will override the |
|
|
|
The customized python modules need to be imported before loading the executor |
|
|
|
The port for input data to bind to, default is a random port between [49152, 65535] |
|
|
|
The host address for binding to, by default it is 0.0.0.0 |
|
|
|
If set, only native Executors is allowed, and the Executor is always run inside WorkerRuntime. |
|
|
|
The type of array |
|
|
|
Dictionary of kwargs arguments that will be passed to the grpc server as options when starting the server, example : {‘grpc.max_send_message_length’: -1} |
|
|
|
Number of requests fetched from the client before feeding into the first Executor. |
|
|
|
The title of this HTTP server. It will be used in automatics docs such as Swagger UI. |
|
|
|
The description of this HTTP server. It will be used in automatics docs such as Swagger UI. |
|
|
|
If set, a CORS middleware is added to FastAPI frontend to allow cross-origin access. |
|
|
|
If set, |
|
|
|
If set, |
|
|
|
A JSON string that represents a map from executor endpoints ( |
|
|
|
Dictionary of kwargs arguments that will be passed to Uvicorn server when starting the server |
|
|
|
the path to the certificate file |
|
|
|
the path to the key file |
|
|
|
If set, /graphql endpoint is added to HTTP interface. |
|
|
|
Communication protocol between server and client. |
|
|
|
The host address of the runtime, by default it is 0.0.0.0. |
|
|
|
If set, respect the http_proxy and https_proxy environment variables. otherwise, it will unset these proxy variables before start. gRPC seems to prefer no proxy |
|
|
|
Routing graph for the gateway |
|
|
|
Dictionary stating which filtering conditions each Executor in the graph requires to receive Documents. |
|
|
|
dictionary JSON with the input addresses of each Deployment |
|
|
|
list JSON disabling the built-in merging mechanism for each Deployment listed |
|
|
|
The compression mechanism used when sending requests from the Head to the WorkerRuntimes. For more details, check https://grpc.github.io/grpc/python/grpc.html#compression. |
|
|
|
The timeout in milliseconds used when sending data requests to Executors, -1 means no timeout, disabled by default |
|
|
|
The runtime class to run inside the Pod |
|
|
|
The timeout in milliseconds of a Pod waits for the runtime to be ready, -1 for waiting forever |
|
|
|
The map of environment variables that are available inside runtime |
|
|
|
The number of shards in the deployment running at the same time. For more details check https://docs.jina.ai/fundamentals/flow/create-flow/#complex-flow-topologies |
|
|
|
The number of replicas in the deployment |
|
|
|
If set, spawn an http server with a prometheus endpoint to expose metrics |
|
|
|
The port on which the prometheus server is exposed, default is a random port between [49152, 65535] |
|
|
|
Number of retries per gRPC call. If <0 it defaults to max(3, num_replicas) |
|
|
|
If set, the current Pod/Deployment can not be further chained, and the next |
|
|
executors
#
Collection of Executors used in the Flow.
Each item in the collection corresponds to on add()
call and specifies one Executor.
All keyword arguments passed to the Flow add()
method can be used here.
Name |
Description |
Type |
Default |
---|---|---|---|
|
The name of this object. |
|
|
|
The working directory for any IO operations in this object. If not set, then derive from its parent |
|
|
|
The YAML config of the logger used in this object. |
|
|
|
If set, then no log will be emitted from this object. |
|
|
|
If set, then exception stack information will not be added to the log |
|
|
|
The timeout in milliseconds of the control request, -1 for waiting forever |
|
|
|
The polling strategy of the Deployment and its endpoints (when |
|
|
|
The config of the executor, it could be one of the followings: |
|
|
|
Dictionary of keyword arguments that will override the |
|
|
|
Dictionary of keyword arguments that will override the |
|
|
|
Dictionary of keyword arguments that will override the |
|
|
|
The customized python modules need to be imported before loading the executor |
|
|
|
The port for input data to bind to, default is a random port between [49152, 65535] |
|
|
|
The host address for binding to, by default it is 0.0.0.0 |
|
|
|
If set, only native Executors is allowed, and the Executor is always run inside WorkerRuntime. |
|
|
|
The type of array |
|
|
|
Dictionary of kwargs arguments that will be passed to the grpc server as options when starting the server, example : {‘grpc.max_send_message_length’: -1} |
|
|
|
The entrypoint command overrides the ENTRYPOINT in Docker image. when not set then the Docker image ENTRYPOINT takes effective. |
|
|
|
Dictionary of kwargs arguments that will be passed to Docker SDK when starting the docker ‘ |
|
|
|
The path on the host to be mounted inside the container. |
|
|
|
This argument allows dockerized Jina executor discover local gpu devices. |
|
|
|
Do not automatically mount a volume for dockerized Executors. |
|
|
|
The host address of the runtime, by default it is 0.0.0.0. |
|
|
|
Do not display the streaming of remote logs on local console |
|
|
|
The files on the host to be uploaded to the remote |
|
|
|
The runtime class to run inside the Pod |
|
|
|
The timeout in milliseconds of a Pod waits for the runtime to be ready, -1 for waiting forever |
|
|
|
The map of environment variables that are available inside runtime |
|
|
|
The number of shards in the deployment running at the same time. For more details check https://docs.jina.ai/fundamentals/flow/create-flow/#complex-flow-topologies |
|
|
|
The number of replicas in the deployment |
|
|
|
If set, spawn an http server with a prometheus endpoint to expose metrics |
|
|
|
The port on which the prometheus server is exposed, default is a random port between [49152, 65535] |
|
|
|
Number of retries per gRPC call. If <0 it defaults to max(3, num_replicas) |
|
|
|
If set, the current Pod/Deployment can not be further chained, and the next |
|
|
|
If set, install |
|
|
|
If set, always pull the latest Hub Executor bundle even it exists on local |
|
|
|
The compression mechanism used when sending requests from the Head to the WorkerRuntimes. For more details, check https://grpc.github.io/grpc/python/grpc.html#compression. |
|
|
|
The address of the uses-before runtime |
|
|
|
The address of the uses-before runtime |
|
|
|
dictionary JSON with a list of connections to configure |
|
|
|
Disable the built-in reduce mechanism, set this if the reduction is to be handled by the Executor connected to this Head |
|
|
|
The timeout in milliseconds used when sending data requests to Executors, -1 means no timeout, disabled by default |
|
|
Variables#
Jina Flow YAMLs support variables and variable substitution according to the Github Actions syntax.
This means that the following variable substitutions are supported:
Environment variables#
Use ${{ ENV.VAR }}
to refer to the environment variable VAR
. You can find all Jina environment variables here.
Context variables#
Use ${{ CONTEXT.VAR }}
to refer to the context variable VAR
.
Context variables can be passed to f.load_config(..., context=...)
in the form of a Python dictionary.
Relative paths#
Use ${{root.path.to.var}}
to refer to the variable var
within the same YAML file, found at the provided path in the file’s structure.
Note that the only difference between environment variable syntax and relative path syntax is the omission of spaces in the latter.