本頁說明如何建立及管理 AML AI 預測結果。預測結果會儲存至 BigQuery 資料表。
如要進一步瞭解預測結果的內容,請參閱「瞭解預測輸出內容」。
事前準備
-
如要取得建立及管理預測結果所需的權限,請要求管理員為您授予專案的 Financial Services 管理員 (
financialservices.admin) 身分與存取權管理角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。 - 建立執行個體
- 建立模型
- 建立資料集
建立預測結果
部分 API 方法會傳回長時間執行的作業 (LRO)。這些方法是以非同步方式執行,並會傳回 Operation 物件。詳情請參閱「REST 參考資料」。方法傳回回應時,作業可能尚未完成。對於這些方法,請先傳送要求,然後檢查結果。一般來說,所有 POST、PUT、UPDATE 和 DELETE 作業都是長時間執行的作業。
傳送要求
如要建立預測結果,請使用 projects.locations.instances.predictionResults.create 方法。
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID: Google Cloud 「身分與存取權管理設定」中列出的專案 IDLOCATION:執行個體的位置;請使用支援的區域之一。顯示地區us-central1us-east1asia-south1europe-west1europe-west2europe-west4northamerica-northeast1southamerica-east1australia-southeast1
INSTANCE_ID:使用者定義的執行個體 IDPREDICTION_RESULTS_ID:使用者定義的預測結果 IDMODEL_ID:使用者定義的模型 IDDATASET_ID:使用者定義的資料集 ID,用於預測;資料表不應有訓練標籤資料欄PREDICTION_END_DATE:系統用來產生預測特徵的最新時間。這個日期應與資料集的結束時間相同或更早。使用 RFC3339 UTC「Zulu」格式 (例如2014-10-02T15:01:23Z)。PREDICTION_PERIODS:產生預測的連續月數,最後一個月為預測結束日期前一個月的完整月份,以資料集的時區為準。BQ_OUTPUT_DATASET_NAME:用於預測的輸出 BigQuery 資料集名稱BQ_OUTPUT_PREDICTION_TABLE:使用者定義的輸出 BigQuery 資料表 ID,用於預測BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE:使用者定義的輸出說明 BigQuery 資料表 ID,用於預測;如果不想匯出至 BigQuery 資料表,請從要求 JSON 中移除選用的explainabilityDestination物件。WRITE_DISPOSITION:如果目標資料表已存在,則會執行的動作;請使用下列其中一個值:-
WRITE_EMPTY:只有在 BigQuery 資料表為空時,才能匯出資料。 -
WRITE_TRUNCATE:先清除 BigQuery 資料表中的所有現有資料,再寫入資料表。
-
JSON 要求主體:
{
"model": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID",
"dataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
"endTime": "PREDICTION_END_DATE",
"predictionPeriods": "PREDICTION_PERIODS",
"outputs": {
"predictionDestination": {
"tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_TABLE",
"writeDisposition": "WRITE_DISPOSITION"
},
"explainabilityDestination": {
"tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE",
"writeDisposition": "WRITE_DISPOSITION"
}
}
}
如要傳送要求,請選擇以下其中一個選項:
curl
將要求主體儲存在名為 request.json 的檔案中。
在終端機中執行下列指令,在目前目錄中建立或覆寫這個檔案:
cat > request.json << 'EOF'
{
"model": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID",
"dataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
"endTime": "PREDICTION_END_DATE",
"predictionPeriods": "PREDICTION_PERIODS",
"outputs": {
"predictionDestination": {
"tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_TABLE",
"writeDisposition": "WRITE_DISPOSITION"
},
"explainabilityDestination": {
"tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_EXPLAINABILITY_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/predictionResults?prediction_result_id=PREDICTION_RESULTS_ID"
PowerShell
將要求主體儲存在名為 request.json 的檔案中。
在終端機中執行下列指令,在目前目錄中建立或覆寫這個檔案:
@'
{
"model": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID",
"dataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
"endTime": "PREDICTION_END_DATE",
"predictionPeriods": "PREDICTION_PERIODS",
"outputs": {
"predictionDestination": {
"tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_TABLE",
"writeDisposition": "WRITE_DISPOSITION"
},
"explainabilityDestination": {
"tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_EXPLAINABILITY_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/predictionResults?prediction_result_id=PREDICTION_RESULTS_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/predictionResults/PREDICTION_RESULTS_ID",
"verb": "create",
"requestedCancellation": false,
"apiVersion": "v1"
},
"done": false
}
查看結果
使用 projects.locations.operations.get 方法檢查是否已建立預測結果。如果回應包含 "done": false,請重複執行指令,直到回應包含 "done": true 為止。這些作業可能需要幾分鐘到幾小時才能完成。
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID: Google Cloud 「身分與存取權管理設定」中列出的專案 IDLOCATION:執行個體的位置;請使用支援的區域之一。顯示地區us-central1us-east1asia-south1europe-west1europe-west2europe-west4northamerica-northeast1southamerica-east1australia-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/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID",
"verb": "create",
"requestedCancellation": false,
"apiVersion": "v1"
},
"done": true,
"response": {
"@type": "type.googleapis.com/dataresidency.monitoring.DataResidencyAugmentedView",
"tpIds": [
"i608e8cf4abb2a7d9-tp"
]
}
}
匯出中繼資料
如要從預測結果匯出中繼資料,請使用 projects.locations.instances.predictionResults.exportMetadata 方法。
詳情請參閱「AML 輸出資料模型中匯出的中繼資料」。
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID: Google Cloud 「身分與存取權管理設定」中列出的專案 IDLOCATION:執行個體的位置;請使用其中一個 支援的區域顯示地區us-central1us-east1asia-south1europe-west1europe-west2europe-west4northamerica-northeast1southamerica-east1australia-southeast1
INSTANCE_ID:使用者定義的執行個體 IDPREDICTION_RESULTS_ID:使用者定義的預測結果 IDBQ_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/predictionResults/PREDICTION_RESULTS_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/predictionResults/PREDICTION_RESULTS_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/predictionResults/PREDICTION_RESULTS_ID",
"verb": "exportMetadata",
"requestedCancellation": false,
"apiVersion": "v1"
},
"done": false
}
如要進一步瞭解如何取得長時間執行的作業 (LRO) 結果,請參閱「檢查結果」。
取得預測結果
如要取得預測結果,請使用 projects.locations.instances.predictionResults.get 方法。
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID: Google Cloud 「身分與存取權管理設定」中列出的專案 IDLOCATION:執行個體的位置;請使用支援的區域之一。顯示地區us-central1us-east1asia-south1europe-west1europe-west2europe-west4northamerica-northeast1southamerica-east1australia-southeast1
INSTANCE_ID:使用者定義的執行個體 IDPREDICTION_RESULTS_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/predictionResults/PREDICTION_RESULTS_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/predictionResults/PREDICTION_RESULTS_ID" | Select-Object -Expand Content
您應該會收到如下的 JSON 回應:
{
"name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID",
"createTime": "2023-03-14T15:52:55.358979323Z",
"updateTime": "2023-03-15T15:52:55.358979323Z",
"state": "ACTIVE",
"model": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID",
"dataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
"endTime": "PREDICTION_END_DATE",
"predictionPeriods": PREDICTION_PERIODS,
"outputs": {
"predictionDestination": {
"tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_TABLE",
"writeDisposition": "WRITE_DISPOSITION"
},
"explainabilityDestination": {
"tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE",
"writeDisposition": "WRITE_DISPOSITION"
}
},
"lineOfBusiness": "RETAIL"
}
更新預測結果
如要更新預測結果,請使用 projects.locations.instances.predictionResults.patch 方法。
您只能更新預測結果中的 labels 欄位。下列範例會更新與預測結果相關聯的使用者標籤鍵/值組合。
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID: Google Cloud 「身分與存取權管理設定」中列出的專案 IDLOCATION:執行個體的位置;請使用支援的區域之一。顯示地區us-central1us-east1asia-south1europe-west1europe-west2europe-west4northamerica-northeast1southamerica-east1australia-southeast1
INSTANCE_ID:使用者定義的執行個體 IDPREDICTION_RESULTS_ID:使用者定義的預測結果 IDKEY:鍵/值組合中的鍵,用於整理預測結果。詳情請參閱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/predictionResults/PREDICTION_RESULTS_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/predictionResults/PREDICTION_RESULTS_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/predictionResults/PREDICTION_RESULTS_ID",
"verb": "update",
"requestedCancellation": false,
"apiVersion": "v1"
},
"done": false
}
如要進一步瞭解如何取得長時間執行的作業 (LRO) 結果,請參閱「檢查結果」。
列出預測結果
如要列出特定執行個體的預測結果,請使用 projects.locations.instances.predictionResults.list 方法。
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID: Google Cloud 「身分與存取權管理設定」中列出的專案 IDLOCATION:執行個體的位置;請使用支援的區域之一。顯示地區us-central1us-east1asia-south1europe-west1europe-west2europe-west4northamerica-northeast1southamerica-east1australia-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/predictionResults"
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/predictionResults" | Select-Object -Expand Content
您應該會收到如下的 JSON 回應:
{
"predictionResults": [
{
"name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID",
"createTime": "2023-03-14T15:52:55.358979323Z",
"updateTime": "2023-03-15T15:52:55.358979323Z",
"state": "ACTIVE",
"model": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID",
"dataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
"endTime": "PREDICTION_END_DATE",
"predictionPeriods": PREDICTION_PERIODS,
"outputs": {
"predictionDestination": {
"tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_TABLE",
"writeDisposition": "WRITE_DISPOSITION"
},
"explainabilityDestination": {
"tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE",
"writeDisposition": "WRITE_DISPOSITION"
}
},
"lineOfBusiness": "RETAIL"
}
]
}
刪除預測結果
如要刪除預測結果,請使用 projects.locations.instances.predictionResults.delete 方法。
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID: Google Cloud 「身分與存取權管理設定」中列出的專案 IDLOCATION:執行個體的位置;請使用支援的區域之一。顯示地區us-central1us-east1asia-south1europe-west1europe-west2europe-west4northamerica-northeast1southamerica-east1australia-southeast1
INSTANCE_ID:使用者定義的執行個體 IDPREDICTION_RESULTS_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/predictionResults/PREDICTION_RESULTS_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/predictionResults/PREDICTION_RESULTS_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/predictionResults/PREDICTION_RESULTS_ID",
"verb": "delete",
"requestedCancellation": false,
"apiVersion": "v1"
},
"done": false
}
如要進一步瞭解如何取得長時間執行的作業 (LRO) 結果,請參閱「檢查結果」。