Fazer solicitações de API ao AI Platform Vizier

Fazer solicitações de API ao AI Platform Vizier

Beta

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos do serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Nesta página, descrevemos como fazer solicitações de API para o AI Platform Vizier usando curl.

Antes de começar

1. Leia a visão geral do AI Platform Vizier para saber como funciona.
2. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

3. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Acessar o seletor de projetos

4. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

5. Ative a AI Platform Training and Prediction API.

   Ative a API

6. Instale a CLI do Google Cloud.

7. Para inicializar a CLI gcloud, execute o seguinte comando:

   gcloud init

8. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Acessar o seletor de projetos

9. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

10. Ative a AI Platform Training and Prediction API.

    Ative a API

11. Instale a CLI do Google Cloud.

12. Para inicializar a CLI gcloud, execute o seguinte comando:

    gcloud init

Como fazer login na sua conta do Cloud Billing

Use os seguintes comandos para fazer login na sua conta do Google Cloud:

gcloud auth application-default login
gcloud auth login

Como definir constantes

Execute os seguintes comandos, substituindo USERNAME e PROJECT_ID pelas informações de nome de usuário e ID do projeto. Crie seu próprio nome de estudo e ID do cliente ou use os valores sugeridos.

Observação :no momento, o AI Platform Vizier é compatível apenas com a região us-central1.

export USER=USERNAME
export PROJECT_ID=PROJECT_ID{"</var>"}}
export REGION=us-central1

export STUDY_NAME=${USER}_vizier_study_$(date +%Y%m%d%H%M%S)
export CLIENT_ID=${USER}_client_1
export ENDPOINT=https://$REGION-ml.googleapis.com/v1

Como criar solicitações de API

Veja a seguir como criar solicitações de API de linha de comando para o AI Platform Vizier usando curl.

Como criar um estudo

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

Para criar um estudo, crie uma configuração de estudo no formato JSON e envie uma solicitação POST que transmite a configuração para o AI Platform Vizier.

A configuração do estudo pode ser semelhante a isto. Saiba mais sobre opções de algoritmo, tipos de meta e outras opções na documentação da AI Platform Training and API Prediction.

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 facilmente calculada para ajudar a demonstrar como usar o AI Platform Vizier.

Saiba mais sobre como o AI Platform Vizier pode ser usada para problemas complexos de otimização e como otimizar várias funções de uma só vez.

cat > /tmp/create_study.json <<EOF
{
  "studyConfig": {
    "algorithm": 0,
    "metrics": [
      {
        "goal": "MAXIMIZE",
        "metric": "y"
      }
    ],
    "parameters": [
      {
        "doubleValueSpec": {
          "maxValue": 10.0,
          "minValue": -10.0
        },
        "parameter": "x",
        "type": "DOUBLE"
      }
    ]
  }
}
EOF

Para criar o estudo usando a configuração, envie a seguinte solicitação POST.

curl -X POST -H "Content-Type: application/json" \
  -d @/tmp/create_study.json \
  -H "Authorization: Bearer `gcloud auth print-access-token`" \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies?study_id=${STUDY_NAME}"

Como conseguir um estudo

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

curl -H "Content-Type: application/json"   \
  -H "Authorization: Bearer `gcloud auth print-access-token`"   \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/${STUDY_NAME}"

Como listar estudos

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

curl -H "Content-Type: application/json"  \
  -H "Authorization: Bearer `gcloud auth print-access-token`"   \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/"

Como receber sugestões de testes

Para receber uma sugestão de teste do AI Platform Vizier, crie um arquivo JSON que contenha um suggestionCount e seu ID do cliente. Depois, envie uma solicitação POST que transmite essas informações para o AI Platform Vizier.

Crie o arquivo JSON usando os seguintes comandos. Altere o suggestionCount para o número de sugestões que quer receber de cada solicitação.

cat > /tmp/suggest_trial.json <<EOF
{
  "suggestionCount": 1,
  "clientId": "${CLIENT_ID}"
}
EOF

Para receber sugestões ou sugestões, envie a seguinte solicitação POST.

curl -X POST -H "Content-Type: application/json" \
  -d @/tmp/suggest_trial.json \
  -H "Authorization: Bearer `gcloud auth print-access-token`" \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/${STUDY_NAME}/trials:suggest"

suggestTrial inicia uma operação de longa duração que gera o teste. A resposta informa que o AI Platform Vizier está trabalhando em sugestões de teste. Essa resposta estará no seguinte formato:

{
  "name": "projects/<project>/locations/<region>/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.ml.v1.SuggestTrialsMetadata",
    "study": <study-name>,
    "createTime": <create-time>,
    "suggestionCount": <suggestion-count>
  }
}

É possível usar o ID da operação na resposta anterior para pesquisar a operação de sugestão e receber sugestões de testes. Use o seguinte comando:

SUGGEST_OPERATION_ID=OPERATION_ID

curl -H "Content-Type: application/json"   \
  -H "Authorization: Bearer `gcloud auth print-access-token`"   \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/operations/${SUGGEST_OPERATION_ID}"

Se você não receber uma resposta, a solicitação suggestTrial talvez não esteja concluída. Repita o comando anterior, se necessário.

A resposta fornece sugestões de testes, neste formato:

{
  "name": "projects/<project>/locations/<region>/operations/<operation-id>",
  "metadata": {...},
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.ml.v1.SuggestTrialsResponse",
    "trials": [
      {
        "name": "projects/<project>/locations/<region>/studies/<study-id>/trials/TRIAL_ID",
        "state": "ACTIVE",
        "parameters": [
          {
            "parameter": "x",
            "floatValue": 0.1
          }
        ],
        ...
      }
    ],
    ...
  }
}

No exemplo acima, este teste sugere o uso do valor 0.1 para o parâmetro x.

Usando o ID do teste da resposta anterior, é possível conseguir um teste usando o seguinte comando:

TRIAL_ID=TRIAL_ID

curl -H "Content-Type: application/json"   \
  -H "Authorization: Bearer `gcloud auth print-access-token`"   \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/${STUDY_NAME}/trials/${TRIAL_ID}"

Como 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.

Como adicionar uma medida

Depois de avaliar a sugestão de teste para conseguir uma medida, adicione essa medida ao teste. Primeiro, crie um arquivo JSON que contenha a métrica medida e o resultado. Depois, envie uma solicitação POST que transmite essas informações para o AI Platform Vizier.

Armazene a medida e crie o arquivo JSON usando os comandos a seguir. 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.

METRIC_VALUE=RESULT

cat > /tmp/add_measurement.json <<EOF
{
  "measurement": {
    "stepCount": 1,
    "metrics": [
      {
        "metric": "y",
        "value": ${METRIC_VALUE}
      }
    ]
  }
}
EOF

Observação: se a avaliação for um processo de várias etapas e puder produzir mais de uma medida intermediária, será possível chamar o método várias vezes com diferentes valores de stepCount e metric. Por exemplo, se você estiver treinando um modelo de aprendizado de máquina, poderá relatar uma medida intermediária para cada período.

Para adicionar essa medida ao teste, envie a seguinte solicitação POST.

curl -X POST -H "Content-Type: application/json" \
  -d @/tmp/add_measurement.json \
  -H "Authorization: Bearer `gcloud auth print-access-token`" \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/${STUDY_NAME}/trials/${TRIAL_ID}:addMeasurement"

Como concluir um teste

Depois de adicionar todas as medidas para um teste, conclua-o usando o seguinte comando. Como alternativa, é possível adicionar uma medida final ao chamar completeTrial.

Sem medida final

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

curl -X POST -H "Content-Type: application/json" \
  -d "" \
  -H "Authorization: Bearer `gcloud auth print-access-token`" \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/${STUDY_NAME}/trials/${TRIAL_ID}:complete"

Com medida final

Para incluir uma medida final ao concluir o teste, primeiro armazene a medida final e crie um arquivo JSON usando os seguintes comandos, substituindo RESULT pela medida final.

FINAL_METRIC_VALUE=RESULT

cat > /tmp/complete_trial.json <<EOF
{
  "finalMeasurement": {
    "stepCount": 1,
    "metrics": [
      {
        "metric": "y",
        "value": ${FINAL_METRIC_VALUE}
      }
    ]
  }
}
EOF

Envie a seguinte solicitação POST.

curl -X POST -H "Content-Type: application/json" \
  -d @/tmp/complete_trial.json \
  -H "Authorization: Bearer `gcloud auth print-access-token`" \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/${STUDY_NAME}/trials/${TRIAL_ID}:complete"

Como listar testes

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

curl -H "Content-Type: application/json"   \
  -H "Authorization: Bearer `gcloud auth print-access-token`"   \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/${STUDY_NAME}/trials/"

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

A seguir

Para exemplos de como usar a API, consulte:

• Primeiros passos: como otimizar um modelo de aprendizado de máquina.
• Primeiros passos: como otimizar vários objetivos.