Esta página mostra como criar e gerir resultados de testes retroativos de previsões de IA de AML. O teste retroativo da previsão usa um modelo preparado com base nos dados do histórico existentes. Para estes meses, o conjunto de dados tem de conter uma parte com datas de início de atividade ou investigação suspeitas que originem um evento AML_EXIT
. Para mais informações sobre como a IA de AML etiqueta várias partes, consulte o ciclo de vida de um registo de risco.
O mesmo conjunto de dados pode ser usado para a preparação e o teste retroativo, desde que a data de fim da preparação seja anterior às datas do teste retroativo.
Antes de começar
-
Para receber as autorizações necessárias para criar e gerir resultados de testes retrospetivos, peça ao seu administrador para lhe conceder a função de administrador de serviços financeiros (
financialservices.admin
) do IAM no seu projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.
- Crie uma instância
- Crie um modelo
- Crie um conjunto de dados
Crie resultados de testes retroativos
Alguns métodos da API devolvem uma operação de longa duração (LRO). Estes métodos são assíncronos e devolvem um objeto Operation. Para ver detalhes, consulte a referência REST. A operação pode não estar concluída quando o método devolve uma resposta. Para estes métodos, envie o pedido e, em seguida, verifique o resultado. Em geral, todas as operações POST, PUT, UPDATE e DELETE são de longa duração.
Envie o pedido
Para criar resultados de testes retroativos, use o método
projects.locations.instances.backtestResults.create
.
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
PROJECT_ID
: o ID do seu Google Cloud projeto indicado nas definições de IAMLOCATION
: a localização da instância; use uma das regiões suportadasMostrar localizaçõesus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
INSTANCE_ID
: um identificador definido pelo utilizador para a instânciaBACKTEST_RESULTS_ID
: um identificador definido pelo utilizador para os resultados do teste retrospetivoMODEL_ID
: um identificador definido pelo utilizador para o modeloBACKTEST_DATASET_ID
: o identificador definido pelo utilizador para o conjunto de dados usado para o teste retrospetivo; as tabelas não devem ter as colunas de etiquetas de preparaçãoBACKTEST_END_DATE
: a hora mais recente a partir da qual os dados são usados para gerar funcionalidades para testes retrospetivos. Esta data deve ser igual ou anterior à hora de fim dos conjuntos de dados. Use o formato "Zulu" UTC RFC3339 (por exemplo,2014-10-02T15:01:23Z
).PARTY_INVESTIGATIONS_PER_PERIOD_HINT
: Um número que dá ao otimizador uma sugestão sobre o número de partes destes dados que vão ser investigadas por período (mensal). Isto é usado para controlar a forma como o modelo é avaliado. Por exemplo, quando tentar usar a IA de AML pela primeira vez, recomendamos que defina este valor para o número de partes investigadas num mês médio, com base em alertas do seu sistema de alertas automatizado existente.
Corpo JSON do pedido:
{ "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" } }
Para enviar o seu pedido, escolha uma destas opções:
curl
Guarde o corpo do pedido num ficheiro denominado request.json
.
Execute o seguinte comando no terminal para criar ou substituir
este ficheiro no diretório atual:
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
Em seguida, execute o seguinte comando para enviar o seu pedido 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
Guarde o corpo do pedido num ficheiro denominado request.json
.
Execute o seguinte comando no terminal para criar ou substituir
este ficheiro no diretório atual:
@' { "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
Em seguida, execute o seguinte comando para enviar o seu pedido 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
Deve receber uma resposta JSON semelhante à seguinte:
{ "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 }
Verifique o resultado
Para verificar se foram criados resultados de testes retrospetivos, use o método
projects.locations.operations.get
. Se a resposta contiver "done": false
, repita o comando até que a resposta contenha "done": true
. Estas operações podem demorar alguns minutos a várias horas a serem concluídas.
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
PROJECT_ID
: o ID do projeto indicado nas definições de IAM Google CloudLOCATION
: a localização da instância; use uma das regiões suportadasMostrar localizaçõesus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
OPERATION_ID
: o identificador da operação
Para enviar o seu pedido, escolha uma destas opções:
curl
Execute o seguinte 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
Execute o seguinte 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
Deve receber uma resposta JSON semelhante à seguinte:
{ "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" ] } }
Exporte metadados
Para exportar metadados dos resultados do teste retrospetivo, use o método projects.locations.instances.backtestResults.exportMetadata
.
Para mais informações, consulte o artigo Metadados exportados no modelo de dados de saída da AML.
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
PROJECT_ID
: o ID do seu Google Cloud projeto indicado nas definições de IAMLOCATION
: a localização da instância; use uma das regiões suportadasMostrar localizaçõesus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
INSTANCE_ID
: o identificador definido pelo utilizador para a instânciaBACKTEST_RESULTS_ID
: um identificador definido pelo utilizador para os resultados do teste retrospetivoBQ_OUTPUT_DATASET_NAME
: um conjunto de dados do BigQuery no qual exportar uma tabela que descreve os metadados estruturados dos resultados do teste retroativoSTRUCTURED_METADATA_TABLE
: a tabela na qual escrever os metadados estruturadosWRITE_DISPOSITION
: a ação que ocorre se a tabela de destino já existir; use um dos seguintes valores:-
WRITE_EMPTY
: exporte dados apenas se a tabela do BigQuery estiver vazia. -
WRITE_TRUNCATE
: apaga todos os dados existentes na tabela do BigQuery antes de escrever na tabela.
-
Corpo JSON do pedido:
{ "structuredMetadataDestination": { "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.STRUCTURED_METADATA_TABLE", "writeDisposition": "WRITE_DISPOSITION" } }
Para enviar o seu pedido, escolha uma destas opções:
curl
Guarde o corpo do pedido num ficheiro denominado request.json
.
Execute o seguinte comando no terminal para criar ou substituir
este ficheiro no diretório atual:
cat > request.json << 'EOF' { "structuredMetadataDestination": { "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.STRUCTURED_METADATA_TABLE", "writeDisposition": "WRITE_DISPOSITION" } } EOF
Em seguida, execute o seguinte comando para enviar o seu pedido 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
Guarde o corpo do pedido num ficheiro denominado request.json
.
Execute o seguinte comando no terminal para criar ou substituir
este ficheiro no diretório atual:
@' { "structuredMetadataDestination": { "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.STRUCTURED_METADATA_TABLE", "writeDisposition": "WRITE_DISPOSITION" } } '@ | Out-File -FilePath request.json -Encoding utf8
Em seguida, execute o seguinte comando para enviar o seu pedido 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
Deve receber uma resposta JSON semelhante à seguinte:
{ "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 }
Para mais informações sobre como obter o resultado da operação de longa duração (LRO), consulte a secção Verifique o resultado.
Obtenha resultados de testes retroativos
Para obter resultados de testes retrospetivos, use o método projects.locations.instances.backtestResults.get
.
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
PROJECT_ID
: o ID do seu Google Cloud projeto indicado nas definições de IAMLOCATION
: a localização da instância; use uma das regiões suportadasMostrar localizaçõesus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
INSTANCE_ID
: o identificador definido pelo utilizador para a instânciaBACKTEST_RESULTS_ID
: o identificador definido pelo utilizador para os resultados do teste retrospetivo
Para enviar o seu pedido, escolha uma destas opções:
curl
Execute o seguinte 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
Execute o seguinte 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
Deve receber uma resposta JSON semelhante à seguinte:
{ "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" }
Atualize os resultados do teste retrospetivo
Para atualizar os resultados dos testes retroativos, use o método
projects.locations.instances.backtestResults.patch
.
Só é possível atualizar o campo labels
nos resultados do teste retrospetivo. O exemplo
seguinte atualiza o par de chave-valor
etiquetas de utilizador
associado aos resultados do teste retrospetivo.
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
PROJECT_ID
: o ID do seu Google Cloud projeto indicado nas definições de IAMLOCATION
: a localização da instância; use uma das regiões suportadasMostrar localizaçõesus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
INSTANCE_ID
: o identificador definido pelo utilizador para a instânciaBACKTEST_RESULTS_ID
: o identificador definido pelo utilizador para os resultados do teste retrospetivoKEY
: a chave num par de chave-valor usado para organizar os resultados do teste retrospetivo. Consultelabels
para mais informações.VALUE
: o valor num par de chave-valor usado para organizar os resultados dos testes retroativos. Consultelabels
para mais informações.
Corpo JSON do pedido:
{ "labels": { "KEY": "VALUE" } }
Para enviar o seu pedido, escolha uma destas opções:
curl
Guarde o corpo do pedido num ficheiro denominado request.json
.
Execute o seguinte comando no terminal para criar ou substituir
este ficheiro no diretório atual:
cat > request.json << 'EOF' { "labels": { "KEY": "VALUE" } } EOF
Em seguida, execute o seguinte comando para enviar o seu pedido 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
Guarde o corpo do pedido num ficheiro denominado request.json
.
Execute o seguinte comando no terminal para criar ou substituir
este ficheiro no diretório atual:
@' { "labels": { "KEY": "VALUE" } } '@ | Out-File -FilePath request.json -Encoding utf8
Em seguida, execute o seguinte comando para enviar o seu pedido 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
Deve receber uma resposta JSON semelhante à seguinte:
{ "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 }
Para mais informações sobre como obter o resultado da operação de longa duração (LRO), consulte a secção Verifique o resultado.
Listar os resultados do teste retroativo
Para listar os resultados do teste retrospetivo de uma determinada instância, use o método
projects.locations.instances.backtestResults.list
.
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
PROJECT_ID
: o ID do seu Google Cloud projeto indicado nas definições de IAMLOCATION
: a localização da instância; use uma das regiões suportadasMostrar localizaçõesus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
INSTANCE_ID
: o identificador definido pelo utilizador para a instância
Para enviar o seu pedido, escolha uma destas opções:
curl
Execute o seguinte 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
Execute o seguinte 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
Deve receber uma resposta JSON semelhante à seguinte:
{ "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" } ] }
Elimine os resultados do teste retroativo
Para eliminar os resultados do teste retrospetivo, use o método
projects.locations.instances.backtestResults.delete
.
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
PROJECT_ID
: o ID do seu Google Cloud projeto indicado nas definições de IAMLOCATION
: a localização da instância; use uma das regiões suportadasMostrar localizaçõesus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
INSTANCE_ID
: o identificador definido pelo utilizador para a instânciaBACKTEST_RESULTS_ID
: o identificador definido pelo utilizador para os resultados do teste retrospetivo
Para enviar o seu pedido, escolha uma destas opções:
curl
Execute o seguinte 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
Execute o seguinte 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
Deve receber uma resposta JSON semelhante à seguinte:
{ "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 }
Para mais informações sobre como obter o resultado da operação de longa duração (LRO), consulte a secção Verifique o resultado.