Envoyer des requêtes API à AI Platform Vizier

Envoyer des requêtes API à AI Platform Vizier

Bêta

Ce produit ou cette fonctionnalité est soumis aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent bénéficier d'une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Cette page explique comment envoyer des requêtes API à AI Platform Vizier à l'aide de curl.

Avant de commencer

1. Consultez la présentation d'AI Platform Vizier pour en savoir plus sur le fonctionnement d'AI Platform Vizier.
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

Se connecter au compte de facturation Cloud

Exécutez les commandes suivantes pour vous connecter à votre compte Google Cloud :

gcloud auth application-default login
gcloud auth login

Définir des constantes

Exécutez les commandes suivantes en remplaçant USERNAME et PROJECT_ID par votre nom d'utilisateur et votre ID de projet. Saisissez le nom de votre étude et votre ID client, ou utilisez les valeurs suggérées.

Remarque : À l'heure actuelle, AI Platform Vizier est uniquement compatible avec la région 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

Créer des requêtes API

La section suivante décrit comment créer des requêtes API en ligne de commande destinées à AI Platform Vizier, à l'aide de curl.

Créer une étude

Une étude est une série de tests, ou d'essais, visant à optimiser vos hyperparamètres ou paramètres.

Pour créer une étude, créez une configuration d'étude au format JSON, puis envoyez une requête POST qui transmet votre configuration à AI Platform Vizier.

La configuration de l'étude peut se présenter comme suit. Pour en savoir plus sur les options d'algorithme, les types d'objectifs et d'autres options, consultez la documentation des API AI Platform Training et AI Platform Prediction.

Dans l'exemple suivant, l'objectif est d'optimiser y = x^2 avec x dans la plage [-10. 10]. Cet exemple ne comporte qu'un seul paramètre et exécute une fonction simple à calculer pour vous montrer comment utiliser AI Platform Vizier.

Découvrez comment utiliser AI Platform Vizier pour les problèmes d'optimisation complexes et comment optimiser plusieurs fonctions à la fois.

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

Pour créer l'étude à l'aide de votre configuration d'étude, envoyez la requête POST suivante.

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

Obtenir une étude

Pour obtenir une étude, envoyez la requête suivante.

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

Répertorier les études

Pour répertorier les études d'un projet et d'une région spécifiques, envoyez la requête suivante.

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

Obtenir des suggestions d'essais

Pour obtenir une suggestion d'essai d'AI Platform Vizier, créez un fichier JSON contenant un ID de projet (suggestionCount) et votre ID client. Envoyez ensuite une requête POST qui transmet ces informations à AI Platform Vizier.

Créez le fichier JSON à l'aide des commandes suivantes. Remplacez suggestionCount par le nombre de suggestions que vous souhaitez obtenir pour chaque requête.

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

Pour recevoir une ou plusieurs suggestions, envoyez la requête POST suivante.

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"

La requête suggestTrial lance une opération de longue durée qui consiste à générer l'essai. La réponse vous indique qu'AI Platform Vizier est en train de générer des suggestions d'essais. Cette réponse doit être au format suivant :

{
  "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>
  }
}

Vous pouvez utiliser l'ID d'opération de la réponse précédente pour interroger l'opération de suggestion et obtenir des suggestions d'essais. Exécutez la commande suivante :

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

Si vous n'obtenez pas de réponse, c'est peut-être parce que la requête suggestTrial n'a pas encore abouti. Si nécessaire, répétez la commande précédente.

La réponse fournit des suggestions d'essais au format suivant :

{
  "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
          }
        ],
        ...
      }
    ],
    ...
  }
}

Dans l'exemple ci-dessus, cet essai suggère d'utiliser la valeur 0.1 pour le paramètre x.

À l'aide de l'ID d'essai de la réponse précédente, vous pouvez obtenir l'essai en exécutant la commande suivante :

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

Évaluer les résultats

Après avoir reçu les suggestions d'essais, vous évaluez chaque essai et enregistrez chaque résultat en tant que mesure.

Par exemple, si la fonction que vous essayez d'optimiser est y = x^2, vous l'évaluez à l'aide de la valeur suggérée de x de l'essai. En utilisant une valeur suggérée de 0.1, la fonction renvoie y = 0.1 * 0.1 et génère la valeur 0.01.

Ajouter une mesure

Après avoir évalué la suggestion d'essai pour obtenir une mesure, vous devez ajouter celle-ci à votre essai. Commencez par créer un fichier JSON contenant la métrique que vous avez mesurée et le résultat obtenu. Envoyez ensuite une requête POST qui transmet ces informations à AI Platform Vizier.

Enregistrez la mesure et créez le fichier JSON à l'aide des commandes suivantes. Dans cet exemple, vous remplacez RESULT par la mesure. Si la fonction que vous optimisez est y = x^2 et que la valeur suggérée de x est 0.1, le résultat est 0.01.

METRIC_VALUE=RESULT

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

Remarque : Si l'évaluation est un processus en plusieurs étapes et peut générer plusieurs mesures intermédiaires, vous pouvez appeler la méthode plusieurs fois en fournissant des valeurs stepCount et metric différentes. Par exemple, si vous l'entraînement d'un modèle de machine learning, vous pouvez signaler un problème pour chaque élément epoch.

Pour ajouter cette mesure à votre essai, envoyez la requête POST suivante.

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"

Effectuer un essai

Après avoir ajouté toutes les mesures à un essai, effectuez cet essai en exécutant la commande suivante. Vous pouvez éventuellement ajouter une mesure finale lorsque vous appelez completeTrial.

Sans mesure finale

Pour effectuer l'essai sans ajouter de mesure finale, envoyez la requête POST suivante.

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"

Avec une mesure finale

Pour inclure une mesure finale à la fin de l'essai, enregistrez d'abord votre mesure finale et créez un fichier JSON à l'aide des commandes suivantes, en remplaçant RESULT par la mesure finale.

FINAL_METRIC_VALUE=RESULT

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

Envoyez la requête POST suivante.

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"

Répertorier les essais

Pour répertorier les essais d'une étude spécifique, envoyez la requête suivante.

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

Une fois tous les essais en attente terminés, vous pouvez appeler la requête suggestTrial pour obtenir d'autres suggestions et répéter le processus d'évaluation de l'essai.

Étapes suivantes

Consultez les pages suivantes pour obtenir des exemples d'utilisation de l'API :

• Premiers pas : optimiser un modèle de machine learning
• Premiers pas : optimiser plusieurs objectifs