How to Set and Use Run Names in Vertex AI Experiments

What will you learn?

In this tutorial, you will learn how to effectively name and manage runs within experiments using Google Cloud’s Vertex AI platform. By setting up run names, you can efficiently organize and track different iterations of your machine learning models, making it easier to compare performances across various trials.

Introduction to Setting Up Run Names in Vertex AI Experiments

Managing machine learning experiments involves tracking multiple runs with varying parameters and configurations. In the context of Google Cloud’s Vertex AI, setting up run names is essential for categorizing and organizing these trials under specific experiments. This guide will walk you through the process of creating named runs within an experiment using Python client for Google Cloud�s Vertex AI.

Short Intro

Organizing experiment versions efficiently is crucial for enhancing productivity in machine learning projects. By establishing clear run names in Vertex AI experiments, you can streamline the monitoring and evaluation of model performance throughout different iterations.

Understanding the Problem and Solution

Working on machine learning projects on platforms like Google Cloud’s Vertex AI requires a structured approach to manage experimentation processes effectively. With each experiment run potentially involving distinct hyperparameters, datasets, or model architectures, manually tracking these variations can be challenging. Setting up run names provides a solution by allowing us to neatly categorize different trials under their respective experiments.

To address this challenge, we will utilize the Python client for Google Cloud�s Vertex AI. The step-by-step solution involves initializing the project environment, creating an experiment, and then establishing named runs within that experiment�each representing a specific trial or version of our model. This organized method not only simplifies comparison between different runs but also facilitates efficient management of experimental variations.


from import aiplatform

def create_experiment_run(project_id: str, location: str,
                          experiment_name: str, run_name: str):
    # Initialize the client with your project ID and location
    aiplatform.init(project=project_id, location=location)

    # Create or get an existing experiment
    experiment = aiplatform.Experiment(experiment_name)

    # Start a new run within the specified experiment with our chosen name 
    run = experiment.start_run(run_name=run_name)

    # Your model training code goes here 
    # For demonstration purposes we're keeping it simple

    # End the current run once training is complete

# Example usage:
project_id = 'your-google-cloud-project-id'
location = 'us-central1'  # Example location
experiment_name = 'my-first-experiment'
run_name = 'experiment-run-001'


# Copyright PHD


In this script:

  1. Initialize Client: Begin by initializing the aiplatform client with your GCP project ID and preferred location.
  2. Create/Get Experiment: Instantiate an Experiment object by either creating a new one or retrieving an existing one based on experiment_name.
  3. Start New Run: Within the Experiment, use start_run() to initiate a new named container for operations related to that specific iteration.
  4. Model Training Placeholder: Include your model training logic at this stage.
  5. End Run: Conclude operations associated with that particular run using the end() method.

By structuring each experimental trial within its designated named run as shown above, you can maintain organization and facilitate easy retrieval for performance evaluation or further analysis later on.

  1. How do I install the required library?

  2. To install the necessary library, execute:

  3. pip install google-cloud-aiplatform
  4. # Copyright PHD
  5. Can I list all runs within an Experiment?

  6. Yes! Utilize aiplatform.Experiment.list_runs() after initializing your environment as demonstrated earlier.

  7. Is it possible to add custom tags or labels to my Runs?

  8. Certainly! When starting your run (start_run()), additional metadata such as tags can be included through parameters like description=”My detailed description”.

  9. What if I forget my Run Name?

  10. You can retrieve details about each available runtime including their names using methods like .list_runs() mentioned previously.

  11. Can I delete a Run?

  12. Yes! Delete runs via .delete_run(run_identifier) method from the Experiment object context.

  13. How do I compare different Runs?

  14. Vertex AI offers tools like TensorBoard integration for visual comparisons among other techniques based on logged metrics during execution phases.

  15. Can multiple users access these Experiments & Runs?

  16. With appropriate IAM permissions at project or resource level granted to users; yes!

  17. Are there any limitations on Naming Conventions?

  18. While relatively flexible; avoid excessively long names (>128 chars), special characters beyond hyphens & underscores _, leading numerics/trailing spaces for smooth operation.

  19. What happens if I try creating a Run with an already existing name?

  20. The API enforces unique naming; attempting duplication would trigger an error prompting selection of another identifier unless handling data overwrite scenarios explicitly in code logic beforehand.


Efficiently naming and organizing runs within experiments plays a vital role in optimizing machine learning workflows on platforms like Google Cloud�s Vertex AI. By structuring experimental iterations systematically through named runs, you enable seamless tracking of progress over time�whether adjusting hyperparameters or exploring diverse algorithmic approaches against shared datasets/metrics frameworks established early-on during exploratory phases.

Leave a Comment