---

name: jina-serve description: "Use Jina-serve to build, serve, orchestrate, call, observe, and deploy AI microservices and pipelines with the jina Python package." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Jina-serve

Use this repo skill when a task involves the jina Python package, Jina-serve, Executor, Deployment, Flow, Gateway, Client, DocArray-based service IO, Jina CLI commands, or Jina cloud-native deployment surfaces.

This skill is self-contained for the versioned Jina-serve package baseline in repo provenance. It does not require the original repository checkout.

Quick start

Install a public package release:

pip install "jina==3.34.1"

For the current latest compatible release, use:

pip install -U jina

Verify the install:

python -c "from jina import Executor, Flow, Deployment, Client, requests; import jina; print(jina.__version__)"
jina --version

For a richer read-only diagnostic, run the bundled helper:

python scripts/check_jina_install.py

Read install and compatibility before changing dependency variants, Python versions, DocArray/Pydantic/Protobuf/GRPC pins, or optional service extras.

Route by task

• Use cli-and-configuration for install variants, CLI command selection, jina help, jina -vf, YAML/JAML, environment variables, telemetry opt-out, schemas, autocomplete, and parser inspection.
• Use executor-service-patterns to write Executor classes, @requests endpoints, DocArray schemas, standalone Deployments, dynamic batching, Executor templates, Hub packaging, and GPU-executor prerequisites.
• Use orchestration-and-deployment for multi-Executor Flows, Gateway protocols, Flow/Deployment YAML, readiness/profiling, replicas/shards, topology decisions, and static exports to Docker Compose or Kubernetes YAML.
• Use client-and-protocols for Client construction, request batching, async/streaming calls, retries, callbacks, parameters, target executors, protocol/TLS mismatches, and response handling.
• Use observability-and-production for health checks, monitoring, OpenTelemetry, Prometheus/Grafana, Docker Compose operations, Kubernetes/JCloud/Hub boundaries, custom Gateway/FastAPI surfaces, and production troubleshooting.

Public API anchors

Common public imports verified for this baseline:

from jina import Executor, Flow, Deployment, Client, requests
from jina import dynamic_batching, monitor
from docarray import BaseDoc, DocList

The core mental model:

1. Define document schemas with DocArray BaseDoc and DocList.
2. Implement service logic in an Executor subclass and expose methods with @requests.
3. Serve one Executor with Deployment, or compose several services with Flow.
4. Expose traffic through a Gateway using gRPC, HTTP, WebSocket, or multi-protocol settings.
5. Send data with Client.post() or streaming/async client APIs.
6. Add observability, health checks, container/cloud deployment, and credentials only when the target environment requires them.

Read API overview for signatures and route ownership.

Common decisions

• Prefer explicit Client usage for production callers; Flow.post() and Deployment.post() are convenient for local debugging while the object is in scope.
• Use YAML for production Deployment/Flow definitions when you need reproducible config independent of Python service logic.
• Keep user model dependencies in the Executor project requirements, not in the global Jina install. Jina orchestrates services but does not choose torch, TensorFlow, diffusers, or GPU wheels for you.
• Treat Docker, Kubernetes, JCloud, Hub, and full OpenTelemetry stacks as optional operational surfaces that may need credentials, Docker/K8s clusters, network access, or long-running services.

Troubleshooting first stops

• Cross-cutting install/import/runtime issues: root troubleshooting.
• CLI/YAML/env issues: CLI troubleshooting.
• Executor/Deployment errors: Executor troubleshooting.
• Flow/Gateway topology or export errors: Flow troubleshooting.
• Client/protocol/retry issues: Client troubleshooting.
• Production/observability/cloud issues: Production troubleshooting.