Manage BigQuery ML models in Vertex AI

You can register BigQuery ML models with the Vertex AI Model Registry, in order to manage them alongside your Vertex AI models without needing to export them. When you register models with Model Registry, you can version, evaluate, and deploy the models for online prediction by using a single interface, and without needing a serving container. If you aren't familiar with Vertex AI and how it integrates with BigQuery ML, see Vertex AI for BigQuery users.

To learn more about Vertex AI prediction, see Overview of getting predictions on Vertex AI.

To learn how to manage your BigQuery ML models from Vertex AI Model Registry, see Introduction to Vertex AI Model Registry.

Prerequisites

To register BigQuery ML models to Model Registry, you must meet several prerequisites.

Enable the Vertex AI API

You must enable the Vertex AI API in your project before you register BigQuery ML models to the Model Registry. You can do this by using the APIs & Services page in the Google Cloud console, or by running the following Google Cloud CLI command:

gcloud --project PROJECT_ID services enable aiplatform.googleapis.com

Grant IAM permissions

The service account or user account that you use to register BigQuery ML models to the Model Registry must be granted the Vertex AI Administrator (roles/aiplatform.admin) role. For more information about Vertex AI roles and permissions, see Access control with IAM.

Use the following command to grant the Vertex AI Administrator role to a service account:

gcloud projects add-iam-policy-binding PROJECT_ID --member=serviceAccount:SERVICE_ACCOUNT_EMAIL --role=roles/aiplatform.admin --condition=None

Use the following command to grant the Vertex AI Administrator role to a user account:

gcloud projects add-iam-policy-binding PROJECT_ID --member=user:USER_ACCOUNT --role=roles/aiplatform.admin --condition=None

Register models

When you create a BigQuery ML model you can use the MODEL_REGISTRY option in the CREATE MODEL statement to register the model to the Model Registry. The CREATE MODEL statement also contains the VERTEX_AI_MODEL_ID option for specifying the model ID, and the VERTEX_AI_MODEL_VERSION_ALIASES option for specifying one or more model version aliases, which you can use to streamline deployment, manage models, and enable Vertex Explainable AI Explainable AI on models.

If you set the MODEL_REGISTRY option when creating a model, the model automatically displays in the Model Registry once it has completed training in BigQuery ML. You can use the Source column in the Model Registry page of the Google Cloud console to see where a model is sourced from.

Once a BigQuery ML model is registered, you can use Model Registry capabilities with your model. You can deploy the model to an endpoint, compare model versions, make predictions, monitor the model, and view model evaluations. Additionally, if you want to understand what features contribute to your predictions, you can use Vertex Explainable AI to get feature-based explanations about your model.

All models created using BigQuery ML still display in the BigQuery user interface, regardless of whether they are registered to the Model Registry.

Specify a Vertex AI model ID

To make it easier to manage models, specify a Vertex AI model ID by using the VERTEX_AI_MODEL_ID option when you create the model. The model ID is associated with your BigQuery ML model, and is visible from the Model Registry.

The Vertex AI model ID does not accept uppercase letters. If you don't specify a Vertex AI model ID, the BigQuery ML model ID is used. In this case, make sure the BigQuery ML model ID is also lowercase. To see a full list of the model ID requirements, see the specifications in upload reference documentation.

To update the Vertex AI model ID, you must delete the model and recreate it with the correct new Vertex AI model ID. You cannot update the Vertex AI model ID using the ALTER MODEL command.

Specify a Vertex AI model alias

To specify a model alias, specify the VERTEX_AI_MODEL_VERSION_ALIASES option when you create the model. Model aliases are helpful for fetching or deploying a particular model version by reference without needing to know the specific version ID. In this way, they operate similarly to Docker Tags or Branch references in Git.

To learn more about how Model Registry aliases work, see How to use model version aliases.

Register multiple versions of BigQuery ML models

If you want to create a new version of an existing BigQuery ML model and compare it to others in the Model Registry, you need to specify a different BigQuery ML model ID when you create the model, and then register it to the original Model Registry model ID.

If you create or replace a BigQuery ML model and use a BigQuery ML model ID that is already associated with a model in the Model Registry, the existing Model Registry model version is deleted and replaced with the new model.

Register an existing BigQuery ML model to the Model Registry

BigQuery ML models aren't automatically added to the Model Registry. You can use the ALTER MODEL statement, to add a model ID and register the model to the Model Registry, and also and update metadata like the model description and labels.

To learn more about updating model metadata in BigQuery ML, see Update model metadata.

To register an existing model:

ALTER MODEL [IF EXISTS] <model_name> SET OPTIONS (vertex_ai_model_id="VERTEX_AI_MODEL_ID");

bq update --model --vertex_ai_model_id "VERTEX_AI_MODEL_ID" PROJECT_ID:DATASET.MODEL

  {
    "trainingRuns": [
      {
        "vertexAiModelId": "VERTEX_AI_MODEL_ID"
      }
  }
 ```

If you specify a new model ID when registering the model, the BigQuery ML model displays as model version 1 in the Model Registry. To add the model as a new version of an existing model, specify the existing model's ID. This automatically registers the new model as the latest version of the existing model.

Change the model ID of a registered BigQuery ML model

Once a BigQuery ML model is registered to the Model Registry, you can't change the VERTEX_AI_MODEL_ID value. To register the model with a new VERTEX_AI_MODEL_ID, use one of the following options:

• Delete the model and recreate it, if the re-training cost is acceptable.

• Copy the model, and then use the ALTER MODEL statement to register the new model with a new VERTEX_AI_MODEL_ID value.

Location considerations

If you register a multi-region BigQuery ML model to Model Registry, the model becomes a regional model in Vertex AI. A BigQuery ML US multi-region model is synced to Vertex AI (us-central1) and a BigQuery ML multi-region EU model is synced to Vertex AI (europe-west4). For single region models, there are no changes.

For information about how to update model locations, see Choosing your location.

Delete BigQuery ML models from the Model Registry

To delete a BigQuery ML model from the Model Registry, delete the model in BigQuery ML. The model is automatically removed from the Model Registry.

There are multiple ways you can delete a BigQuery ML model. For more information, see Delete models.

If you want to delete a model in BigQuery ML that has been registered in the Model Registry and deployed to an endpoint, you must first use Model Registry to undeploy the model. You can then return to BigQuery ML and delete the model. For more information on how to undeploy a model, see Delete an endpoint.

What's next

Use the Online prediction with BigQuery ML notebook to train a model using BigQuery ML, register the model to Model Registry, and deploy it to an endpoint for real-time prediction.