AI Platform Vizier の使用

このページでは、curl を使用して AI Platform Vizier に API リクエストを行う方法について説明します。

始める前に

  1. AI Platform Vizier の仕組みについては、AI Platform Vizier の概要をご覧ください。
  2. Google Cloud アカウントにログインします。Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。
  3. Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

    プロジェクト セレクタに移動

  4. Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトに対して課金が有効になっていることを確認する方法を学習する

  5. AI Platform Training and Prediction API を有効にします。

    API を有効にする

  6. Cloud SDK をインストールして初期化します。
  7. Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

    プロジェクト セレクタに移動

  8. Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトに対して課金が有効になっていることを確認する方法を学習する

  9. AI Platform Training and Prediction API を有効にします。

    API を有効にする

  10. Cloud SDK をインストールして初期化します。

Cloud 請求先アカウントへのログイン

次のコマンドを使用して、Google Cloud アカウントにログインします。

gcloud auth application-default login
gcloud auth login

定数の定義

次のコマンドを実行します。USERNAMEPROJECT_ID は、ユーザー名とプロジェクト ID の情報に置き換えます。独自のスタディ名とクライアント ID を作成するか、推奨値を使用します。

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

API リクエストの作成

ここでは curl を使用して、AI Platform Vizier にコマンドライン API リクエストを発行する方法を説明します。

スタディの作成

スタディは、ハイパーパラメータまたはパラメータを最適化するための一連のテストまたはトライアルです。

スタディを作成するには、JSON 形式でスタディ構成を作成し、構成を AI Platform Vizier に渡す POST リクエストを送信します。

スタディ構成は次のようになります。アルゴリズム オプション目標タイプ、その他のオプションの詳細については、AI Platform Training と Prediction API のドキュメントをご覧ください。

次の例では、x が [-10. 10] の範囲内で y = x^2 を最大化することが目標です。この例では、パラメータが 1 つのみで、簡単な計算関数を使用した AI Platform Vizier の使用方法が示されています。必要に応じて、AI Platform Vizier を使用してより複雑な最適化の問題に対処する方法を学習するか、2 つの関数を同時に最適化してみてください

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

スタディ構成を使用して学習を作成するには、次の 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}"

スタディの取得

スタディを取得するには、次のリクエストを送信します。

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

スタディの一覧表示

特定のプロジェクトとリージョンのスタディを一覧表示するには、次のリクエストを送信します。

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

提案されたトライアルの取得

AI Platform Vizier からトライアルの提案を取得するには、suggestionCount とクライアント ID を含む JSON ファイルを作成します。次に、この情報を AI Platform Vizier に渡す POST リクエストを送信します。

次のコマンドを使用して JSON ファイルを作成します。suggestionCount を、各リクエストから取得する必要がある提案数に変更します。

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

提案を取得するには、次の 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 は、トライアルの生成で動作する長時間実行オペレーションを開始します。レスポンスから、AI Platform Vizier がトライアルの提案に取り掛かっていることがわかります。このレスポンスは次の形式になります。

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

前のレスポンスのオペレーション ID を使用して、提案オペレーションをポーリングし、トライアルの提案を取得できます。次のコマンドを使用します。

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

応答がない場合、suggestTrial リクエストが完了していない可能性があります。必要に応じて、上記のコマンドを繰り返します。

レスポンスには、トライアルの提案が次の形式で表示されます。

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

上記の例のトライアルは、パラメータ x に値 0.1 を使用することを提案しています。

次のコマンドで前のレスポンスのトライアル ID を使用して、トライアルを取得できます。

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

結果の評価

トライアルの提案を受け取ったら、各トライアルを評価し、各結果を測定値として記録します。

たとえば、最適化しようとしている関数が y = x^2 の場合は、トライアルの推奨値 x を使用して関数を評価します。推奨値の 0.1 が使用され、関数の評価は y = 0.1 * 0.1 となり、結果は 0.01 になります。

測定値の追加

トライアルの提案を評価して測定値を取得したら、この測定値をトライアルに追加します。まず、測定した指標と結果を含む JSON ファイルを作成します。次に、この情報を AI Platform Vizier に渡す POST リクエストを送信します。

次のコマンドを使用して、測定値を保存し、JSON ファイルを作成します。この例では、RESULT を測定値に置き換えます。最適化する関数が y = x^2 で、x の推奨値が 0.1 の場合、結果は 0.01 になります。

METRIC_VALUE=RESULT

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

この測定値をトライアルに追加するには、次の 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"

トライアルの完了

トライアルの測定値をすべて追加したら、次のコマンドを使用してトライアルを完了します。必要に応じて、completeTrial の呼び出し時に最終的な測定値を追加できます。

最終的な測定なし

最終的な測定値を追加せずにトライアルを完了するには、次の 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"

最終的な測定あり

トライアルの完了時に最終的な測定値を含めるには、まず最終測定を保存し、次のコマンドを使用して JSON ファイルを作成します。RESULT は、最終的な測定値に置き換えます。

FINAL_METRIC_VALUE=RESULT

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

次の 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"

トライアルの一覧表示

特定のスタディのトライアルを一覧表示するには、次のリクエストを送信します。

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

保留中のトライアルをすべて完了したら、suggestTrial を呼び出してトライアルの提案をさらに取得し、評価プロセスを繰り返すことができるようになります。

次のステップ

API の使用例については、以下をご覧ください。