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

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

ベータ版

このプロダクトまたは機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 一般提供前のプロダクトと機能は「現状のまま」ご利用いただけますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

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

始める前に

1. AI Platform Vizier の仕組みについては、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. Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

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

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

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

   API を有効にする

6. Google Cloud CLI をインストールします。

7. gcloud CLI を初期化するには:

   gcloud init

8. Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

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

9. Google Cloud プロジェクトで課金が有効になっていることを確認します。

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

    API を有効にする

11. Google Cloud CLI をインストールします。

12. gcloud CLI を初期化するには:

    gcloud init

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

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

gcloud auth application-default login
gcloud auth login

定数の定義

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

注: 現在のところ、AI Platform Vizier では 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

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

注: 評価が複数ステップからなるプロセスで、複数の中間測定値を生成できる場合、異なる stepCount と metric 値で、メソッドを複数回呼び出せます。たとえば、機械学習モデルをトレーニングしている場合、エポックごとに中間測定値をレポートできます。

この測定値をトライアルに追加するには、次の 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 の使用例については、以下をご覧ください。

• スタートガイド: 機械学習モデルの最適化
• スタートガイド: 複数の目標の最適化