このプロダクトは、次世代の AI Platform である Vertex AI でご利用いただけます。リソースを Vertex AI Vizier に移行することで、AI Platform では利用できない新しい機械学習機能を取得できます。

AI Platform Vizier に対して API リクエストを実行する

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

始める前に

AI Platform Vizier の仕組みについては、AI Platform Vizier の概要をご覧ください。

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.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the AI Platform Training and Prediction API.

Enable the 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.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the AI Platform Training and Prediction API.

Enable the API

Install the Google Cloud CLI.

To initialize the gcloud CLI, run the following command:

gcloud init

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

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

gcloud auth application-default login
gcloud auth login

定数の定義

次のコマンドを実行します。USERNAME と PROJECT_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 を使用して複雑な最適化問題に対処する方法と、複数の関数を一度に最適化する方法をご確認ください。

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 の使用例については、以下をご覧ください。