Package: google-cloud-aiplatform
Vertex AI: Google Vertex AI is an integrated suite of machine learning tools and services for building and using ML models with AutoML or custom code. It offers both novices and experts the best workbench for the entire machine learning development lifecycle.Client Library DocumentationProduct DocumentationQuick StartIn order to use this library, you first need to go through the following steps:Select or create a Cloud Platform project.Enable billing for your project.Enable the Vertex AI API.Setup Authentication.InstallationInstall this library in avirtualenvusing pip.virtualenvis a tool to
create isolated Python environments. The basic problem it addresses is one of
dependencies and versions, and indirectly permissions.Withvirtualenv, it’s possible to install this library without needing system
install permissions, and without clashing with the installed system
dependencies.Mac/Linuxpip install virtualenv
virtualenv <your-env>
source <your-env>/bin/activate
<your-env>/bin/pip install google-cloud-aiplatformWindowspip install virtualenv
virtualenv <your-env>
<your-env>\Scripts\activate
<your-env>\Scripts\pip.exe install google-cloud-aiplatformSupported Python VersionsPython >= 3.8Deprecated Python VersionsPython <= 3.7.The last version of this library compatible with Python 3.6 is google-cloud-aiplatform==1.12.1.OverviewThis section provides a brief overview of the Vertex AI SDK for Python. You can also reference the notebooks invertex-ai-samplesfor examples.All publicly available SDK features can be found in thegoogle/cloud/aiplatformdirectory.
Under the hood, Vertex SDK builds on top of GAPIC, which stands for Google API CodeGen.
The GAPIC library code sits ingoogle/cloud/aiplatform_v1andgoogle/cloud/aiplatform_v1beta1,
and it is auto-generated from Google’s service proto files.For most developers’ programmatic needs, they can follow these steps to figure out which libraries to import:Look throughgoogle/cloud/aiplatformfirst – Vertex SDK’s APIs will almost always be easier to use and more concise comparing with GAPICIf the feature that you are looking for cannot be found there, look throughaiplatform_v1to see if it’s available in GAPICIf it is still in beta phase, it will be available inaiplatform_v1beta1If none of the above scenarios could help you find the right tools for your task, please feel free to open a github issue and send us a feature request.ImportingVertex AI SDK resource based functionality can be used by importing the following namespace:fromgoogle.cloudimportaiplatformVertex AI SDK preview functionality can be used by importing the following namespace:fromvertexaiimportpreviewVertex AI SDK general availability (GA) functionality can be used by importing the following namespace:importvertexaiInitializationInitialize the SDK to store common configurations that you use with the SDK.aiplatform.init(# your Google Cloud Project ID or number# environment default used is not setproject='my-project',# the Vertex AI region you will use# defaults to us-central1location='us-central1',# Google Cloud Storage bucket in same region as location# used to stage artifactsstaging_bucket='gs://my_staging_bucket',# custom google.auth.credentials.Credentials# environment default credentials used if not setcredentials=my_credentials,# customer managed encryption key resource name# will be applied to all Vertex AI resources if setencryption_spec_key_name=my_encryption_key_name,# the name of the experiment to use to track# logged metrics and parametersexperiment='my-experiment',# description of the experiment aboveexperiment_description='my experiment description')DatasetsVertex AI provides managed tabular, text, image, and video datasets. In the SDK, datasets can be used downstream to
train models.To create a tabular dataset:my_dataset=aiplatform.TabularDataset.create(display_name="my-dataset",gcs_source=['gs://path/to/my/dataset.csv'])You can also create and import a dataset in separate steps:fromgoogle.cloudimportaiplatformmy_dataset=aiplatform.TextDataset.create(display_name="my-dataset")my_dataset.import_data(gcs_source=['gs://path/to/my/dataset.csv'],import_schema_uri=aiplatform.schema.dataset.ioformat.text.multi_label_classification)To get a previously created Dataset:dataset=aiplatform.ImageDataset('projects/my-project/location/us-central1/datasets/{DATASET_ID}')Vertex AI supports a variety of dataset schemas. References to these schemas are available under theaiplatform.schema.datasetnamespace. For more information on the supported dataset schemas please refer to thePreparing data docs.TrainingThe Vertex AI SDK for Python allows you train Custom and AutoML Models.You can train custom models using a custom Python script, custom Python package, or container.Preparing Your Custom CodeVertex AI custom training enables you to train on Vertex AI datasets and produce Vertex AI models. To do so your
script must adhere to the following contract:It must read datasets from the environment variables populated by the training service:os.environ['AIP_DATA_FORMAT']# provides format of dataos.environ['AIP_TRAINING_DATA_URI']# uri to training splitos.environ['AIP_VALIDATION_DATA_URI']# uri to validation splitos.environ['AIP_TEST_DATA_URI']# uri to test splitPlease visitUsing a managed dataset in a custom training applicationfor a detailed overview.It must write the model artifact to the environment variable populated by the training service:os.environ['AIP_MODEL_DIR']Running Trainingjob=aiplatform.CustomTrainingJob(display_name="my-training-job",script_path="training_script.py",container_uri="us-docker.pkg.dev/vertex-ai/training/tf-cpu.2-2:latest",requirements=["gcsfs==0.7.1"],model_serving_container_image_uri="us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-2:latest",)model=job.run(my_dataset,replica_count=1,machine_type="n1-standard-4",accelerator_type='NVIDIA_TESLA_K80',accelerator_count=1)In the code block abovemy_datasetis managed dataset created in theDatasetsection above. Themodelvariable is a managed Vertex AI model that can be deployed or exported.AutoMLsThe Vertex AI SDK for Python supports AutoML tabular, image, text, video, and forecasting.To train an AutoML tabular model:dataset=aiplatform.TabularDataset('projects/my-project/location/us-central1/datasets/{DATASET_ID}')job=aiplatform.AutoMLTabularTrainingJob(display_name="train-automl",optimization_prediction_type="regression",optimization_objective="minimize-rmse",)model=job.run(dataset=dataset,target_column="target_column_name",training_fraction_split=0.6,validation_fraction_split=0.2,test_fraction_split=0.2,budget_milli_node_hours=1000,model_display_name="my-automl-model",disable_early_stopping=False,)ModelsTo get a model:model=aiplatform.Model('/projects/my-project/locations/us-central1/models/{MODEL_ID}')To upload a model:model=aiplatform.Model.upload(display_name='my-model',artifact_uri="gs://python/to/my/model/dir",serving_container_image_uri="us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-2:latest",)To deploy a model:endpoint=model.deploy(machine_type="n1-standard-4",min_replica_count=1,max_replica_count=5machine_type='n1-standard-4',accelerator_type='NVIDIA_TESLA_K80',accelerator_count=1)Please visitImporting models to Vertex AIfor a detailed overview:Model EvaluationThe Vertex AI SDK for Python currently supports getting model evaluation metrics for all AutoML models.To list all model evaluations for a model:model=aiplatform.Model('projects/my-project/locations/us-central1/models/{MODEL_ID}')evaluations=model.list_model_evaluations()To get the model evaluation resource for a given model:model=aiplatform.Model('projects/my-project/locations/us-central1/models/{MODEL_ID}')# returns the first evaluation with no arguments, you can also pass the evaluation IDevaluation=model.get_model_evaluation()eval_metrics=evaluation.metricsYou can also create a reference to your model evaluation directly by passing in the resource name of the model evaluation:evaluation=aiplatform.ModelEvaluation(evaluation_name='projects/my-project/locations/us-central1/models/{MODEL_ID}/evaluations/{EVALUATION_ID}')Alternatively, you can create a reference to your evaluation by passing in the model and evaluation IDs:evaluation=aiplatform.ModelEvaluation(evaluation_name={EVALUATION_ID},model_id={MODEL_ID})Batch PredictionTo create a batch prediction job:model=aiplatform.Model('/projects/my-project/locations/us-central1/models/{MODEL_ID}')batch_prediction_job=model.batch_predict(job_display_name='my-batch-prediction-job',instances_format='csv',machine_type='n1-standard-4',gcs_source=['gs://path/to/my/file.csv'],gcs_destination_prefix='gs://path/to/my/batch_prediction/results/',service_account='my-sa@my-project.iam.gserviceaccount.com')You can also create a batch prediction job asynchronously by including thesync=Falseargument:batch_prediction_job=model.batch_predict(...,sync=False)# wait for resource to be createdbatch_prediction_job.wait_for_resource_creation()# get the statebatch_prediction_job.state# block until job is completebatch_prediction_job.wait()EndpointsTo create an endpoint:endpoint=aiplatform.Endpoint.create(display_name='my-endpoint')To deploy a model to a created endpoint:model=aiplatform.Model('/projects/my-project/locations/us-central1/models/{MODEL_ID}')endpoint.deploy(model,min_replica_count=1,max_replica_count=5,machine_type='n1-standard-4',accelerator_type='NVIDIA_TESLA_K80',accelerator_count=1)To get predictions from endpoints:endpoint.predict(instances=[[6.7,3.1,4.7,1.5],[4.6,3.1,1.5,0.2]])To undeploy models from an endpoint:endpoint.undeploy_all()To delete an endpoint:endpoint.delete()PipelinesTo create a Vertex AI Pipeline run and monitor until completion:# Instantiate PipelineJob objectpl=PipelineJob(display_name="My first pipeline",# Whether or not to enable caching# True = always cache pipeline step result# False = never cache pipeline step result# None = defer to cache option for each pipeline component in the pipeline definitionenable_caching=False,# Local or GCS path to a compiled pipeline definitiontemplate_path="pipeline.json",# Dictionary containing input parameters for your pipelineparameter_values=parameter_values,# GCS path to act as the pipeline rootpipeline_root=pipeline_root,)# Execute pipeline in Vertex AI and monitor until completionpl.run(# Email address of service account to use for the pipeline run# You must have iam.serviceAccounts.actAs permission on the service account to use itservice_account=service_account,# Whether this function call should be synchronous (wait for pipeline run to finish before terminating)# or asynchronous (return immediately)sync=True)To create a Vertex AI Pipeline without monitoring until completion, usesubmitinstead ofrun:# Instantiate PipelineJob objectpl=PipelineJob(display_name="My first pipeline",# Whether or not to enable caching# True = always cache pipeline step result# False = never cache pipeline step result# None = defer to cache option for each pipeline component in the pipeline definitionenable_caching=False,# Local or GCS path to a compiled pipeline definitiontemplate_path="pipeline.json",# Dictionary containing input parameters for your pipelineparameter_values=parameter_values,# GCS path to act as the pipeline rootpipeline_root=pipeline_root,)# Submit the Pipeline to Vertex AIpl.submit(# Email address of service account to use for the pipeline run# You must have iam.serviceAccounts.actAs permission on the service account to use itservice_account=service_account,)Explainable AI: Get MetadataTo get metadata in dictionary format from TensorFlow 1 models:fromgoogle.cloud.aiplatform.explain.metadata.tf.v1importsaved_model_metadata_builderbuilder=saved_model_metadata_builder.SavedModelMetadataBuilder('gs://python/to/my/model/dir',tags=[tf.saved_model.tag_constants.SERVING])generated_md=builder.get_metadata()To get metadata in dictionary format from TensorFlow 2 models:fromgoogle.cloud.aiplatform.explain.metadata.tf.v2importsaved_model_metadata_builderbuilder=saved_model_metadata_builder.SavedModelMetadataBuilder('gs://python/to/my/model/dir')generated_md=builder.get_metadata()To use Explanation Metadata in endpoint deployment and model upload:explanation_metadata=builder.get_metadata_protobuf()# To deploy a model to an endpoint with explanationmodel.deploy(...,explanation_metadata=explanation_metadata)# To deploy a model to a created endpoint with explanationendpoint.deploy(...,explanation_metadata=explanation_metadata)# To upload a model with explanationaiplatform.Model.upload(...,explanation_metadata=explanation_metadata)Cloud ProfilerCloud Profiler allows you to profile your remote Vertex AI Training jobs on demand and visualize the results in Vertex AI Tensorboard.To start using the profiler with TensorFlow, update your training script to include the following:fromgoogle.cloud.aiplatform.training_utilsimportcloud_profiler...cloud_profiler.init()Next, run the job with with a Vertex AI TensorBoard instance. For full details on how to do this, visithttps://cloud.google.com/vertex-ai/docs/experiments/tensorboard-overviewFinally, visit your TensorBoard in your Google Cloud Console, navigate to the “Profile” tab, and click theCapture Profilebutton. This will allow users to capture profiling statistics for the running jobs.Next StepsRead theClient Library Documentationfor Vertex AI
API to see other available methods on the client.Read theVertex AI API Product documentationto learn
more about the product and see How-to Guides.View thisREADMEto see the full list of Cloud
APIs that we cover.