Criar estudos do Vizier no Agent Platform

Nesta página, descrevemos como fazer solicitações de API para o Agent Platform Vizier usando Python. Para informações sobre como o Vizier da Agent Platform funciona, consulte Visão geral do Vizier da Agent Platform.

Para ver um exemplo de otimização de vários objetivos como parte de um fluxo de trabalho mais abrangente, execute o notebook "Como otimizar vários objetivos" em um dos seguintes ambientes:

Abrir no Colab | Abrir no Colab Enterprise | Abrir no Agent Platform Workbench | Ver no GitHub

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Agent Platform API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Agent Platform API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

1. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:

   gcloud auth application-default login

   Não é necessário fazer isso se você estiver usando o Cloud Shell.

   Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

2. Instale o SDK da Agent Platform para Python.

definir constantes

Para definir constantes, execute os seguintes comandos, substituindo REGION e PROJECT_ID pela região e pelo ID do projeto. Crie seu próprio nome de estudo ou use os valores sugeridos.

import json
import datetime
from google.cloud import aiplatform

REGION = "REGION"
PROJECT_ID = "PROJECT_ID"

# The following placeholder variables are automatically filled in.
STUDY_DISPLAY_NAME = '{}_study_{}'.format(PROJECT_ID.replace('-', ''), datetime.datetime.now().strftime('%Y%m%d_%H%M%S')) #@param {type: 'string'}
ENDPOINT = REGION + '-aiplatform.googleapis.com'
PARENT = 'projects/{}/locations/{}'.format(PROJECT_ID, REGION)

Crie solicitações de API

As solicitações da API de linha de comando a seguir são escritas em Python.

Criar um estudo

Um estudo é uma série de experimentos, ou testes, que ajudam a otimizar seus hiperparâmetros ou parâmetros.

No exemplo a seguir, a meta é maximizar y = x^2 com x no intervalo de [-10. 10]. Este exemplo tem apenas um parâmetro e usa uma função calculada para ajudar a demonstrar como usar o Agent Platform Vizier.

param_x = {
    'parameter_id': 'x',
    'double_value_spec': {
        'min_value': -10.0,
        'max_value': 10.0
    }
}

metric_y = {
    'metric_id': 'y',
    'goal': 'MAXIMIZE'
}

study = {
    'display_name': STUDY_DISPLAY_NAME,
    'study_spec': {
      'algorithm': 'RANDOM_SEARCH',
      'parameters': [param_x],
      'metrics': [metric_y],
    }
}

Para criar o estudo usando a configuração, envie a seguinte solicitação por meio do VizierServiceClient. Use o STUDY_NAME retornado para consultar o estudo.

vizier_client = aiplatform.gapic.VizierServiceClient(client_options=dict(api_endpoint=ENDPOINT))
study = vizier_client.create_study(parent=PARENT, study=study)
STUDY_NAME = study.name

Ver seu estudo

Depois que o estudo for criado, você poderá encontrá-lo no Google Cloud console, na seção "Gemini Enterprise Agent Platform", na página Experimentos.

Acessar a página "Experimentos"

Receber um estudo

Para receber um estudo, envie a solicitação a seguir.

vizier_client.get_study({'name': STUDY_NAME})

Listar estudos

Para listar estudos em um projeto e região específicos, envie a solicitação a seguir:

vizier_client.list_studies({'parent': PARENT})

Receber testes sugeridos

Para receber uma sugestão de teste do Agent Platform Vizier, crie uma solicitação que contenha um SUGGEST_COUNT e um CLIENT_ID. Envie essas informações para o Agent Platform Vizier enviando a solicitação.

Crie a solicitação usando os comandos a seguir. Altere o SUGGEST_COUNT para o número de sugestões que quer receber de cada solicitação.

suggest_response = vizier_client.suggest_trials({
    'parent': STUDY_NAME,
    'suggestion_count': SUGGEST_COUNT,
    'client_id': CLIENT_ID
    })

suggest_trials inicia uma operação de longa duração para gerar o teste. A resposta informa que o Agent Platform Vizier está trabalhando nas sugestões de teste.

Para aguardar o resultado retornado, use a função result() .

suggest_response.result().trials

O formato a seguir mostra um exemplo de teste. Este teste sugere o uso do valor 0.1 para o parâmetro x.

name: "TRIAL_ID"
state: ACTIVE
parameters {
  parameter_id: "x"
  value {
    number_value: 0.1
  }
}
start_time {
  seconds: 1618011215
}

Use o TRIAL_ID da resposta anterior para receber o teste:

vizier_client.get_trial({
        'name': TRIAL_ID
      })

Avaliar os resultados

Depois de receber suas sugestões de teste, avalie cada teste e registre cada resultado como uma medida.

Por exemplo, se a função que está tentando otimizar for y = x^2, avalie-a usando o valor de teste x sugerido. Usando um valor sugerido de 0.1, a função é avaliada como y = 0.1 * 0.1, o que resulta em 0.01.

Adicionar uma medida

Depois de avaliar a sugestão de teste para conseguir uma medida, adicione essa medida ao teste.

Use os seguintes comandos para armazenar sua medida e enviar a solicitação. Neste exemplo, você substitui RESULT pela medida. Se a função que você está otimizando for y = x^2, e o valor sugerido de x for 0.1, o resultado será 0.01.

vizier_client.add_trial_measurement({
        'trial_name': TRIAL_ID,
        'measurement': {
            'metrics': [{'metric_id': 'y', 'value':RESULT }]
        }
    })

Observação: se a avaliação for um processo de várias etapas capaz de produzir mais de uma medida intermediária, será possível chamar o método diversas vezes usando diferentes valores stepCount e metrics. Por exemplo, se você estiver treinando um modelo de machine learning, poderá informar uma medição intermediária para cada época.

Concluir um teste

Depois de adicionar todas as medidas para um teste, é necessário concluir o teste enviando um comando.

Ao concluir o teste, você pode enviar um comando para o teste ou adicionar um comando para adicionar uma medida final e concluir o teste.

Sem medida final

Para concluir o teste sem adicionar uma medida final, envie a seguinte solicitação:

vizier_client.complete_trial({
      'name': TRIAL_ID
  })

Com a medida final

Para concluir um teste e incluir uma medida final, use os comandos a seguir, substituindo RESULT pela medida final.

vizier_client.complete_trial({
      'name': TRIAL_ID
      'final_measurement': {
        'metrics': [{'metric_id': 'y', 'value': RESULT}]
      }
  })

Listar testes

Para listar os testes em um estudo específico, envie a solicitação a seguir:

vizier_client.list_trials({
    'parent': STUDY_NAME
})

Depois de concluir todos os testes pendentes, chame suggestTrials para mais sugestões e repita o processo de avaliação de teste.

Listar o teste ótimo

Veja no exemplo a seguir list_optimal_trials, que retorna os testes ideais para um estudo de vários objetivos ou os testes ideais para um estudo de objetivo único:

vizier_client.list_optimal_trials({
    'parent': STUDY_NAME
})

A seguir

• Consulte a referência REST estudos.