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
- Leia a visão geral do AI Platform Vizier para saber como funciona.
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the AI Platform Training and Prediction API.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init -
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the AI Platform Training and Prediction API.
- Install the Google Cloud CLI.
-
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: