ray.serve.get_deployment_handle#

ray.serve.get_deployment_handle(deployment_name: str, app_name: str | None = None, _check_exists: bool = True, _record_telemetry: bool = True) → DeploymentHandle[source]#

Get a handle to a deployment by name.

This is a developer API and is for advanced Ray users and library developers.

Parameters:

  • deployment_name – Name of deployment to get a handle to.

  • app_name – Application in which deployment resides. If calling from inside a Serve application and app_name is not specified, this will default to the application from which this API is called.

Raises:

RayServeException – If no Serve controller is running, or if calling from outside a Serve application and no application name is specified.

The following example gets the handle to the ingress deployment of an application, which is equivalent to using serve.get_app_handle.

import ray
from ray import serve

@serve.deployment
def f(val: int) -> int:
    return val * 2

serve.run(f.bind(), name="my_app")
handle = serve.get_deployment_handle("f", app_name="my_app")
assert handle.remote(3).result() == 6

serve.shutdown()

The following example demonstrates how you can use this API to get the handle to a non-ingress deployment in an application.

import ray
from ray import serve
from ray.serve.handle import DeploymentHandle

@serve.deployment
class Multiplier:
    def __init__(self, multiple: int):
        self._multiple = multiple

    def __call__(self, val: int) -> int:
        return val * self._multiple

@serve.deployment
class Adder:
    def __init__(self, handle: DeploymentHandle, increment: int):
        self._handle = handle
        self._increment = increment

    async def __call__(self, val: int) -> int:
        return await self._handle.remote(val) + self._increment


# The app calculates 2 * x + 3
serve.run(Adder.bind(Multiplier.bind(2), 3), name="math_app")
handle = serve.get_app_handle("math_app")
assert handle.remote(5).result() == 13

# Get handle to Multiplier only
handle = serve.get_deployment_handle("Multiplier", app_name="math_app")
assert handle.remote(5).result() == 10

serve.shutdown()

DeveloperAPI: This API may change across minor Ray releases.