建立及管理模型

本頁說明如何建立及管理 AML AI 模型。建立模型，啟動 AML AI 的機器學習訓練管道。您可以使用模型對各種資料集執行預測或回溯測試。

此時您只需要建立模型，並匯出相關聯的中繼資料。提供其他模型方法是為了完整性。

事前準備

建立模型

部分 API 方法會傳回長時間執行的作業 (LRO)。這些方法是以非同步方式執行，並會傳回 Operation 物件。詳情請參閱「REST 參考資料」。方法傳回回應時，作業可能尚未完成。對於這些方法，請先傳送要求，然後檢查結果。一般來說，所有 POST、PUT、UPDATE 和 DELETE 作業都是長時間執行的作業。

傳送要求

如要建立模型，請使用 projects.locations.instances.models.create 方法。

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 「身分與存取權管理設定」中列出的專案 ID
  • LOCATION：執行個體的位置；請使用支援的區域之一。
    顯示地區
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID：使用者定義的執行個體 ID
  • MODEL_ID：使用者定義的模型 ID
  • ENGINE_CONFIG_ID：引擎設定的使用者定義 ID
  • DATASET_ID：使用者定義的 ID，用於訓練這個模型的主要資料集
  • TRAINING_END_DATE：系統用來產生訓練特徵的最新時間。這個日期應與主要資料集的結束時間相同或更早。使用 RFC3339 UTC「Zulu」格式 (例如 2014-10-02T15:01:23Z)。

JSON 要求主體：

{
    "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"
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

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

接著，請執行下列指令來傳送 REST 要求： 

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

將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

@'
{
    "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

接著，請執行下列指令來傳送 REST 要求： 

$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

您應該會收到如下的 JSON 回應：

{
  "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
}

查看結果

使用 projects.locations.operations.get 方法檢查模型是否已建立。如果回應包含 "done": false，請重複執行指令，直到回應包含 "done": true 為止。這些作業可能需要幾分鐘到幾小時才能完成。

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 「身分與存取權管理設定」中列出的專案 ID
  • LOCATION：執行個體的位置；請使用支援的區域之一。
    顯示地區
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • OPERATION_ID：作業的 ID

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令：

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

執行下列指令：

$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

您應該會收到如下的 JSON 回應：

{
  "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"
  }
}

匯出中繼資料

如要從模型匯出中繼資料，請使用 projects.locations.instances.models.exportMetadata 方法。

詳情請參閱「AML 輸出資料模型中匯出的中繼資料」。

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 「身分與存取權管理設定」中列出的專案 ID
  • LOCATION：執行個體的位置；請使用其中一個 支援的區域
    顯示地區
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID：使用者定義的執行個體 ID
  • MODEL_ID：使用者定義的模型 ID
  • BQ_OUTPUT_DATASET_NAME：要匯出資料表的 BigQuery 資料集，該資料表會說明模型的結構化中繼資料
  • STRUCTURED_METADATA_TABLE：要寫入結構化中繼資料的資料表
  • WRITE_DISPOSITION：如果目標資料表已存在，則會執行的動作；請使用下列其中一個值：
    • WRITE_EMPTY：只有在 BigQuery 資料表為空時，才能匯出資料。
    • WRITE_TRUNCATE：先清除 BigQuery 資料表中的所有現有資料，再寫入資料表。

JSON 要求主體：

{
  "structuredMetadataDestination": {
    "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.STRUCTURED_METADATA_TABLE",
    "writeDisposition": "WRITE_DISPOSITION"
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

cat > request.json << 'EOF'
{
  "structuredMetadataDestination": {
    "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.STRUCTURED_METADATA_TABLE",
    "writeDisposition": "WRITE_DISPOSITION"
  }
}
EOF

接著，請執行下列指令來傳送 REST 要求： 

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

將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

@'
{
  "structuredMetadataDestination": {
    "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.STRUCTURED_METADATA_TABLE",
    "writeDisposition": "WRITE_DISPOSITION"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

接著，請執行下列指令來傳送 REST 要求： 

$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

您應該會收到如下的 JSON 回應：

{
  "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
}

如要進一步瞭解如何取得長時間執行的作業 (LRO) 結果，請參閱「檢查結果」。

取得模型

如要取得模型，請使用 projects.locations.instances.models.get 方法。

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 「身分與存取權管理設定」中列出的專案 ID
  • LOCATION：執行個體的位置；請使用支援的區域之一。
    顯示地區
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID：使用者定義的執行個體 ID
  • MODEL_ID：使用者定義的模型 ID

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令：

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

執行下列指令：

$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

您應該會收到如下的 JSON 回應：

{
  "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"
}

更新模型

如要更新模型，請使用 projects.locations.instances.models.patch 方法。

您只能更新模型中的標籤欄位。以下範例會更新與模型相關聯的這些使用者標籤鍵/值組合。

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 「身分與存取權管理設定」中列出的專案 ID
  • LOCATION：執行個體的位置；請使用支援的區域之一。
    顯示地區
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID：使用者定義的執行個體 ID
  • MODEL_ID：使用者定義的模型 ID
  • KEY：用於整理模型的鍵/值組合中的鍵。詳情請參閱 labels。
  • VALUE：鍵/值組合中的值，用於整理模型。詳情請參閱 labels。

JSON 要求主體：

{
  "labels": {
    "KEY": "VALUE"
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

cat > request.json << 'EOF'
{
  "labels": {
    "KEY": "VALUE"
  }
}
EOF

接著，請執行下列指令來傳送 REST 要求： 

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

將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

@'
{
  "labels": {
    "KEY": "VALUE"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

接著，請執行下列指令來傳送 REST 要求： 

$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

您應該會收到如下的 JSON 回應：

{
  "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
}

如要進一步瞭解如何取得長時間執行的作業 (LRO) 結果，請參閱「檢查結果」。

列出模型

如要列出特定執行個體的模型，請使用 projects.locations.instances.models.list 方法。

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 「身分與存取權管理設定」中列出的專案 ID
  • LOCATION：執行個體的位置；請使用支援的區域之一。
    顯示地區
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID：使用者定義的執行個體 ID

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令：

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

執行下列指令：

$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

您應該會收到如下的 JSON 回應：

{
  "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"
    }
  ]
}

刪除模型

如要刪除模型，請使用 projects.locations.instances.models.delete 方法。

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 「身分與存取權管理設定」中列出的專案 ID
  • LOCATION：執行個體的位置；請使用支援的區域之一。
    顯示地區
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID：使用者定義的執行個體 ID
  • MODEL_ID：使用者定義的模型 ID

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令：

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

執行下列指令：

$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

您應該會收到如下的 JSON 回應：

{
  "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
}

如要進一步瞭解如何取得長時間執行的作業 (LRO) 結果，請參閱「檢查結果」。