API

API reference

This documentation covers using the Anyscale Ray Client through the ray.init API, which only works on Ray 1.5 or higher. If you're on an older version of Ray, see the reference for the Anyscale Client Builder API.

Connection Options

To connect to a cluster using the Anyscale Ray Client you can run ray.init("anyscale://cluster_name"). Anyscale will automatically detect your laptop's ray and python versions and start a compatible cluster with a cluster environment that has the same ray/python versions as your laptop.

To create or connect to a Ray cluster, use ray.init(url). The URL can be provided explicitly in the code or by setting the RAY_ADDRESS environment variable. For example:

1)

# script.py
import ray
ray.init()

and then run RAY_ADDRESS=anyscale://cluster_name python script.py is equivalent to

2)

# script.py
import ray
ray.init("anyscale://cluster_name")

and then run python script.py

Keyword Arguments

You can configure your connection using keyword arguments in your call to ray.init. For example:

ray.init("anyscale://myCluster", job_name="production_job", cloud="aws_test_cloud")

The following keyword arguments are supported:

Keyword Argument	Description	Example values
update (bool)	Whether to update cluster configurations when connecting to an existing cluster. Note that this may restart the Ray runtime. By default, update is set to False.	True
cluster_compute (str or dict)	Name of the cluster compute to use or a dictionary to build a new cluster compute.	"my_cluster_compute", {"cloud_id": "1234", ... }
cluster_env (str or dict)	The name (and optionally revision) of the cluster environment or a dictionary to build a new cluster environment. If no revision is specified, use the latest revision.	"prev_created_cluster_env:2", {"base_image": "anyscale/ray-ml:1.1.0-gpu"}
runtime_env (dict)	A python dictionary with runtime environment specifications.	{"pip": "./requirements.txt"}, {"conda": "conda.yaml"}, {"working_dir": "/tmp/test", "pip": ["chess"]}
cloud (str)	The name of the cloud to start the cluster in.	"aws_test_account"
project_dir (str)	Path to the project code directory. If not specified, the project directory will be autodetected based on the current working directory. If no Anyscale project is found, a "scratch" project will be used. In general the project directory will be synced to all nodes in the cluster at /tmp/ray/session_latest /runtime_resources/_ray_pkg_<hash>. Ray workers will start in this directory, so when working with files, you may use relative filepaths in your remote task and actor definitions, and your code will work in the same way whether running locally or on your cluster. By default, ".git", "__pycache__", and "venv" are excluded from being uploaded, along with the contents of any ".gitignore" file in the directory. Note: if working_dir is specified in runtime_env, that directory is synced instead of project_dir.	"~/my-proj-dir"
project_name (str)	Optional name to use if the project for the directory specified by `project_dir` doesn't already exist.	"my_project"
request_cpus (int)	The initial number of CPUs to scale to. The cluster will immediately scale to accommodate the requested number of CPUS, bypassing normal upscaling speed constraints. The requested CPUs are pinned and exempt from downscaling.	8
request_gpus (int)	The initial number of GPUs to scale to. The cluster will immediately scale to accommodate the requested number of GPUS, bypassing normal upscaling speed constraints. The requested GPUs are pinned and exempt from downscaling.	2
request_bundles (list)	A list of initial resource bundles to scale to. Each bundle is a dictionary mapping a resource name to a quantity that can be allocated on a single machine. The cluster will immediately scale to accommodate the requested resources, bypassing normal upscaling speed constraints. The requested resources are pinned and exempt from downscaling.	[{"CPU": 8}, {"GPU": 8}, {"GPU": 1}]
autosuspend (int or str)	Either an integer representing the number of minutes before the cluster autosuspends (after being idle), or a string with "h" or "m" representing the number of hours or minutes before the cluster autosuspends respectively.	90 (90 minutes), "120m" (120 minutes), "4h" (4 hours), -1 (disabled)
job_name (str)	The name of the job, which will be shown in the UI. This name is only used for display purposes.	"production_job"
namespace (str)	The name of the namespace to run this cluster in.	"training_namespace"

ClientContext

Calling ray.init("anyscale://...") returns a ClientContext object. This object provides information about the cluster (Ray version, Python version, and a URL to the Ray dashboard). The ClientContext also provides a disconnect() method that will disconnect from the current cluster. Finally, you may also use ClientContext as a context manager, which will automatically call disconnect() for you after the with block is complete.

context = ray.init("anyscale://cluster1")
... # Computation in Cluster 1
context.disconnect() # Manually disconnect

# Start client using a `with` statement
with ray.init("anyscale://cluster2") as c2:
    ... # Computation in Cluster 2
# Automatically disconnect from cluster 2 after exiting the `with` block