Criar e gerenciar configurações de mecanismo

Nesta página, mostramos como criar e gerenciar configurações do mecanismo da IA do AML, que são configurações para modelos de treinamento. Uma configuração de mecanismo pode incluir informações ajustadas para conjuntos de dados específicos.

Só é preciso criar a configuração do mecanismo neste momento. Os outros métodos de configuração do mecanismo são fornecidos como conveniência.

Antes de começar

Criar uma configuração de mecanismo

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. A operação pode não estar 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 uma configuração de mecanismo, use o método projects.locations.instances.engineConfigs.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
    • europe-west1
    • europe-west2
    • europe-west4
    • southamerica-east1
  • INSTANCE_ID: o identificador da instância definido pelo usuário.
  • ENGINE_CONFIG_ID: um identificador definido pelo usuário para a configuração do mecanismo
  • ENGINE_VERSION_ID: a versão do mecanismo, usada para as definições iniciais da configuração do mecanismo
  • DATASET_ID: o identificador definido pelo usuário para o conjunto de dados principal usado para ajustar um modelo
  • TUNING_END_DATE: o horário mais recente em que os dados são usados para gerar recursos de treinamento. 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 investigações que serão realizadas nesses dados por período (mensal). Isso é usado para controlar como o modelo é avaliado.

Solicitar corpo JSON:

{
  "engineVersion": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineVersions/ENGINE_VERSION_ID",
  "tuning": {
    "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
    "endTime": "TUNING_END_DATE",
  },
  "performanceTarget": {
    "partyInvestigationsPerPeriodHint": "PARTY_INVESTIGATIONS_PER_PERIOD_HINT"
  }
}

Para enviar a solicitação, expanda uma destas opções:

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

Conferir o resultado

Use o método projects.locations.operations.get para verificar se a configuração do mecanismo foi criada. 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 do IAM
  • LOCATION: o local da instância. Use uma das regiões compatíveis:
    • us-central1
    • us-east1
    • europe-west1
    • europe-west2
    • europe-west4
    • southamerica-east1
  • OPERATION_ID: o identificador da operação.

Para enviar a solicitação, expanda uma destas opções:

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/engineConfigs/ENGINE_CONFIG_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.EngineConfig",
    "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineConfigs/ENGINE_CONFIG_ID",
    "createTime": CREATE_TIME,
    "updateTime": UPDATE_TIME,
    "state": "ACTIVE",
    "engineVersion": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineVersions/ENGINE_VERSION_ID",
    "tuning": {
      "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
      "endTime": "TUNING_END_DATE",
    },
    "performanceTarget": {
      "partyInvestigationsPerPeriodHint": "PARTY_INVESTIGATIONS_PER_PERIOD_HINT"
    },
    "lineOfBusiness": "RETAIL",
    "billingUuid": "BILLING_UUID"
  }
}

Acessar uma configuração de mecanismo

Para acessar uma configuração de mecanismo, use o método projects.locations.instances.engineConfigs.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
    • europe-west1
    • europe-west2
    • europe-west4
    • southamerica-east1
  • INSTANCE_ID: o identificador da instância definido pelo usuário.
  • ENGINE_CONFIG_ID: o identificador definido pelo usuário para a configuração do mecanismo.

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineConfigs/ENGINE_CONFIG_ID",
  "createTime": CREATE_TIME,
  "updateTime": UPDATE_TIME,
  "state": "ACTIVE",
  "engineVersion": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineVersions/ENGINE_VERSION_ID",
  "tuning": {
    "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
    "endTime": "TUNING_END_DATE",
  },
  "performanceTarget": {
    "partyInvestigationsPerPeriodHint": "PARTY_INVESTIGATIONS_PER_PERIOD_HINT"
  },
  "lineOfBusiness": "RETAIL"
}

Atualizar uma configuração de mecanismo

Para atualizar uma configuração de mecanismo, use o método projects.locations.instances.engineConfigs.patch.

