Inviare richieste API ad AI Platform Vizier

Inviare richieste API ad AI Platform Vizier

Beta

Questo prodotto o funzionalità è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici del servizio. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

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. Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

3. Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

   Vai al selettore progetti

4. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

5. Attiva AI Platform Training and Prediction API.

   Abilita l'API

6. Installa Google Cloud CLI.

7. Per initialize gcloud CLI, esegui questo comando:

   gcloud init

8. Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

   Vai al selettore progetti

9. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

10. Attiva AI Platform Training and Prediction API.

    Abilita l'API

11. Installa Google Cloud CLI.

12. Per initialize gcloud CLI, esegui questo comando:

    gcloud init

Accesso 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 le informazioni relative al tuo nome utente e all'ID progetto. Crea il nome dello studio e il tuo ID client oppure utilizza i valori suggeriti.

Nota: al momento AI Platform Vizier supporta solo la regione 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

Creazione delle richieste API

Di seguito viene descritto come costruire 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 consentono di ottimizzare gli iperparametri o i parametri.

Per creare uno studio, devi creare una configurazione di studio in formato JSON e poi inviare una richiesta POST che passa la configurazione ad AI Platform Vizier.

La configurazione di studio potrebbe essere la seguente. Scopri di più su opzioni degli algoritmi, tipi di obiettivi e altre opzioni nella documentazione relativa all'API Prediction AI Platform Training and Prediction.

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

Scopri di più su come utilizzare AI Platform Vizier per problemi di ottimizzazione complessi e su 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 configurazione dello studio, invia la seguente richiesta 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}"

Trovare uno studio

Per ricevere 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}"

Studi delle schede

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/"

Come ottenere le prove suggerite

Per ricevere un suggerimento per la prova da AI Platform Vizier, crea un file JSON che contenga un suggestionCount e il tuo ID client. Dopodiché invii una richiesta POST che passa queste informazioni ad AI Platform Vizier.

Crea il file JSON utilizzando i seguenti comandi. Modifica suggestionCount nel 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 genera la prova. La risposta indica che AI Platform Vizier sta lavorando sui suggerimenti delle 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 il polling dell'operazione sul suggerimento e ricevere suggerimenti sulla prova. Utilizza il seguente 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, la richiesta di suggestTrial potrebbe non essere completata. Se necessario, ripeti il comando precedente.

La risposta fornisce suggerimenti per la prova, 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, questa prova 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 relativi alle prove, valuti ogni prova e registri ogni risultato come misurazione.

Ad esempio, se la funzione che stai tentando di ottimizzare è y = x^2, la valuti utilizzando il valore x suggerito per la prova. Utilizzando il valore suggerito 0.1, la funzione restituisce y = 0.1 * 0.1, che genera 0.01.

Aggiungere una misurazione

Dopo aver valutato il suggerimento per la prova per ottenere una misurazione, aggiungi questa misurazione alla prova. Per prima cosa, crea un file JSON contenente la metrica che hai misurato e il risultato. Dopodiché invii una richiesta POST che passa queste informazioni ad AI Platform Vizier.

Archivia la misurazione e crea il file JSON utilizzando i seguenti comandi. 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

Nota: se la valutazione è un processo a più passaggi e può produrre più di una misurazione intermedia, puoi chiamare il metodo più volte con valori stepCount e metric diversi. Ad esempio, se stai addestrando un modello di machine learning, puoi segnalare una misurazione intermedia per ogni epoca.

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

Completamento di una prova

Dopo aver aggiunto tutte le misurazioni per una prova, completa la prova utilizzando il comando seguente. 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 misurazione finale

Per includere una misurazione finale quando completi la prova, archivia prima 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 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"

Prove della scheda

Per elencare le prove in uno studio specifico, 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}/trials/"

Una volta completate tutte le prove in attesa, puoi chiamare suggestTrial per altri suggerimenti e ripetere il processo di valutazione della prova.

Passaggi successivi

Per esempi su come utilizzare l'API, vedi:

• Guida introduttiva: ottimizzazione di un modello di machine learning.
• Per iniziare: ottimizzare più obiettivi.