Class Model (1.5.0)

Model(
    model_name: str,
    project: Optional[str] = None,
    location: Optional[str] = None,
    credentials: Optional[google.auth.credentials.Credentials] = None,
)

Retrieves the model resource and instantiates its representation.

Parameters

Name	Description
model_name	`str` Required. A fully-qualified model resource name or model ID. Example: "projects/123/locations/us-central1/models/456" or "456" when project and location are initialized or passed.
project	`str` Optional project to retrieve model from. If not set, project set in aiplatform.init will be used.
location	`str` Optional location to retrieve model from. If not set, location set in aiplatform.init will be used.

Inheritance

builtins.object > google.cloud.aiplatform.base.VertexAiResourceNoun > builtins.object > google.cloud.aiplatform.base.FutureManager > google.cloud.aiplatform.base.VertexAiResourceNounWithFutureManager > Model

Properties

container_spec

The specification of the container that is to be used when deploying this Model. Not present for AutoML Models.

description

Description of the model.

predict_schemata

The schemata that describe formats of the Model's predictions and explanations, if available.

supported_deployment_resources_types

List of deployment resource types accepted for this Model.

When this Model is deployed, its prediction resources are described by the prediction_resources field of the objects returned by Endpoint.list_models(). Because not all Models support all resource configuration types, the configuration types this Model supports are listed here.

If no configuration types are listed, the Model cannot be deployed to an Endpoint and does not support online predictions (Endpoint.predict() or Endpoint.explain()). Such a Model can serve predictions by using a BatchPredictionJob, if it has at least one entry each in Model.supported_input_storage_formats and Model.supported_output_storage_formats.

supported_export_formats

The formats and content types in which this Model may be exported. If empty, this Model is not available for export.

For example, if this model can be exported as a Tensorflow SavedModel and have the artifacts written to Cloud Storage, the expected value would be:

{'tf-saved-model': [<ExportableContent.ARTIFACT: 1>]}

supported_input_storage_formats

The formats this Model supports in the input_config field of a BatchPredictionJob. If Model.predict_schemata.instance_schema_uri exists, the instances should be given as per that schema.

Read the docs for more on batch prediction formats

If this Model doesn't support any of these formats it means it cannot be used with a BatchPredictionJob. However, if it has supported_deployment_resources_types, it could serve online predictions by using Endpoint.predict() or Endpoint.explain().

supported_output_storage_formats

The formats this Model supports in the output_config field of a BatchPredictionJob.

If both Model.predict_schemata.instance_schema_uri and Model.predict_schemata.prediction_schema_uri exist, the predictions are returned together with their instances. In other words, the prediction has the original instance data first, followed by the actual prediction content (as per the schema).

Read the docs for more on batch prediction formats

training_job

The TrainingJob that uploaded this Model, if any.

Exceptions

Type	Description
api_core.exceptions.NotFound	If the Model's training job resource cannot be found on the Vertex service.

uri

Path to the directory containing the Model artifact and any of its supporting files. Not present for AutoML Models.

Methods

batch_predict

batch_predict(
    job_display_name: str,
    gcs_source: Optional[Union[str, Sequence[str]]] = None,
    bigquery_source: Optional[str] = None,
    instances_format: str = "jsonl",
    gcs_destination_prefix: Optional[str] = None,
    bigquery_destination_prefix: Optional[str] = None,
    predictions_format: str = "jsonl",
    model_parameters: Optional[Dict] = None,
    machine_type: Optional[str] = None,
    accelerator_type: Optional[str] = None,
    accelerator_count: Optional[int] = None,
    starting_replica_count: Optional[int] = None,
    max_replica_count: Optional[int] = None,
    generate_explanation: Optional[bool] = False,
    explanation_metadata: Optional[
        google.cloud.aiplatform_v1.types.explanation_metadata.ExplanationMetadata
    ] = None,
    explanation_parameters: Optional[
        google.cloud.aiplatform_v1.types.explanation.ExplanationParameters
    ] = None,
    labels: Optional[Dict[str, str]] = None,
    credentials: Optional[google.auth.credentials.Credentials] = None,
    encryption_spec_key_name: Optional[str] = None,
    sync: bool = True,
)

Creates a batch prediction job using this Model and outputs prediction results to the provided destination prefix in the specified predictions_format. One source and one destination prefix are required.

Example usage:

my_model.batch_predict( job_display_name="prediction-123", gcs_source="gs://example-bucket/instances.csv", instances_format="csv", bigquery_destination_prefix="projectId.bqDatasetId.bqTableId" )

Parameters

Name	Description
job_display_name	`str` Required. The user-defined name of the BatchPredictionJob. The name can be up to 128 characters long and can be consist of any UTF-8 characters.
generate_explanation	`bool` Optional. Generate explanation along with the batch prediction results. This will cause the batch prediction output to include explanations based on the `prediction_format`: - `bigquery`: output includes a column named `explanation`. The value is a struct that conforms to the [aiplatform.gapic.Explanation] object. - `jsonl`: The JSON objects on each line include an additional entry keyed `explanation`. The value of the entry is a JSON object that conforms to the [aiplatform.gapic.Explanation] object. - `csv`: Generating explanations for CSV format is not supported.
explanation_metadata	`explain.ExplanationMetadata` Optional. Explanation metadata configuration for this BatchPredictionJob. Can be specified only if `generate_explanation` is set to `True`. This value overrides the value of `Model.explanation_metadata`. All fields of `explanation_metadata` are optional in the request. If a field of the `explanation_metadata` object is not populated, the corresponding field of the `Model.explanation_metadata` object is inherited. For more details, see `Ref docs <http://tinyurl.com/1igh60kt>`
explanation_parameters	`explain.ExplanationParameters` Optional. Parameters to configure explaining for Model's predictions. Can be specified only if `generate_explanation` is set to `True`. This value overrides the value of `Model.explanation_parameters`. All fields of `explanation_parameters` are optional in the request. If a field of the `explanation_parameters` object is not populated, the corresponding field of the `Model.explanation_parameters` object is inherited. For more details, see `Ref docs <http://tinyurl.com/1an4zake>`
encryption_spec_key_name	`Optional[str]` Optional. The Cloud KMS resource identifier of the customer managed encryption key used to protect the model. Has the form: `projects/my-project/locations/my-region/keyRings/my-kr/cryptoKeys/my-key`. The key needs to be in the same region as where the compute resource is created. If set, this Model and all sub-resources of this Model will be secured by this key. Overrides encryption_spec_key_name set in aiplatform.init.

Returns

Type	Description
(jobs.BatchPredictionJob)	Instantiated representation of the created batch prediction job.

deploy

deploy(
    endpoint: Optional[google.cloud.aiplatform.models.Endpoint] = None,
    deployed_model_display_name: Optional[str] = None,
    traffic_percentage: Optional[int] = 0,
    traffic_split: Optional[Dict[str, int]] = None,
    machine_type: Optional[str] = None,
    min_replica_count: int = 1,
    max_replica_count: int = 1,
    accelerator_type: Optional[str] = None,
    accelerator_count: Optional[int] = None,
    service_account: Optional[str] = None,
    explanation_metadata: Optional[
        google.cloud.aiplatform_v1.types.explanation_metadata.ExplanationMetadata
    ] = None,
    explanation_parameters: Optional[
        google.cloud.aiplatform_v1.types.explanation.ExplanationParameters
    ] = None,
    metadata: Optional[Sequence[Tuple[str, str]]] = (),
    encryption_spec_key_name: Optional[str] = None,
    sync=True,
)

Deploys model to endpoint. Endpoint will be created if unspecified.

Parameters

Name	Description
endpoint	`"Endpoint"` Optional. Endpoint to deploy model to. If not specified, endpoint display name will be model display name+'_endpoint'.
deployed_model_display_name	`str` Optional. The display name of the DeployedModel. If not provided upon creation, the Model's display_name is used.
traffic_percentage	`int` Optional. Desired traffic to newly deployed model. Defaults to 0 if there are pre-existing deployed models. Defaults to 100 if there are no pre-existing deployed models. Negative values should not be provided. Traffic of previously deployed models at the endpoint will be scaled down to accommodate new deployed model's traffic. Should not be provided if traffic_split is provided.
traffic_split	`Dict[str, int]` Optional. A map from a DeployedModel's ID to the percentage of this Endpoint's traffic that should be forwarded to that DeployedModel. If a DeployedModel's ID is not listed in this map, then it receives no traffic. The traffic percentage values must add up to 100, or map must be empty if the Endpoint is to not accept any traffic at the moment. Key for model being deployed is "0". Should not be provided if traffic_percentage is provided.
machine_type	`str` Optional. The type of machine. Not specifying machine type will result in model to be deployed with automatic resources.
min_replica_count	`int` Optional. The minimum number of machine replicas this deployed model will be always deployed on. If traffic against it increases, it may dynamically be deployed onto more replicas, and as traffic decreases, some of these extra replicas may be freed.
max_replica_count	`int` Optional. The maximum number of replicas this deployed model may be deployed on when the traffic against it increases. If requested value is too large, the deployment will error, but if deployment succeeds then the ability to scale the model to that many replicas is guaranteed (barring service outages). If traffic against the deployed model increases beyond what its replicas at maximum may handle, a portion of the traffic will be dropped. If this value is not provided, the smaller value of min_replica_count or 1 will be used.
accelerator_type	`str` Optional. Hardware accelerator type. Must also set accelerator_count if used. One of ACCELERATOR_TYPE_UNSPECIFIED, NVIDIA_TESLA_K80, NVIDIA_TESLA_P100, NVIDIA_TESLA_V100, NVIDIA_TESLA_P4, NVIDIA_TESLA_T4
accelerator_count	`int` Optional. The number of accelerators to attach to a worker replica.
service_account	`str` The service account that the DeployedModel's container runs as. Specify the email address of the service account. If this service account is not specified, the container runs as a service account that doesn't have access to the resource project. Users deploying the Model must have the `iam.serviceAccounts.actAs` permission on this service account.
explanation_metadata	`explain.ExplanationMetadata` Optional. Metadata describing the Model's input and output for explanation. Both `explanation_metadata` and `explanation_parameters` must be passed together when used. For more details, see `Ref docs <http://tinyurl.com/1igh60kt>`
explanation_parameters	`explain.ExplanationParameters` Optional. Parameters to configure explaining for Model's predictions. For more details, see `Ref docs <http://tinyurl.com/1an4zake>`
metadata	`Sequence[Tuple[str, str]]` Optional. Strings which should be sent along with the request as metadata.
encryption_spec_key_name	`Optional[str]` Optional. The Cloud KMS resource identifier of the customer managed encryption key used to protect the model. Has the form: `projects/my-project/locations/my-region/keyRings/my-kr/cryptoKeys/my-key`. The key needs to be in the same region as where the compute resource is created. If set, this Model and all sub-resources of this Model will be secured by this key. Overrides encryption_spec_key_name set in aiplatform.init
sync	`bool` Whether to execute this method synchronously. If False, this method will be executed in concurrent Future and any downstream object will be immediately returned and synced when the Future has completed.

Returns

Type	Description
endpoint ("Endpoint")	Endpoint with the deployed model.

export_model

export_model(
    export_format_id: str,
    artifact_destination: Optional[str] = None,
    image_destination: Optional[str] = None,
    sync: bool = True,
)

Exports a trained, exportable Model to a location specified by the user. A Model is considered to be exportable if it has at least one supported_export_formats. Either artifact_destination or image_destination must be provided.

Usage: my_model.export( export_format_id='tf-saved-model' artifact_destination='gs://my-bucket/models/' )

or

my_model.export(
    export_format_id='custom-model'
    image_destination='us-central1-docker.pkg.dev/projectId/repo/image'
)

Parameters

Name	Description
export_format_id	`str` Required. The ID of the format in which the Model must be exported. The list of export formats that this Model supports can be found by calling `Model.supported_export_formats`.
artifact_destination	`str` The Cloud Storage location where the Model artifact is to be written to. Under the directory given as the destination a new one with name "`model-export-<model-display-name>-<timestamp-of-export-call>`", where timestamp is in YYYY-MM-DDThh:mm:ss.sssZ ISO-8601 format, will be created. Inside, the Model and any of its supporting files will be written. This field should only be set when, in [Model.supported_export_formats], the value for the key given in `export_format_id` contains `ARTIFACT`.
image_destination	`str` The Google Container Registry or Artifact Registry URI where the Model container image will be copied to. Accepted forms: - Google Container Registry path. For example: `gcr.io/projectId/imageName:tag`. - Artifact Registry path. For example: `us-central1-docker.pkg.dev/projectId/repoName/imageName:tag`. This field should only be set when, in [Model.supported_export_formats], the value for the key given in `export_format_id` contains `IMAGE`.
sync	`bool` Whether to execute this export synchronously. If False, this method will be executed in concurrent Future and any downstream object will be immediately returned and synced when the Future has completed.

Exceptions

Type	Description
ValueErro	if model does not support exporting.:
ValueErro	if invalid arguments or export formats are provided.:

Returns

Type	Description
output_info (Dict[str, str])	Details of the completed export with output destination paths to the artifacts or container image.

list

list(
    filter: Optional[str] = None,
    order_by: Optional[str] = None,
    project: Optional[str] = None,
    location: Optional[str] = None,
    credentials: Optional[google.auth.credentials.Credentials] = None,
)

List all Model resource instances.

Example Usage:

aiplatform.Model.list( filter='labels.my_label="my_label_value" AND display_name="my_model"', )

Parameters

Name	Description
filter	`str` Optional. An expression for filtering the results of the request. For field names both snake_case and camelCase are supported.
order_by	`str` Optional. A comma-separated list of fields to order by, sorted in ascending order. Use "desc" after a field name for descending. Supported fields: `display_name`, `create_time`, `update_time`
project	`str` Optional. Project to retrieve list from. If not set, project set in aiplatform.init will be used.
location	`str` Optional. Location to retrieve list from. If not set, location set in aiplatform.init will be used.
credentials	`auth_credentials.Credentials` Optional. Custom credentials to use to retrieve list. Overrides credentials set in aiplatform.init.

upload

upload(
    display_name: str,
    serving_container_image_uri: str,
    *,
    artifact_uri: Optional[str] = None,
    serving_container_predict_route: Optional[str] = None,
    serving_container_health_route: Optional[str] = None,
    description: Optional[str] = None,
    serving_container_command: Optional[Sequence[str]] = None,
    serving_container_args: Optional[Sequence[str]] = None,
    serving_container_environment_variables: Optional[Dict[str, str]] = None,
    serving_container_ports: Optional[Sequence[int]] = None,
    instance_schema_uri: Optional[str] = None,
    parameters_schema_uri: Optional[str] = None,
    prediction_schema_uri: Optional[str] = None,
    explanation_metadata: Optional[
        google.cloud.aiplatform_v1.types.explanation_metadata.ExplanationMetadata
    ] = None,
    explanation_parameters: Optional[
        google.cloud.aiplatform_v1.types.explanation.ExplanationParameters
    ] = None,
    project: Optional[str] = None,
    location: Optional[str] = None,
    credentials: Optional[google.auth.credentials.Credentials] = None,
    labels: Optional[Dict[str, str]] = None,
    encryption_spec_key_name: Optional[str] = None,
    sync=True
)

Uploads a model and returns a Model representing the uploaded Model resource.

Example usage:

my_model = Model.upload( display_name='my-model', artifact_uri='gs://my-model/saved-model' serving_container_image_uri='tensorflow/serving' )

Parameters

