diff --git a/docs/cloud-nativeness/docker-compose.md b/docs/cloud-nativeness/docker-compose.md index fee9e71a587e9..1b76e8d608101 100644 --- a/docs/cloud-nativeness/docker-compose.md +++ b/docs/cloud-nativeness/docker-compose.md @@ -9,7 +9,7 @@ that operates on `Documents`. These `Executors` live in different runtimes depen your Flow. By default, if you are serving your Flow locally they live within processes. Nevertheless, -because Jina is cloud native your Flow can easily manage Executors that live in containers and that are +because Jina-serve is cloud native your Flow can easily manage Executors that live in containers and that are orchestrated by your favorite tools. One of the simplest is Docker Compose which is supported out of the box. You can deploy a Flow with Docker Compose in one line: @@ -24,7 +24,7 @@ flow = Flow(...).add(...).add(...) flow.to_docker_compose_yaml('docker-compose.yml') ``` -Jina generates a `docker-compose.yml` configuration file corresponding with your Flow. You can use this directly with +Jina-serve generates a `docker-compose.yml` configuration file corresponding with your Flow. You can use this directly with Docker Compose, avoiding the overhead of manually defining all of your Flow's services. ````{admonition} Use Docker-based Executors @@ -34,15 +34,15 @@ All Executors in the Flow should be used with `jinaai+docker://...` or `docker:/ ````{admonition} Health check available from 3.1.3 :class: caution -If you use Executors that rely on Docker images built with a version of Jina prior to 3.1.3, remove the +If you use Executors that rely on Docker images built with a version of Jina-serve prior to 3.1.3, remove the health check from the dumped YAML file, otherwise your Docker Compose services will always be "unhealthy." ```` -````{admonition} Matching Jina versions +````{admonition} Matching Jina-serve versions :class: caution If you change the Docker images in your Docker Compose generated file, ensure that all services included in -the Gateway are built with the same Jina version to guarantee compatibility. +the Gateway are built with the same Jina-serve version to guarantee compatibility. ```` ## Example: Index and search text using your own built Encoder and Indexer diff --git a/docs/cloud-nativeness/k8s.md b/docs/cloud-nativeness/k8s.md index 403b6980e76b8..7104e02f06b32 100644 --- a/docs/cloud-nativeness/k8s.md +++ b/docs/cloud-nativeness/k8s.md @@ -7,15 +7,15 @@ kubernetes ``` -Jina is a cloud-native framework and therefore runs natively and easily on Kubernetes. -Deploying a Jina Deploymenr or Flow on Kubernetes is actually the recommended way to use Jina in production. +Jina-serve is a cloud-native framework and therefore runs natively and easily on Kubernetes. +Deploying a Jina-serve Deploymenr or Flow on Kubernetes is actually the recommended way to use Jina-serve in production. A {class}`~jina.Deployment` and {class}`~jina.Flow` are services composed of single or multiple microservices called {class}`~jina.Executor` and {class}`~jina.Gateway`s which natively run in containers. This means that Kubernetes can natively take over the lifetime management of Executors. Deploying a {class}`~jina.Deployment` or `~jina.Flow` on Kubernetes means wrapping these services containers in the appropriate K8s abstraction (Deployment, StatefulSet, and so on), exposing them internally via K8s service and connecting them together by passing the right set of parameters. ```{hint} -This documentation is designed for users who want to **manually** deploy a Jina project on Kubernetes. +This documentation is designed for users who want to **manually** deploy a Jina-serve project on Kubernetes. Check out {ref}`jcloud` if you want a **one-click** solution to deploy and host Jina, leveraging a cloud-native stack of Kubernetes, Prometheus and Grafana, **without worrying about provisioning**. ``` @@ -29,8 +29,8 @@ translation work automatically. ``` This helper function can be called from: -* Jina's Python interface to translate a Flow defined in Python to K8s YAML files -* Jina's CLI interface to export a YAML Flow to K8s YAML files +* Jina-serve's Python interface to translate a Flow defined in Python to K8s YAML files +* Jina-serve's CLI interface to export a YAML Flow to K8s YAML files ```{seealso} More detail in the {ref}`Deployment export documentation` and {ref}`Flow export documentation ` @@ -38,19 +38,19 @@ More detail in the {ref}`Deployment export documentation` for more information about these scaling mechanism For shards, Jina creates one separate Deployment in Kubernetes per Shard. Setting `Deployment(..., shards=num_shards)` is sufficient to create a corresponding Kubernetes configuration. -For replicas, Jina uses [Kubernetes native replica scaling](https://kubernetes.io/docs/tutorials/kubernetes-basics/scale/scale-intro/) and **relies on a service mesh** to load-balance requests between replicas of the same Executor. +For replicas, Jina-serve uses [Kubernetes native replica scaling](https://kubernetes.io/docs/tutorials/kubernetes-basics/scale/scale-intro/) and **relies on a service mesh** to load-balance requests between replicas of the same Executor. Without a service mesh installed in your Kubernetes cluster, all traffic will be routed to the same replica. ````{admonition} See Also @@ -129,7 +129,7 @@ This can be done in a Pythonic way or in YAML: ````{tab} Using Python -You can use {meth}`~jina.Flow.config_gateway` to add `replicas` parameter +You can use {meth}`~jina-serve.Flow.config_gateway` to add `replicas` parameter ```python from jina import Flow @@ -159,8 +159,8 @@ You can use a custom Docker image for the Gateway deployment by setting the envi ```` ## See also -- {ref}`Step by step deployment of a Jina Flow on Kubernetes ` +- {ref}`Step by step deployment of a Jina-serve Flow on Kubernetes ` - {ref}`Export a Flow to Kubernetes ` -- {meth}`~jina.Flow.to_kubernetes_yaml` +- {meth}`~jina-serve.Flow.to_kubernetes_yaml` - {ref}`Deploy a standalone Executor on Kubernetes ` - [Kubernetes Documentation](https://kubernetes.io/docs/home/) diff --git a/docs/cloud-nativeness/kubernetes.md b/docs/cloud-nativeness/kubernetes.md index f9ddf07129e8d..c4d4ae5ad38f5 100644 --- a/docs/cloud-nativeness/kubernetes.md +++ b/docs/cloud-nativeness/kubernetes.md @@ -4,7 +4,7 @@ This how-to will go through deploying a Deployment and a simple Flow using Kubernetes, customizing the Kubernetes configuration to your needs, and scaling Executors using replicas and shards. -Deploying Jina services in Kubernetes is the recommended way to use Jina in production because Kubernetes can easily take over the lifetime management of Executors and Gateways. +Deploying Jina-serve services in Kubernetes is the recommended way to use Jina-serve in production because Kubernetes can easily take over the lifetime management of Executors and Gateways. ```{seelaso} This page is a step by step guide, refer to the {ref}`Kubernetes support documentation ` for more details @@ -12,7 +12,7 @@ This page is a step by step guide, refer to the {ref}`Kubernetes support documen ```{hint} -This guide is designed for users who want to **manually** deploy a Jina project on Kubernetes. +This guide is designed for users who want to **manually** deploy a Jina-serve project on Kubernetes. Check out {ref}`jcloud` if you want a **one-click** solution to deploy and host Jina, leveraging a cloud-native stack of Kubernetes, Prometheus and Grafana, **without worrying about provisioning**. ``` @@ -256,14 +256,14 @@ Just ensure that the Executor is containerized, either by using *'jinaai+docker' Executors `. Next, generate Kubernetes YAML configs from the Flow. Notice, that this step may be a little slow, because [Executor Hub](https://cloud.jina.ai/) may -adapt the image to your Jina and docarray version. +adapt the image to your Jina-serve and docarray version. ```python d.to_kubernetes_yaml('./k8s_deployment', k8s_namespace='custom-namespace') ``` The following file structure will be generated - don't worry if it's slightly different -- there can be -changes from one Jina version to another: +changes from one Jina-serve version to another: ``` . @@ -369,14 +369,14 @@ Executors `. The example Flow here simply encodes and indexes text data using two Executors pushed to the [Executor Hub](https://cloud.jina.ai/). Next, generate Kubernetes YAML configs from the Flow. Notice, that this step may be a little slow, because [Executor Hub](https://cloud.jina.ai/) may -adapt the image to your Jina and docarray version. +adapt the image to your Jina-serve and docarray version. ```python f.to_kubernetes_yaml('./k8s_flow', k8s_namespace='custom-namespace') ``` The following file structure will be generated - don't worry if it's slightly different -- there can be -changes from one Jina version to another: +changes from one Jina-serve version to another: ``` . diff --git a/docs/cloud-nativeness/monitoring.md b/docs/cloud-nativeness/monitoring.md index e0cc45c7c475a..6717b5337bc7b 100644 --- a/docs/cloud-nativeness/monitoring.md +++ b/docs/cloud-nativeness/monitoring.md @@ -3,12 +3,12 @@ ```{admonition} Deprecated :class: caution -The Prometheus-only based feature will soon be deprecated in favor of the OpenTelemetry Setup. Refer to {ref}`OpenTelemetry Setup ` for the details on OpenTelemetry setup for Jina. +The Prometheus-only based feature will soon be deprecated in favor of the OpenTelemetry Setup. Refer to {ref}`OpenTelemetry Setup ` for the details on OpenTelemetry setup for Jina-serve. Refer to the {ref}`OpenTelemetry migration guide ` for updating your existing Prometheus and Grafana configurations. ``` -We recommend the Prometheus/Grafana stack to leverage the metrics exposed by Jina. In this setup, Jina exposes different metrics, and Prometheus scrapes these endpoints, as well as +We recommend the Prometheus/Grafana stack to leverage the metrics exposed by Jina-serve. In this setup, Jina-serve exposes different metrics, and Prometheus scrapes these endpoints, as well as collecting, aggregating, and storing the metrics. External entities (like Grafana) can access these aggregated metrics via the query language [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/) and let users visualize the metrics with dashboards. @@ -28,7 +28,7 @@ In this guide, we deploy the Prometheus/Grafana stack and use it to monitor a Fl One challenge of monitoring a {class}`~jina.Flow` is communicating its different metrics endpoints to Prometheus. Fortunately, the [Prometheus operator for Kubernetes](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/getting-started.md) makes this fairly easy because it can automatically discover new metrics endpoints to scrape. -We recommend deploying your Jina Flow on Kubernetes to leverage the full potential of the monitoring feature because: +We recommend deploying your Jina-serve Flow on Kubernetes to leverage the full potential of the monitoring feature because: * The Prometheus operator can automatically discover new endpoints to scrape. * You can extend monitoring with the rich built-in Kubernetes metrics. diff --git a/docs/cloud-nativeness/opentelemetry.md b/docs/cloud-nativeness/opentelemetry.md index 49f6f308e7b73..ff8bda64346ee 100644 --- a/docs/cloud-nativeness/opentelemetry.md +++ b/docs/cloud-nativeness/opentelemetry.md @@ -12,11 +12,11 @@ monitoring Prometheus-only based metrics collection will soon be deprecated. Refer to {ref}`Monitor with Prometheus and Grafana ` for the old setup. ``` -There are two major setups required to visualize/monitor your application's signals using [OpenTelemetry](https://opentelemetry.io). The first setup is covered by Jina which integrates the [OpenTelemetry API and SDK](https://opentelemetry-python.readthedocs.io/en/stable/api/index.html) at the application level. The {ref}`Flow Instrumentation ` page covers in detail the steps required to enable OpenTelemetry in a Flow. A {class}`~jina.Client` can also be instrumented which is documented in the {ref}`Client Instrumentation ` section. +There are two major setups required to visualize/monitor your application's signals using [OpenTelemetry](https://opentelemetry.io). The first setup is covered by Jina-serve which integrates the [OpenTelemetry API and SDK](https://opentelemetry-python.readthedocs.io/en/stable/api/index.html) at the application level. The {ref}`Flow Instrumentation ` page covers in detail the steps required to enable OpenTelemetry in a Flow. A {class}`~jina.Client` can also be instrumented which is documented in the {ref}`Client Instrumentation ` section. This section covers the OpenTelemetry infrastructure setup required to collect, store and visualize the traces and metrics data exported by the Pods. This setup is the user's responsibility, and this section only serves as the initial/introductory guide to running OpenTelemetry infrastructure components. -Since OpenTelemetry is open source and is mostly responsible for the API standards and specification, various providers implement the specification. This section follows the default recommendations from the OpenTelemetry documentation that also fits into the Jina implementations. +Since OpenTelemetry is open source and is mostly responsible for the API standards and specification, various providers implement the specification. This section follows the default recommendations from the OpenTelemetry documentation that also fits into the Jina-serve implementations. ## Exporting traces and metrics data @@ -26,12 +26,12 @@ The push/export-based mechanism also allows the application to start pushing dat You can configure the exporter backend host and port using the `traces_exporter_host`, `traces_exporter_port`, `metrics_exporter_host` and `metrics_exporter_port`. Even though the Collector is metric data-type agnostic (it accepts any type of OpenTelemetry API data model), we provide separate configuration for Tracing and Metrics to give you more flexibility in choosing infrastructure components. -Jina's default exporter implementation is `OTLPSpanExporter` and `OTLPMetricExporter`. The exporters also use the gRPC data transfer protocol. The following environment variables can be used to further configure the exporter client based on your requirements. The full list of exporter related environment variables are documented by the [PythonSDK library](https://opentelemetry-python.readthedocs.io/en/latest/exporter/otlp/otlp.html). Apart from `OTEL_EXPORTER_OTLP_PROTOCOL` and `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, you can use all other library version specific environment variables to configure the exporter clients. +Jina-serve's default exporter implementation is `OTLPSpanExporter` and `OTLPMetricExporter`. The exporters also use the gRPC data transfer protocol. The following environment variables can be used to further configure the exporter client based on your requirements. The full list of exporter related environment variables are documented by the [PythonSDK library](https://opentelemetry-python.readthedocs.io/en/latest/exporter/otlp/otlp.html). Apart from `OTEL_EXPORTER_OTLP_PROTOCOL` and `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, you can use all other library version specific environment variables to configure the exporter clients. ## Collector -The [Collector](https://opentelemetry.io/docs/collector/) is a huge ecosystem of components that support features like scraping, collecting, processing and further exporting data to storage backends. The collector itself can also expose endpoints to allow scraping data. We recommend reading the official documentation to understand the the full set of features and configuration required to run a Collector. Read the below section to understand the minimum number of components and the respective configuration required for operating with Jina. +The [Collector](https://opentelemetry.io/docs/collector/) is a huge ecosystem of components that support features like scraping, collecting, processing and further exporting data to storage backends. The collector itself can also expose endpoints to allow scraping data. We recommend reading the official documentation to understand the the full set of features and configuration required to run a Collector. Read the below section to understand the minimum number of components and the respective configuration required for operating with Jina-serve. We recommend using the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) from the contrib repository. We also use: - [Jaeger](https://www.jaegertracing.io) for collecting traces, visualizing tracing data and alerting based on tracing data. diff --git a/docs/concepts/client/callbacks.md b/docs/concepts/client/callbacks.md index dcd2137f15321..9daaba1a7cfc7 100644 --- a/docs/concepts/client/callbacks.md +++ b/docs/concepts/client/callbacks.md @@ -3,7 +3,7 @@ After performing {meth}`~jina.clients.mixin.PostMixin.post`, you may want to further process the obtained results. -For this purpose, Jina implements a promise-like interface, letting you specify three kinds of callback functions: +For this purpose, Jina-serve implements a promise-like interface, letting you specify three kinds of callback functions: - `on_done` is executed while streaming, after successful completion of each request - `on_error` is executed while streaming, whenever an error occurs in each request @@ -17,12 +17,12 @@ For example, a `SIGKILL` from the client OS during the handling of the request, will not trigger the callback. -Callback functions in Jina expect a `Response` of the type {class}`~jina.types.request.data.DataRequest`, which contains resulting Documents, +Callback functions in Jina-serve expect a `Response` of the type {class}`~jina.types.request.data.DataRequest`, which contains resulting Documents, parameters, and other information. ## Handle DataRequest in callbacks -`DataRequest`s are objects that are sent by Jina internally. Callback functions process DataRequests, and `client.post()` +`DataRequest`s are objects that are sent by Jina-serve internally. Callback functions process DataRequests, and `client.post()` can return DataRequests. `DataRequest` objects can be seen as a container for data relevant for a given request, it contains the following fields: diff --git a/docs/concepts/client/index.md b/docs/concepts/client/index.md index 4dcab70076794..597a6037f3d0f 100644 --- a/docs/concepts/client/index.md +++ b/docs/concepts/client/index.md @@ -66,7 +66,7 @@ with Flow(port=1234, protocol='grpc') as f: The Client has to specify the followings parameters to match the Flow and how it was set up: * the `protocol` it needs to use to communicate with the Flow * the `host` and the `port` as exposed by the Flow -* if it needs to use `TLS` encryption (to connect to a {class}`~jina.Flow` that has been {ref}`configured to use TLS ` in combination with gRPC, http, or websocket) +* if it needs to use `TLS` encryption (to connect to a {class}`~jina-serve.Flow` that has been {ref}`configured to use TLS ` in combination with gRPC, http, or websocket) ````{Hint} Default port @@ -186,7 +186,7 @@ c.post( (client-compress)= ## Enable compression -If the communication to the Gateway is via gRPC, you can pass `compression` parameter to {meth}`~jina.clients.mixin.PostMixin.post` to benefit from [gRPC compression](https://grpc.github.io/grpc/python/grpc.html#compression) methods. +If the communication to the Gateway is via gRPC, you can pass `compression` parameter to {meth}`~jina-serve.clients.mixin.PostMixin.post` to benefit from [gRPC compression](https://grpc.github.io/grpc/python/grpc.html#compression) methods. The supported choices are: None, `gzip` and `deflate`. @@ -212,7 +212,7 @@ One can also specify the compression of the internal communication {ref}`as desc ## Simple profiling of the latency -Before sending any real data, you can test the connectivity and network latency by calling the {meth}`~jina.clients.mixin.ProfileMixin.profiling` method: +Before sending any real data, you can test the connectivity and network latency by calling the {meth}`~jina-serve.clients.mixin.ProfileMixin.profiling` method: ```python from jina import Client diff --git a/docs/concepts/client/instrumentation.md b/docs/concepts/client/instrumentation.md index 890bca94700b2..7f4eedfac7a56 100644 --- a/docs/concepts/client/instrumentation.md +++ b/docs/concepts/client/instrumentation.md @@ -55,5 +55,5 @@ You can find more about instrumentation from the resources below: - [Tracing in OpenTelemetry](https://opentelemetry.io/docs/concepts/signals/traces/) - {ref}`Instrumenting a Flow ` -- {ref}`Deploying and using OpenTelemetry in Jina ` +- {ref}`Deploying and using OpenTelemetry in Jina-serve ` diff --git a/docs/concepts/client/send-graphql-mutation.md b/docs/concepts/client/send-graphql-mutation.md index 826475a0caf43..4b5735bb65d56 100644 --- a/docs/concepts/client/send-graphql-mutation.md +++ b/docs/concepts/client/send-graphql-mutation.md @@ -1,6 +1,6 @@ # Send GraphQL Mutation -If the Flow is configured with GraphQL endpoint, then you can use Jina {class}`~jina.Client` {meth}`~jina.clients.mixin.MutateMixin.mutate` to fetch data via GraphQL mutations: +If the Flow is configured with GraphQL endpoint, then you can use Jina-serve {class}`~jina.Client` {meth}`~jina.clients.mixin.MutateMixin.mutate` to fetch data via GraphQL mutations: ````{admonition} Only available for docarray<0.30 :class: note diff --git a/docs/concepts/client/send-receive-data.md b/docs/concepts/client/send-receive-data.md index c491d79ac135e..627124dce9a21 100644 --- a/docs/concepts/client/send-receive-data.md +++ b/docs/concepts/client/send-receive-data.md @@ -98,7 +98,7 @@ Hence, `deployment.post()` and `flow.post()` are not recommended outside of test (request-size-client)= ## Send data in batches -Especially during indexing, a Client can send up to thousands or millions of Documents to a {class}`~jina.Flow`. +Especially during indexing, a Client can send up to thousands or millions of Documents to a {class}`~jina-serve.Flow`. Those Documents are internally batched into a `Request`, providing a smaller memory footprint and faster response times thanks to {ref}`callback functions `. @@ -117,8 +117,8 @@ with Deployment() as dep: ## Send data asynchronously -There is an async version of the Python Client which works with {meth}`~jina.clients.mixin.PostMixin.post` and -{meth}`~jina.clients.mixin.MutateMixin.mutate`. +There is an async version of the Python Client which works with {meth}`~jina-serve.clients.mixin.PostMixin.post` and +{meth}`~jina-serve.clients.mixin.MutateMixin.mutate`. While the standard `Client` is also asynchronous under the hood, its async version exposes this fact to the outside world, @@ -165,8 +165,8 @@ class DummyExecutor(Executor): ## Send data to specific Executors -Usually a {class}`~jina.Flow` will send each request to all {class}`~jina.Executor`s with matching endpoints as -configured. But the {class}`~jina.Client` also allows you to only target specific Executors in a Flow using +Usually a {class}`~jina-serve.Flow` will send each request to all {class}`~jina-serve.Executor`s with matching endpoints as +configured. But the {class}`~jina-serve.Client` also allows you to only target specific Executors in a Flow using the `target_executor` keyword. The request will then only be processed by the Executors which match the provided target_executor regex. Its usage is shown in the listing below. @@ -209,7 +209,7 @@ Executor. The Flow with **gRPC** protocol implements the unary and the streaming RPC lifecycle for communicating with the clients. When sending more than one request using the batching or the iterator mechanism, the RPC lifecycle for the -{meth}`~jina.clients.mixin.PostMixin.post` method can be controlled using the `stream` boolean method argument. By +{meth}`~jina-serve.clients.mixin.PostMixin.post` method can be controlled using the `stream` boolean method argument. By default the stream option is set to `True` which uses the streaming RPC to send the data to the Flow. If the stream option is set to `False`, the unary RPC is used to send the data to the Flow. Both RPC lifecycles are implemented to provide the flexibility for the clients. @@ -247,7 +247,7 @@ used to overwrite the default options. The default **gRPC** options are: # allow grpc pings from client without data every 4 seconds ``` -If the `max_attempts` is greater than 1 on the {meth}`~jina.clients.mixin.PostMixin.post` method, +If the `max_attempts` is greater than 1 on the {meth}`~jina-serve.clients.mixin.PostMixin.post` method, the `grpc.service_config` option will not be applied since the retry options will be configured internally. @@ -261,9 +261,9 @@ Refer to the {ref}`Configure Executor gRPC options `: gRPC, HTTP, or WebSocket. +Jina-serve Flows can use one of {ref}`three protocols `: gRPC, HTTP, or WebSocket. Only Flows that use HTTP can be accessed via the methods described below. ``` @@ -271,7 +271,7 @@ You should finally be able to communicate with your Flow using the gRPC protocol This article does not serve as the introduction to GraphQL. If you are not already familiar with GraphQL, we recommend you learn more about GraphQL from the [official documentation](https://graphql.org/learn/). -You may also want to learn about [Strawberry](https://strawberry.rocks/), the library that powers Jina's GraphQL support. +You may also want to learn about [Strawberry](https://strawberry.rocks/), the library that powers Jina-serve's GraphQL support. ```` Jina Flows that use the HTTP protocol can also provide a GraphQL API, which is located behind the `/graphql` endpoint. GraphQL has the advantage of letting you define your own response schema, which means that only the fields you require @@ -305,7 +305,7 @@ While you can always use the Python client to stream requests like any other pro You can use the same set of arguments as {ref}`HTTP ` in the payload. We use [subprotocols](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#subprotocols) to separate streaming JSON vs bytes. -The Flow defaults to `json` if you don't specify a sub-protocol while establishing the connection (Our Python client uses `bytes` streaming by using [jina.proto](../../proto/docs.md) definition). +The Flow defaults to `json` if you don't specify a sub-protocol while establishing the connection (Our Python client uses `bytes` streaming by using [jina-serve.proto](../../proto/docs.md) definition). ````{Hint} diff --git a/docs/concepts/jcloud/configuration.md b/docs/concepts/jcloud/configuration.md index 79f6664161c73..8a859df0ed56e 100644 --- a/docs/concepts/jcloud/configuration.md +++ b/docs/concepts/jcloud/configuration.md @@ -1,7 +1,7 @@ (jcloud-configuration)= # {octicon}`file-code` Configuration -JCloud extends Jina's {ref}`Flow YAML specification` by introducing the special field `jcloud`. This lets you define resources and scaling policies for each Executor and Gateway. +JCloud extends Jina-serve's {ref}`Flow YAML specification` by introducing the special field `jcloud`. This lets you define resources and scaling policies for each Executor and Gateway. Here's a Flow with two Executors that have specific resource needs: `indexer` requires a 10 GB `ebs` disk, whereas `encoder` requires a G4 instance, which implies that two cores and 4 GB RAM are used. See the below sections for further information about instance types. diff --git a/docs/concepts/jcloud/index.md b/docs/concepts/jcloud/index.md index 8df998fa03c31..632d25c337b57 100644 --- a/docs/concepts/jcloud/index.md +++ b/docs/concepts/jcloud/index.md @@ -18,7 +18,7 @@ configuration :width: 0 % ``` -After building a Jina project, the next step is to deploy and host it on the cloud. [Jina AI Cloud](https://cloud.jina.ai/) is Jina's reliable, scalable and production-ready cloud-hosting solution that manages your project lifecycle without surprises or hidden development costs. +After building a Jina-serve project, the next step is to deploy and host it on the cloud. [Jina AI Cloud](https://cloud.jina.ai/) is Jina-serve's reliable, scalable and production-ready cloud-hosting solution that manages your project lifecycle without surprises or hidden development costs. ```{tip} Are you ready to unlock the power of AI with Jina AI Cloud? Take a look at our [pricing options](https://cloud.jina.ai/pricing) now! @@ -31,7 +31,7 @@ In addition to deploying Flows, `jcloud` supports the creation of secrets and jo Jina AI Cloud provides a CLI that you can use via `jina cloud` from the terminal (or `jcloud` or simply `jc` for minimalists.) ````{hint} -You can also install just the JCloud CLI without installing the Jina package. +You can also install just the JCloud CLI without installing the Jina-serve package. ```bash pip install jcloud diff --git a/docs/concepts/orchestration/add-executors.md b/docs/concepts/orchestration/add-executors.md index 545a6c7e2bed5..5fcf13f701ffa 100644 --- a/docs/concepts/orchestration/add-executors.md +++ b/docs/concepts/orchestration/add-executors.md @@ -58,7 +58,7 @@ f = Flow(extra_search_paths=['../executor']).add(uses='config1.yml').add(uses='c (flow-configure-executors)= ## Configure Executors -You can set and override {class}`~jina.Executor` configuration when adding them to an Orchestration. +You can set and override {class}`~jina-serve.Executor` configuration when adding them to an Orchestration. This example shows how to start a Flow with an Executor using the Python API: diff --git a/docs/concepts/orchestration/deployment.md b/docs/concepts/orchestration/deployment.md index a8e61a6784b62..8be2bcd2a9e84 100644 --- a/docs/concepts/orchestration/deployment.md +++ b/docs/concepts/orchestration/deployment.md @@ -166,14 +166,14 @@ dep.save_config('deployment.yml') ## Start and stop -When a {class}`~jina.Deployment` starts, all the replicated Executors will start as well, making it possible to {ref}`reach the service through its API `. +When a {class}`~jina-serve.Deployment` starts, all the replicated Executors will start as well, making it possible to {ref}`reach the service through its API `. There are three ways to start a Deployment: In Python, from a YAML file, or from the terminal. - Generally in Python: use Deployment as a context manager. - As an entrypoint from terminal: use `Jina CLI ` and a Deployment YAML file. - As an entrypoint from Python code: use Deployment as a context manager inside `if __name__ == '__main__'` -- No context manager, manually call {meth}`~jina.Deployment.start` and {meth}`~jina.Deployment.close`. +- No context manager, manually call {meth}`~jina-serve.Deployment.start` and {meth}`~jina-serve.Deployment.close`. ````{tab} General in Python ```python @@ -187,7 +187,7 @@ with dep: The statement `with dep:` starts the Deployment, and exiting the indented `with` block stops the Deployment, including its Executor. ```` -````{tab} Jina CLI entrypoint +````{tab} Jina-serve CLI entrypoint ```bash jina deployment --uses deployment.yml ``` @@ -257,7 +257,7 @@ with dep: ```` ````{tab} YAML ```shell -jina deployment --uses deployment.yml +jina-serve deployment --uses deployment.yml ``` ```` @@ -270,7 +270,7 @@ In this case, the Deployment can be stopped by interrupting the thread or proces Alternatively, a `multiprocessing` or `threading` `Event` object can be passed to `.block()`, which stops the Deployment once set. ```python -from jina import Deployment +from jina-serve import Deployment import threading @@ -301,7 +301,7 @@ A Deployment YAML can be exported as a Docker Compose YAML or Kubernetes YAML bu ````{tab} Python ```python -from jina import Deployment +from jina-serve import Deployment dep = Deployment() dep.to_docker_compose_yaml() @@ -309,20 +309,20 @@ dep.to_docker_compose_yaml() ```` ````{tab} Terminal ```shell -jina export docker-compose deployment.yml docker-compose.yml +jina-serve export docker-compose deployment.yml docker-compose.yml ``` ```` This will generate a single `docker-compose.yml` file. -For advanced utilization of Docker Compose with Jina, refer to {ref}`How to ` +For advanced utilization of Docker Compose with Jina-serve, refer to {ref}`How to ` (deployment-kubernetes-export)= ### Kubernetes ````{tab} Python ```python -from jina import Deployment +from jina-serve import Deployment dep = Deployment dep.to_kubernetes_yaml('dep_k8s_configuration') @@ -330,13 +330,13 @@ dep.to_kubernetes_yaml('dep_k8s_configuration') ```` ````{tab} Terminal ```shell -jina export kubernetes deployment.yml ./my-k8s +jina-serve export kubernetes deployment.yml ./my-k8s ``` ```` The generated folder can be used directly with `kubectl` to deploy the Deployment to an existing Kubernetes cluster. -For advanced utilisation of Kubernetes with Jina please refer to {ref}`How to ` +For advanced utilisation of Kubernetes with Jina-serve please refer to {ref}`How to ` ```{tip} Based on your local Jina version, Executor Hub may rebuild the Docker image during the YAML generation process. @@ -345,7 +345,7 @@ If you do not wish to rebuild the image, set the environment variable `JINA_HUB_ ```{tip} If an Executor requires volumes to be mapped to persist data, Jina will create a StatefulSet for that Executor instead of a Deployment. -You can control the access mode, storage class name and capacity of the attached Persistent Volume Claim by using {ref}`Jina environment variables ` +You can control the access mode, storage class name and capacity of the attached Persistent Volume Claim by using {ref}`Jina environment variables ` `JINA_K8S_ACCESS_MODES`, `JINA_K8S_STORAGE_CLASS_NAME` and `JINA_K8S_STORAGE_CAPACITY`. Only the first volume will be considered to be mounted. ``` @@ -355,7 +355,7 @@ For more in-depth guides on deployment, check our how-tos for {ref}`Docker compo ``` ```{caution} -The port or ports arguments are ignored when calling the Kubernetes YAML, Jina will start the services binding to the ports 8080, except when multiple protocols +The port or ports arguments are ignored when calling the Kubernetes YAML, Jina-serve will start the services binding to the ports 8080, except when multiple protocols need to be served when the consecutive ports (8081, ...) will be used. This is because the Kubernetes service will direct the traffic from you and it is irrelevant to the services around because in Kubernetes services communicate via the service names irrespective of the internal port. ``` @@ -363,7 +363,7 @@ to the services around because in Kubernetes services communicate via the servic (logging-configuration)= ## Logging -The default {class}`jina.logging.logger.JinaLogger` uses rich console logging that writes to the system console. The `log_config` argument can be used to pass in a string of the pre-configured logging configuration names in Jina or the absolute YAML file path of the custom logging configuration. For most cases, the default logging configuration sufficiently covers local, Docker and Kubernetes environments. +The default {class}`jina.logging.logger.JinaLogger` uses rich console logging that writes to the system console. The `log_config` argument can be used to pass in a string of the pre-configured logging configuration names in Jina-serve or the absolute YAML file path of the custom logging configuration. For most cases, the default logging configuration sufficiently covers local, Docker and Kubernetes environments. Custom logging handlers can be configured by following the Python official [Logging Cookbook](https://docs.python.org/3/howto/logging-cookbook.html#logging-cookbook) examples. An example custom logging configuration file defined in a YAML file `logging.json.yml` is: @@ -381,7 +381,7 @@ The logging configuration can be used as follows: ````{tab} Python ```python -from jina import Deployment +from jina-serve import Deployment dep = Deployment(log_config='./logging.json.yml') ``` @@ -408,7 +408,7 @@ gRPC is the default protocol used by a Deployment to expose Executors to the out HTTP can be used for a stand-alone Deployment (without being part of a Flow), which allows external services to connect via REST. ```python -from jina import Deployment, Executor, requests +from jina-serve import Deployment, Executor, requests from docarray import DocList from docarray.documents import TextDoc @@ -470,5 +470,5 @@ The most important methods of the `Deployment` object are the following: | {meth}`~jina.clients.mixin.PostMixin.post()` | Sends requests to the Deployment API. | | {meth}`~jina.Deployment.block()` | Blocks execution until the program is terminated. This is useful to keep the Deployment alive so it can be used from other places (clients, etc). | | {meth}`~jina.Deployment.to_docker_compose_yaml()` | Generates a Docker-Compose file listing all Executors as services. | -| {meth}`~jina.Deployment.to_kubernetes_yaml()` | Generates Kubernetes configuration files in ``. Based on your local Jina version, Executor Hub may rebuild the Docker image during the YAML generation process. If you do not wish to rebuild the image, set the environment variable `JINA_HUB_NO_IMAGE_REBUILD`. | +| {meth}`~jina.Deployment.to_kubernetes_yaml()` | Generates Kubernetes configuration files in ``. Based on your local Jina-serve version, Executor Hub may rebuild the Docker image during the YAML generation process. If you do not wish to rebuild the image, set the environment variable `JINA_HUB_NO_IMAGE_REBUILD`. | | {meth}`~jina.clients.mixin.HealthCheckMixin.is_deployment_ready()` | Check if the Deployment is ready to process requests. Returns a boolean indicating the readiness. | diff --git a/docs/concepts/orchestration/flow.md b/docs/concepts/orchestration/flow.md index 00fcf38395e91..1de1a3a5b2702 100644 --- a/docs/concepts/orchestration/flow.md +++ b/docs/concepts/orchestration/flow.md @@ -159,14 +159,14 @@ Exceptions raised inside the `with f:` block will close the Flow context manager ## Start and stop -When a {class}`~jina.Flow` starts, all included Executors (single for a Deployment, multiple for a Flow) will start as well, making it possible to {ref}`reach the service through its API `. +When a {class}`~jina-serve.Flow` starts, all included Executors (single for a Deployment, multiple for a Flow) will start as well, making it possible to {ref}`reach the service through its API `. There are three ways to start an Flow: In Python, from a YAML file, or from the terminal. - Generally in Python: use Deployment or Flow as a context manager in Python. - As an entrypoint from terminal: use `Jina CLI ` and a Flow YAML file. - As an entrypoint from Python code: use Flow as a context manager inside `if __name__ == '__main__'` -- No context manager: manually call {meth}`~jina.Flow.start` and {meth}`~jina.Flow.close`. +- No context manager: manually call {meth}`~jina-serve.Flow.start` and {meth}`~jina-serve.Flow.close`. ````{tab} General in Python ```python @@ -179,7 +179,7 @@ with f: ``` ```` -````{tab} Jina CLI entrypoint +````{tab} Jina-serve CLI entrypoint ```bash jina flow --uses flow.yml ``` @@ -353,12 +353,12 @@ The generated folder can be used directly with `kubectl` to deploy the Flow to a For advanced utilisation of Kubernetes with Jina please refer to {ref}`How to ` ```{tip} -Based on your local Jina version, Executor Hub may rebuild the Docker image during the YAML generation process. +Based on your local Jina-serve version, Executor Hub may rebuild the Docker image during the YAML generation process. If you do not wish to rebuild the image, set the environment variable `JINA_HUB_NO_IMAGE_REBUILD`. ``` ```{tip} -If an Executor requires volumes to be mapped to persist data, Jina will create a StatefulSet for that Executor instead of a Deployment. +If an Executor requires volumes to be mapped to persist data, Jina-serve will create a StatefulSet for that Executor instead of a Deployment. You can control the access mode, storage class name and capacity of the attached Persistent Volume Claim by using {ref}`Jina environment variables ` `JINA_K8S_ACCESS_MODES`, `JINA_K8S_STORAGE_CLASS_NAME` and `JINA_K8S_STORAGE_CAPACITY`. Only the first volume will be considered to be mounted. ``` @@ -381,11 +381,11 @@ to the services around because in Kubernetes services communicate via the servic This section is for Flow-specific considerations when working with Executors. Check more information on {ref}`working with Executors `. ``` -A {class}`~jina.Flow` orchestrates its {class}`~jina.Executor`s as a graph and sends requests to all Executors in the order specified by {meth}`~jina.Flow.add` or listed in {ref}`a YAML file`. +A {class}`~jina-serve.Flow` orchestrates its {class}`~jina-serve.Executor`s as a graph and sends requests to all Executors in the order specified by {meth}`~jina-serve.Flow.add` or listed in {ref}`a YAML file`. When you start a Flow, Executors always run in **separate processes**. Multiple Executors run in **different processes**. Multiprocessing is the lowest level of separation when you run a Flow locally. When running a Flow on Kubernetes, Docker Swarm, {ref}`jcloud`, different Executors run in different containers, pods or instances. -Executors can be added into a Flow with {meth}`~jina.Flow.add`. +Executors can be added into a Flow with {meth}`~jina-serve.Flow.add`. ```python from jina import Flow @@ -393,7 +393,7 @@ from jina import Flow f = Flow().add() ``` -This adds an "empty" Executor called {class}`~jina.serve.executors.BaseExecutor` to the Flow. This Executor (without any parameters) performs no actions. +This adds an "empty" Executor called {class}`~jina-serve.serve.executors.BaseExecutor` to the Flow. This Executor (without any parameters) performs no actions. ```{figure} images/no-op-flow.svg :scale: 70% @@ -434,7 +434,7 @@ More Flow YAML specifications can be found in {ref}`Flow YAML Specification`. Based on your local Jina and docarray versions, Executor Hub may rebuild the Docker image during the YAML generation process. If you do not wish to rebuild the image, set the environment variable `JINA_HUB_NO_IMAGE_REBUILD`. | -| {meth}`~jina.clients.mixin.HealthCheckMixin.is_flow_ready()` | Check if the Flow is ready to process requests. Returns a boolean indicating the readiness. | +| {meth}`~jina-serve.Flow.plot()` | Visualizes the Flow. Helpful for building complex pipelines. | +| {meth}`~jina-serve.clients.mixin.PostMixin.post()` | Sends requests to the Flow API. | +| {meth}`~jina-serve.Flow.block()` | Blocks execution until the program is terminated. This is useful to keep the Flow alive so it can be used from other places (clients, etc). | +| {meth}`~jina-serve.Flow.to_docker_compose_yaml()` | Generates a Docker-Compose file listing all Executors as services. | +| {meth}`~jina-serve.Flow.to_kubernetes_yaml()` | Generates Kubernetes configuration files in ``. Based on your local Jina and docarray versions, Executor Hub may rebuild the Docker image during the YAML generation process. If you do not wish to rebuild the image, set the environment variable `JINA_HUB_NO_IMAGE_REBUILD`. | +| {meth}`~jina-serve.clients.mixin.HealthCheckMixin.is_flow_ready()` | Check if the Flow is ready to process requests. Returns a boolean indicating the readiness. | diff --git a/docs/concepts/orchestration/handle-exceptions.md b/docs/concepts/orchestration/handle-exceptions.md index e89db49d876bd..f5864a4aa2e01 100644 --- a/docs/concepts/orchestration/handle-exceptions.md +++ b/docs/concepts/orchestration/handle-exceptions.md @@ -1,9 +1,9 @@ (flow-error-handling)= # Handle Exceptions -When building a complex solution, things sometimes go wrong. Jina does its best to recover from failures, handle them gracefully, and report useful failure information to the user. +When building a complex solution, things sometimes go wrong. Jina-serve does its best to recover from failures, handle them gracefully, and report useful failure information to the user. -The following outlines (more or less) common failure cases, and explains how Jina responds to each. +The following outlines (more or less) common failure cases, and explains how Jina-serve responds to each. ## Executor errors @@ -77,7 +77,7 @@ A Kubernetes service mesh can enable load balancing, and thus retries, between a While Jina supports any service mesh, the output of `f.to_kubernetes_yaml()` already includes the necessary annotations for [Linkerd](https://linkerd.io/). ```` -If a service mesh is installed alongside Jina in the Kubernetes cluster, the following retry policy applies for each Executor: +If a service mesh is installed alongside Jina-serve in the Kubernetes cluster, the following retry policy applies for each Executor: - Try the request at least three times, or until it succeeds - Distribute the requests to the replicas according to the service mesh's configuration diff --git a/docs/concepts/orchestration/index.md b/docs/concepts/orchestration/index.md index 367011904a78d..3b86d1182bae2 100644 --- a/docs/concepts/orchestration/index.md +++ b/docs/concepts/orchestration/index.md @@ -1,7 +1,7 @@ (orchestration)= # {fas}`network-wired` Orchestration -As seen in the {ref}`architecture overview `, Jina is organized in different layers. +As seen in the {ref}`architecture overview `, Jina-serve is organized in different layers. The Orchestration layer is composed of concepts that let you orchestrate, serve and scale your Executors with ease. diff --git a/docs/concepts/orchestration/instrumentation.md b/docs/concepts/orchestration/instrumentation.md index 95e413f67140e..fede90b27bf25 100644 --- a/docs/concepts/orchestration/instrumentation.md +++ b/docs/concepts/orchestration/instrumentation.md @@ -70,20 +70,20 @@ Because not all Pods have the same role, they expose different kinds of traces: | Operation name | Description | |-------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------| -| `/jina.JinaRPC/Call` | Traces the request from the client to the Gateway server. | -| `/jina.JinaSingleDataRequestRPC/process_single_data` | Internal operation for the request originating from the Gateway to the target Head or Executor. | +| `/jina-serve.JinaRPC/Call` | Traces the request from the client to the Gateway server. | +| `/jina-serve.JinaSingleDataRequestRPC/process_single_data` | Internal operation for the request originating from the Gateway to the target Head or Executor. | #### Head Pods | Operation name | Description | |-------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------| -| `/jina.JinaSingleDataRequestRPC/process_single_data` | Internal operation for the request originating from the Gateway to the target Head. Another child span is created for the request originating from the Head to the Executor.| +| `/jina-serve.JinaSingleDataRequestRPC/process_single_data` | Internal operation for the request originating from the Gateway to the target Head. Another child span is created for the request originating from the Head to the Executor.| #### Executor Pods | Operation name | Description | |-------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------| -| `/jina.JinaSingleDataRequestRPC/process_single_data` | Executor server operation for the request originating from the Gateway/Head to the Executor request handler. | +| `/jina-serve.JinaSingleDataRequestRPC/process_single_data` | Executor server operation for the request originating from the Gateway/Head to the Executor request handler. | | `/endpoint` | Internal operation for the request originating from the Executor request handler to the target `@requests(=/endpoint)` method. The `endpoint` will be `default` if no endpoint name is provided. | ```{seealso} @@ -203,6 +203,6 @@ Beyond the default metrics outlined above, you can also define {ref}`custom metr ## See also - {ref}`Defining custom traces and metrics in an Executor ` -- {ref}`How to deploy and use OpenTelemetry in Jina ` +- {ref}`How to deploy and use OpenTelemetry in Jina-serve ` - [Tracing in OpenTelemetry](https://opentelemetry.io/docs/concepts/signals/traces/) - [Metrics in OpenTelemetry](https://opentelemetry.io/docs/concepts/signals/metrics/) \ No newline at end of file diff --git a/docs/concepts/orchestration/readiness.md b/docs/concepts/orchestration/readiness.md index 49dcae47a1677..0af6bd5fac58c 100644 --- a/docs/concepts/orchestration/readiness.md +++ b/docs/concepts/orchestration/readiness.md @@ -43,7 +43,7 @@ False ``` ```` -## Via Jina Client +## Via Jina-serve Client @@ -95,7 +95,7 @@ True `````{tab} Deployment ```python -from jina import Deployment +from jina-serve import Deployment dep = Deployment(port=12345) @@ -103,24 +103,24 @@ with dep: dep.block() ``` ```bash -jina ping executor grpc://localhost:12345 +jina-serve ping executor grpc://localhost:12345 ``` ````{tab} Success ```text -INFO JINA@92877 ping grpc://localhost:12345 at 0 round... [09/08/22 12:58:13] -INFO JINA@92877 ping grpc://localhost:12345 at 0 round takes 0 seconds (0.04s) -INFO JINA@92877 ping grpc://localhost:12345 at 1 round... [09/08/22 12:58:14] -INFO JINA@92877 ping grpc://localhost:12345 at 1 round takes 0 seconds (0.01s) -INFO JINA@92877 ping grpc://localhost:12345 at 2 round... [09/08/22 12:58:15] -INFO JINA@92877 ping grpc://localhost:12345 at 2 round takes 0 seconds (0.01s) -INFO JINA@92877 avg. latency: 24 ms [09/08/22 12:58:16] +INFO Jina-serve@92877 ping grpc://localhost:12345 at 0 round... [09/08/22 12:58:13] +INFO Jina-serve@92877 ping grpc://localhost:12345 at 0 round takes 0 seconds (0.04s) +INFO Jina-serve@92877 ping grpc://localhost:12345 at 1 round... [09/08/22 12:58:14] +INFO Jina-serve@92877 ping grpc://localhost:12345 at 1 round takes 0 seconds (0.01s) +INFO Jina-serve@92877 ping grpc://localhost:12345 at 2 round... [09/08/22 12:58:15] +INFO Jina-serve@92877 ping grpc://localhost:12345 at 2 round takes 0 seconds (0.01s) +INFO Jina-serve@92877 avg. latency: 24 ms [09/08/22 12:58:16] ``` ```` ````{tab} Failure ```text -INFO JINA@92986 ping grpc://localhost:12345 at 0 round... [09/08/22 12:59:00] +INFO Jina-serve@92986 ping grpc://localhost:12345 at 0 round... [09/08/22 12:59:00] ERROR GRPCClient@92986 Error while getting response from grpc server -WARNI… JINA@92986 not responding, retry (1/3) in 1s -INFO JINA@92986 ping grpc://localhost:12345 at 0 round takes 0 seconds (0.01s) -INFO JINA@92986 ping grpc://localhost:12345 at 1 round... [09/08/22 12:59:01] +WARNI… Jina-serve@92986 not responding, retry (1/3) in 1s +INFO Jina-serve@92986 ping grpc://localhost:12345 at 0 round takes 0 seconds (0.01s) +INFO Jina-serve@92986 ping grpc://localhost:12345 at 1 round... [09/08/22 12:59:01] ERROR GRPCClient@92986 Error while getting response from grpc server -WARNI… JINA@92986 not responding, retry (2/3) in 1s -INFO JINA@92986 ping grpc://localhost:12345 at 1 round takes 0 seconds (0.01s) -INFO JINA@92986 ping grpc://localhost:12345 at 2 round... [09/08/22 12:59:02] +WARNI… Jina-serve@92986 not responding, retry (2/3) in 1s +INFO Jina-serve@92986 ping grpc://localhost:12345 at 1 round takes 0 seconds (0.01s) +INFO Jina-serve@92986 ping grpc://localhost:12345 at 2 round... [09/08/22 12:59:02] ERROR GRPCClient@92986 Error while getting response from grpc server -WARNI… JINA@92986 not responding, retry (3/3) in 1s -INFO JINA@92986 ping grpc://localhost:12345 at 2 round takes 0 seconds (0.02s) -WARNI… JINA@92986 message lost 100% (3/3) +WARNI… Jina-serve@92986 not responding, retry (3/3) in 1s +INFO Jina-serve@92986 ping grpc://localhost:12345 at 2 round takes 0 seconds (0.02s) +WARNI… Jina-serve@92986 message lost 100% (3/3) ``` ```` ````` `````{tab} Flow ```python -from jina import Flow +from jina-serve import Flow f = Flow(port=12345) @@ -164,24 +164,24 @@ with f: f.block() ``` ```bash -jina ping flow grpc://localhost:12345 +jina-serve ping flow grpc://localhost:12345 ``` ````{tab} Success ```text -INFO JINA@92877 ping grpc://localhost:12345 at 0 round... [09/08/22 12:58:13] -INFO JINA@92877 ping grpc://localhost:12345 at 0 round takes 0 seconds (0.04s) -INFO JINA@92877 ping grpc://localhost:12345 at 1 round... [09/08/22 12:58:14] -INFO JINA@92877 ping grpc://localhost:12345 at 1 round takes 0 seconds (0.01s) -INFO JINA@92877 ping grpc://localhost:12345 at 2 round... [09/08/22 12:58:15] -INFO JINA@92877 ping grpc://localhost:12345 at 2 round takes 0 seconds (0.01s) -INFO JINA@92877 avg. latency: 24 ms [09/08/22 12:58:16] +INFO Jina-serve@92877 ping grpc://localhost:12345 at 0 round... [09/08/22 12:58:13] +INFO Jina-serve@92877 ping grpc://localhost:12345 at 0 round takes 0 seconds (0.04s) +INFO Jina-serve@92877 ping grpc://localhost:12345 at 1 round... [09/08/22 12:58:14] +INFO Jina-serve@92877 ping grpc://localhost:12345 at 1 round takes 0 seconds (0.01s) +INFO Jina-serve@92877 ping grpc://localhost:12345 at 2 round... [09/08/22 12:58:15] +INFO Jina-serve@92877 ping grpc://localhost:12345 at 2 round takes 0 seconds (0.01s) +INFO Jina-serve@92877 avg. latency: 24 ms [09/08/22 12:58:16] ``` ```` ````{tab} Failure ```text -INFO JINA@92986 ping grpc://localhost:12345 at 0 round... [09/08/22 12:59:00] +INFO Jina-serve@92986 ping grpc://localhost:12345 at 0 round... [09/08/22 12:59:00] ERROR GRPCClient@92986 Error while getting response from grpc server -WARNI… JINA@92986 not responding, retry (1/3) in 1s -INFO JINA@92986 ping grpc://localhost:12345 at 0 round takes 0 seconds (0.01s) -INFO JINA@92986 ping grpc://localhost:12345 at 1 round... [09/08/22 12:59:01] +WARNI… Jina-serve@92986 not responding, retry (1/3) in 1s +INFO Jina-serve@92986 ping grpc://localhost:12345 at 0 round takes 0 seconds (0.01s) +INFO Jina-serve@92986 ping grpc://localhost:12345 at 1 round... [09/08/22 12:59:01] ERROR GRPCClient@92986 Error while getting response from grpc server -WARNI… JINA@92986 not responding, retry (2/3) in 1s -INFO JINA@92986 ping grpc://localhost:12345 at 1 round takes 0 seconds (0.01s) -INFO JINA@92986 ping grpc://localhost:12345 at 2 round... [09/08/22 12:59:02] +WARNI… Jina-serve@92986 not responding, retry (2/3) in 1s +INFO Jina-serve@92986 ping grpc://localhost:12345 at 1 round takes 0 seconds (0.01s) +INFO Jina-serve@92986 ping grpc://localhost:12345 at 2 round... [09/08/22 12:59:02] ERROR GRPCClient@92986 Error while getting response from grpc server -WARNI… JINA@92986 not responding, retry (3/3) in 1s -INFO JINA@92986 ping grpc://localhost:12345 at 2 round takes 0 seconds (0.02s) -WARNI… JINA@92986 message lost 100% (3/3) +WARNI… Jina-serve@92986 not responding, retry (3/3) in 1s +INFO Jina-serve@92986 ping grpc://localhost:12345 at 2 round takes 0 seconds (0.02s) +WARNI… Jina-serve@92986 message lost 100% (3/3) ``` ```` ````` ## Readiness check via third-party clients -You can check the status of a Flow using any gRPC/HTTP/WebSockets client, not just via Jina Client. +You can check the status of a Flow using any gRPC/HTTP/WebSockets client, not just via Jina-serve Client. To see how this works, first instantiate the Flow with its corresponding protocol and block it for serving: diff --git a/docs/concepts/orchestration/scale-out.md b/docs/concepts/orchestration/scale-out.md index 00dfab81252e9..ba7c1c2eff92b 100644 --- a/docs/concepts/orchestration/scale-out.md +++ b/docs/concepts/orchestration/scale-out.md @@ -278,7 +278,7 @@ This increases QPS from 2.5 to 5. ## Replicate on multiple GPUs -To replicate your {class}`~jina.Executor`s so that each replica uses a different GPU on your machine, you can tell the Orchestration to use multiple GPUs by passing `CUDA_VISIBLE_DEVICES=RR` as an environment variable. +To replicate your {class}`~jina-serve.Executor`s so that each replica uses a different GPU on your machine, you can tell the Orchestration to use multiple GPUs by passing `CUDA_VISIBLE_DEVICES=RR` as an environment variable. ```{caution} You should only replicate on multiple GPUs with `CUDA_VISIBLE_DEVICES=RR` locally. diff --git a/docs/concepts/orchestration/yaml-spec.md b/docs/concepts/orchestration/yaml-spec.md index 813ef53374b05..72430025274b2 100644 --- a/docs/concepts/orchestration/yaml-spec.md +++ b/docs/concepts/orchestration/yaml-spec.md @@ -11,7 +11,7 @@ We provide a [JSON Schema](https://json-schema.org/) for your IDE to enable code 1. Click menu `Preferences` -> `JSON Schema mappings`; 2. Add a new schema, in the `Schema File or URL` write `https://schemas.jina.ai/schemas/latest.json`; select `JSON Schema Version 7`; -3. Add a file path pattern and link it to `*.jaml` or `*.jina.yml` or any suffix you commonly used for Jina Flow's YAML. +3. Add a file path pattern and link it to `*.jaml` or `*.jina.yml` or any suffix you commonly used for Jina-serve Flow's YAML. ### VSCode users @@ -24,7 +24,7 @@ We provide a [JSON Schema](https://json-schema.org/) for your IDE to enable code } ``` -You can bind Schema to any file suffix you commonly used for Jina Flow's YAML. +You can bind Schema to any file suffix you commonly used for Jina-serve Flow's YAML. ## Example YAML diff --git a/docs/concepts/orchestration/yaml-vars.md b/docs/concepts/orchestration/yaml-vars.md index dc04b9fa1d7a7..389e3cc718f2b 100644 --- a/docs/concepts/orchestration/yaml-vars.md +++ b/docs/concepts/orchestration/yaml-vars.md @@ -1,6 +1,6 @@ ## Variables -Jina Orchestration YAML supports variables and variable substitution according to the [GitHub Actions syntax](https://docs.github.com/en/actions/learn-github-actions/environment-variables). +Jina-serve Orchestration YAML supports variables and variable substitution according to the [GitHub Actions syntax](https://docs.github.com/en/actions/learn-github-actions/environment-variables). ### Environment variables diff --git a/docs/concepts/preliminaries/coding-in-python-yaml.md b/docs/concepts/preliminaries/coding-in-python-yaml.md index 17f009c67f6cf..b8770c0fc2e10 100644 --- a/docs/concepts/preliminaries/coding-in-python-yaml.md +++ b/docs/concepts/preliminaries/coding-in-python-yaml.md @@ -1,7 +1,7 @@ (python-yaml)= # Coding in Python/YAML -In the docs, you often see two coding styles when describing a Jina project: +In the docs, you often see two coding styles when describing a Jina-serve project: ```{glossary} diff --git a/docs/concepts/preliminaries/index.md b/docs/concepts/preliminaries/index.md index af931d224d416..8dddeed8c0718 100644 --- a/docs/concepts/preliminaries/index.md +++ b/docs/concepts/preliminaries/index.md @@ -3,8 +3,8 @@ This chapter introduces the basic terminology and concepts you will encounter in the docs. But first, look at the code below: -In this code, we are going to use Jina to serve simple logic with one Deployment, or a combination of two services with a Flow. -We are also going to see how we can query these services with Jina's client. +In this code, we are going to use Jina-serve to serve simple logic with one Deployment, or a combination of two services with a Flow. +We are also going to see how we can query these services with Jina-serve's client. (dummy-example)= ````{tab} Deployment @@ -101,14 +101,14 @@ gRPC, WebSocket and HTTP are network protocols for transmitting data. gRPC is al TLS is a security protocol to facilitate privacy and data security for communications over the Internet. The communication between {term}`Client` and {term}`Gateway` is protected by TLS. ``` -Jina is an MLOPs serving framework that is structured in two main layers. These layers work with DocArray's data structure and Jina's Python Client to complete the framework. All of these are covered in the user guide +Jina-serve is an MLOPs serving framework that is structured in two main layers. These layers work with DocArray's data structure and Jina-serve's Python Client to complete the framework. All of these are covered in the user guide and contains the following concepts: ```{glossary} **DocArray data structure** -Data structures coming from [docarray](https://docs.docarray.org/) are the basic fundamental data structure in Jina. +Data structures coming from [docarray](https://docs.docarray.org/) are the basic fundamental data structure in Jina-serve. - **BaseDoc** @@ -117,13 +117,13 @@ Data structures coming from [docarray](https://docs.docarray.org/) are the basic - **DocList** DocList is a list-like container of multiple Documents. More information can be found in [DocArray's Docs](https://docs.docarray.org/user_guide/representing/array/). -All the components in Jina use `BaseDoc` and/or `DocList` as the main data format for communication, making use of the different +All the components in Jina-serve use `BaseDoc` and/or `DocList` as the main data format for communication, making use of the different serialization capabilities of these structures. **Serving** This layer contains all the objects and concepts that are used to actually serve the logic and receive and respond to queries. These components are designed to be used as microservices ready to be containerized. -These components can be orchestrated by Jina's {term}`orchestration` layer or by other container orchestration frameworks such as Kubernetes or Docker Compose. +These components can be orchestrated by Jina-serve's {term}`orchestration` layer or by other container orchestration frameworks such as Kubernetes or Docker Compose. - **Executor** diff --git a/docs/concepts/serving/executor/add-endpoints.md b/docs/concepts/serving/executor/add-endpoints.md index 6b25591960e31..9843baad9c452 100644 --- a/docs/concepts/serving/executor/add-endpoints.md +++ b/docs/concepts/serving/executor/add-endpoints.md @@ -19,7 +19,7 @@ from jina import requests {class}`~jina.requests` takes an optional `on=` parameter, which binds the decorated method to the specified route: ```python -from jina import Executor, requests +from jina-serve import Executor, requests import asyncio @@ -153,14 +153,14 @@ and `response_schema` will be used. ```{admonition} Note :class: note -When no type annotation or argument is provided, Jina assumes that [LegacyDocument](https://docs.docarray.org/API_reference/documents/documents/#docarray.documents.legacy.LegacyDocument) is the type used. -This is intended to ease the transition from using Jina with `docarray<0.30.0` to using it with the newer versions. +When no type annotation or argument is provided, Jina-serve assumes that [LegacyDocument](https://docs.docarray.org/API_reference/documents/documents/#docarray.documents.legacy.LegacyDocument) is the type used. +This is intended to ease the transition from using Jina-serve with `docarray<0.30.0` to using it with the newer versions. ``` (executor-api)= ## Executor API -Methods decorated by `@requests` require an API for Jina to serve them with a {class}`~jina.Deployment` or {class}`~jina.Flow`. +Methods decorated by `@requests` require an API for Jina-serve to serve them with a {class}`~jina.Deployment` or {class}`~jina.Flow`. An Executor's job is to process `Documents` that are sent via the network. Executors can work on these `Documents` one by one or in batches. @@ -176,7 +176,7 @@ These APIs and related type annotations also affect how your {ref}`OpenAPI looks When using `doc` as a keyword argument, you need to add a single `BaseDoc` as your request and response schema as seen in {ref}`the document type binding section `. -Jina will ensure that even if multiple `Documents` are sent from the client, the Executor will process only one at a time. +Jina-serve will ensure that even if multiple `Documents` are sent from the client, the Executor will process only one at a time. ```{code-block} python --- @@ -208,7 +208,7 @@ and models can be heavy enough that they cannot profit from processing multiple When using `docs` as a keyword argument, you need to add a parametrized `DocList` as your request and response schema as seen in {ref}`the document type binding section `. -In this case, Jina will ensure that all the request's `Documents` are passed to the Executor. The {ref}`"request_size" parameter from Client ` controls how many Documents are passed to the server in each request. +In this case, Jina-serve will ensure that all the request's `Documents` are passed to the Executor. The {ref}`"request_size" parameter from Client ` controls how many Documents are passed to the server in each request. When using batches, you can leverage the {ref}`dynamic batching feature `. ```{code-block} python @@ -417,7 +417,7 @@ with Deployment( ``` From the client side, any SSE client can be used to receive the Documents, one at a time. -Jina offers a standard python client for using the streaming endpoint: +Jina-serve offers a standard python client for using the streaming endpoint: ```python from jina import Client @@ -500,7 +500,7 @@ NotImplementedError('no time for it') (openapi-deployment)= ## OpenAPI from Executor endpoints -When deploying an Executor and serving it with HTTP, Jina uses FastAPI to expose all Executor endpoints as HTTP endpoints, and you can +When deploying an Executor and serving it with HTTP, Jina-serve uses FastAPI to expose all Executor endpoints as HTTP endpoints, and you can enjoy a corresponding OpenAPI via the Swagger UI. You can also add descriptions and examples to your DocArray and Pydantic types so your users and clients can enjoy an API. diff --git a/docs/concepts/serving/executor/containerize.md b/docs/concepts/serving/executor/containerize.md index e55b76a6f73ba..29ed3936a5814 100644 --- a/docs/concepts/serving/executor/containerize.md +++ b/docs/concepts/serving/executor/containerize.md @@ -20,8 +20,8 @@ The image building happens on the cloud, and once done the image is available im You can also build a Docker image yourself and use it like any other Executor. There are some requirements on how this image needs to be built: -- Jina must be installed inside the image. -- The Jina CLI command to start the Executor must be the default entrypoint. +- Jina-serve must be installed inside the image. +- The Jina-serve CLI command to start the Executor must be the default entrypoint. ## Prerequisites @@ -31,19 +31,19 @@ a [Dockerfile](https://docs.docker.com/engine/reference/builder/), and how to bu You need Docker installed locally to reproduce the example below. -## Install Jina in the Docker image +## Install Jina-serve in the Docker image -Jina **must** be installed inside the Docker image. This can be achieved in one of two ways: +Jina-serve **must** be installed inside the Docker image. This can be achieved in one of two ways: -- Use a [Jina based image](https://hub.docker.com/r/jinaai/jina) as the base image in your Dockerfile. -This ensures that everything needed for Jina to run the Executor is installed. +- Use a [Jina-serve based image](https://hub.docker.com/r/jinaai/jina) as the base image in your Dockerfile. +This ensures that everything needed for Jina-serve to run the Executor is installed. ```dockerfile FROM jinaai/jina:3-py38-perf ``` - Install Jina like any other Python package. You can do this by specifying Jina in `requirements.txt`, -or by including the `pip install jina` command as part of the image building process. +or by including the `pip install jina-serve` command as part of the image building process. ```dockerfile RUN pip install jina @@ -59,7 +59,7 @@ ENTRYPOINT ["jina", "executor", "--uses", "config.yml"] ```{note} We **strongly encourage** you to name the Executor YAML as `config.yml`, otherwise using your containerized Executor with Kubernetes requires an extra step. -When using {meth}`~jina.serve.executors.BaseExecutor.to_kubernetes_yaml()` or {meth}`~jina.serve.executors.BaseExecutor.to_docker_compose_yaml()`, Jina adds `--uses config.yml` in the entrypoint. +When using {meth}`~jina.serve.executors.BaseExecutor.to_kubernetes_yaml()` or {meth}`~jina.serve.executors.BaseExecutor.to_docker_compose_yaml()`, Jina-serve adds `--uses config.yml` in the entrypoint. To change that you need to manually edit the generated files. ``` @@ -97,7 +97,7 @@ The YAML configuration, as a minimal working example, is required to point to th ```{admonition} More YAML options :class: seealso -To see what else can be configured using Jina's YAML interface, see {ref}`here `. +To see what else can be configured using Jina-serve's YAML interface, see {ref}`here `. ``` This is necessary for the Executor to be put inside the Docker image, @@ -121,7 +121,7 @@ torch ### Write the Dockerfile -The last step is to write a `Dockerfile`, which has to do little more than launching the Executor via the Jina CLI: +The last step is to write a `Dockerfile`, which has to do little more than launching the Executor via the Jina-serve CLI: ```dockerfile FROM jinaai/jina:3-py38-perf diff --git a/docs/concepts/serving/executor/create.md b/docs/concepts/serving/executor/create.md index 6538fac627fe1..b4c61589b8863 100644 --- a/docs/concepts/serving/executor/create.md +++ b/docs/concepts/serving/executor/create.md @@ -37,7 +37,7 @@ MyExecutor/ - `executor.py` contains your Executor's main logic. The command should generate the following boilerplate code: ```python -from jina import Executor, requests +from jina-serve import Executor, requests from docarray import DocList, BaseDoc class MyExecutor(Executor): @@ -60,7 +60,7 @@ If your Executor has `__init__`, it needs to carry `**kwargs` in the signature a in the body: ```python -from jina import Executor +from jina-serve import Executor class MyExecutor(Executor): @@ -72,7 +72,7 @@ class MyExecutor(Executor): ````{admonition} What is inside kwargs? :class: hint -Here, `kwargs` are reserved for Jina to inject `metas` and `requests` (representing the request-to-function mapping) values when the Executor is used inside a {ref}`Flow `. +Here, `kwargs` are reserved for Jina-serve to inject `metas` and `requests` (representing the request-to-function mapping) values when the Executor is used inside a {ref}`Flow `. You can access the values of these arguments in the `__init__` body via `self.metas`/`self.requests`/`self.runtime_args`, or modify their values before passing them to `super().__init__()`. ```` @@ -83,11 +83,11 @@ can be overridden using the {ref}`Executor YAML with keyword`. @@ -170,7 +170,7 @@ The list of the `runtime_args` is: - `workspace`: Path to be used by the Executor. Note that the actual workspace directory used by the Executor is obtained by appending `'///'` to this value. - `py_modules`: Python package path e.g. `foo.bar.package.module` or file path to the modules needed to import the Executor. -You **cannot** provide these through any API. They are generated by the orchestration mechanism, be it a {class}`~jina.Deployment` or a {class}`~jina.Flow`. +You **cannot** provide these through any API. They are generated by the orchestration mechanism, be it a {class}`~jina-serve.Deployment` or a {class}`~jina-serve.Flow`. ## Tips diff --git a/docs/concepts/serving/executor/file-structure.md b/docs/concepts/serving/executor/file-structure.md index 5ba7bf039fabf..2b5a2b1f25239 100644 --- a/docs/concepts/serving/executor/file-structure.md +++ b/docs/concepts/serving/executor/file-structure.md @@ -23,7 +23,7 @@ When you are working with multiple Python files, you should organize them as a * your repository (as you would normally do with Python packages). Specifically, you should do the following: - Put all Python files (as well as an `__init__.py`) inside a special folder (called `executor` by convention.) - - Because of how Jina registers Executors, ensure you import your Executor in this `__init__.py` (see the contents of `executor/__init__.py` in the example below). + - Because of how Jina-serve registers Executors, ensure you import your Executor in this `__init__.py` (see the contents of `executor/__init__.py` in the example below). - Use relative imports (`from .bar import foo`, and not `from bar import foo`) inside the Python modules in this folder. - Only list `executor/__init__.py` under `py_modules` in `config.yml` - this way Python knows that you are importing a package, and ensures that all relative imports within your package work properly. diff --git a/docs/concepts/serving/executor/health-check.md b/docs/concepts/serving/executor/health-check.md index 5271560c43296..bdf6d070aff70 100644 --- a/docs/concepts/serving/executor/health-check.md +++ b/docs/concepts/serving/executor/health-check.md @@ -4,7 +4,7 @@ ## Using gRPC You can check every individual Executor, by using a [standard gRPC health check endpoint](https://github.com/grpc/grpc/blob/master/doc/health-checking.md). -In most cases this is not necessary, since such checks are performed by Jina, a Kubernetes service mesh or a load balancer under the hood. +In most cases this is not necessary, since such checks are performed by Jina-serve, a Kubernetes service mesh or a load balancer under the hood. Nevertheless, you can perform these checks yourself. When performing these checks, you can expect one of the following `ServingStatus` responses: diff --git a/docs/concepts/serving/executor/hub/create-hub-executor.md b/docs/concepts/serving/executor/hub/create-hub-executor.md index c64346c429960..abeae2d0df83d 100644 --- a/docs/concepts/serving/executor/hub/create-hub-executor.md +++ b/docs/concepts/serving/executor/hub/create-hub-executor.md @@ -49,9 +49,9 @@ In the `jina hub new` wizard you can choose from four Dockerfile templates: `cpu ``` -* If you push your Executor to the [Executor Hub](https://cloud.jina.ai/executors), you don't need to bump the Jina version +* If you push your Executor to the [Executor Hub](https://cloud.jina.ai/executors), you don't need to bump the Jina-serve version - Hub Executors are version-agnostic. When you pull an Executor from Executor Hub, it will select the right Jina version for you. You don't need to upgrade your version of Jina. + Hub Executors are version-agnostic. When you pull an Executor from Executor Hub, it will select the right Jina-serve version for you. You don't need to upgrade your version of Jina-serve. * Fill in metadata of your Executor correctly diff --git a/docs/concepts/serving/executor/hub/debug-executor.md b/docs/concepts/serving/executor/hub/debug-executor.md index 4193c16a03747..8a8213dde2952 100644 --- a/docs/concepts/serving/executor/hub/debug-executor.md +++ b/docs/concepts/serving/executor/hub/debug-executor.md @@ -34,7 +34,7 @@ Executor.from_hub('jinaai://jina-ai/Hello') ## Set breakpoints -In the `~/.jina/hub-package` directory there is one subdirectory for each Executor that you pulled, named by the Executor ID. You can find the Executor's source files in this directory. +In the `~/.jina-serve/hub-package` directory there is one subdirectory for each Executor that you pulled, named by the Executor ID. You can find the Executor's source files in this directory. Once you locate the source, you can set the breakpoints as you always do. diff --git a/docs/concepts/serving/executor/hub/hub-portal.md b/docs/concepts/serving/executor/hub/hub-portal.md index 349461fae875f..241c53684e4e3 100644 --- a/docs/concepts/serving/executor/hub/hub-portal.md +++ b/docs/concepts/serving/executor/hub/hub-portal.md @@ -6,7 +6,7 @@ Let's see the [Hub portal](https://cloud.jina.ai) in detail. ## Catalog page -The main page contains a list of all Executors created by Jina developers all over the world. You can see the Editor's Pick at the top of the list, which shows Executors highlighted by the Jina team. +The main page contains a list of all Executors created by Jina-serve developers all over the world. You can see the Editor's Pick at the top of the list, which shows Executors highlighted by the Jina-serve team. ```{figure} ../../../../../.github/hub-website-list.png :align: center diff --git a/docs/concepts/serving/executor/hub/index.md b/docs/concepts/serving/executor/hub/index.md index d1cbf6ef291c3..a46544e0a8eb1 100644 --- a/docs/concepts/serving/executor/hub/index.md +++ b/docs/concepts/serving/executor/hub/index.md @@ -1,7 +1,7 @@ (jina-hub)= # Executor Hub -Now that you understand that {class}`~jina.Executor` is a building block in Jina, you may also wonder: +Now that you understand that {class}`~jina.Executor` is a building block in Jina-serve, you may also wonder: - Can I streamline the process of containerizing my {class}`~jina.Executor`? - Can I reuse my Executor in another project? diff --git a/docs/concepts/serving/executor/hub/push-executor.md b/docs/concepts/serving/executor/hub/push-executor.md index c2501bbecebc4..a5cd9948ca4d3 100644 --- a/docs/concepts/serving/executor/hub/push-executor.md +++ b/docs/concepts/serving/executor/hub/push-executor.md @@ -16,9 +16,9 @@ jina hub push [--public/--private] -If you have logged into Jina, it will return a `TASK_ID`. You need that to get your Executor's build status and logs. +If you have logged into Jina-serve, it will return a `TASK_ID`. You need that to get your Executor's build status and logs. -If you haven't logged into Jina, it will return `NAME` and `SECRET`. You need them to use (if the Executor is private) or update the Executor. **Please keep them safe.** +If you haven't logged into Jina-serve, it will return `NAME` and `SECRET`. You need them to use (if the Executor is private) or update the Executor. **Please keep them safe.** ````{admonition} Note :class: note diff --git a/docs/concepts/serving/executor/hub/use-hub-executor.md b/docs/concepts/serving/executor/hub/use-hub-executor.md index 89cf0c4695efb..a2249867a607d 100644 --- a/docs/concepts/serving/executor/hub/use-hub-executor.md +++ b/docs/concepts/serving/executor/hub/use-hub-executor.md @@ -36,11 +36,11 @@ To keep up-to-date with upstream, use `.from_hub(..., force_update=True)`. You can also use `jina hub` CLI to pull an Executor without actually using it in the Flow. -````{admonition} Jina and DocArray version +````{admonition} Jina-serve and DocArray version :class: note -Independently of the Jina and DocArray version existing when the Executor was pushed to the Hub. When pulling, the Hub will try -to install the Jina and DocArray version that you have installed locally in the pulled docker images. +Independently of the Jina-serve and DocArray version existing when the Executor was pushed to the Hub. When pulling, the Hub will try +to install the Jina-serve and DocArray version that you have installed locally in the pulled docker images. ```` ### Pull the Docker image diff --git a/docs/concepts/serving/executor/instrumentation.md b/docs/concepts/serving/executor/instrumentation.md index 300eaacb5f4cf..8b7cd34afdbfb 100644 --- a/docs/concepts/serving/executor/instrumentation.md +++ b/docs/concepts/serving/executor/instrumentation.md @@ -23,7 +23,7 @@ default tracing span for the defined operation. In addition, the operation span is propagated to the method for creating further user-defined child spans within the method. -You can create custom spans to observe the operation's individual steps or record details and attributes with finer granularity. When tracing is enabled, Jina provides the OpenTelemetry Tracer implementation as an Executor class attribute that you can use to create new child spans. The `tracing_context` method argument contains the parent span context using which a new span can be created to trace the desired operation in the method. +You can create custom spans to observe the operation's individual steps or record details and attributes with finer granularity. When tracing is enabled, Jina-serve provides the OpenTelemetry Tracer implementation as an Executor class attribute that you can use to create new child spans. The `tracing_context` method argument contains the parent span context using which a new span can be created to trace the desired operation in the method. If tracing is enabled, each Executor exports its traces to the configured exporter host via the [Span Exporter](https://opentelemetry.io/docs/reference/specification/trace/sdk/#span-exporter). The backend combines these traces for visualization and alerting. @@ -67,7 +67,7 @@ The above pieces of instrumentation generate three spans: ```{admonition} -The Python OpenTelemetry API provides a global tracer via the `opentelemetry.trace.tracer()` method which is not set or used directly in Jina. The class attribute `self.tracer` is used for the default `@requests` method tracing and must also be used as much as possible within the method for creating child spans. +The Python OpenTelemetry API provides a global tracer via the `opentelemetry.trace.tracer()` method which is not set or used directly in Jina-serve. The class attribute `self.tracer` is used for the default `@requests` method tracing and must also be used as much as possible within the method for creating child spans. However within a span context, the `opentelemetry.trace.get_current_span()` method returns the span created inside the context. ``` @@ -87,14 +87,14 @@ If tracing is not enabled by default or enabled in your environment, check `self Prometheus-only based metrics collection will be deprecated soon. Refer to {ref}`Monitoring Executor ` section for the deprecated setup. ``` -Any method that uses the {class}`~jina.requests` decorator is monitored and creates a +Any method that uses the {class}`~jina-serve.requests` decorator is monitored and creates a [histogram](https://opentelemetry.io/docs/reference/specification/metrics/data-model/#histogram) which tracks the method's execution time. -This section documents adding custom monitoring to the {class}`~jina.Executor` with the OpenTelemetry Metrics API. +This section documents adding custom monitoring to the {class}`~jina-serve.Executor` with the OpenTelemetry Metrics API. Custom metrics are useful to monitor each sub-part of your Executor(s). Jina lets you leverage the [Meter](https://opentelemetry.io/docs/reference/specification/metrics/api/#meter) to define useful metrics -for each of your Executors. We also provide a convenient wrapper, ({func}`~jina.monitor`), which lets you monitor +for each of your Executors. We also provide a convenient wrapper, ({func}`~jina-serve.monitor`), which lets you monitor your Executor's sub-methods. When metrics are enabled, each Executor exposes its @@ -134,7 +134,7 @@ class MyExecutor(Executor): #### Use the `@monitor` decorator -Add custom monitoring to a method with the {func}`~jina.monitor` decorator: +Add custom monitoring to a method with the {func}`~jina-serve.monitor` decorator: ```python from jina import Executor, monitor @@ -148,7 +148,7 @@ class MyExecutor(Executor): This creates a [Histogram](https://opentelemetry.io/docs/reference/specification/metrics/data-model/#histogram) `jina_my_method_seconds` which tracks the execution time of `my_method` -By default, the name and documentation of the metric created by {func}`~jina.monitor` are auto-generated based on the function's name. +By default, the name and documentation of the metric created by {func}`~jina-serve.monitor` are auto-generated based on the function's name. To set a custom name: ```python @@ -166,7 +166,7 @@ You should respect OpenTelemetry Metrics [semantic conventions](https://opentele #### Use OpenTelemetry Meter -Under the hood, Python [OpenTelemetry Metrics API](https://opentelemetry.io/docs/concepts/signals/metrics/) handles the Executor's metrics feature. The {func}`~jina.monitor` decorator is convenient for monitoring an Executor's sub-methods, but if you need more flexibility, use the `self.meter` Executor class attribute to create supported instruments: +Under the hood, Python [OpenTelemetry Metrics API](https://opentelemetry.io/docs/concepts/signals/metrics/) handles the Executor's metrics feature. The {func}`~jina-serve.monitor` decorator is convenient for monitoring an Executor's sub-methods, but if you need more flexibility, use the `self.meter` Executor class attribute to create supported instruments: ```python @@ -276,6 +276,6 @@ class MyExecutor(Executor): ## See also - {ref}`List of available metrics ` -- {ref}`How to deploy and use OpenTelemetry in Jina ` +- {ref}`How to deploy and use OpenTelemetry in Jina-serve ` - [Tracing in OpenTelemetry](https://opentelemetry.io/docs/concepts/signals/traces/) - [Metrics in OpenTelemetry](https://opentelemetry.io/docs/concepts/signals/metrics/) diff --git a/docs/concepts/serving/executor/serve.md b/docs/concepts/serving/executor/serve.md index c05b72c4cf089..9d551b862d0cf 100644 --- a/docs/concepts/serving/executor/serve.md +++ b/docs/concepts/serving/executor/serve.md @@ -19,7 +19,7 @@ to achieve this with the {ref}`Flow ` In Jina there are two ways of running standalone Executors: *Served Executors* and *shared Executors*. -- A **served Executor** is launched by one of the following methods: {class}`~jina.orchestrate.deployments.Deployment`, `to_kubernetes_yaml()`, or `to_docker_compose_yaml()`. +- A **served Executor** is launched by one of the following methods: {class}`~jina-serve.orchestrate.deployments.Deployment`, `to_kubernetes_yaml()`, or `to_docker_compose_yaml()`. It resides behind a {ref}`Gateway ` and can be directly accessed by a {ref}`Client `. It can also be used as part of a Flow. @@ -33,9 +33,9 @@ In any case, the user needs to make sure that the Document types bound to each e (deployment)= ## Serve directly -An {class}`~jina.Executor` can be served using the {class}`~jina.orchestrate.deployments.Deployment` class. +An {class}`~jina-serve.Executor` can be served using the {class}`~jina-serve.orchestrate.deployments.Deployment` class. -The {class}`~jina.orchestrate.deployments.Deployment` class aims to separate the deployment configuration from the serving logic. +The {class}`~jina-serve.orchestrate.deployments.Deployment` class aims to separate the deployment configuration from the serving logic. In other words: * the Executor cares about defining the logic to serve, which endpoints to define and what data to accept. * the Deployment layer cares about how to orchestrate this service, how many replicas or shards, etc. @@ -144,7 +144,7 @@ py_modules: - executor.py ``` -This simply points Jina to our file and Executor class. Now we can run the command: +This simply points Jina-serve to our file and Executor class. Now we can run the command: ```bash jina executor --uses my-exec.yml --port 12345 @@ -222,7 +222,7 @@ Unlike the `jina executor` CLI, this command supports replication and sharding. Read more about the {ref}`YAML specifications of Deployments `. ## Serve via Kubernetes -You can generate Kubernetes configuration files for your containerized Executor by using the {meth}`~jina.Deployment.to_kubernetes_yaml()` method: +You can generate Kubernetes configuration files for your containerized Executor by using the {meth}`~jina-serve.Deployment.to_kubernetes_yaml()` method: ```python from jina import Deployment @@ -263,7 +263,7 @@ Let's export the external IP address created and use it to send requests to the export EXTERNAL_IP=`kubectl get service executor-exposed -n my-namespace -o=jsonpath='{.status.loadBalancer.ingress[0].ip}'` ``` -Then, we can send requests using {meth}`~jina.Client`. Since Kubernetes load balancers cannot load balance streaming +Then, we can send requests using {meth}`~jina-serve.Client`. Since Kubernetes load balancers cannot load balance streaming gRPC requests, it is recommended to set `stream=False` when using gRPC (note that this is only applicable for Kubernetes deployments of Executors): ```python import os @@ -296,12 +296,12 @@ This type of standalone Executor can be either *external* or *shared*. By defaul - An external Executor is deployed alongside a {ref}`Gateway `. - A shared Executor has no Gateway. -Although both types can join a {class}`~jina.Flow`, use a shared Executor if the Executor is only intended to join Flows +Although both types can join a {class}`~jina-serve.Flow`, use a shared Executor if the Executor is only intended to join Flows to have less network hops and save the costs of running the Gateway in Kubernetes. ## Serve via Docker Compose -You can generate a Docker Compose service file for your containerized Executor with the static {meth}`~jina.Deployment.to_docker_compose_yaml` method. +You can generate a Docker Compose service file for your containerized Executor with the static {meth}`~jina-serve.Deployment.to_docker_compose_yaml` method. ```python from jina import Deployment diff --git a/docs/concepts/serving/gateway/customization.md b/docs/concepts/serving/gateway/customization.md index e5dd11b041296..9b089f3f93c47 100644 --- a/docs/concepts/serving/gateway/customization.md +++ b/docs/concepts/serving/gateway/customization.md @@ -1,8 +1,8 @@ (custom-gateway)= # Customization -Gateways are customizable in Jina. You can implement them in much the same way as an Executor. -With customized Gateways, Jina gives you more power by letting you implement any server, protocol and +Gateways are customizable in Jina-serve. You can implement them in much the same way as an Executor. +With customized Gateways, Jina-serve gives you more power by letting you implement any server, protocol and interface at the Gateway level. This means you have more freedom to: * Define and expose your own API Gateway interface to clients. You can define your JSON schema or protos etc. @@ -14,7 +14,7 @@ The next sections detail the steps to implement and use a custom Gateway. ## Implementing the custom Gateway Just like for Executors, you can implement a custom Gateway by inheriting from a base `Gateway` class. -Jina will instantiate your implemented class, inject runtime arguments and user-defined arguments into it, +Jina-serve will instantiate your implemented class, inject runtime arguments and user-defined arguments into it, run it, orchestrate it, and send it health-checks. There are two Gateway base classes for implementing a custom Gateway: @@ -196,7 +196,7 @@ Use this object to send Documents to Executors in the Flow. A {class}`~jina.serv connects the custom Gateway with the rest of the Flow. You can get this object in 2 different ways: -* A `streamer` object (instance of {class}`~jina.serve.streamer.GatewayStreamer`) is injected by Jina to your `Gateway` class. +* A `streamer` object (instance of {class}`~jina.serve.streamer.GatewayStreamer`) is injected by Jina-serve to your `Gateway` class. * If your server logic cannot access the `Gateway` class (for instance separate script), you can still get a `streamer` object using {meth}`~jina.serve.streamer.GatewayStreamer.get_streamer()`: @@ -284,7 +284,7 @@ It is recommended to always pass the `return_type` parameter (executor-streamer)= ## Calling an individual Executor -Jina injects an `executor` object into your Gateway class which lets you call individual Executors from the Gateway. +Jina-serve injects an `executor` object into your Gateway class which lets you call individual Executors from the Gateway. After transforming requests that arrive to the Gateway server into Documents, you can call the Executor in your Python code using `self.executor['executor_name'].post(args)`. This method expects a DocList object and an endpoint exposed by the Executor (similar to {ref}`Jina Client `). @@ -397,8 +397,8 @@ with Flow().config_gateway(uses=MyGateway, protocol='http').add(uses=FirstExec, ### Runtime attributes -Jina injects runtime attributes into the Gateway classes. You can use them to set up your custom gateway: -* `logger`: Jina logger object. +Jina-serve injects runtime attributes into the Gateway classes. You can use them to set up your custom gateway: +* `logger`: Jina-serve logger object. * `streamer`: {class}`~jina.serve.streamer.GatewayStreamer`. Use this object to send Documents from the Gateway to Executors. Refer to {ref}`this section ` for more information. * `runtime_args`: `argparse.Namespace` object containing runtime arguments. * `port`: main port exposed by the Gateway. @@ -440,8 +440,8 @@ Refer to the {ref}`Use Custom Gateway section ` for more inf (custom-gateway-health-check)= ## Required health-checks -Jina relies on health-checks to determine the health of the Gateway. In environments like Kubernetes, -Docker Compose and Jina Cloud, this information is crucial for orchestrating the Gateway. +Jina-serve relies on health-checks to determine the health of the Gateway. In environments like Kubernetes, +Docker Compose and Jina-serve Cloud, this information is crucial for orchestrating the Gateway. Since you have full control over your custom gateways, you are always responsible for implementing health-check endpoints: * If the protocol used is gRPC, a health servicer (for instance `health.aio.HealthServicer()`) from `grpcio-health-checking` is expected to be added to the gRPC server. Refer to {class}`~jina.serve.runtimes.gateway.grpc.gateway.GRPCGateway` as @@ -479,15 +479,15 @@ or Kubernetes. This assumes that you've already implemented a custom Gateway class and have defined a `config.yml` for it. In this case, dockerizing the Gateway is straightforward: -* If you need dependencies other than Jina, make sure to add a `requirements.txt` file (for instance, you use a server library). +* If you need dependencies other than Jina-serve, make sure to add a `requirements.txt` file (for instance, you use a server library). * Create a `Dockerfile` as follows: -1. Use a [Jina based image](https://hub.docker.com/r/jinaai/jina) with the `standard` tag as the base image in your Dockerfile. -This ensures that everything needed for Jina to run the Gateway is installed. Make sure the Jina version supports +1. Use a [Jina-serve based image](https://hub.docker.com/r/jinaai/jina) with the `standard` tag as the base image in your Dockerfile. +This ensures that everything needed for Jina-serve to run the Gateway is installed. Make sure the Jina-serve version supports custom Gateways: ```dockerfile FROM jinaai/jina:latest-py38-standard ``` -Alternatively, you can just install jina using `pip`: +Alternatively, you can just install jina-serve using `pip`: ```dockerfile RUN pip install jina ``` @@ -525,7 +525,7 @@ docker build -t gateway-image ``` (use-custom-gateway)= ## Use the Custom Gateway -You can include the Custom Gateway in a Jina Flow in different formats: Python class, configuration YAML and Docker image: +You can include the Custom Gateway in a Jina-serve Flow in different formats: Python class, configuration YAML and Docker image: ### Flow python API ````{tab} Python Class diff --git a/docs/concepts/serving/gateway/customize-http-endpoints.md b/docs/concepts/serving/gateway/customize-http-endpoints.md index c94426cd71258..be0c26f7e47ac 100644 --- a/docs/concepts/serving/gateway/customize-http-endpoints.md +++ b/docs/concepts/serving/gateway/customize-http-endpoints.md @@ -130,12 +130,12 @@ f = Flow().config_gateway(cors=True, protocol='http') :class: caution GraphQL support is an optional feature that requires optional dependencies. -To install these, run `pip install jina[graphql]` or `pip install jina[all]`. +To install these, run `pip install jina-serve[graphql]` or `pip install jina-serve[all]`. Unfortunately, these dependencies are **not available through Conda**. You will have to use `pip` to be able to use GraphQL feature. ```` -A {class}`~jina.Flow` can optionally expose a [GraphQL](https://graphql.org/) endpoint, located at `/graphql`. +A {class}`~jina-serve.Flow` can optionally expose a [GraphQL](https://graphql.org/) endpoint, located at `/graphql`. To enable this endpoint, all you need to do is set `expose_graphql_endpoint=True` on your HTTP Flow: diff --git a/docs/concepts/serving/gateway/index.md b/docs/concepts/serving/gateway/index.md index 49fab594b34b7..796cc441581bf 100644 --- a/docs/concepts/serving/gateway/index.md +++ b/docs/concepts/serving/gateway/index.md @@ -190,7 +190,7 @@ In case you want to serve a Flow using multiple protocols, make sure to specify ## Enable TLS for client traffics -You can enable TLS encryption between your Gateway and Clients, for any of the protocols supported by Jina (HTTP, gRPC, +You can enable TLS encryption between your Gateway and Clients, for any of the protocols supported by Jina-serve (HTTP, gRPC, and WebSocket). ````{admonition} Caution @@ -220,7 +220,7 @@ with any Client. ## Enable in-Flow compression -The communication between {class}`~jina.Executor`s inside a {class}`~jina.Flow` is done via gRPC. To optimize the +The communication between {class}`~jina-serve.Executor`s inside a {class}`~jina-serve.Flow` is done via gRPC. To optimize the performance and the bandwidth of these connections, you can enable [compression](https://grpc.github.io/grpc/python/grpc.html#compression) by specifying `compression` argument to the Gateway. @@ -244,7 +244,7 @@ It is a dict-like structure with the following keys: - `jina`: A dictionary containing information about the system and the versions of several packages including jina package itself -- `envs`: A dictionary containing all the values if set of the {ref}`environment variables used in Jina ` +- `envs`: A dictionary containing all the values if set of the {ref}`environment variables used in Jina-serve ` ### Use gRPC @@ -320,7 +320,7 @@ You can also use it to check Executor status, as Executor's communication protoc (gateway-grpc-server-options)= ### Configure Gateway gRPC options -The {class}`~jina.Gateway` supports the `grpc_server_options` parameter which allows more customization of the **gRPC** +The {class}`~jina-serve.Gateway` supports the `grpc_server_options` parameter which allows more customization of the **gRPC** server. The `grpc_server_options` parameter accepts a dictionary of **gRPC** configuration options which will be used to overwrite the default options. The **gRPC** channel used for server to server communication can also be customized using the `grpc_channel_options` parameter. @@ -355,7 +355,7 @@ Refer to the {ref}`Configure Executor gRPC options ` option in the Flow. Otherwise, requests may queue up at an Executor and eventually time out. diff --git a/docs/concepts/serving/index.md b/docs/concepts/serving/index.md index dfd068811124c..a1d9231910222 100644 --- a/docs/concepts/serving/index.md +++ b/docs/concepts/serving/index.md @@ -1,7 +1,7 @@ (serving)= # {fas}`gears` Serving -As seen in the {ref}`architecture overview `, Jina is organized in different layers. +As seen in the {ref}`architecture overview `, Jina-serve is organized in different layers. The Serving layer is composed of concepts that allow developers to write their logic to be served by the objects in {ref}`orchestration ` layer. diff --git a/docs/docarray-support.md b/docs/docarray-support.md index 61e4fe261d5e2..a5b069badad35 100644 --- a/docs/docarray-support.md +++ b/docs/docarray-support.md @@ -1,11 +1,11 @@ (docarray-support)= # DocArray support -Jina depends heavily on DocArray to provide the data that is processed inside Jina Executors and sent by our Clients. +Jina-serve depends heavily on DocArray to provide the data that is processed inside Jina-serve Executors and sent by our Clients. Recently, DocArray was heavily refactored for version 0.30. -Starting from that version, DocArray usage has changed drastically, however Jina can work seamlessly and automatically with any of the versions of Jina. -Jina will automatically detect the docarray version installed and use the corresponding methods and APIs. However, developers +Starting from that version, DocArray usage has changed drastically, however Jina-serve can work seamlessly and automatically with any of the versions of Jina-serve. +Jina-serve will automatically detect the docarray version installed and use the corresponding methods and APIs. However, developers must take into account that some APIs and usages have changed, especially when it comes to developing Executors. The new version makes the dataclass feature of DocArray<0.30 a first-class citizen and for this @@ -22,10 +22,10 @@ Please note that also the names of data structure change in the new version of D TODO: ADD snippets for both versions -On the Jina side, this flexibility extends to every Executor, where you can now customize input and output schemas: +On the Jina-serve side, this flexibility extends to every Executor, where you can now customize input and output schemas: - With DocArray<0.30 a Document has a fixed schema in the input and the output -- With DocArray>=0.30 (the version currently used by default in Jina), an Executor defines its own input and output schemas. +- With DocArray>=0.30 (the version currently used by default in Jina-serve), an Executor defines its own input and output schemas. It also provides several predefined schemas that you can use out of the box. ## Executor API diff --git a/docs/envs/index.md b/docs/envs/index.md index 48161ba263bcd..9a6813cdb2a6e 100644 --- a/docs/envs/index.md +++ b/docs/envs/index.md @@ -1,7 +1,7 @@ (jina-env-vars)= # {octicon}`list-unordered` Environment Variables -Jina uses environment variables to determine different behaviours. To see all supported environment variables and their current values, run: +Jina-serve uses environment variables to determine different behaviours. To see all supported environment variables and their current values, run: ```bash jina -vf diff --git a/docs/get-started/create-app.md b/docs/get-started/create-app.md index e71c5a36329aa..2f68a1200d488 100644 --- a/docs/get-started/create-app.md +++ b/docs/get-started/create-app.md @@ -1,6 +1,6 @@ # {fas}`folder-plus` Create First Project -Let's build a toy application with Jina. To start, use Jina CLI to make a new Deployment or a Flow: +Let's build a toy application with Jina-serve. To start, use Jina-serve CLI to make a new Deployment or a Flow: ## Create a Deployment or Flow @@ -12,7 +12,7 @@ A {ref}`Deployment ` lets you serve and scale a single model or micr jina new hello-jina --type=deployment ``` -This creates a new project folder called `hello-jina` with the following file structure: +This creates a new project folder called `hello-jina-serve` with the following file structure: ```text hello-jina/ @@ -63,7 +63,7 @@ jina deployment --uses deployment.yml jina new hello-jina --type=flow ``` -This creates a new project folder called `hello-jina` with the following file structure: +This creates a new project folder called `hello-jina-serve` with the following file structure: ```text hello-jina/ @@ -77,7 +77,7 @@ hello-jina/ - `flow.yml` is the configuration file for the Flow`. - `executor1/` is where you write your {ref}`Executor ` code. - `config.yml` is the configuration file for the Executor. It stores metadata for your Executor, as well as dependencies. -- `client.py` is the entrypoint of your Jina project. You can run it via `python app.py`. +- `client.py` is the entrypoint of your Jina-serve project. You can run it via `python app.py`. There are some other files like `README.md` and `requirements.txt` to provide extra metadata about that Executor. More information {ref}`can be found here`. @@ -86,7 +86,7 @@ Now run it and observe the output of the server and client: ## Launch Flow ```shell -jina flow --uses flow.yml +jina-serve flow --uses flow.yml ``` ```shell @@ -141,7 +141,7 @@ emphasize-lines: 13-16 import numpy as np import torch -from jina import Executor, requests +from jina-serve import Executor, requests class MyExecutor(Executor): @@ -163,7 +163,7 @@ Kill the last server with `Ctrl-C` and restart the server with `jina flow --uses Modify `client.py` to call the `/crunch-numbers` endpoint: ```python -from jina import Client +from jina-serve import Client from docarray import DocList from docarray.documents.legacy import LegacyDocument @@ -213,7 +213,7 @@ At present, JCloud is only available for Flows. We are currently working on supp ``` ```bash -jina auth login +jina-serve auth login ``` Log in with your GitHub, Google or Email account: @@ -245,7 +245,7 @@ Now change the Client's code to use the deployed endpoint shown above: --- emphasize-lines: 6 --- -from jina import Client +from jina-serve import Client from docarray import DocList from docarray.documents.legacy import LegacyDocument @@ -295,4 +295,4 @@ jina cloud flow remove 1655d050ad Successfully removed Flow 1655d050ad. ``` -You've just finished your first toy Jina project, congratulations! You can now start your own project. +You've just finished your first toy Jina-serve project, congratulations! You can now start your own project. diff --git a/docs/get-started/install.md b/docs/get-started/install.md index 86245f5b34163..5c6c85ebbab03 100644 --- a/docs/get-started/install.md +++ b/docs/get-started/install.md @@ -1,8 +1,8 @@ (install)= # {octicon}`desktop-download` Install -Jina comes with multiple installation options, enabling different feature sets. -Standard install enables all major features of Jina and is the recommended installation for most users. +Jina-serve comes with multiple installation options, enabling different feature sets. +Standard install enables all major features of Jina-serve and is the recommended installation for most users. ````{tab} via PyPI ```shell @@ -26,7 +26,7 @@ Version identifiers [are explained here](https://github.com/jina-ai/jina/blob/ma ### Minimum -Minimum install enables basic features of Jina, but without support for HTTP, WebSocket, Docker and Hub. +Minimum install enables basic features of Jina-serve, but without support for HTTP, WebSocket, Docker and Hub. Minimum install is often used when building and deploying an Executor. @@ -89,7 +89,7 @@ docker run jinaai/jina:latest-perf ### Full development dependencies -This installs additional dependencies, useful for developing Jina itself. This includes Pytest, CI components etc. +This installs additional dependencies, useful for developing Jina-serve itself. This includes Pytest, CI components etc. ````{tab} via PyPI @@ -112,7 +112,7 @@ docker run jinaai/jina:latest-devel ### Prerelease -Prerelease is the version always synced with the `master` branch of Jina's GitHub repository. +Prerelease is the version always synced with the `master` branch of Jina-serve's GitHub repository. ````{tab} via PyPI diff --git a/docs/get-started/install/apple-silicon-m1-m2.md b/docs/get-started/install/apple-silicon-m1-m2.md index f514ae1b70bca..f7386dd39933d 100644 --- a/docs/get-started/install/apple-silicon-m1-m2.md +++ b/docs/get-started/install/apple-silicon-m1-m2.md @@ -1,6 +1,6 @@ # On Apple Silicon -If you own a macOS device with an Apple Silicon M1/M2 chip, you can run Jina **natively** on it (instead of running under Rosetta) and enjoy up to 10x faster performance. This chapter summarizes how to install Jina. +If you own a macOS device with an Apple Silicon M1/M2 chip, you can run Jina-serve **natively** on it (instead of running under Rosetta) and enjoy up to 10x faster performance. This chapter summarizes how to install Jina-serve. ## Check terminal and device @@ -72,15 +72,15 @@ Ensure you note down where `python` and `pip` are installed. In this example, th ## Install dependencies wheels -There are some core dependencies that Jina needs to run, whose wheels are not available on PyPI but fortunately are available as wheels. To install them, run: +There are some core dependencies that Jina-serve needs to run, whose wheels are not available on PyPI but fortunately are available as wheels. To install them, run: ```bash brew install protobuf numpy ``` -## Install Jina +## Install Jina-serve -Now we can install Jina via `pip`. Ensure you use the correct `pip`: +Now we can install Jina-serve via `pip`. Ensure you use the correct `pip`: ```bash /opt/homebrew/opt/python@3.10/libexec/bin/pip install jina @@ -95,7 +95,7 @@ export GRPC_PYTHON_BUILD_SYSTEM_OPENSSL=1 export GRPC_PYTHON_BUILD_SYSTEM_ZLIB=1 ``` -After all the dependencies are installed, you can run Jina CLI and check the system information. +After all the dependencies are installed, you can run Jina-serve CLI and check the system information. ```bash jina -vf @@ -144,7 +144,7 @@ emphasize-lines: 13-15 ``` -Congratulations! You have successfully installed Jina on Apple Silicon. +Congratulations! You have successfully installed Jina-serve on Apple Silicon. ````{tip} diff --git a/docs/get-started/install/docker.md b/docs/get-started/install/docker.md index e3828458abce6..f40ae42a31836 100644 --- a/docs/get-started/install/docker.md +++ b/docs/get-started/install/docker.md @@ -6,7 +6,7 @@ Our universal Docker image is ready-to-use on linux/amd64 and linux/arm64. The D jinaai/jina:{version}{python_version}{extra} ``` -- `{version}`: The version of Jina. Possible values: +- `{version}`: The version of Jina-serve. Possible values: - `latest`: the last release; - `master`: the master branch of `jina-ai/jina` repository; - `x.y.z`: the release of a particular version; @@ -15,7 +15,7 @@ jinaai/jina:{version}{python_version}{extra} - ` `, `-py37`: Python 3.7; - `-py38` for Python 3.8; - `-py39` for Python 3.9; -- `{extra}`: the extra dependency installed along with Jina. Possible values: +- `{extra}`: the extra dependency installed along with Jina-serve. Possible values: - ` `: Jina is installed inside the image with minimum dependencies `pip install jina`; - `-perf`: Jina is installed inside the image via `pip install jina`. It includes all performance dependencies; - `-standard`: Jina is installed inside the image via `pip install jina`. It includes all recommended dependencies; diff --git a/docs/get-started/install/troubleshooting.md b/docs/get-started/install/troubleshooting.md index 96f29f773f01a..17aa87f95a43b 100644 --- a/docs/get-started/install/troubleshooting.md +++ b/docs/get-started/install/troubleshooting.md @@ -1,14 +1,14 @@ # Troubleshooting -This article helps you to solve the installation problems of Jina. +This article helps you to solve the installation problems of Jina-serve. ## On Linux/Mac, building wheels takes long time -The normal installation of Jina takes 10 seconds. If yours takes longer than this, then it is likely you unnecessarily built wheels from scratch. +The normal installation of Jina-serve takes 10 seconds. If yours takes longer than this, then it is likely you unnecessarily built wheels from scratch. -Every upstream dependency of Jina has pre-built wheels exhaustively for x86/arm64, macos/Linux and Python 3.7/3.8/3.9, including `numpy`, `protobuf`, `grpcio` etc. This means when you install Jina, your `pip` should directly leverage the pre-built wheels instead of building them from scratch locally. For example, you should expect the install log to contain `-cp38-cp38-macosx_10_15_x86_64.whl` when installing Jina on macOS with Python 3.8. +Every upstream dependency of Jina-serve has pre-built wheels exhaustively for x86/arm64, macos/Linux and Python 3.7/3.8/3.9, including `numpy`, `protobuf`, `grpcio` etc. This means when you install Jina-serve, your `pip` should directly leverage the pre-built wheels instead of building them from scratch locally. For example, you should expect the install log to contain `-cp38-cp38-macosx_10_15_x86_64.whl` when installing Jina-serve on macOS with Python 3.8. -If you find you are building wheels during installation (see an example below), then it is a sign that you are installing Jina **wrongly**. +If you find you are building wheels during installation (see an example below), then it is a sign that you are installing Jina-serve **wrongly**. ```text Collecting numpy==2.0.* @@ -29,15 +29,15 @@ pip install -U pip ### If not, then... -Then you are likely installing Jina on a less-supported system/architecture. For example, on native Mac M1, Alpine Linux, or Raspberry Pi 2/3 (armv6/7). +Then you are likely installing Jina-serve on a less-supported system/architecture. For example, on native Mac M1, Alpine Linux, or Raspberry Pi 2/3 (armv6/7). ## On Windows with `conda` Unfortunately, `conda install` is not supported on Windows. You can either do `pip install jina` natively on Windows, or use `pip/conda install` under WSL2. -## Upgrading from Jina 2.x to 3.x -If you upgraded an existing Jina installation from 2.x to 3.x you may see the following error message: +## Upgrading from Jina-serve 2.x to 3.x +If you upgraded an existing Jina-serve installation from 2.x to 3.x you may see the following error message: ```text OSError: `docarray` dependency is not installed correctly, please reinstall with `pip install -U --force-reinstall docarray` @@ -49,4 +49,4 @@ This can be fixed by reinstalling the `docarray` package manually: pip install -U --force-reinstall docarray ``` -To avoid this issue in the first place, we recommend installing Jina in a new virtual environment instead of upgrading from an old installation. +To avoid this issue in the first place, we recommend installing Jina-serve in a new virtual environment instead of upgrading from an old installation. diff --git a/docs/get-started/install/windows.md b/docs/get-started/install/windows.md index 6769364f3d7d0..af392572c6231 100644 --- a/docs/get-started/install/windows.md +++ b/docs/get-started/install/windows.md @@ -1,9 +1,9 @@ (jina-on-windows)= # On Windows -You can install and use Jina on Windows. +You can install and use Jina-serve on Windows. -However, Jina is built keeping *nix-based platforms in mind, and the upstream libraries that Jina depends on also follow the similar ideology. Hence, there are some caveats when running Jina on Windows. [If you face additional issues, please let us know.](https://github.com/jina-ai/jina/issues/) +However, Jina-serve is built keeping *nix-based platforms in mind, and the upstream libraries that Jina-serve depends on also follow the similar ideology. Hence, there are some caveats when running Jina-serve on Windows. [If you face additional issues, please let us know.](https://github.com/jina-ai/jina/issues/) ```{caution} There can be a significant performance impact while running Jina on Windows. You may not want to use it in production. @@ -19,7 +19,7 @@ Once done, you can install Jina as on a native *nix platform. ### `multiprocessing spawn` -Jina relies heavily on `multiprocessing` to enable scaling and distribution. Windows only supports [spawn start method for multiprocessing](https://docs.python.org/3/library/multiprocessing.html#the-spawn-and-forkserver-start-methods), which has a several caveats. +Jina-serve relies heavily on `multiprocessing` to enable scaling and distribution. Windows only supports [spawn start method for multiprocessing](https://docs.python.org/3/library/multiprocessing.html#the-spawn-and-forkserver-start-methods), which has a several caveats. {ref}`Please follow the guidelines here.` @@ -32,7 +32,7 @@ We've added preliminary support for using Executors listed in the Hub portal. No [Install Docker Desktop on Windows](https://docs.docker.com/desktop/windows/install/) ``` -### `UnicodeEncodeError` on Jina CLI +### `UnicodeEncodeError` on Jina-serve CLI ``` UnicodeEncodeError: 'charmap' codec can't encode character '\u25ae' in position : character maps to diff --git a/docs/index.md b/docs/index.md index 529e26e00517a..8287d196f01e6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -# Welcome to Jina! +# Welcome to Jina-serve! ```{admonition} Survey :class: tip @@ -28,7 +28,7 @@ conda install jina -c conda-forge (build-ai-services)= (build-a-pipeline)= ## Getting Started -Jina supports developers in building AI services and pipelines: +Jina-serve supports developers in building AI services and pipelines: ````{tab} Build AI Services ```{include} ../README.md @@ -101,7 +101,7 @@ Executor Hub allows you to containerize, share, explore and make Executors ready :link-type: doc :class-card: color-gradient-card-2 -Jina AI Cloud is the MLOps platform for hosting Jina projects. +Jina AI Cloud is the MLOps platform for hosting Jina-serve projects. :::: diff --git a/docs/jina-ai-cloud/index.md b/docs/jina-ai-cloud/index.md index 13d544427f3f9..b3895bd5e142e 100644 --- a/docs/jina-ai-cloud/index.md +++ b/docs/jina-ai-cloud/index.md @@ -20,7 +20,7 @@ Executor Hub is an Executor marketplace that allows you to share, explore and te :link: ../concepts/jcloud/index :link-type: doc -JCloud is a cost-efficient hosting platform specifically designed for Jina projects. +JCloud is a cost-efficient hosting platform specifically designed for Jina-serve projects. :::: diff --git a/docs/jina-ai-cloud/login.md b/docs/jina-ai-cloud/login.md index 644e939ffec23..635bf33280384 100644 --- a/docs/jina-ai-cloud/login.md +++ b/docs/jina-ai-cloud/login.md @@ -19,7 +19,7 @@ After log in you can see your name and avatar in the top-right corner. ### Token Management -You can follow the GUI to create/delete personal access tokens for your Jina applications. +You can follow the GUI to create/delete personal access tokens for your Jina-serve applications. ```{figure} pat.png ``` @@ -69,7 +69,7 @@ jina auth token delete ## via Python API -Installed along with Jina, you can leverage the `hubble` package to manage login from Python +Installed along with Jina-serve, you can leverage the `hubble` package to manage login from Python ### Login diff --git a/docs/proto/README.md b/docs/proto/README.md index 1326527983d33..0b0dc1cd4a972 100644 --- a/docs/proto/README.md +++ b/docs/proto/README.md @@ -1,9 +1,9 @@ # Build proto -Jina support two versions of protobuf, before 3.19 and after (which is a breaking change for python), therefore we have +Jina-serve support two versions of protobuf, before 3.19 and after (which is a breaking change for python), therefore we have duplicate python file generation from proto based on the installed protobuf version. -Moreover, jina is compatible with docarray v1 and docarray v2 that introduce breaking change in the proto definition. +Moreover, jina-serve is compatible with docarray v1 and docarray v2 that introduce breaking change in the proto definition. Therefore, we end with 2 proto files, one for each version of docarray that we support. (Note in the future docarray v1 support will be dropped, and we will come back to have proto version) diff --git a/docs/telemetry.md b/docs/telemetry.md index 7d48cc6b277ce..829cc8f89ee48 100644 --- a/docs/telemetry.md +++ b/docs/telemetry.md @@ -6,13 +6,13 @@ To opt out from telemetry, set the `JINA_OPTOUT_TELEMETRY=1` as an environment v Telemetry is the process of collecting data about the usage of a system. This data can be used to improve the system by understanding how it is being used and what areas need improvement. -Jina AI uses telemetry to collect data about how Jina is being used. This data is then used to improve the software. For example, if we see that a lot of users are having trouble with a certain feature, we can improve that feature to make it easier to use. +Jina AI uses telemetry to collect data about how Jina-serve is being used. This data is then used to improve the software. For example, if we see that a lot of users are having trouble with a certain feature, we can improve that feature to make it easier to use. -Telemetry is important for Jina because it allows the team to understand how the software is being used and what areas need improvement. Without telemetry, Jina would not be able to improve as quickly or as effectively. +Telemetry is important for Jina-serve because it allows the team to understand how the software is being used and what areas need improvement. Without telemetry, Jina-serve would not be able to improve as quickly or as effectively. The data collected include: -- Jina and its dependencies versions; +- Jina-serve and its dependencies versions; - A hashed unique user identifier; - A hashed unique session identifier; - Boolean events: start of a Flow, Gateway, Runtime, Client. diff --git a/docs/tutorials/before-you-start.md b/docs/tutorials/before-you-start.md index 38fb234650ce9..2f9cab7346c95 100644 --- a/docs/tutorials/before-you-start.md +++ b/docs/tutorials/before-you-start.md @@ -3,17 +3,17 @@ Before you jump in to any tutorials, we recommend you do the following: -## Understand Jina +## Understand Jina-serve Read through an {ref}`introduction to Jina concepts ` to understand the basic components that will be used in the tutorial. ## Work in a virtual environment -We highly recommend you work in [a virtual environment](https://docs.python.org/3/library/venv.html) to prevent conflicts in packaging versions. This applies not just to Jina, but Python as a whole. +We highly recommend you work in [a virtual environment](https://docs.python.org/3/library/venv.html) to prevent conflicts in packaging versions. This applies not just to Jina-serve, but Python as a whole. -## Install Jina +## Install Jina-serve -For most purposes, you can install Jina with: +For most purposes, you can install Jina-serve with: ```shell pip install jina @@ -23,4 +23,4 @@ For more installation options, see {ref}`our installation guide `. ## Python vs YAML -Jina supports YAML in many circumstances for easier deployment. For more information, see our {ref}`guide on coding in Python and YAML in Jina `. +Jina-serve supports YAML in many circumstances for easier deployment. For more information, see our {ref}`guide on coding in Python and YAML in Jina `. diff --git a/docs/tutorials/deploy-model.md b/docs/tutorials/deploy-model.md index b3dadab7713f4..27a5aadc544dc 100644 --- a/docs/tutorials/deploy-model.md +++ b/docs/tutorials/deploy-model.md @@ -14,7 +14,7 @@ It will *probably* still work for later versions. If you have trouble, please as ## Introduction -In this tutorial we'll build a fast, reliable and scalable gRPC-based AI service. In Jina we call this an {class}`~jina.Executor`. Our Executor will use [Stable Diffusion](https://stability.ai/blog/stable-diffusion-public-release) to generate images from a given text prompt. We'll then use a {class}`~jina.Deployment` to serve it. +In this tutorial we'll build a fast, reliable and scalable gRPC-based AI service. In Jina-serve we call this an {class}`~jina.Executor`. Our Executor will use [Stable Diffusion](https://stability.ai/blog/stable-diffusion-public-release) to generate images from a given text prompt. We'll then use a {class}`~jina.Deployment` to serve it. ![](images/deployment.png) @@ -32,17 +32,17 @@ You can also run this code interactively in [Colab](https://colab.research.googl ## Understand: Executors and Deployments -- All data that goes into and out of Jina is in the form of [Documents](https://docs.docarray.org/user_guide/representing/first_step/) inside a [DocList](https://docs.docarray.org/user_guide/representing/array/) from the [DocArray](https://docs.docarray.org/) package. +- All data that goes into and out of Jina-serve is in the form of [Documents](https://docs.docarray.org/user_guide/representing/first_step/) inside a [DocList](https://docs.docarray.org/user_guide/representing/array/) from the [DocArray](https://docs.docarray.org/) package. - An {ref}`Executor ` is a self-contained gRPC microservice that performs a task on Documents. This could be very simple (like merely capitalizing the entire text of a Document) or a lot more complex (like generating vector embeddings for a given piece of content). - A {ref}`Deployment ` lets you serve your Executor, scale it up with replicas, and allow users to send and receive requests. -When you build a model or service in Jina, it's always in the form of an Executor. An Executor is a Python class that transforms and processes Documents, and can go way beyond image generation, for example, encoding text/images into vectors, OCR, extracting tables from PDFs, or lots more. +When you build a model or service in Jina-serve, it's always in the form of an Executor. An Executor is a Python class that transforms and processes Documents, and can go way beyond image generation, for example, encoding text/images into vectors, OCR, extracting tables from PDFs, or lots more. ## Install prerequisites In this example we need to install: -- The [Jina framework](https://docs.jina.ai/) itself +- The [Jina-serve framework](https://docs.jina.ai/) itself - The dependencies of the specific model we want to serve and deploy ```shell @@ -84,13 +84,13 @@ class TextToImage(Executor): from docarray import DocList, BaseDoc ``` -[Documents](https://docs.docarray.org/user_guide/representing/first_step/) and [DocList](https://docs.docarray.org/user_guide/representing/array/) (from the DocArray package) are Jina's native IO format. +[Documents](https://docs.docarray.org/user_guide/representing/first_step/) and [DocList](https://docs.docarray.org/user_guide/representing/array/) (from the DocArray package) are Jina-serve's native IO format. ```python from jina import Executor, requests ``` -Jina's Executor class and requests decorator - we'll jump into these in the next section. +Jina-serve's Executor class and requests decorator - we'll jump into these in the next section. ```python import numpy as np @@ -124,7 +124,7 @@ class TextToImage(Executor): ).to("cuda") ``` -All Executors are created from Jina's Executor class. User-definable parameters (like `self.pipe`) are {ref}`arguments defined in the `__init__()` method. +All Executors are created from Jina-serve's Executor class. User-definable parameters (like `self.pipe`) are {ref}`arguments defined in the `__init__()` method. ### Requests decorator @@ -193,7 +193,7 @@ In a notebook, you can't use `deployment.block()` and then make requests with th ## Client: Send and receive requests to your service -Use {class}`~jina.Client` to make requests to the service. As before, we use Documents as our basic IO format. We'll use the text prompt `rainbow unicorn butterfly kitten`: +Use {class}`~jina-serve.Client` to make requests to the service. As before, we use Documents as our basic IO format. We'll use the text prompt `rainbow unicorn butterfly kitten`: ```python from jina import Client diff --git a/docs/tutorials/gpu-executor.md b/docs/tutorials/gpu-executor.md index e03c4e348aee9..5117834e98300 100644 --- a/docs/tutorials/gpu-executor.md +++ b/docs/tutorials/gpu-executor.md @@ -13,12 +13,12 @@ reducing response latency by anything from 5 to 100 times, depending on the mode This tutorial assumes familiarity with basic Jina concepts, such as Document, [Executor](../concepts/executor/index), and [Deployment](../concepts/deployment/index). Some knowledge of [Executor Hub](../concepts/executor/hub/index) is also needed for the last part of the tutorial. ``` -## Jina and GPUs in a nutshell +## Jina-serve and GPUs in a nutshell For a thorough walkthrough of using GPU resources in your code, check the full tutorial in the {ref}`next section `. If you already know how to use your GPU, just proceed like you usually would in your machine learning framework of choice. -Jina lets you use GPUs like you would in a Python script or Docker +Jina-serve lets you use GPUs like you would in a Python script or Docker container, without imposing additional requirements or configuration. Here's a minimal working example, written in PyTorch: @@ -131,7 +131,7 @@ the deep learning framework that you use, that might be required (for local exec For the Docker part of the tutorial you will also need to have [Docker](https://docs.docker.com/get-docker/) and [nvidia-docker](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) installed. -To run Python scripts you need a virtual environment (for example [venv](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) or [conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-environments)), and install Jina inside it using: +To run Python scripts you need a virtual environment (for example [venv](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) or [conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-environments)), and install Jina-serve inside it using: ```bash pip install jina @@ -148,7 +148,7 @@ Executor inside a Docker container, or (if you so choose) to publish it to Execu ``` We'll create a simple sentence encoder, and start by creating the Executor -"skeleton" using Jina's CLI: +"skeleton" using Jina-serve's CLI: ```bash jina hub new diff --git a/docs/yaml-spec.md b/docs/yaml-spec.md index 8e9232b022a0a..e43a61bd44050 100644 --- a/docs/yaml-spec.md +++ b/docs/yaml-spec.md @@ -1,7 +1,7 @@ (yaml-spec)= # {octicon}`file-code` YAML Specification -YAML is widely used in Jina to define an Executor, Flow. This page helps you quickly navigate different YAML specifications. +YAML is widely used in Jina-serve to define an Executor, Flow. This page helps you quickly navigate different YAML specifications. ## Executor-level YAML @@ -49,7 +49,7 @@ Gateway specification is nested under the Flow YAML via `with:` keywords. :link: concepts/jcloud/yaml-spec :link-type: doc -Define the resources and autoscaling settings on Jina Cloud +Define the resources and autoscaling settings on Jina-serve Cloud +++ JCloud specification is nested under the Flow YAML via `jcloud:` keywords.