This page shows you how to create and manage AML AI models. Create a model to start AML AI's ML training pipeline. You can use a model to run predictions or backtest across various datasets.
You only need to create the model and export the associated metadata at this point. The other model methods are provided for completeness.
Before you begin
-
To get the permissions that you need to create and manage engine models, ask your administrator to grant you the Financial Services Admin (
financialservices.admin
) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.You might also be able to get the required permissions through custom roles or other predefined roles.
- Create an instance
- Create an engine config
- Create a dataset
Create a model
Some API methods return a long-running operation (LRO). These methods are asynchronous and return an Operation object; for details, see REST Reference. The operation might not be completed when the method returns a response. For these methods, send the request and then check for the result. In general, all POST, PUT, UPDATE, and DELETE operations are long-running.
Send the request
To create a model, use the
projects.locations.instances.models.create
method.
Before using any of the request data, make the following replacements:
PROJECT_ID
: your Google Cloud project ID listed in the IAM SettingsLOCATION
: the location of the instance; use one of the supported regionsShow locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
INSTANCE_ID
: the user-defined identifier for the instanceMODEL_ID
: a user-defined identifier for the modelENGINE_CONFIG_ID
: a user-defined identifier for the engine configDATASET_ID
: the user-defined identifier for the primary dataset used for training this modelTRAINING_END_DATE
: The latest time from which data is used to generate features for training. This date should be the same or earlier than the end time of the primary dataset. Use RFC3339 UTC "Zulu" format (for example,2014-10-02T15:01:23Z
).
Request JSON body:
{ "engineConfig": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineConfigs/ENGINE_CONFIG_ID", "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID", "endTime": "TRAINING_END_DATE" }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
cat > request.json << 'EOF' { "engineConfig": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineConfigs/ENGINE_CONFIG_ID", "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID", "endTime": "TRAINING_END_DATE" } EOF
Then execute the following command to send your REST request:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models?model_id=MODEL_ID"
PowerShell
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
@' { "engineConfig": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineConfigs/ENGINE_CONFIG_ID", "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID", "endTime": "TRAINING_END_DATE" } '@ | Out-File -FilePath request.json -Encoding utf8
Then execute the following command to send your REST request:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models?model_id=MODEL_ID" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": "2023-03-14T15:52:55.358979323Z", "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID", "verb": "create", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
Check for the result
Use the
projects.locations.operations.get
method to check if the model has been created. If the response contains
"done": false
, repeat the command until the response contains "done": true
.
These operations can take a few minutes to several hours to complete.
Before using any of the request data, make the following replacements:
PROJECT_ID
: your Google Cloud project ID listed in the IAM SettingsLOCATION
: the location of the instance; use one of the supported regionsShow locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
OPERATION_ID
: the identifier for the operation
To send your request, choose one of these options:
curl
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
PowerShell
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": "2023-03-14T15:52:55.358979323Z", "endTime": "2023-03-14T16:52:55.358979323Z", "target": "projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID", "verb": "create", "requestedCancellation": false, "apiVersion": "v1" }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.Model", "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID", "createTime": CREATE_TIME, "updateTime": UPDATE_TIME, "state": "ACTIVE", "engineVersion": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineVersions/ENGINE_VERSION_ID", "engineConfig": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineConfigs/ENGINE_CONFIG_ID", "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID", "endTime": "TRAINING_END_DATE", "lineOfBusiness": "RETAIL" } }
Export metadata
To export metadata from a model, use the
projects.locations.instances.models.exportMetadata
method.
For more information, see Exported metadata in the AML output data model.
Before using any of the request data, make the following replacements:
PROJECT_ID
: your Google Cloud project ID listed in the IAM SettingsLOCATION
: the location of the instance; use one of the supported regionsShow locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
INSTANCE_ID
: the user-defined identifier for the instanceMODEL_ID
: the user-defined identifier for the modelBQ_OUTPUT_DATASET_NAME
: a BigQuery dataset in which to export a table that describes the structured metadata of the modelSTRUCTURED_METADATA_TABLE
: the table to write the structured metadata toWRITE_DISPOSITION
: the action that occurs if the destination table already exists; use one of the following values:-
WRITE_EMPTY
: Only export data if the BigQuery table is empty. -
WRITE_TRUNCATE
: Erase all existing data in the BigQuery table before writing to the table.
-
Request JSON body:
{ "structuredMetadataDestination": { "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.STRUCTURED_METADATA_TABLE", "writeDisposition": "WRITE_DISPOSITION" } }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
cat > request.json << 'EOF' { "structuredMetadataDestination": { "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.STRUCTURED_METADATA_TABLE", "writeDisposition": "WRITE_DISPOSITION" } } EOF
Then execute the following command to send your REST request:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID:exportMetadata"
PowerShell
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
@' { "structuredMetadataDestination": { "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.STRUCTURED_METADATA_TABLE", "writeDisposition": "WRITE_DISPOSITION" } } '@ | Out-File -FilePath request.json -Encoding utf8
Then execute the following command to send your REST request:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID:exportMetadata" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": "2023-03-14T15:52:55.358979323Z", "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID", "verb": "exportMetadata", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
For more information on how to get the result of the long-running operation (LRO), see Check for the result.
Get a model
To get a model, use the
projects.locations.instances.models.get
method.
Before using any of the request data, make the following replacements:
PROJECT_ID
: your Google Cloud project ID listed in the IAM SettingsLOCATION
: the location of the instance; use one of the supported regionsShow locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
INSTANCE_ID
: the user-defined identifier for the instanceMODEL_ID
: the user-defined identifier for the model
To send your request, choose one of these options:
curl
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID"
PowerShell
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID", "createTime": "2023-03-14T15:52:55.358979323Z", "updateTime": "2023-03-15T15:52:55.358979323Z", "state": "ACTIVE", "engineVersion": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineVersions/ENGINE_VERSION_ID", "engineConfig": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineConfigs/ENGINE_CONFIG_ID", "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID", "endTime": "TRAINING_END_DATE", "lineOfBusiness": "RETAIL" }
Update a model
To update a model, use the
projects.locations.instances.models.patch
method.
Only the label field in a model can be updated. The following example updates these key-value pair user labels associated with the model.
Before using any of the request data, make the following replacements:
PROJECT_ID
: your Google Cloud project ID listed in the IAM SettingsLOCATION
: the location of the instance; use one of the supported regionsShow locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
INSTANCE_ID
: the user-defined identifier for the instanceMODEL_ID
: a user-defined identifier for the modelKEY
: The key in a key-value pair used to organize models. Seelabels
for more information.VALUE
: The value in a key-value pair used to organize models. Seelabels
for more information.
Request JSON body:
{ "labels": { "KEY": "VALUE" } }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
cat > request.json << 'EOF' { "labels": { "KEY": "VALUE" } } EOF
Then execute the following command to send your REST request:
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID?updateMask=labels"
PowerShell
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
@' { "labels": { "KEY": "VALUE" } } '@ | Out-File -FilePath request.json -Encoding utf8
Then execute the following command to send your REST request:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID?updateMask=labels" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": "2023-03-14T15:52:55.358979323Z", "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID", "verb": "update", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
For more information on how to get the result of the long-running operation (LRO), see Check for the result.
List the models
To list the models for a given instance, use the
projects.locations.instances.models.list
method.
Before using any of the request data, make the following replacements:
PROJECT_ID
: your Google Cloud project ID listed in the IAM SettingsLOCATION
: the location of the instance; use one of the supported regionsShow locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
INSTANCE_ID
: the user-defined identifier for the instance
To send your request, choose one of these options:
curl
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models"
PowerShell
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "models": [ { "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID", "createTime": "2023-03-14T15:52:55.358979323Z", "updateTime": "2023-03-15T15:52:55.358979323Z", "state": "ACTIVE", "engineVersion": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineVersions/ENGINE_VERSION_ID", "engineConfig": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineConfigs/ENGINE_CONFIG_ID", "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID", "endTime": "TRAINING_END_DATE", "lineOfBusiness": "RETAIL" } ] }
Delete a model
To delete a model, use the
projects.locations.instances.models.delete
method.
Before using any of the request data, make the following replacements:
PROJECT_ID
: your Google Cloud project ID listed in the IAM SettingsLOCATION
: the location of the instance; use one of the supported regionsShow locationsus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
INSTANCE_ID
: the user-defined identifier for the instanceMODEL_ID
: the user-defined identifier for the model
To send your request, choose one of these options:
curl
Execute the following command:
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID"
PowerShell
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata", "createTime": "2023-03-14T15:52:55.358979323Z", "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID", "verb": "delete", "requestedCancellation": false, "apiVersion": "v1" }, "done": false }
For more information on how to get the result of the long-running operation (LRO), see Check for the result.