快速入门：使用 AutoML Vision API 为图片添加标签

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

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

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

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

准备工作

地区要求：目前，项目资源必须位于 us-central1 地区才能使用此 API。

设置项目

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

安装 Google Cloud CLI。

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

gcloud init

创建或选择 Google Cloud 项目。

创建 Cloud 项目：
```
gcloud projects create PROJECT_ID
```
选择您创建的 Cloud 项目：
```
gcloud config set project PROJECT_ID
```

确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。

Enable the AutoML and Cloud Storage APIs:

gcloud services enable storage-component.googleapis.comautoml.googleapis.comstorage-api.googleapis.com

安装 Google Cloud CLI。

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

gcloud init

创建或选择 Google Cloud 项目。

创建 Cloud 项目：
```
gcloud projects create PROJECT_ID
```
选择您创建的 Cloud 项目：
```
gcloud config set project PROJECT_ID
```

确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。

Enable the AutoML and Cloud Storage APIs:

gcloud services enable storage-component.googleapis.comautoml.googleapis.comstorage-api.googleapis.com

将 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,,

每行对应一个位于较大图片内的对象，每个对象专门指定为测试数据、训练数据或验证数据。此处包含的三行表示位于同一张图片 (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 提供了一组总体评估指标以及针对每个标签的评估指标；前者指示模型的整体表现，后者指示模型在不同阈值条件下针对该标签的表现。

完整响应

{
  "modelEvaluation": [
    {
      "name": "projects/PROJECT_NUMBER/locations/us-central1/models/IOD4151192956528754688/modelEvaluations/1182890778171518665",
      "annotationSpecId": "not available",
      "createTime": "2018-10-29T18:25:04.748671Z",
      "evaluatedExampleCount": 15,
      "imageObjectDetectionEvaluationMetrics": {
        "evaluatedBoundingBoxCount": 46,
        "boundingBoxMetricsEntries": [
          {
            "iouThreshold": 0.75,
            "meanAveragePrecision": 0.5,
            "confidenceMetricsEntries": [
              {
                "confidenceThreshold": 1.810214e-07,
                "recall": 0.5,
                "precision": 0.010810811,
                "f1Score": 0.021164022
              },
              {
                "confidenceThreshold": 0.17042068,
                "recall": 0.25,
                "precision": 1,
                "f1Score": 0.4
              }
            ]
          },
          {
            "iouThreshold": 0.1,
            "meanAveragePrecision": 0.76785713,
            "confidenceMetricsEntries": [
              {
                "confidenceThreshold": 1.810214e-07,
                "recall": 1,
                "precision": 0.021621622,
                "f1Score": 0.042328045
              },
              ...
              {
                "confidenceThreshold": 0.17042068,
                "recall": 0.25,
                "precision": 1,
                "f1Score": 0.4
              }
            ]
          },
          ....
          {
            "iouThreshold": 0.35,
            "meanAveragePrecision": 0.625,
            "confidenceMetricsEntries": [
              {
                "confidenceThreshold": 1.810214e-07,
                "recall": 0.75,
                "precision": 0.016216217,
                "f1Score": 0.03174603
              },
              ...
              {
                "confidenceThreshold": 0.17042068,
                "recall": 0.25,
                "precision": 1,
                "f1Score": 0.4
              }
            ]
          }
        ],
        "boundingBoxMeanAveragePrecision": 0.6041587
      },
      "displayName": "Baked goods"
    },
    {
      "name": "projects/1061035157773/locations/us-central1/models/IOD4151192956528754688/modelEvaluations/4394438244360404425",
      "annotationSpecId": "not available",
      "createTime": "2018-10-29T18:25:04.748671Z",
      "evaluatedExampleCount": 16,
      "imageObjectDetectionEvaluationMetrics": {
        "evaluatedBoundingBoxCount": 483,
        "boundingBoxMetricsEntries": [
          {
            "iouThreshold": 0.75,
            "meanAveragePrecision": 0.7840024,
            "confidenceMetricsEntries": [
              {
                "confidenceThreshold": 8.309368e-08,
                "recall": 0.90909094,
                "precision": 0.10869565,
                "f1Score": 0.19417474
              },
              ...
              {
                "confidenceThreshold": 0.9996754,
                "recall": 0.030303031,
                "precision": 1,
                "f1Score": 0.058823533
              }
            ]
          },
          ...
          {
            "iouThreshold": 0.35,
            "meanAveragePrecision": 0.86702496,
            "confidenceMetricsEntries": [
              {
                "confidenceThreshold": 8.309368e-08,
                "recall": 0.969697,
                "precision": 0.11594203,
                "f1Score": 0.20711976
              },
              ...
              {
                "confidenceThreshold": 0.9996754,
                "recall": 0.030303031,
                "precision": 1,
                "f1Score": 0.058823533
              }
            ]
          }
        ],
        "boundingBoxMeanAveragePrecision": 0.7937659
      },
      "displayName": "Salad"
    },
    {
      "name": "projects/1061035157773/locations/us-central1/models/IOD4151192956528754688/modelEvaluations/6580321110534243778",
      "createTime": "2018-10-29T18:25:04.748671Z",
      "evaluatedExampleCount": 16,
      "imageObjectDetectionEvaluationMetrics": {
        "evaluatedBoundingBoxCount": 1429,
        "boundingBoxMetricsEntries": [
          {
            "iouThreshold": 0.5,
            "meanAveragePrecision": 0.47700325,
            "confidenceMetricsEntries": [
              {
                "confidenceThreshold": 8.309368e-08,
                "recall": 0.8220339,
                "precision": 0.08083333,
                "f1Score": 0.14719272
              },
              ...
              {
                "confidenceThreshold": 0.9996754,
                "recall": 0.008474576,
                "precision": 1,
                "f1Score": 0.016806722
              }
            ]
          },
          ...
          {
            "iouThreshold": 0.55,
            "meanAveragePrecision": 0.46909538,
            "confidenceMetricsEntries": [
              {
                "confidenceThreshold": 8.309368e-08,
                "recall": 0.7966102,
                "precision": 0.07833333,
                "f1Score": 0.14264037
              },
              ...
              {
                "confidenceThreshold": 0.9996754,
                "recall": 0.008474576,
                "precision": 1,
                "f1Score": 0.016806722
              }
            ]
          }
        ],
        "boundingBoxMeanAveragePrecision": 0.43594807
      }
    },
    {
      "name": "projects/1061035157773/locations/us-central1/models/IOD4151192956528754688/modelEvaluations/6664671194249632675",
      "annotationSpecId": "not available",
      "createTime": "2018-10-29T18:25:04.748671Z",
      "evaluatedExampleCount": 16,
      "imageObjectDetectionEvaluationMetrics": {
        "evaluatedBoundingBoxCount": 575,
        "boundingBoxMetricsEntries": [
          {
            "iouThreshold": 0.5,
            "meanAveragePrecision": 0.47446758,
            "confidenceMetricsEntries": [
              {
                "confidenceThreshold": 6.9239513e-07,
                "recall": 0.84444445,
                "precision": 0.14074074,
                "f1Score": 0.24126983
              },
              ...
              {
                "confidenceThreshold": 0.9993529,
                "recall": 0.022222223,
                "precision": 1,
                "f1Score": 0.043478258
              }
            ]
          },
          ...
          {
            "iouThreshold": 0.55,
            "meanAveragePrecision": 0.46771756,
            "confidenceMetricsEntries": [
              {
                "confidenceThreshold": 6.9239513e-07,
                "recall": 0.82222223,
                "precision": 0.13703704,
                "f1Score": 0.23492064
              },
              ...
              {
                "confidenceThreshold": 0.9993529,
                "recall": 0.022222223,
                "precision": 1,
                "f1Score": 0.043478258
              }
            ]
          }
        ],
        "boundingBoxMeanAveragePrecision": 0.43788764
      },
      "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: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 帐号产生费用，请删除包含这些资源的 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