使用 AutoML Vision API 为图片添加标签

本快速入门将引导您完成以下过程：

  • 将列有带标签的图片和边界框的 CSV 文件复制到 Google Cloud Storage 中。
  • 使用 AutoML Vision Object Detection 来创建数据集，并训练和部署模型。

在本快速入门中，您将使用 cURL 命令来向 AutoML Vision API 发送请求。您也可以参考《快速入门：使用界面》，在界面中完成本文列出的所有步骤。 如需查看有关如何使用界面或 API 的更多说明，请参阅方法指南。

准备工作

设置项目

  1. 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手，请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。
  2. 安装 Google Cloud CLI。

  3. 如需初始化 gcloud CLI，请运行以下命令： 

    gcloud init

  4. 创建或选择 Google Cloud 项目。

    • 创建 Google Cloud 项目：

      gcloud projects create PROJECT_ID

      将 PROJECT_ID 替换为您要创建的 Google Cloud 项目的名称。

    • 选择您创建的 Google Cloud 项目：

      gcloud config set project PROJECT_ID

      将 PROJECT_ID 替换为您的 Google Cloud 项目 名称。

  5. 确保您的 Google Cloud 项目已启用结算功能。

  6. Enable the AutoML and Cloud Storage APIs: 

    gcloud services enable storage-component.googleapis.com automl.googleapis.com storage-api.googleapis.com
    7.
  7. 安装 Google Cloud CLI。

  8. 如需初始化 gcloud CLI，请运行以下命令： 

    gcloud init

  9. 创建或选择 Google Cloud 项目。

    • 创建 Google Cloud 项目：

      gcloud projects create PROJECT_ID

      将 PROJECT_ID 替换为您要创建的 Google Cloud 项目的名称。

    • 选择您创建的 Google Cloud 项目：

      gcloud config set project PROJECT_ID

      将 PROJECT_ID 替换为您的 Google Cloud 项目 名称。

  10. 确保您的 Google Cloud 项目已启用结算功能。

  11. Enable the AutoML and Cloud Storage APIs: 

    gcloud services enable storage-component.googleapis.com automl.googleapis.com storage-api.googleapis.com
    12.
  12. 将 PROJECT_ID 环境变量设置为项目 ID。 
    export PROJECT_ID=PROJECT_ID
    AutoML API 调用和资源名称中包含您的项目 ID。PROJECT_ID 环境变量提供了一种指定此 ID 的便捷方式。

准备数据集

在本快速入门中，您将使用通过 Open Images Dataset V4 创建的数据集。 此公开可用的沙拉数据集位于 gs://cloud-ml-data/img/openimage/csv/salads_ml_use.csv。

CSV 格式如下：

TRAINING,gs://cloud-ml-data/img/openimage/3/2520/3916261642_0a504acd60_o.jpg,Salad,0.0,0.0954,,,0.977,0.957,,
VALIDATION,gs://cloud-ml-data/img/openimage/3/2520/3916261642_0a504acd60_o.jpg,Seafood,0.0154,0.1538,,,1.0,0.802,,
TEST,gs://cloud-ml-data/img/openimage/3/2520/3916261642_0a504acd60_o.jpg,Tomato,0.0,0.655,,,0.231,0.839,,
数据集图片示例
3916261642_0a504acd60_o.jpg

每行对应一个位于较大图片内的对象，每个对象专门指定为测试数据、训练数据或验证数据。此处包含的三行表示位于同一张图片 (gs://cloud-ml-data/img/openimage/3/2520/3916261642_0a504acd60_o.jpg) 内的三个不同对象。除了具有 Baked goods 或 Cheese 标签的其他行以外，这三行中的每一行具有不同的标签：Salad、Seafood、Tomato。

我们使用左上顶点和右下顶点为每张图片指定边界框：

  • (0,0) 对应于左上角最远处的顶点。
  • (1,1) 对应于右下角最远处的顶点。

对于上面显示的第一行，具有 Salad 标签的对象的左上顶点的 (x, y) 坐标为 (0.0,0.0954)，其右下顶点的坐标为 (0.977,0.957)。

如需详细了解如何设置 CSV 文件格式以及创建有效数据集的最低要求，请参阅准备训练数据。


创建数据集并导入训练数据

curl 命令使用 gcloud auth print-access-token 命令来获取您的 Google 账号的访问令牌。

对于 Beta 版，无论实际位置如何，都请使用 us-central1 作为地区。

创建数据集

通过以下 curl 命令，使用您选择的显示名创建一个新数据集：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
"https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/datasets" -d '{
    "display_name": "DISPLAY_NAME",
    "image_object_detection_dataset_metadata": {
    }
}'

