Entraîner et tester des modèles conçus pour détecter le blanchiment d'argent

Créer une instance

Cette section explique comment créer une instance. L'instance d'IA AML se trouve à la racine de toutes les autres ressources d'IA AML. Chaque instance nécessite une seule clé de chiffrement gérée par le client (CMEK) associée, qui permet de chiffrer toutes les données créées par l'IA AML.

Créer un trousseau de clés

Pour créer un trousseau, utilisez la méthode projects.locations.keyRings.create.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings?key_ring_id=my-key-ring"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings?key_ring_id=my-key-ring" | Select-Object -Expand Content

{
  "name": "projects/PROJECT_ID/locations/LOCATION/keyRings/my-key-ring",
  "createTime": CREATE_TIME
}

gcloud kms keyrings create my-key-ring \
  --location LOCATION

gcloud kms keyrings create my-key-ring `
  --location LOCATION

gcloud kms keyrings create my-key-ring ^
  --location LOCATION

$

Créer une clé

Pour créer une clé, utilisez la méthode projects.locations.keyRings.cryptoKeys.

{
  "purpose": "ENCRYPT_DECRYPT"
}

cat > request.json << 'EOF'
{
  "purpose": "ENCRYPT_DECRYPT"
}
EOF

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/my-key-ring/cryptoKeys?crypto_key_id=my-key"

@'
{
  "purpose": "ENCRYPT_DECRYPT"
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/my-key-ring/cryptoKeys?crypto_key_id=my-key" | Select-Object -Expand Content

{
  "name": "projects/PROJECT_ID/locations/LOCATION/keyRings/my-key-ring/cryptoKeys/my-key",
  "primary": {
    "name": "projects/PROJECT_ID/locations/LOCATION/keyRings/my-key-ring/cryptoKeys/my-key/cryptoKeyVersions/1",
    "state": "ENABLED",
    "createTime": CREATE_TIME,
    "protectionLevel": "SOFTWARE",
    "algorithm": "GOOGLE_SYMMETRIC_ENCRYPTION",
    "generateTime": GENERATE_TIME
  },
  "purpose": "ENCRYPT_DECRYPT",
  "createTime": CREATE_TIME,
  "versionTemplate": {
    "protectionLevel": "SOFTWARE",
    "algorithm": "GOOGLE_SYMMETRIC_ENCRYPTION"
  },
  "destroyScheduledDuration": "86400s"
}

gcloud kms keys create my-key \
  --keyring my-key-ring \
  --location LOCATION \
  --purpose "encryption"

gcloud kms keys create my-key `
  --keyring my-key-ring `
  --location LOCATION `
  --purpose "encryption"

gcloud kms keys create my-key ^
  --keyring my-key-ring ^
  --location LOCATION ^
  --purpose "encryption"

$

Créer l'instance à l'aide de l'API

Pour créer une instance, utilisez la méthode projects.locations.instances.create.

Corps JSON de la requête :

{
  "kmsKey": "projects/PROJECT_ID/locations/LOCATION/keyRings/my-key-ring/cryptoKeys/my-key"
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

cat > request.json << 'EOF'
{
  "kmsKey": "projects/PROJECT_ID/locations/LOCATION/keyRings/my-key-ring/cryptoKeys/my-key"
}
EOF

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=my-instance"

@'
{
  "kmsKey": "projects/PROJECT_ID/locations/LOCATION/keyRings/my-key-ring/cryptoKeys/my-key"
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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=my-instance" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

{
  "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/my-instance",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Si la requête aboutit, le corps de la réponse contient une opération de longue durée contenant un ID qui peut être utilisé pour récupérer l'état en cours de l'opération asynchrone. Copiez le OPERATION_ID renvoyé pour l'utiliser dans la section suivante.

Vérifier le résultat

Utilisez la méthode projects.locations.operations.get pour vérifier si l'instance a été créée. Si la réponse contient "done": false, répétez la commande jusqu'à ce qu'elle contienne "done": true.

Les opérations décrites dans ce guide peuvent prendre quelques minutes à plusieurs heures. Vous devez attendre la fin d'une opération avant de continuer dans ce guide, car l'API utilise la sortie de certaines méthodes comme entrée pour d'autres.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

• OPERATION_ID: identifiant de l'opération

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"

$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

Vous devriez recevoir une réponse JSON de ce type :

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "endTime": END_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.Instance",
    "name": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance",
    "createTime": CREATE_TIME,
    "updateTime": UPDATE_TIME,
    "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/my-key-ring/cryptoKeys/my-key",
    "state": "ACTIVE"
  }
}

Accorder l'accès à la clé CMEK

L'API crée automatiquement un compte de service dans votre projet. Le compte de service doit avoir accès à la clé CMEK pour pouvoir l'utiliser pour chiffrer et déchiffrer les données sous-jacentes. Accordez l'accès à la clé.

gcloud kms keys add-iam-policy-binding "projects/PROJECT_ID/locations/LOCATION/keyRings/my-key-ring/cryptoKeys/my-key" \
  --keyring "projects/PROJECT_ID/locations/LOCATION/keyRings/my-key-ring" \
  --location "LOCATION" \
  --member "serviceAccount:service-PROJECT_NUMBER@gcp-sa-financialservices.iam.gserviceaccount.com" \
  --role="roles/cloudkms.cryptoKeyEncrypterDecrypter" \
  --project="PROJECT_ID"

créer des ensembles de données BigQuery ;

Cette section explique comment créer des ensembles de données BigQuery d'entrée et de sortie, puis copier des exemples de données bancaires dans l'ensemble de données d'entrée.

Créer un ensemble de données de sortie

Créez un ensemble de données à utiliser pour envoyer les sorties du pipeline AML.

bq mk \
  --location=LOCATION \
  --project_id=PROJECT_ID \
  my_bq_output_dataset

bq mk `
  --location=LOCATION `
  --project_id=PROJECT_ID `
  my_bq_output_dataset

Créer un ensemble de données d'entrée

Créez un ensemble de données dans lequel copier les exemples de tables bancaires.

bq mk \
  --location=LOCATION \
  --project_id=PROJECT_ID \
  my_bq_input_dataset

bq mk `
  --location=LOCATION `
  --project_id=PROJECT_ID `
  my_bq_input_dataset

Copier l'exemple d'ensemble de données

Des exemples de données bancaires sont fournis sous forme d'ensemble de données BigQuery dans le projet d'ensemble de données partagé de Google. Vous devez avoir accès à l'API d'IA AML pour que cet ensemble de données soit accessible. Voici les principales caractéristiques de cet ensemble de données:

• 100 000 parties
• Une période de référence allant du 1er janvier 2020 au 1er janvier 2023, ainsi que 24 mois supplémentaires de données rétrospectives
• 300 cas de risque négatifs et 20 cas de risque positifs par mois
• Cas à risque avec les attributs suivants :
  • La moitié des cas de risque positif concerne l'activité de structuration qui s'est produite au cours des deux mois précédant l'événement AML_PROCESS_START.
  • L'autre moitié concerne les parties ayant reçu le plus d'argent au cours des deux mois précédant l'événement AML_PROCESS_START.
  • Les cas négatifs sont générés de manière aléatoire.
  • 0,1% de chances que le cas à risque soit généré dans l'état opposé (par exemple, une partie aléatoire positive, ou une partie qui a une activité de structuration ou les revenus les plus élevés et est signalée comme négative)
• Le schéma AML est défini dans le modèle de données d'entrée AML.

1. Copiez l'exemple de données bancaires dans l'ensemble de données d'entrée que vous avez créé.

   Bash

   bq mk --transfer_config \
     --project_id=PROJECT_ID \
     --data_source=cross_region_copy \
     --target_dataset="my_bq_input_dataset" \
     --display_name="Copy the AML sample dataset." \
     --schedule=None \
     --params='{
       "source_project_id":"bigquery-public-data",
       "source_dataset_id":"aml_ai_input_dataset",
       "overwrite_destination_table":"true"
     }'
   

   PowerShell

   bq mk --transfer_config `
   --project_id=PROJECT_ID `
   --data_source=cross_region_copy `
   --target_dataset="my_bq_input_dataset" `
   --display_name="Copy the AML sample dataset." `
   --schedule=None `
   --params='{\"source_project_id\":\"bigquery-public-data\",\"source_dataset_id\":\"aml_ai_input_dataset\",\"overwrite_destination_table\":\"true\"}'
   

