Esta página foi traduzida pela API Cloud Translation.

Criar e gerenciar os resultados do backtest

Nesta página, mostramos como criar e gerenciar os resultados da previsão de backtest da IA antilavagem de dinheiro. A previsão de backtest usa um modelo treinado em dados históricos atuais. Para esses meses, o conjunto de dados precisa conter um rótulo.

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 do backtest.

Você só precisa criar os resultados do backtest e exportar os metadados associados neste momento. Os outros métodos de resultados de backtest são fornecidos como conveniência.

Antes de começar

Para receber as permissões necessárias para criar e gerenciar os resultados do backtest, peça ao administrador que conceda a você o papel de Administrador de serviços financeiros (financialservices.admin) do IAM no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

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
Criar 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. Talvez a operação não esteja concluída quando o método retornar uma resposta. Para esses métodos, envie a solicitação e verifique o resultado.

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, faça as substituições a seguir:

PROJECT_ID: o ID do projeto do Google Cloud listado nas Configurações do IAM
LOCATION: o local da instância. Use uma das regiões compatíveis:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
INSTANCE_ID: um identificador definido pelo usuário para a instância.
BACKTEST_RESULTS_ID: um identificador definido pelo usuário para os resultados do backtest
MODEL_ID: um identificador definido pelo usuário para o modelo
BACKTEST_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ótulos de treinamento.
BACKTEST_END_DATE: o horário mais recente em que os dados são usados para gerar recursos para backtests. Essa data precisa ser igual ou anterior ao horário 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 investigadas por período (mensal). Isso é usado para controlar como o modelo é avaliado. Por exemplo, ao testar a IA antilavagem de dinheiro pela primeira vez, recomendamos definir como o número de partes investigadas em um mês médio, com base nos alertas do sistema de alertas automatizado atual.

Solicitar corpo JSON:

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

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
}

Conferir 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 de alguns minutos a várias horas para serem concluídas.

Antes de usar os dados da solicitação, faça as substituições a seguir:

PROJECT_ID: o ID do projeto do Google Cloud listado nas Configurações de IAM.
LOCATION: o local da instância. Use uma das regiões compatíveis:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
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": CREATE_TIME,
    "endTime": END_TIME,
    "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 de 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 da AML.

Antes de usar os dados da solicitação, faça as substituições a seguir:

PROJECT_ID: o ID do projeto do Google Cloud listado nas Configurações do IAM
LOCATION: o local da instância. Use uma das regiões compatíveis:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
INSTANCE_ID: o identificador definido pelo usuário para a instância
BACKTEST_RESULTS_ID: um identificador definido pelo usuário para os resultados do backtest
BQ_OUTPUT_DATASET_NAME: um conjunto de dados do BigQuery em que é possível exportar uma tabela com a descrição dos metadados estruturados dos resultados do backtest
STRUCTURED_METADATA_TABLE: a tabela em que os metadados estruturados serão gravados.
WRITE_DISPOSITION: a ação que ocorrerá se a tabela de destino já existir. Use um dos seguintes valores:
- WRITE_EMPTY: exportar dados apenas se a tabela do BigQuery estiver vazia.
- WRITE_TRUNCATE: apague todos os dados atuais na tabela do BigQuery antes de gravar na tabela.

Solicitar corpo JSON:

{
  "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 conseguir o resultado da operação de longa duração (LRO, na sigla em inglês), consulte Verificar o resultado.

Métodos opcionais

Os métodos de resultados do backtest a seguir são fornecidos como conveniência.

Receber resultados do backtest

Para receber os resultados do backtest, use o método projects.locations.instances.backtestResults.get.

Antes de usar os dados da solicitação, faça as substituições a seguir:

PROJECT_ID: o ID do projeto do Google Cloud listado nas Configurações do IAM
LOCATION: o local da instância. Use uma das regiões compatíveis:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
INSTANCE_ID: o identificador definido pelo usuário para a instância
BACKTEST_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 os resultados do backtest

Para atualizar os resultados do backtest, use o método projects.locations.instances.backtestResults.patch.

Nem todos os campos nos resultados do backtest podem ser atualizados. O exemplo a seguir atualiza os rótulos de usuário do par de chave-valor associados aos resultados do backtest.

Antes de usar os dados da solicitação, faça as substituições a seguir:

PROJECT_ID: o ID do projeto do Google Cloud listado nas Configurações do IAM
LOCATION: o local da instância. Use uma das regiões compatíveis:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
INSTANCE_ID: o identificador definido pelo usuário para a instância
BACKTEST_RESULTS_ID: o identificador definido pelo usuário para os resultados do backtest
KEY: a chave em um par de chave-valor usada para organizar os resultados do backtest. Consulte labels para ver mais informações.
VALUE: o valor em um par de chave-valor usado para organizar os resultados do backtest. Consulte labels para ver mais informações.

Solicitar corpo JSON:

{
  "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 conseguir o resultado da operação de longa duração (LRO, na sigla em inglês), 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, faça as substituições a seguir:

PROJECT_ID: o ID do projeto do Google Cloud listado nas Configurações do IAM
LOCATION: o local da instância. Use uma das regiões compatíveis:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
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 do backtest

Para excluir os resultados do backtest, use o método projects.locations.instances.backtestResults.delete.

Antes de usar os dados da solicitação, faça as substituições a seguir:

PROJECT_ID: o ID do projeto do Google Cloud listado nas Configurações do IAM
LOCATION: o local da instância. Use uma das regiões compatíveis:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
INSTANCE_ID: o identificador definido pelo usuário para a instância
BACKTEST_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 conseguir o resultado da operação de longa duração (LRO, na sigla em inglês), consulte Verificar o resultado.