该响应会返回一个相关数据集 ID（例如 IOD5491013845671477445），您在后续步骤中需要用到该 ID。

{
  "name": "projects/PROJECT_ID/locations/us-central1/datasets/IOD5491013845671477445",
  "displayName": "DISPLAY_NAME",
  "createTime": "2018-10-29T15:45:53.353442Z",
  "imageObjectDetectionDatasetMetadata": {}
}

导入数据

将训练数据导入数据集。importData 命令接受数据集的 URI 作为输入。在这里，您将提供存储 Salads 数据集的公开 Google Cloud Storage 地址。此过程最多可能需要 30 分钟。

  • 将 DATASET_ID 替换为数据集的标识符（而不是显示名）。例如：IOD5491013845671477445。
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/datasets/DATASET_ID:importData \
-d '{
  "input_config": {
    "gcs_source": {
       "input_uris": [
         "gs://cloud-ml-data/img/openimage/csv/salads_ml_use.csv"
        ]
    }
  }
}'

该响应会返回一个相关操作 ID（例如 IOD1555149246326374411），该 ID 可用于获取操作状态。

{
  "name": "projects/PROJECT_NUMBER/locations/us-central1/operations/IOD1555149246326374411",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.automl.v1beta1.OperationMetadata",
    "createTime": "2018-10-29T15:56:29.176485Z",
    "updateTime": "2018-10-29T15:56:29.176485Z",
    "importDataDetails": {}
  }
}

获取导入操作的状态

您可以使用以下 curl 命令查询导入数据操作的状态。

  • 将 OPERATION_ID 替换为从导入数据操作返回的操作 ID。
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID

导入操作可能需要一些时间才能完成。导入任务完成后，您将在操作状态中看到 done: true，且无错误列出，如下例所示。

此请求还会返回针对您的数据集导入的所有警告。我们已向此数据集添加了错误，以向您展示这些警告的示例。利用此操作查看这些警告，有助于您查找数据中的错误。

{
  "name": "projects/PROJECT_NUMBER/locations/us-central1/operations/IOD1555149246326374411",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.automl.v1beta1.OperationMetadata",
    "createTime": "2018-10-29T15:56:29.176485Z",
    "updateTime": "2018-10-29T16:10:41.326614Z",
    "importDataDetails": {}
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

获取数据集列表

您可以使用以下命令获取数据集列表。

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/datasets

您将看到如下所示的输出：

{
  "datasets": [
    {
      "name": "projects/PROJECT_NUMBER/locations/us-central1/datasets/DATASET_ID1",
      "displayName": "DISPLAY_NAME1",
      "createTime": "2018-10-29T15:45:53.353442Z",
      "exampleCount": 227,
      "imageObjectDetectionDatasetMetadata": {}
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/us-central1/datasets/DATASET_ID2",
      "displayName": "DISPLAY_NAME2",
      "createTime": "2018-10-24T21:06:05.390059Z",
      "exampleCount": 227,
      "imageObjectDetectionDatasetMetadata": {}
    }
  ]
}

训练模型

启动模型训练应用

创建数据集并将训练数据导入数据集后，您就可训练自定义模型了。

使用以下 curl 命令来训练您的模型。

  • 将 DATASET_ID 替换为数据集的标识符（而不是显示名）。
  • 将 DISPLAY_NAME 替换为您为模型选择的名称。
  • 指定 image_object_detection_model_metadata.model_type。您可以使用以下两种选项分别针对延迟时间和准确率进行优化：
    • cloud-low-latency-1 - 针对延迟时间优化训练。
    • cloud-high-accuracy-1 - 针对准确率优化训练。
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models -d '{
  "datasetId": "DATASET_ID",
  "displayName": "DISPLAY_NAME",
  "image_object_detection_model_metadata": {},
}'

您应该会收到训练模型操作的 ID（例如 IOD5644417707978784777），此 ID 可用于获取训练操作的状态。

{
  "name": "projects/PROJECT_NUMBER/locations/us-central1/operations/IOD5644417707978784777",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.automl.v1beta1.OperationMetadata",
    "createTime": "2018-10-29T16:41:23.902167Z",
    "updateTime": "2018-10-29T16:41:23.902167Z",
    "createModelDetails": {}
  }
}

训练过程可能需要数小时才能完成。

获取模型训练操作的状态

您可以使用如下 curl 命令查询模型训练操作的状态。

  • 将 OPERATION_ID 替换为训练操作的 ID。
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID

您应该会看到类似如下所示的输出。操作完成后，您会看到 done: true，并且无错误列出。


{
  "name": "projects/PROJECT_NUMBER/locations/us-central1/operations/IOD5644417707978784777",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.automl.v1beta1.OperationMetadata",
    "createTime": "2018-10-24T22:08:23.327323Z",
    "updateTime": "2018-10-24T23:41:18.452855Z",
    "createModelDetails": {}
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.automl.v1beta1.Model",
    "name": "projects/PROJECT_NUMBER/locations/us-central1/models/IOD5644417707978784777"
  }
}

验证模型可用性

模型训练操作成功完成后，您可以使用以下命令列出项目的模型，从而验证模型是否可用。

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models

您应该会收到一个模型 ID（例如 IOD5644417707978784778）；在模型训练完成时，您可以使用此 ID 来获取模型评估指标。 您应该会看到类似如下所示的输出：

{
  "model": [
    {
      "name": "projects/PROJECT_NUMBER/locations/us-central1/models/IOD5644417707978784778",
      "displayName": "DISPLAY_NAME",
      "datasetId": "IOD5491013845671477445",
      "createTime": "2018-10-24T23:37:00.858493Z",
      "updateTime": "2018-10-24T23:37:00.858493Z",
      "deploymentState": "DEPLOYED",
      "imageObjectDetectionModelMetadata": {
          "modelType": "cloud-low-latency-1",
          "nodeCount": "1",
          "nodeQps": 1.2987012987012987
      }
    }
  ]
}

评估模型

模型训练完毕后，您可以使用以下 curl 命令列出模型评估指标。

  • 将 MODEL_ID 替换为模型的标识符。
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models/MODEL_ID/modelEvaluations

AutoML Vision Object Detection 提供了一组总体评估指标以及针对每个标签的评估指标；前者指示模型的整体表现，后者指示模型在不同阈值条件下针对该标签的表现。

部署模型

您必须手动部署模型，然后才能执行预测。

请使用以下命令部署您的模型：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "x-goog-user-project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models/MODEL_ID:deploy \
  -d '{
      "imageObjectDetectionModelDeploymentMetadata": {
        "nodeCount": 2
      }
    }'

进行预测

发送预测请求

您可以利用如下 JSON 文件和 curl 命令，使用已部署的模型对一张本地图片执行预测。

  • 创建名为 predict_request.json 的请求 JSON 文件，并在 "imageBytes" 字段中提供 base64 编码的图片。

predict_request.json 

{
    "payload": {
        "image": {
            "image_bytes": "/9j/4QAYRXhpZgAA...base64-encoded-image...9tAVx/zDQDlGxn//2Q=="
        }
    }
}

  • 将 MODEL_ID 替换为模型的标识符。
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
"https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models/MODEL_ID:predict" -d @PATH_TO_JSON_FILE/predict_request.json

如果请求成功，返回的响应中将包含一个或多个边界框，边界框由两个呈对角关系的 normalizedVertices 指定。 所标识的每个边界框都具有关联的置信度 score 和注释 (displayName)。

{
  "payload": [
    {
      "imageObjectDetection": {
        "boundingBox": {
          "normalizedVertices": [
            {
              "x": 0.034553755,
              "y": 0.015524037
            },
            {
              "x": 0.941527,
              "y": 0.9912563
            }
          ]
        },
        "score": 0.9997793
      },
      "displayName": "Salad"
    },
    {
      "imageObjectDetection": {
        "boundingBox": {
          "normalizedVertices": [
            {
              "x": 0.11737197,
              "y": 0.7098793
            },
            {
              "x": 0.510878,
              "y": 0.87987
            }
          ]
        },
        "score": 0.63219965
      },
      "displayName": "Tomato"
    }
  ]
}

取消部署模型（可选）

模型部署后即会产生费用。为避免产生这一模型托管费用，您可以取消部署模型。

运行以下命令来取消部署模型：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "x-goog-user-project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  "https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models/MODEL_ID:undeploy"

清理

为避免因本页面中使用的资源导致您的 Google Cloud 账号产生费用，请删除包含这些资源的 Google Cloud 项目。

如果您不再需要自定义模型和相关数据集，可以将其删除。

列出模型

您可以使用以下命令列出项目的模型及其标识符：

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models

删除模型

您可以使用以下命令删除模型。

  • 将 MODEL_ID 替换为模型的标识符。
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models/MODEL_ID

列出数据集

您可以使用以下命令列出项目的数据集及其标识符：

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/datasets

删除数据集

您可以使用以下命令删除数据集。

  • 将 DATASET_ID 替换为模型的标识符。
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/datasets/DATASET_ID

后续步骤