向 AI Platform Vizier 发出 API 请求

本页面介绍如何使用 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. 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

登录您的 Cloud Billing 账号

使用以下命令登录您的 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 格式创建一个研究配置，然后发送一个 POST 请求将您的配置传递给 AI Platform Vizier。

研究配置可能如下所示。详细了解算法选项、目标类型和 AI Platform Training and Prediction API 文档中的其他选项。

以下示例的目标是计算 y = x^2 的最大值，其中 x 的范围为 [-10. 10]。此示例只有一个参数，并使用易于计算的函数来帮助演示如何使用 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 文件。然后发送一个 POST 请求，用于将此信息传递给 AI Platform Vizier。

使用以下命令创建 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 文件，其中包含您计算的指标和结果。 然后发送一个 POST 请求，用于将此信息传递给 AI Platform Vizier。

使用以下命令存储计算结果并创建 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 的示例，请参阅以下内容：