Esta página mostra como criar e gerenciar resultados de previsão de backtest de IA
de AML. A previsão de backtest usa um modelo treinado em dados históricos
existentes. Para esses meses, o conjunto de dados precisa conter uma parte com
atividade suspeita ou datas de início da investigação que levam a um evento AML_EXIT
. Para mais informações sobre como a IA de AML rotula várias partes, consulte o
ciclo de vida de um caso de risco.
O mesmo conjunto de dados pode ser usado para treinamento e backtest, desde que a data de término do treinamento seja anterior às datas de backtest.
Antes de começar
-
Para receber as permissões necessárias para criar e gerenciar resultados de backtest, peça ao administrador para conceder a você o papel do IAM de administrador de serviços financeiros (
financialservices.admin
) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.
- Criar uma instância
- Criar um modelo
- crie um conjunto de dados
Criar resultados de backtest
Alguns métodos da API retornam uma operação de longa duração (LRO, na sigla em inglês). Esses métodos são assíncronos e retornam um objeto Operation. Para saber mais, consulte a Referência REST. A operação pode não ser concluída quando o método retornar uma resposta. Para esses métodos, envie a solicitação e verifique o resultado. Em geral, todas as operações POST, PUT, UPDATE e DELETE são de longa duração.
Enviar a solicitação
Para criar resultados de backtest, use o
método
projects.locations.instances.backtestResults.create
.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID
: o ID do projeto do Google Cloud listado nas Configurações do IAMLOCATION
: o local da instância. Use uma das regiões compatíveis.Mostrar locaisus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
INSTANCE_ID
: um identificador definido pelo usuário para a instânciaBACKTEST_RESULTS_ID
: um identificador definido pelo usuário para os resultados do backtestMODEL_ID
: um identificador definido pelo usuário para o modeloBACKTEST_DATASET_ID
: o identificador definido pelo usuário para o conjunto de dados usado no backtest. As tabelas não podem ter colunas de rótulo de treinamento.BACKTEST_END_DATE
: o tempo mais recente em que os dados são usados para gerar recursos para testes retrospectivos. Essa data precisa ser igual ou anterior à data de término dos conjuntos de dados. Use o formato UTC "Zulu" RFC3339 (por exemplo,2014-10-02T15:01:23Z
).PARTY_INVESTIGATIONS_PER_PERIOD_HINT
: um número que dá ao sintonizador uma dica sobre o número de partes desses dados que serão investigados por período (mensal). Ele é usado para controlar como o modelo é avaliado. Por exemplo, ao testar a IA de AML pela primeira vez, recomendamos definir esse valor como o número de partes investigadas em um mês médio, com base nos alertas do seu sistema de alertas automatizado.
Corpo JSON da solicitação:
{ "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 a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo chamado request.json
.
Execute o comando a seguir no terminal para criar ou substituir
esse arquivo 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
Depois execute o comando a seguir para enviar a solicitação 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
Salve o corpo da solicitação em um arquivo chamado request.json
.
Execute o comando a seguir no terminal para criar ou substituir
esse arquivo 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
Depois execute o comando a seguir para enviar a solicitação 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
Você receberá uma resposta JSON semelhante a esta:
{ "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 }
Verificar o resultado
Para verificar se os resultados do backtest foram criados, use o
método
projects.locations.operations.get
. Se a resposta contiver "done": false
, repita o comando até que
a resposta contenha "done": true
. Essas operações podem levar alguns minutos ou
várias horas para serem concluídas.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID
: o ID do projeto do Google Cloud listado nas Configurações do IAMLOCATION
: o local da instância. Use uma das regiões compatíveis.Mostrar locaisus-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 a solicitação, 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
Você receberá uma resposta JSON semelhante a esta:
{ "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" ] } }
Exportar metadados
Para exportar metadados dos resultados de backtest, use o
método
projects.locations.instances.backtestResults.exportMetadata
.
Para mais informações, consulte Metadados exportados no modelo de dados de saída do AML.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID
: o ID do projeto do Google Cloud listado nas Configurações do IAMLOCATION
: o local da instância. Use uma das regiões compatíveis.Mostrar locaisus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
INSTANCE_ID
: o identificador definido pelo usuário para a instânciaBACKTEST_RESULTS_ID
: um identificador definido pelo usuário para os resultados do backtestBQ_OUTPUT_DATASET_NAME
: um conjunto de dados do BigQuery para exportar uma tabela que descreve os metadados estruturados dos resultados do backtestSTRUCTURED_METADATA_TABLE
: a tabela para gravar os metadados estruturadosWRITE_DISPOSITION
: a ação que ocorre se a tabela de destino já existir. Use um dos seguintes valores:-
WRITE_EMPTY
: só exporta dados se a tabela do BigQuery estiver vazia. -
WRITE_TRUNCATE
: apague todos os dados da tabela do BigQuery antes de gravar nela.
-
Corpo JSON da solicitação:
{ "structuredMetadataDestination": { "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.STRUCTURED_METADATA_TABLE", "writeDisposition": "WRITE_DISPOSITION" } }
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo chamado request.json
.
Execute o comando a seguir no terminal para criar ou substituir
esse arquivo no diretório atual:
cat > request.json << 'EOF' { "structuredMetadataDestination": { "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.STRUCTURED_METADATA_TABLE", "writeDisposition": "WRITE_DISPOSITION" } } EOF
Depois execute o comando a seguir para enviar a solicitação 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
Salve o corpo da solicitação em um arquivo chamado request.json
.
Execute o comando a seguir no terminal para criar ou substituir
esse arquivo 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
Depois execute o comando a seguir para enviar a solicitação 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
Você receberá uma resposta JSON semelhante a esta:
{ "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 receber o resultado da operação de longa duração (LRO), consulte Verificar o resultado.
Conferir os resultados do backtest
Para receber os resultados do teste de regressão, use o
método
projects.locations.instances.backtestResults.get
.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID
: o ID do projeto do Google Cloud listado nas Configurações do IAMLOCATION
: o local da instância. Use uma das regiões compatíveis.Mostrar locaisus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
INSTANCE_ID
: o identificador definido pelo usuário para a instânciaBACKTEST_RESULTS_ID
: o identificador definido pelo usuário para os resultados do backtest
Para enviar a solicitação, 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
Você receberá uma resposta JSON semelhante a esta:
{ "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" }
Atualizar resultados do backtest
Para atualizar os resultados do backtest, use o
método
projects.locations.instances.backtestResults.patch
.
Somente o campo labels
nos resultados de backtest pode ser atualizado. O exemplo
a seguir atualiza o par de chave-valor
rótulos do usuário
associado aos resultados do backtest.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID
: o ID do projeto do Google Cloud listado nas Configurações do IAMLOCATION
: o local da instância. Use uma das regiões compatíveis.Mostrar locaisus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
INSTANCE_ID
: o identificador definido pelo usuário para a instânciaBACKTEST_RESULTS_ID
: o identificador definido pelo usuário para os resultados do backtestKEY
: a chave em um par de chave-valor usado para organizar os resultados do backtest. Consultelabels
para ver mais informações.VALUE
: o valor em um par de chave-valor usado para organizar os resultados do backtest. Consultelabels
para ver mais informações.
Corpo JSON da solicitação:
{ "labels": { "KEY": "VALUE" } }
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo chamado request.json
.
Execute o comando a seguir no terminal para criar ou substituir
esse arquivo no diretório atual:
cat > request.json << 'EOF' { "labels": { "KEY": "VALUE" } } EOF
Depois execute o comando a seguir para enviar a solicitação 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
Salve o corpo da solicitação em um arquivo chamado request.json
.
Execute o comando a seguir no terminal para criar ou substituir
esse arquivo no diretório atual:
@' { "labels": { "KEY": "VALUE" } } '@ | Out-File -FilePath request.json -Encoding utf8
Depois execute o comando a seguir para enviar a solicitação 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
Você receberá uma resposta JSON semelhante a esta:
{ "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 receber o resultado da operação de longa duração (LRO), consulte Verificar o resultado.
Listar os resultados do backtest
Para listar os resultados do backtest de uma determinada instância, use o
método
projects.locations.instances.backtestResults.list
.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID
: o ID do projeto do Google Cloud listado nas Configurações do IAMLOCATION
: o local da instância. Use uma das regiões compatíveis.Mostrar locaisus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
INSTANCE_ID
: o identificador definido pelo usuário para a instância
Para enviar a solicitação, 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
Você receberá uma resposta JSON semelhante a esta:
{ "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" } ] }
Excluir resultados de backtest
Para excluir resultados de backtest, use o
método
projects.locations.instances.backtestResults.delete
.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID
: o ID do projeto do Google Cloud listado nas Configurações do IAMLOCATION
: o local da instância. Use uma das regiões compatíveis.Mostrar locaisus-central1
us-east1
asia-south1
europe-west1
europe-west2
europe-west4
northamerica-northeast1
southamerica-east1
australia-southeast1
INSTANCE_ID
: o identificador definido pelo usuário para a instânciaBACKTEST_RESULTS_ID
: o identificador definido pelo usuário para os resultados do backtest
Para enviar a solicitação, 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
Você receberá uma resposta JSON semelhante a esta:
{ "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 receber o resultado da operação de longa duração (LRO), consulte Verificar o resultado.