Invia richieste API ad AI Platform Vizier

Questa pagina descrive come effettuare richieste API ad AI Platform Vizier utilizzando curl.

Prima di iniziare

  1. Leggi la panoramica di AI Platform Vizier per scoprire come funziona.
  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. Make sure that billing is enabled for your Google Cloud project.

  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. Make sure that billing is enabled for your Google Cloud project.

  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

Accedere all'account di fatturazione Cloud

Utilizza i seguenti comandi per accedere al tuo account Google Cloud:

gcloud auth application-default login
gcloud auth login

Definizione delle costanti

Esegui i comandi seguenti, sostituendo USERNAME e PROJECT_ID con il tuo nome utente e le informazioni sull'ID progetto. Crea il nome dello studio e ID client oppure utilizza i valori suggeriti.

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

Costruzione delle richieste API

Di seguito viene descritto come creare richieste API a riga di comando per AI Platform Vizier utilizzando curl.

Creazione di uno studio

Uno studio è una serie di esperimenti o prove che ti aiutano a ottimizzare i tuoi iperparametri o parametri.

Per creare uno studio, devi creare una configurazione di studio in formato JSON, quindi invia una richiesta POST che trasmette la tua configurazione ad AI Platform Vizier.

La configurazione di studio potrebbe essere simile alla seguente. Scopri di più su opzioni dell'algoritmo, tipi di obiettivi e e altre opzioni nell'API AI Platform Training and Prediction documentazione.

Nell'esempio seguente, l'obiettivo è massimizzare la metrica y = x^2 con x nell'intervallo [-10. 10]. Questo esempio ha un solo parametro e utilizza una funzione facilmente calcolabile per dimostrare come utilizzare AI Platform Vizier.

Scopri di più su come AI Platform Vizier può essere utilizzata per problemi di ottimizzazione complessi e come ottimizzare più funzioni contemporaneamente.

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

Per creare lo studio utilizzando la tua configurazione di studio, invia la seguente richiesta di 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}"

Partecipare a uno studio

Per ottenere uno studio, invia la richiesta seguente.

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

Elenco di studi

Per elencare gli studi in un progetto e in una regione specifici, invia la richiesta seguente.

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

Ricevere prove suggerite

Per ricevere un suggerimento per la prova da AI Platform Vizier, devi creare un file JSON contenente un suggestionCount e il tuo ID client. Poi invii una richiesta POST che trasmette queste informazioni a AI Platform Vizier.

Crea il file JSON utilizzando i seguenti comandi. Modifica suggestionCount in base al numero di suggerimenti che vuoi ricevere da ogni richiesta.

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

Per ricevere il suggerimento o i suggerimenti, invia la seguente richiesta 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 avvia un'operazione a lunga esecuzione che lavora per generare la prova. La risposta ti informa che AI Platform Vizier è al lavoro sui suggerimenti per le prove. Questa risposta avrà il seguente 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>
  }
}

Puoi utilizzare l'ID operazione nella risposta precedente per eseguire un polling sul suggerimento operativa e ricevere i suggerimenti per la prova. Utilizza questo 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 non ricevi una risposta, suggestTrial potrebbe non essere completata. Se necessario, ripeti il comando precedente.

La risposta fornisce suggerimenti per le prove, in questo 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
          }
        ],
        ...
      }
    ],
    ...
  }
}

Nell'esempio precedente, questo esperimento suggerisce di utilizzare il valore 0.1 per il parametro x.

Utilizzando l'ID prova della risposta precedente, puoi ottenere la prova utilizzando il seguente 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}"

Valutazione dei risultati

Dopo aver ricevuto i suggerimenti per le prove, valuta ogni prova e registra ogni risultato come misurazione.

Ad esempio, se la funzione che stai cercando di ottimizzare è y = x^2, la valuti utilizzando il valore suggerito dalla prova di x. Utilizzando un valore suggerito di 0.1, la funzione restituisce y = 0.1 * 0.1, che corrisponde a 0.01.

Aggiunta di una misurazione

Dopo aver valutato il suggerimento di prova per ottenere una misurazione, aggiungi questa misurazione alla prova. Innanzitutto, crea un file JSON contenente la metrica misurata e il risultato. Dopodiché, invierai una richiesta POST per trasmettere queste informazioni in AI Platform Vizier.

Archivia le tue misurazioni e crea il file JSON utilizzando quanto segue. tramite comandi SQL. In questo esempio, sostituisci RESULT con la misurazione. Se la funzione che stai ottimizzando è y = x^2 e il valore suggerito di x è 0.1, il risultato è 0.01.

METRIC_VALUE=RESULT

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

Per aggiungere questa misurazione alla prova, invia la seguente richiesta di 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"

Completare una prova

Dopo aver aggiunto tutte le misurazioni di una prova, completa la prova utilizzando il seguente comando. Se vuoi, puoi aggiungere una misurazione finale quando chiami completeTrial

Senza misurazione finale

Per completare la prova senza aggiungere una misurazione finale, invia la seguente richiesta 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"

Con la misurazione finale

Per includere una misurazione finale al termine della prova, devi prima archiviare la misurazione finale e crea un file JSON utilizzando i seguenti comandi, sostituendo RESULT con la misurazione finale.

FINAL_METRIC_VALUE=RESULT

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

Invia la seguente richiesta di 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"

Elenco delle prove

Per elencare i trial in uno studio specifico, invia la seguente richiesta.

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

Dopo aver completato tutte le prove in sospeso, puoi chiamare suggestTrial per altri suggerimenti e ripetere il processo di valutazione della prova.

Passaggi successivi

Per esempi di come utilizzare l'API, consulta quanto segue: