Creare e gestire i risultati dei backtest

Questa pagina mostra come creare e gestire i risultati di previsione del backtest AML AI. La previsione del backtest utilizza un modello addestrato su dati storici esistenti. Per questi mesi, il set di dati deve contenere una parte con attività sospette o date di inizio dell'indagine che hanno generato un evento AML_EXIT. Per ulteriori informazioni su come l'IA AML etichetta le varie parti, consulta il ciclo di vita di una richiesta di rischio.

Lo stesso set di dati può essere utilizzato per l'addestramento e il backtest, a condizione che la data di fine dell'addestramento sia precedente alle date del backtest.

Prima di iniziare

Creare i risultati del backtest

Alcuni metodi dell'API restituiscono un'operazione a lunga esecuzione (LRO). Questi metodi sono asincroni e restituiscono un oggetto Operation. Per maggiori dettagli, consulta la documentazione di riferimento REST. L'operazione potrebbe non essere completata quando il metodo restituisce una risposta. Per questi metodi, invia la richiesta e poi controlla il risultato. In generale, tutte le operazioni POST, PUT, UPDATE ed DELETE sono di lunga durata.

Invia la richiesta

Per creare i risultati del backtest, utilizza il metodo projects.locations.instances.backtestResults.create.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud elencato nelle Impostazioni IAM
  • LOCATION: la posizione dell'istanza. Utilizza una delle regioni supportate.
    Mostra sedi
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID: un identificatore definito dall'utente per l'istanza
  • BACKTEST_RESULTS_ID: un identificatore definito dall'utente per i risultati del backtest
  • MODEL_ID: un identificatore definito dall'utente per il modello
  • BACKTEST_DATASET_ID: l'identificatore definito dall'utente per il set di dati utilizzato per il backtest; le tabelle non devono avere le colonne delle etichette di addestramento
  • BACKTEST_END_DATE: l'ora più recente a partire dalla quale vengono utilizzati i dati per generare funzionalità per i backtest. Questa data deve essere uguale o precedente all'ora di fine dei set di dati. Utilizza il formato "Zulu" UTC RFC3339 (ad es. 2014-10-02T15:01:23Z).
  • PARTY_INVESTIGATIONS_PER_PERIOD_HINT: Un numero che fornisce all'utente un suggerimento sul numero di parti di questi dati che verranno esaminate per periodo (mensile). Viene utilizzato per controllare il modo in cui il modello viene valutato. Ad esempio, quando provi l'IA AML per la prima volta, ti consigliamo di impostare questo valore sul numero di parti esaminate in un mese medio, in base agli avvisi del tuo sistema di avviso automatico esistente.

Corpo JSON della richiesta: 

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

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

Quindi, esegui il seguente comando per inviare la richiesta 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

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

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

Quindi, esegui il seguente comando per inviare la richiesta 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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Controlla il risultato

Per verificare se sono stati creati risultati del backtest, utilizza il metodo projects.locations.operations.get. Se la risposta contiene "done": false, ripeti il comando finché la risposta non contiene "done": true. Queste operazioni possono richiedere da alcuni minuti a diverse ore.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud elencato nelle Impostazioni IAM
  • LOCATION: la posizione dell'istanza. Utilizza una delle regioni supportate.
    Mostra sedi
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • OPERATION_ID: l'identificatore dell'operazione

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Esegui questo comando: 

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

Esegui questo comando: 

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Esporta metadati

Per esportare i metadati dai risultati del backtest, utilizza il metodo projects.locations.instances.backtestResults.exportMetadata.

Per ulteriori informazioni, consulta Metadati esportati nel modello di dati di output AML.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud elencato nelle Impostazioni IAM
  • LOCATION: la posizione dell'istanza. Utilizza una delle regioni supportate.
    Mostra sedi
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID: l'identificatore definito dall'utente per l'istanza
  • BACKTEST_RESULTS_ID: un identificatore definito dall'utente per i risultati del backtest
  • BQ_OUTPUT_DATASET_NAME: un set di dati BigQuery in cui esportare una tabella che descriva i metadati strutturati dei risultati del backtest
  • STRUCTURED_METADATA_TABLE: la tabella in cui scrivere i metadati strutturati
  • WRITE_DISPOSITION: l'azione che si verifica se la tabella di destinazione esiste già. Utilizza uno dei seguenti valori:
    • WRITE_EMPTY: esporta i dati solo se la tabella BigQuery è vuota.
    • WRITE_TRUNCATE: cancella tutti i dati esistenti nella tabella BigQuery prima di scrivere nella tabella.

Corpo JSON della richiesta: 

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

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

Quindi, esegui il seguente comando per inviare la richiesta 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

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

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

Quindi, esegui il seguente comando per inviare la richiesta 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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Per ulteriori informazioni su come ottenere il risultato dell'operazione a lunga esecuzione (LRO), consulta Verificare il risultato.

Ottenere i risultati del backtest

Per ottenere i risultati del backtest, utilizza il metodo projects.locations.instances.backtestResults.get.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud elencato nelle Impostazioni IAM
  • LOCATION: la posizione dell'istanza. Utilizza una delle regioni supportate.
    Mostra sedi
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID: l'identificatore definito dall'utente per l'istanza
  • BACKTEST_RESULTS_ID: l'identificatore definito dall'utente per i risultati del backtest

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Esegui questo comando: 

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

Esegui questo comando: 

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Aggiornare i risultati del backtest

Per aggiornare i risultati del backtest, utilizza il metodo projects.locations.instances.backtestResults.patch.

È possibile aggiornare solo il campo labels nei risultati del backtest. L'esempio seguente aggiorna la coppia chiave-valore etichette utente associata ai risultati del backtest.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud elencato nelle Impostazioni IAM
  • LOCATION: la posizione dell'istanza. Utilizza una delle regioni supportate.
    Mostra sedi
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID: l'identificatore definito dall'utente per l'istanza
  • BACKTEST_RESULTS_ID: l'identificatore definito dall'utente per i risultati del backtest
  • KEY: la chiave in una coppia chiave-valore utilizzata per organizzare i risultati del backtest. Per maggiori informazioni, consulta labels.
  • VALUE: il valore in una coppia chiave-valore utilizzato per organizzare i risultati del backtest. Per maggiori informazioni, consulta labels.

Corpo JSON della richiesta: 

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

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

Quindi, esegui il seguente comando per inviare la richiesta 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

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

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

Quindi, esegui il seguente comando per inviare la richiesta 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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Per ulteriori informazioni su come ottenere il risultato dell'operazione a lunga esecuzione (LRO), consulta Verificare il risultato.

Elenca i risultati del backtest

Per elencare i risultati del backtest per una determinata istanza, utilizza il metodo projects.locations.instances.backtestResults.list.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud elencato nelle Impostazioni IAM
  • LOCATION: la posizione dell'istanza. Utilizza una delle regioni supportate.
    Mostra sedi
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID: l'identificatore definito dall'utente per l'istanza

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Esegui questo comando: 

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

Esegui questo comando: 

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Eliminare i risultati del backtest

Per eliminare i risultati del backtest, utilizza il metodo projects.locations.instances.backtestResults.delete.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud elencato nelle Impostazioni IAM
  • LOCATION: la posizione dell'istanza. Utilizza una delle regioni supportate.
    Mostra sedi
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID: l'identificatore definito dall'utente per l'istanza
  • BACKTEST_RESULTS_ID: l'identificatore definito dall'utente per i risultati del backtest

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Esegui questo comando: 

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

Esegui questo comando: 

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Per ulteriori informazioni su come ottenere il risultato dell'operazione a lunga esecuzione (LRO), consulta Verificare il risultato.