2. Surveillez la tâche de transfert de données.

   Bash

   bq ls --transfer_config \
   --transfer_location=LOCATION \
   --project_id=PROJECT_ID \
   --filter="dataSourceIds:cross_region_copy"
   

   PowerShell

   bq ls --transfer_config `
   --transfer_location=LOCATION `
   --project_id=PROJECT_ID `
   --filter="dataSourceIds:cross_region_copy"
   

   Une fois le transfert terminé, une tâche de transfert de données avec le nom à afficher Copy the AML sample dataset est créée.

   Vous pouvez également vérifier l'état du transfert à l'aide de la console Google Cloud.

   Le résultat obtenu devrait ressembler à ce qui suit.

                        name                           displayName         dataSourceId       state
   -------------------------------------------  -----------------------  -----------------  ---------
   projects/294024168771/locations/us-central1  Copy AML sample dataset  cross_region_copy  SUCCEEDED
   

Accorder l'accès aux ensembles de données BigQuery

L'API crée automatiquement un compte de service dans votre projet. Le compte de service doit avoir accès aux ensembles de données d'entrée et de sortie BigQuery.

1. Accordez un accès en lecture à l'ensemble de données d'entrée et à ses tables.

   Bash

   bq query --project_id=PROJECT_ID --use_legacy_sql=false \
     'GRANT `roles/bigquery.dataViewer` ON SCHEMA `PROJECT_ID.my_bq_input_dataset` TO "serviceAccount:service-PROJECT_NUMBER@gcp-sa-financialservices.iam.gserviceaccount.com"'
   

   PowerShell

   bq query --project_id=PROJECT_ID --use_legacy_sql=false "GRANT ``roles/bigquery.dataViewer`` ON SCHEMA ``PROJECT_ID.my_bq_input_dataset`` TO 'serviceAccount:service-PROJECT_NUMBER@gcp-sa-financialservices.iam.gserviceaccount.com'"
   

2. Accordez un accès en écriture à l'ensemble de données de sortie.

   Bash

   bq query --project_id=PROJECT_ID --use_legacy_sql=false \
     'GRANT `roles/bigquery.dataEditor` ON SCHEMA `PROJECT_ID.my_bq_output_dataset` TO "serviceAccount:service-PROJECT_NUMBER@gcp-sa-financialservices.iam.gserviceaccount.com"'
   

   PowerShell

   bq query --project_id=PROJECT_ID --use_legacy_sql=false "GRANT ``roles/bigquery.dataEditor`` ON SCHEMA ``PROJECT_ID.my_bq_output_dataset`` TO 'serviceAccount:service-PROJECT_NUMBER@gcp-sa-financialservices.iam.gserviceaccount.com'"
   

Créer un ensemble de données d'AML basée sur l'IA

Créez un ensemble de données d'IA AML pour spécifier les tables d'ensemble de données BigQuery d'entrée et la période à utiliser.

Pour créer un ensemble de données, utilisez la méthode projects.locations.instances.datasets.create.

Corps JSON de la requête :

{
  "tableSpecs": {
    "party": "bq://PROJECT_ID.my_bq_input_dataset.party",
    "account_party_link": "bq://PROJECT_ID.my_bq_input_dataset.account_party_link",
    "transaction": "bq://PROJECT_ID.my_bq_input_dataset.transaction",
    "risk_case_event": "bq://PROJECT_ID.my_bq_input_dataset.risk_case_event",
    "party_supplementary_data": "bq://PROJECT_ID.my_bq_input_dataset.party_supplementary_data"
  },
  "dateRange": {
    "startTime": "2020-01-01T00:00:0.00Z",
    "endTime": "2023-01-01T00:00:0.00Z"
  },
  "timeZone": {
    "id": "UTC"
  }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

cat > request.json << 'EOF'
{
  "tableSpecs": {
    "party": "bq://PROJECT_ID.my_bq_input_dataset.party",
    "account_party_link": "bq://PROJECT_ID.my_bq_input_dataset.account_party_link",
    "transaction": "bq://PROJECT_ID.my_bq_input_dataset.transaction",
    "risk_case_event": "bq://PROJECT_ID.my_bq_input_dataset.risk_case_event",
    "party_supplementary_data": "bq://PROJECT_ID.my_bq_input_dataset.party_supplementary_data"
  },
  "dateRange": {
    "startTime": "2020-01-01T00:00:0.00Z",
    "endTime": "2023-01-01T00:00:0.00Z"
  },
  "timeZone": {
    "id": "UTC"
  }
}
EOF

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/my-instance/datasets?dataset_id=my-dataset"

@'
{
  "tableSpecs": {
    "party": "bq://PROJECT_ID.my_bq_input_dataset.party",
    "account_party_link": "bq://PROJECT_ID.my_bq_input_dataset.account_party_link",
    "transaction": "bq://PROJECT_ID.my_bq_input_dataset.transaction",
    "risk_case_event": "bq://PROJECT_ID.my_bq_input_dataset.risk_case_event",
    "party_supplementary_data": "bq://PROJECT_ID.my_bq_input_dataset.party_supplementary_data"
  },
  "dateRange": {
    "startTime": "2020-01-01T00:00:0.00Z",
    "endTime": "2023-01-01T00:00:0.00Z"
  },
  "timeZone": {
    "id": "UTC"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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/my-instance/datasets?dataset_id=my-dataset" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

{
  "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/my-instance/datasets/my-dataset",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Vous pouvez vérifier le résultat de l'opération à l'aide du nouvel ID d'opération. (Vous pouvez le faire pour les autres requêtes d'API utilisées dans ce guide.)

Créer une configuration de moteur

Créez une configuration de moteur d'IA AML pour régler automatiquement les hyperparamètres en fonction d'une version de moteur donnée et des données fournies. Les versions du moteur sont publiées régulièrement et correspondent à différentes logiques de modèle (par exemple, ciblage d'un secteur du commerce de détail par rapport à un secteur commercial).

Pour créer une configuration de moteur, utilisez la méthode projects.locations.instances.engineConfigs.create.

Cette étape implique le réglage des hyperparamètres, ce qui peut prendre un certain temps. Si vos données ne changent pas de manière significative, cette étape peut être utilisée pour créer et tester de nombreux modèles.

Corps JSON de la requête :

{
  "engineVersion": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/engineVersions/aml-commercial.default.v004.000.202312-000",
  "tuning": {
    "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/datasets/my-dataset",
    "endTime": "2021-07-01T00:00:00Z"
  },
  "performanceTarget": {
    "partyInvestigationsPerPeriodHint": "30"
  }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

cat > request.json << 'EOF'
{
  "engineVersion": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/engineVersions/aml-commercial.default.v004.000.202312-000",
  "tuning": {
    "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/datasets/my-dataset",
    "endTime": "2021-07-01T00:00:00Z"
  },
  "performanceTarget": {
    "partyInvestigationsPerPeriodHint": "30"
  }
}
EOF

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/my-instance/engineConfigs?engine_config_id=my-engine-config"

@'
{
  "engineVersion": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/engineVersions/aml-commercial.default.v004.000.202312-000",
  "tuning": {
    "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/datasets/my-dataset",
    "endTime": "2021-07-01T00:00:00Z"
  },
  "performanceTarget": {
    "partyInvestigationsPerPeriodHint": "30"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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/my-instance/engineConfigs?engine_config_id=my-engine-config" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

{
  "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/my-instance/engineConfigs/my-engine-config",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Créer un modèle

À cette étape, vous entraînez un modèle d'IA AML à l'aide de 12 mois de données allant jusqu'au 1er juillet 2021.

Pour créer un modèle, utilisez la méthode projects.locations.instances.models.create.

Corps JSON de la requête :

{
    "engineConfig": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/engineConfigs/my-engine-config",
    "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/datasets/my-dataset",
    "endTime": "2021-07-01T00:00:00Z"
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

cat > request.json << 'EOF'
{
    "engineConfig": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/engineConfigs/my-engine-config",
    "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/datasets/my-dataset",
    "endTime": "2021-07-01T00:00:00Z"
}
EOF

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/my-instance/models?model_id=my-model"

@'
{
    "engineConfig": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/engineConfigs/my-engine-config",
    "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/datasets/my-dataset",
    "endTime": "2021-07-01T00:00:00Z"
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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/my-instance/models?model_id=my-model" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

{
  "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/my-instance/models/my-model",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Créer un résultat de backtest

La prédiction de backtest utilise le modèle entraîné sur des données historiques existantes. Créez un résultat de rétrotest sur les 12 mois de données précédant janvier 2023, qui n'ont pas été utilisés lors de l'entraînement. Ces mois servent à déterminer le nombre de cas que nous aurions peut-être à traiter si nous avions utilisé le modèle entraîné en juillet 2021 en production de janvier à décembre 2022.

Pour créer un résultat de simulation, utilisez la méthode projects.locations.instances.backtestResults.create.

Corps JSON de la requête :

{
    "model": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/models/my-model",
    "dataset": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/datasets/my-dataset",
    "endTime": "2023-01-01T00:00:00Z",
    "backtestPeriods": 12,
    "performanceTarget": {
      "partyInvestigationsPerPeriodHint": "150"
    }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

cat > request.json << 'EOF'
{
    "model": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/models/my-model",
    "dataset": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/datasets/my-dataset",
    "endTime": "2023-01-01T00:00:00Z",
    "backtestPeriods": 12,
    "performanceTarget": {
      "partyInvestigationsPerPeriodHint": "150"
    }
}
EOF

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/my-instance/backtestResults?backtest_result_id=my-backtest-results"

@'
{
    "model": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/models/my-model",
    "dataset": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/datasets/my-dataset",
    "endTime": "2023-01-01T00:00:00Z",
    "backtestPeriods": 12,
    "performanceTarget": {
      "partyInvestigationsPerPeriodHint": "150"
    }
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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/my-instance/backtestResults?backtest_result_id=my-backtest-results" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

{
  "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/my-instance/backtestResults/my-backtest-results",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Exporter les métadonnées des résultats du test rétrospectif

Une fois un backtest exécuté, vous devez exporter ses résultats vers BigQuery pour les afficher. Pour exporter les métadonnées du résultat du backtest, utilisez la méthode projects.locations.instances.backtestResults.exportMetadata.

Corps JSON de la requête :

{
  "structuredMetadataDestination": {
    "tableUri": "bq://PROJECT_ID.my_bq_output_dataset.my_backtest_results_metadata",
    "writeDisposition": "WRITE_TRUNCATE"
  }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

cat > request.json << 'EOF'
{
  "structuredMetadataDestination": {
    "tableUri": "bq://PROJECT_ID.my_bq_output_dataset.my_backtest_results_metadata",
    "writeDisposition": "WRITE_TRUNCATE"
  }
}
EOF

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/my-instance/backtestResults/my-backtest-results:exportMetadata"

@'
{
  "structuredMetadataDestination": {
    "tableUri": "bq://PROJECT_ID.my_bq_output_dataset.my_backtest_results_metadata",
    "writeDisposition": "WRITE_TRUNCATE"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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/my-instance/backtestResults/my-backtest-results:exportMetadata" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

{
  "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/my-instance/backtestResults/my-backtest-results",
    "verb": "exportMetadata",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Une fois l'opération terminée, procédez comme suit:

1. Ouvrez BigQuery dans la console Google Cloud.

   Accéder à la console Google Cloud

2. Dans le volet Explorateur, recherchez et développez votre projet.

3. Développez my_bq_output_dataset, puis cliquez sur my_backtest_results_metadata.

4. Dans la barre de menu, cliquez sur Aperçu.

5. Dans la colonne name (Nom), recherchez la ligne contenant ObservedRecallValues.

   

6. Supposons que votre capacité d'investigations soit de 120 par mois. Recherchez l'objet de valeur de rappel avec "partyInvestigationsPerPeriod": "120". Pour les exemples de valeurs suivants, si vous limitez les investigations aux parties dont le score de risque est supérieur à 0,53, vous pouvez vous attendre à examiner 120 nouvelles parties chaque mois. Au cours de la période de rétrocompatibilité, l'année 2022, vous identifieriez 86% des cas que le système précédent avait identifiés (et éventuellement d'autres, qui n'ont pas été identifiés par vos processus actuels).

   {
     "recallValues": [
       ...
       {
         "partyInvestigationsPerPeriod": "105",
         "recallValue": 0.8142077,
         "scoreThreshold": 0.6071321
       },
       {
         "partyInvestigationsPerPeriod": "120",
         "recallValue": 0.863388,
         "scoreThreshold": 0.5339603
       },
       {
         "partyInvestigationsPerPeriod": "135",
         "recallValue": 0.89071035,
         "scoreThreshold": 0.4739899
       },
       ...
     ]
   }
   

En savoir plus sur les autres champs des résultats du backtest

En modifiant le champ partyInvestigationsPerPeriodHint, vous pouvez modifier le nombre d'investigations générées par un backtest. Pour obtenir des scores à examiner, enregistrez des parties et émettez des prédictions à leur sujet.

Importer des parties enregistrées

Avant de créer des résultats de prédiction, vous devez importer les parties enregistrées (c'est-à-dire les clients de l'ensemble de données).

Pour importer des parties enregistrées, utilisez la méthode projects.locations.instances.importRegisteredParties.

Corps JSON de la requête :

{
  "partyTables": [
     "bq://PROJECT_ID.my_bq_input_dataset.party_registration"
  ],
  "mode": "REPLACE",
  "lineOfBusiness": "COMMERCIAL"
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

cat > request.json << 'EOF'
{
  "partyTables": [
     "bq://PROJECT_ID.my_bq_input_dataset.party_registration"
  ],
  "mode": "REPLACE",
  "lineOfBusiness": "COMMERCIAL"
}
EOF

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/my-instance:importRegisteredParties"

@'
{
  "partyTables": [
     "bq://PROJECT_ID.my_bq_input_dataset.party_registration"
  ],
  "mode": "REPLACE",
  "lineOfBusiness": "COMMERCIAL"
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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/my-instance:importRegisteredParties" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

{
  "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/my-instance",
    "verb": "importRegisteredParties",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Vérifiez le résultat de cette opération jusqu'à sa fin. Une fois l'opération terminée, vous devriez voir que 10 000 partis ont été enregistrées dans la sortie JSON.

Créer un résultat de prédiction

Créez un résultat de prédiction pour les 12 derniers mois de l'ensemble de données. Ces mois n'ont pas été utilisés pendant l'entraînement. La création de résultats de prédiction génère des scores pour chaque parti chaque mois pour toutes les périodes de prédiction.

Pour créer un résultat de prédiction, utilisez la méthode projects.locations.instances.predictionResults.create.

Corps JSON de la requête :

{
    "model": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/models/my-model",
    "dataset": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/datasets/my-dataset",
    "endTime": "2023-01-01T00:00:00Z",
    "predictionPeriods": "12",
    "outputs": {
      "predictionDestination": {
        "tableUri": "bq://PROJECT_ID.my_bq_output_dataset.my_prediction_results",
        "writeDisposition": "WRITE_TRUNCATE"
      },
      "explainabilityDestination": {
        "tableUri": "bq://PROJECT_ID.my_bq_output_dataset.my_prediction_results_explainability",
        "writeDisposition": "WRITE_TRUNCATE"
      }
    }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

cat > request.json << 'EOF'
{
    "model": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/models/my-model",
    "dataset": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/datasets/my-dataset",
    "endTime": "2023-01-01T00:00:00Z",
    "predictionPeriods": "12",
    "outputs": {
      "predictionDestination": {
        "tableUri": "bq://PROJECT_ID.my_bq_output_dataset.my_prediction_results",
        "writeDisposition": "WRITE_TRUNCATE"
      },
      "explainabilityDestination": {
        "tableUri": "bq://PROJECT_ID.my_bq_output_dataset.my_prediction_results_explainability",
        "writeDisposition": "WRITE_TRUNCATE"
      }
    }
}
EOF

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/my-instance/predictionResults?prediction_result_id=my-prediction-results"

@'
{
    "model": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/models/my-model",
    "dataset": "projects/PROJECT_ID/locations/LOCATION/instances/my-instance/datasets/my-dataset",
    "endTime": "2023-01-01T00:00:00Z",
    "predictionPeriods": "12",
    "outputs": {
      "predictionDestination": {
        "tableUri": "bq://PROJECT_ID.my_bq_output_dataset.my_prediction_results",
        "writeDisposition": "WRITE_TRUNCATE"
      },
      "explainabilityDestination": {
        "tableUri": "bq://PROJECT_ID.my_bq_output_dataset.my_prediction_results_explainability",
        "writeDisposition": "WRITE_TRUNCATE"
      }
    }
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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/my-instance/predictionResults?prediction_result_id=my-prediction-results" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

{
  "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/my-instance/predictionResults/my-prediction-results",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Analyser un seul cas de structuration dans la console Google Cloud

1. Ouvrez BigQuery dans la console Google Cloud.

   Accéder à la console Google Cloud

2. Dans le volet des détails, cliquez sur l'onglet Requête sans titre pour afficher l'éditeur.

3. Copiez l'instruction SQL suivante dans l'éditeur, puis cliquez sur Exécuter.

   SELECT *
   FROM `PROJECT_ID.my_bq_input_dataset.transaction`
   WHERE account_id = '1E60OAUNKP84WDKB' AND DATE_TRUNC(book_time, MONTH) = "2022-08-01"
   ORDER by book_time
   

   Ce relevé vérifie l'ID de compte 1E60OAUNKP84WDKB en août 2022. Ce compte est associé à l'ID de partie EGS4NJD38JZ8NTL8. Pour trouver l'ID de partie d'un ID de compte donné, utilisez la table AccountPartyLink.

   Les données de transaction montrent des transactions fréquentes et arrondies ciblant un seul compte peu de temps après de gros dépôts en espèces, ce qui semble suspect. Ces transactions peuvent indiquer un smurfing (c'est-à-dire la division d'une grande transaction en plusieurs petites transactions) ou une structuration.

   

4. Copiez l'instruction SQL suivante dans l'éditeur, puis cliquez sur Exécuter.

   SELECT *
   FROM `PROJECT_ID.my_bq_input_dataset.risk_case_event`
   WHERE party_id = 'EGS4NJD38JZ8NTL8'
   

   Cette déclaration montre qu'il y a eu un cas de risque ayant entraîné la sortie de ce tiers. La demande de risque a été lancée deux mois après l'activité suspecte.

   

5. Copiez l'instruction SQL suivante dans l'éditeur, puis cliquez sur Exécuter.

   SELECT *
   FROM `PROJECT_ID.my_bq_output_dataset.my_prediction_results`
   WHERE party_id = 'EGS4NJD38JZ8NTL8'
   ORDER BY risk_period_end_time
   

   En vérifiant les résultats de la prédiction, vous pouvez constater que le score de risque de la partie passe de presque zéro (notez la valeur de l'exposant) à des valeurs élevées dans les mois qui suivent l'activité suspecte. Vos résultats peuvent différer de ceux affichés.

   

   Le score de risque n'est pas une probabilité. Un score de risque doit toujours être évalué par rapport aux autres scores de risque. Par exemple, une valeur apparemment faible peut être considérée comme positive lorsque les autres scores de risque sont inférieurs.

6. Copiez l'instruction SQL suivante dans l'éditeur, puis cliquez sur Exécuter.

   SELECT *
   FROM `PROJECT_ID.my_bq_output_dataset.my_prediction_results_explainability`
   WHERE party_id = 'EGS4NJD38JZ8NTL8'
   AND risk_period_end_time = '2022-10-01'
   

   En examinant les résultats d'explicabilité, vous pouvez constater que les familles de caractéristiques correctes obtiennent les valeurs les plus élevées.