建立及管理回測結果

本頁說明如何建立及管理 AML AI 回溯測試預測結果。回溯測試預測會使用現有的歷史資料，訓練模型。在這些月份中，資料集必須包含有可疑活動的當事人，或導致 AML_EXIT 事件的調查開始日期。如要進一步瞭解 AML AI 如何標記各方，請參閱風險案件生命週期。

只要訓練結束日期早於回溯測試日期，您就可以使用相同的資料集進行訓練和回溯測試。

事前準備

建立回測結果

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

傳送要求

如要建立回測結果，請使用 projects.locations.instances.backtestResults.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
  • BACKTEST_RESULTS_ID：使用者定義的回溯測試結果 ID
  • MODEL_ID：使用者定義的模型 ID
  • BACKTEST_DATASET_ID：用於回溯測試的資料集使用者定義 ID；資料表不應有訓練標籤資料欄
  • BACKTEST_END_DATE：用來產生回溯測試特徵的最新時間。這個日期應與資料集的結束時間相同或更早。使用 RFC3339 UTC「Zulu」格式 (例如 2014-10-02T15:01:23Z)。
  • PARTY_INVESTIGATIONS_PER_PERIOD_HINT： 這個數字會提示調整器，每個週期 (每月) 要調查的當事人數量。這項設定用於控管模型的評估方式。舉例來說，首次試用 AML AI 時，建議您根據現有自動警示系統的警示，將此值設為每月平均調查的當事人數量。

JSON 要求主體：

{
    "model": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID",
    "dataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/BACKTEST_DATASET_ID",
    "endTime": "BACKTEST_END_DATE",
    "backtestPeriods": 5,
    "performanceTarget": {
      "partyInvestigationsPerPeriodHint": "PARTY_INVESTIGATIONS_PER_PERIOD_HINT"
    }
}

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

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/BACKTEST_DATASET_ID",
    "endTime": "BACKTEST_END_DATE",
    "backtestPeriods": 5,
    "performanceTarget": {
      "partyInvestigationsPerPeriodHint": "PARTY_INVESTIGATIONS_PER_PERIOD_HINT"
    }
}
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/backtestResults?backtest_result_id=BACKTEST_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/BACKTEST_DATASET_ID",
    "endTime": "BACKTEST_END_DATE",
    "backtestPeriods": 5,
    "performanceTarget": {
      "partyInvestigationsPerPeriodHint": "PARTY_INVESTIGATIONS_PER_PERIOD_HINT"
    }
}
'@  | 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/backtestResults?backtest_result_id=BACKTEST_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": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/backtestResults/BACKTEST_RESULTS_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/instances/INSTANCE_ID/backtestResults/BACKTEST_RESULTS_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/dataresidency.monitoring.DataResidencyAugmentedView",
    "tpIds": [
      "i608e8cf4abb2a7d9-tp"
    ]
  }
}

匯出中繼資料

如要從回溯測試結果匯出中繼資料，請使用 projects.locations.instances.backtestResults.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
  • BACKTEST_RESULTS_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/backtestResults/BACKTEST_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/backtestResults/BACKTEST_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": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/backtestResults/BACKTEST_RESULTS_ID",
    "verb": "exportMetadata",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

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

取得回測結果

如要取得回溯測試結果，請使用 projects.locations.instances.backtestResults.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
  • BACKTEST_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/backtestResults/BACKTEST_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/backtestResults/BACKTEST_RESULTS_ID" | Select-Object -Expand Content

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

{
    "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/backtestResults/BACKTEST_RESULTS_ID",
    "createTime": CREATE_TIME,
    "updateTime": UPDATE_TIME,
    "state": "ACTIVE",
    "dataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/BACKTEST_DATASET_ID",
    "model": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID",
    "endTime": "BACKTEST_END_DATE",
    "performanceTarget": {
      "partyInvestigationsPerPeriodHint": "PARTY_INVESTIGATIONS_PER_PERIOD_HINT"
    },
    "lineOfBusiness": "RETAIL"
}

更新回測結果

如要更新回溯測試結果，請使用 projects.locations.instances.backtestResults.patch 方法。

只有回測結果中的 labels 欄位可以更新。下列範例會更新與回溯測試結果相關聯的使用者標籤鍵/值組合。

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

  • 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
  • BACKTEST_RESULTS_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/backtestResults/BACKTEST_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/backtestResults/BACKTEST_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": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/backtestResults/BACKTEST_RESULTS_ID",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

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

列出回測結果

如要列出特定執行個體的回溯測試結果，請使用 projects.locations.instances.backtestResults.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/backtestResults"

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/backtestResults" | Select-Object -Expand Content

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

{
  "backtestResults": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/backtestResults/BACKTEST_RESULTS_ID",
      "createTime": CREATE_TIME,
      "updateTime": UPDATE_TIME,
      "state": "ACTIVE",
      "dataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/BACKTEST_DATASET_ID",
      "model": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID",
      "endTime": "BACKTEST_END_DATE",
      "performanceTarget": {
        "partyInvestigationsPerPeriodHint": "PARTY_INVESTIGATIONS_PER_PERIOD_HINT"
      },
      "lineOfBusiness": "RETAIL"
    }
  ]
}

刪除回測結果

如要刪除回測結果，請使用 projects.locations.instances.backtestResults.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
  • BACKTEST_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/backtestResults/BACKTEST_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/backtestResults/BACKTEST_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": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/backtestResults/BACKTEST_RESULTS_ID",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

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