Run notebook executions with parameters

Vertex AI Workbench managed notebooks instances let you use parameter values in your notebook executions to specify differences in how your notebook file's code runs. This page describes how to set up your notebook file to use parameters and how to run executions that specify different values for your notebook parameters.

Use parameters to run different iterations of your notebook file

You can use notebook parameter values in your executions to run the same notebook code while specifying differences like the following:

  • Specify a different dataset to use, or a different sample size of the dataset.

  • Specify different model configurations such as learning rate or optimizer type.

  • Run different models, or run different versions of the same model.

How to use parameters in a notebook execution

The process for executing a notebook with parameters has two main steps:

  1. Add the parameters tag to one of your notebook file's cells. While this isn't a technical requirement, this cell typically contains code that assigns values to your parameter variables, though this is not a technical requirement. If you don't assign different parameter values in your execution, the execution uses the parameter values in your notebook file as default values.

  2. Create an execution for your notebook file that includes new values for your parameters. Use the following pattern to format your parameters and their values: parameter1=value1,parameter2=value2. The format requires commas between parameter-value pairs, no spaces, and no quotation marks. When your execution runs, the executor adds a cell to the notebook that updates the values of your parameters directly following the cell that is tagged parameters.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Notebooks and Vertex AI APIs.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Notebooks and Vertex AI APIs.

    Enable the APIs

    8.
  8. If you haven't already, create a managed notebooks instance.

Required roles

To ensure that your instance's service account has the necessary permissions to interact with the Vertex AI Workbench executor, ask your administrator to grant your instance's service account the following IAM roles on the project:

For more information about granting roles, see Manage access to projects, folders, and organizations.

Your administrator might also be able to give your instance's service account the required permissions through custom roles or other predefined roles.

Open JupyterLab

To open JupyterLab and prepare a notebook file to run, complete the following steps.

  1. Open JupyterLab.

  2. Upload a notebook (ipynb) file, open an existing file, or open a new notebook file and add the code that you want to run to the new notebook.

  3. Make sure your notebook file's code meets the requirements for using the executor.

Add the parameters tag to a notebook cell

  1. In your managed notebooks instance's JupyterLab user interface, open the notebook file that you want to run.

  2. Write code in one cell that assigns values to your parameter variables. These are the values your notebook file uses if you don't assign different parameter values in your execution.

  3. Make sure your parameters cell is still selected, and then in the right sidebar, click the  Property inspector.

  4. In the property inspector, in the Cell Tags section, click Add Tag, enter parameters, and then press Enter.

Provide parameter values for your execution

  1. In your managed notebooks instance's JupyterLab user interface, click the  Executor button.

  2. In the Submit notebooks to Executor dialog, enter a name for your execution in the Execution name field.

  3. Select a Machine type and Accelerator type.

  4. Select an Environment.

  5. In the Type field, select One-time execution, or select Schedule-based recurring executions, and complete the dialog for scheduling executions.

  6. In Advanced options, select the Region where you want to run your notebook.

  7. In the Cloud Storage bucket field, select an available Cloud Storage bucket or enter a name for a new bucket and click Create and select. The executor stores your notebook output in this Cloud Storage bucket.

  8. In the Notebook parameterization section and the Input parameters text box, add notebook parameters separated by commas, for example optimizer=SGD,learning_rate=0.01. The format requires that there are no spaces and no quotation marks.

  9. Configure the rest of your execution, and then click Submit.

What's next