AI Platform Vizier に対して API リクエストを実行する
このページでは、curl を使用して AI Platform Vizier に対して API リクエストを実行する方法について説明します。
始める前に
- AI Platform Vizier の仕組みについては、AI Platform Vizier の概要をご覧ください。
- Google Cloud アカウントにログインします。Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。
-
Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。
-
AI Platform Training and Prediction API を有効にします。
- Google Cloud CLI をインストールします。
-
gcloud CLI を初期化するには:
gcloud init
-
Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。
-
AI Platform Training and Prediction API を有効にします。
- Google Cloud CLI をインストールします。
-
gcloud CLI を初期化するには:
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 の使用例については、以下をご覧ください。