Name	Description
display_name	`str` Required. The display name of the Model. The name can be up to 128 characters long and can be consist of any UTF-8 characters.
serving_container_image_uri	`str` Required. The URI of the Model serving container.
artifact_uri	`str` Optional. The path to the directory containing the Model artifact and any of its supporting files. Leave blank for custom container prediction. Not present for AutoML Models.
serving_container_predict_route	`str` Optional. An HTTP path to send prediction requests to the container, and which must be supported by it. If not specified a default HTTP path will be used by Vertex AI.
serving_container_health_route	`str` Optional. An HTTP path to send health check requests to the container, and which must be supported by it. If not specified a standard HTTP path will be used by Vertex AI.
description	`str` The description of the model.
instance_schema_uri	`str` Optional. Points to a YAML file stored on Google Cloud Storage describing the format of a single instance, which are used in `PredictRequest.instances`, `ExplainRequest.instances` and `BatchPredictionJob.input_config`. The schema is defined as an OpenAPI 3.0.2 `Schema Object <https://tinyurl.com/y538mdwt#schema-object>`__. AutoML Models always have this field populated by AI Platform. Note: The URI given on output will be immutable and probably different, including the URI scheme, than the one given on input. The output URI will point to a location where the user only has a read access.
parameters_schema_uri	`str` Optional. Points to a YAML file stored on Google Cloud Storage describing the parameters of prediction and explanation via `PredictRequest.parameters`, `ExplainRequest.parameters` and `BatchPredictionJob.model_parameters`. The schema is defined as an OpenAPI 3.0.2 `Schema Object <https://tinyurl.com/y538mdwt#schema-object>`__. AutoML Models always have this field populated by AI Platform, if no parameters are supported it is set to an empty string. Note: The URI given on output will be immutable and probably different, including the URI scheme, than the one given on input. The output URI will point to a location where the user only has a read access.
prediction_schema_uri	`str` Optional. Points to a YAML file stored on Google Cloud Storage describing the format of a single prediction produced by this Model, which are returned via `PredictResponse.predictions`, `ExplainResponse.explanations`, and `BatchPredictionJob.output_config`. The schema is defined as an OpenAPI 3.0.2 `Schema Object <https://tinyurl.com/y538mdwt#schema-object>`__. AutoML Models always have this field populated by AI Platform. Note: The URI given on output will be immutable and probably different, including the URI scheme, than the one given on input. The output URI will point to a location where the user only has a read access.
explanation_metadata	`explain.ExplanationMetadata` Optional. Metadata describing the Model's input and output for explanation. Both `explanation_metadata` and `explanation_parameters` must be passed together when used. For more details, see `Ref docs <http://tinyurl.com/1igh60kt>`
explanation_parameters	`explain.ExplanationParameters` Optional. Parameters to configure explaining for Model's predictions. For more details, see `Ref docs <http://tinyurl.com/1an4zake>`
labels	`Dict[str, str]` Optional. The labels with user-defined metadata to organize your Models. Label keys and values can be no longer than 64 characters (Unicode codepoints), can only contain lowercase letters, numeric characters, underscores and dashes. International characters are allowed. See https://goo.gl/xmQnxf for more information and examples of labels.
encryption_spec_key_name	`Optional[str]` Optional. The Cloud KMS resource identifier of the customer managed encryption key used to protect the model. Has the form: `projects/my-project/locations/my-region/keyRings/my-kr/cryptoKeys/my-key`. The key needs to be in the same region as where the compute resource is created. If set, this Model and all sub-resources of this Model will be secured by this key. Overrides encryption_spec_key_name set in aiplatform.init.

Exceptions

Type	Description
ValueError	If only `explanation_metadata` or `explanation_parameters` is specified.

Returns

Type	Description
model	Instantiated representation of the uploaded model resource.

Class Model (1.5.0)Stay organized with collections Save and categorize content based on your preferences.

Parameters

Inheritance

Properties

container_spec

description

predict_schemata

supported_deployment_resources_types

supported_export_formats

supported_input_storage_formats

supported_output_storage_formats

training_job

uri

Methods

batch_predict

deploy

export_model

list

upload

Class Model (1.5.0)