• Connect to the Ray cluster on Vertex AI through Ray Clientusing the version oftheVertex AI SDK for Pythonthat includes the functionality of theRay Client.Use this option if you prefer an interactive Python development environment.

  • Use the Vertex AI SDK for Python within the Colab Enterprisenotebook in the Google Cloud console.

  • Use the Vertex AI SDK for Python within a Python session, shell, or Jupyternotebook.

• Write a Python script and submit the script to the Ray cluster on Vertex AIusing theRay JobsAPI.If you prefer to submit jobs programmatically, use this option.

Connect to a Ray cluster through Ray Client

To use the interactive Ray client, connect to your Ray cluster onVertex AI. The connecting environment's network depends on the cluster'snetwork configuration. No restrictions apply to the connecting environmentas long as the cluster has public internet access. That is, you didn't specify a VPC networkduring cluster creation. If, however, thecluster is on a private VPC network that peers with Vertex AI, theconnecting environment must be on the same VPC network as the cluster.

The Ray version on the client side must match the cluster's Ray version.pip install "google-cloud-aiplatform[ray]"installs Ray version 2.47 on the client side by default. If thecluster'sRay version is older than, for example, 2.42, then usepip install ray==2.42.0 to match theclient side's Ray version to the cluster's Ray version.

importray# Necessary even if aiplatform.* symbol is not directly used in your program.fromgoogle.cloudimportaiplatformimportvertex_rayimportvertexaivertexai.init()# The CLUSTER_RESOURCE_NAME is the one returned from vertex_ray.create_ray_cluster.CLUSTER_RESOURCE_NAME='projects/{}/locations/{}/persistentResources/{}'.format(PROJECT_ID,LOCATION,CLUSTER_NAME)ray.init('vertex_ray://{}'.format(CLUSTER_RESOURCE_NAME))

Python version:  3.10.12Ray version: 2.47Vertex SDK version: 1.46.0Dashboard: xxxx-dot-us-central1.aiplatform-training.googleusercontent.com

@ray.remotedefsquare(x):print(x)returnx*x# Launch four parallel square tasks.futures=[square.remote(i)foriinrange(4)]print(ray.get(futures))# Returns [0, 1, 4, 9]

Develop an application using the Ray Jobs API

This section describes how to submit a Python program to theRay cluster on Vertex AI using theRay Jobs API.

Write a Python script

Develop your application as a Python script in any text editor. For example,place the following script in amy_script.py file:

importrayimporttime@ray.remotedefhello_world():return"hello world"@ray.remotedefsquare(x):print(x)time.sleep(100)returnx*xray.init()# No need to specify address="vertex_ray://...."print(ray.get(hello_world.remote()))print(ray.get([square.remote(i)foriinrange(4)]))

Submit a Ray job using Python, the Ray Jobs CLI, or the publicRaydashboard address.

importrayimportvertex_rayfromray.job_submissionimportJobSubmissionClientfromgoogle.cloudimportaiplatform# Necessary even if aiplatform.* symbol is not directly used in your program.CLUSTER_RESOURCE_NAME='projects/{}/locations/REGION/persistentResources/{}'.format(PROJECT_ID,CLUSTER_NAME)client=JobSubmissionClient("vertex_ray://{}".format(CLUSTER_RESOURCE_NAME))job_id=client.submit_job(# Entrypoint shell command to executeentrypoint="python my_script.py",# Path to the local directory that contains the my_script.py file.runtime_env={"working_dir":"./directory-containing-my-script","pip":["numpy","setuptools<70.0.0","xgboost","ray==CLUSTER_RAY_VERSION",# pin the Ray version to the same version as the cluster]})# Ensure that the Ray job has been created.print(job_id)

fromray.job_submissionimportJobSubmissionClientimportvertex_rayDASHBOARD_ADDRESS=DASHBOARD_ADDRESSclient=JobSubmissionClient("vertex_ray://{}".format(DASHBOARD_ADDRESS),)job_id=client.submit_job(# Entrypoint shell command to executeentrypoint="python my_script.py",# Path to the local directory that contains the my_script.py fileruntime_env={"working_dir":"./directory-containing-my-script","pip":["numpy","setuptools<70.0.0","xgboost","ray==CLUSTER_RAY_VERSION",# pin the Ray version to the same version as the cluster]})print(job_id)

$rayjobsubmit--working-dir./--addressvertex_ray://{CLUSTER_RESOURCE_NAME}--pythonmy_script.py

After submitting a long running Ray Job, if you want to monitor your job statususingclient.get_job_status(job_id), re-instantiateJobSubmissionClient(client = JobSubmissionClient("vertex_ray://{}".format(CLUSTER_RESOURCE_NAME))) to refresh the authentication token.

Support for VPC peering and custom service account

Ray on Vertex AI supports Ray Client and Ray Jobs API(JobSubmissionClient) in a public network for default service agent and customservice accounts.

The following table shows Ray on Vertex AI support for VPC peering when you create the Ray cluster with the VPC network:

VPC Service Controls (VPC-SC) requires additional configurations.SeePrivate and public connectivity for more details.

Use Network File System (NFS) in your Ray code

If you set anNFS mount whencreating the Ray cluster, read and write those NFS volumes in yourapplication code.

RayClient

This section shows you how to use Network File System (NFS) in your Ray code.

1. Initialize the RayClient in a Python environment

   importrayfromgoogle.cloudimportaiplatformimportvertex_rayaiplatform.init(project=PROJECT_ID,location=REGION)ray.init(address='vertex_ray://projects/{}/locations/us-central1/persistentResources/{}'.format(PROJECT_NUMBER,PERSISTENT_RESOURCE_ID))

2. Run job script

   importrayimportloggingimportosimportsys@ray.remotedefmain():logging.info("list all files in mounted folder")returnos.listdir("/mnt/nfs/test")print(''.join(ray.get(main.remote())))

Submit a Ray job using Python, the Ray Jobs CLI, or the public Raydashboard address. For more information,seeDevelop an application on the Ray cluster on Vertex AI).

What's next

• Use Ray on Vertex AI withBigQuery

• Deploy a model on Vertex AI and get inferences

• View logs for your Ray cluster on Vertex AI

• Delete a Ray cluster