Nem todos os campos em uma configuração de mecanismo podem ser atualizados. O exemplo a seguir atualiza os rótulos de usuário do par de chave-valor associados à configuração do mecanismo.

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
    • europe-west1
    • europe-west2
    • europe-west4
    • southamerica-east1
  • INSTANCE_ID: o identificador da instância definido pelo usuário.
  • ENGINE_CONFIG_ID: o identificador definido pelo usuário para a configuração do mecanismo.
  • KEY: a chave em um par de chave-valor usado para organizar as configurações do mecanismo. Consulte labels para ver mais informações.
  • VALUE: o valor em um par de chave-valor usado para organizar as configurações do mecanismo. Consulte labels para ver mais informações.

Solicitar corpo JSON:

{
  "labels": {
    "KEY": "VALUE"
  }
}

Para enviar a solicitação, expanda uma destas opções:

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/engineConfigs/ENGINE_CONFIG_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 as configurações de mecanismo

Para listar as configurações de mecanismo de um determinado local, use o método projects.locations.instances.engineConfigs.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
    • europe-west1
    • europe-west2
    • europe-west4
    • southamerica-east1
  • INSTANCE_ID: o identificador da instância definido pelo usuário.

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "engineConfigs": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineConfigs/ENGINE_CONFIG_ID",
      "createTime": CREATE_TIME,
      "updateTime": UPDATE_TIME,
      "state": "ACTIVE",
      "engineVersion": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineVersions/ENGINE_VERSION_ID",
      "tuning": {
        "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
        "endTime": "TUNING_END_DATE",
      },
      "performanceTarget": {
        "partyInvestigationsPerPeriodHint": "PARTY_INVESTIGATIONS_PER_PERIOD_HINT"
      },
      "lineOfBusiness": "RETAIL"
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineConfigs/my-other-engine-config",
      "createTime": CREATE_TIME,
      "updateTime": UPDATE_TIME,
      "state": "ACTIVE",
      "engineVersion": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/engineVersions/ENGINE_VERSION_ID",
      "tuning": {
        "primaryDataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
        "endTime": "TUNING_END_DATE",
      },
      "performanceTarget": {
        "partyInvestigationsPerPeriodHint": "PARTY_INVESTIGATIONS_PER_PERIOD_HINT"
      },
      "lineOfBusiness": "RETAIL"
    }
  ]
}

Exportar metadados

Para exportar metadados de uma configuração de mecanismo, use o método projects.locations.instances.engineConfigs.exportMetadata.

Para mais informações, consulte Metadados exportados no modelo de dados de saí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
    • europe-west1
    • europe-west2
    • europe-west4
    • southamerica-east1
  • INSTANCE_ID: o identificador da instância definido pelo usuário.
  • ENGINE_CONFIG_ID: o identificador definido pelo usuário para a configuração do mecanismo.
  • BQ_OUTPUT_DATASET_NAME: um conjunto de dados do BigQuery para exportar uma tabela com os metadados estruturados da configuração do mecanismo
  • STRUCTURED_METADATA_TABLE: a tabela em que os metadados estruturados serão gravados.
  • WRITE_DISPOSITION: a ação que ocorre se a tabela de destino já existe. Use um dos seguintes valores:
    • WRITE_EMPTY: só exporta dados se a tabela do BigQuery estiver vazia.
    • WRITE_TRUNCATE: apaga 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, expanda uma destas opções:

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/engineConfigs/ENGINE_CONFIG_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.

Excluir uma configuração de mecanismo

Para excluir uma configuração de mecanismo, use o método projects.locations.instances.engineConfigs.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
    • europe-west1
    • europe-west2
    • europe-west4
    • southamerica-east1
  • INSTANCE_ID: o identificador da instância definido pelo usuário.
  • ENGINE_CONFIG_ID: o identificador definido pelo usuário para a configuração do mecanismo.

Para enviar a solicitação, expanda uma destas opções:

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/engineConfigs/ENGINE_CONFIG_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.