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-central1us-east1asia-south1europe-west1europe-west2europe-west4northamerica-northeast1southamerica-east1australia-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"
}
}
EOFEm 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 utf8Em 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-central1us-east1asia-south1europe-west1europe-west2europe-west4northamerica-northeast1southamerica-east1australia-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-central1us-east1asia-south1europe-west1europe-west2europe-west4northamerica-northeast1southamerica-east1australia-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"
}
}
EOFEm 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 utf8Em 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-central1us-east1asia-south1europe-west1europe-west2europe-west4northamerica-northeast1southamerica-east1australia-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-central1us-east1asia-south1europe-west1europe-west2europe-west4northamerica-northeast1southamerica-east1australia-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. Consultelabelspara mais informações.VALUE: o valor num par de chave-valor usado para organizar os resultados dos testes retroativos. Consultelabelspara 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"
}
}
EOFEm 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 utf8Em 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-central1us-east1asia-south1europe-west1europe-west2europe-west4northamerica-northeast1southamerica-east1australia-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-central1us-east1asia-south1europe-west1europe-west2europe-west4northamerica-northeast1southamerica-east1australia-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.