Fazer solicitações de API ao AI Platform Vizier

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. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  3. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

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

  5. Enable the AI Platform Training and Prediction API.

    Enable the API

  6. Install the Google Cloud CLI.
  7. To initialize the gcloud CLI, run the following command:

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

    Go to project selector

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

  10. Enable the AI Platform Training and Prediction API.

    Enable the API

  11. Install the Google Cloud CLI.
  12. To initialize the gcloud CLI, run the following command:

    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.

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

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 a 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: