快速入门

本快速入门演示如何创建和使用三种 Vision API Product Search 资源:一个包含一组商品的商品集以及与这些商品关联的参考图片。

在本快速入门中,您将通过批量导入的方式一步创建商品集、商品及其参考图片。

在将商品集编入索引后,您可以使用 Vision API Product Search 查询该商品集。

本快速入门将引导您逐步完成以下过程:

  • 使用 CSV 和批量导入功能来创建商品集、商品参考图片。
  • 使用存储在 Cloud Storage 存储分区中的图片向 Vision API Product Search 发出请求。

准备工作

请按照以下说明设置您的项目(如果尚未设置)。

设置项目

  1. 登录您的 Google 帐号。

    如果您还没有 Google 帐号,请注册新帐号

  2. 在 Google Cloud Console 的项目选择器页面上,选择或创建一个 Google Cloud 项目。

    转到项目选择器页面

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

  4. 启用 Vision API。

    启用 API

  5. 设置身份验证:
    1. 在 Cloud Console 中,转到创建服务帐号密钥页面。

      转到“创建服务帐号密钥”页面
    2. 服务帐号列表中,选择新的服务帐号
    3. 服务帐号名称字段中,输入一个名称。
    4. 角色列表中,选择 Project > Owner

    5. 点击创建。包含密钥的 JSON 文件就会下载到计算机。
  6. 将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为包含您的服务帐号密钥的 JSON 文件的路径。 此变量仅适用于当前的 shell 会话,因此,如果您打开新的会话,请重新设置该变量。

设置环境变量

为了更方便地运行本主题中的 curl 示例,请设置以下环境变量,其中:

  • project-id 是您的 Google Cloud Platform (GCP) 项目的 ID。
  • region-name 是将运行您的教程的 GCP 位置,例如 us-east1。有效的位置标识符包括 us-west1us-east1europe-west1asia-east1
export PROJECT_ID=project-id
export LOCATION_ID=region-name

使用数据集

在本快速入门中,您将使用一个包含 100 个左右 apparel-v2 商品类别条目的数据集。此公开可用的数据集位于以下公共 Cloud Storage 存储分区中:

CSV 格式如下:

gs://cloud-ai-vision-data/product-search-tutorial/images/filename1.jpg,image0,product_set0,product_id0,apparel-v2,,"style=women,category=shoe",
gs://cloud-ai-vision-data/product-search-tutorial/images/filename2.jpg,image1,product_set0,product_id1,apparel-v2,,"style=men,category=shoe",
gs://cloud-ai-vision-data/product-search-tutorial/images/filename3.jpg,image2,product_set0,product_id2,apparel-v2,,"style=women,category=dress",

通过批量导入方式创建商品集、商品和参考图片

使用以下 curl 命令创建一个包含商品和参考图片的新商品集。此商品集名为 product_set0(在导入 CSV 中声明的值)。

首先,创建一个名为 import_request.json 的请求 JSON 文件,并将其保存到您当前的工作目录中:

import_request.json

{
  "inputConfig": {
    "gcsSource": {
      "csvFileUri": "gs://cloud-samples-data/vision/product_search/product_catalog.csv"
    }
  }
}

创建请求 JSON 文件后,发送以下请求:

curl -X POST \
    -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @import_request.json \
    https://vision.googleapis.com/v1/projects/$PROJECT_ID/locations/$LOCATION_ID/productSets:import

成功的响应包含一个长时间运行的操作对象:

{
  "name": "locations/location-id/operations/0a0aec86192599fa"
}

该响应还包含相关操作 ID(例如 0a0aec86192599fa),该 ID 可用于获取操作状态。

获取导入操作状态

您可以使用从导入操作返回的 operation-id 来检查批量导入操作的状态:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
https://vision.googleapis.com/v1/locations/$LOCATION_ID/operations/operation-id

成功的响应如下所示:

{
  "name": "locations/location-id/operations/0a0aec86192599fb",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.BatchOperationMetadata",
    "state": "SUCCESSFUL",
    "submitTime": "2018-11-30T03:11:04.808114024Z",
    "endTime": "2018-11-30T03:11:38.624444324Z"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.ImportProductSetsResponse",
    "referenceImages": [
      {
        "name": "projects/project-id/locations/location-id/products/product_id0/referenceImages/image0",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/46a0cbcf70ba11e89399d20059124800.jpg"
      },
      {
        "name": "projects/project-id/locations/location-id/products/product_id1/referenceImages/image1",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/46a1aea370ba11e888d4d20059124800.jpg"
      },
      ...
      {
        "name": "projects/project-id/locations/location-id/products/product_id93/referenceImages/image93",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/4697319970ba11e8a7bfd20059124800.jpg"
      },
      {
        "name": "projects/project-id/locations/location-id/products/product_id94/referenceImages/image94",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/4698596370ba11e8bf6ad20059124800.jpg"
      }
    ],
    "statuses": [
      {},
      {},
       ...
      {},
      {}
    ]
  }
}

编制索引

产品的 Product Search 索引大约每 30 分钟更新一次。添加或删除图片后,在下次更新索引之前,此类更改不会反映在您的 Product Search 响应中。

要确保已将某产品集成功编入索引,请检查该产品集的 indexTime 字段。

列出商品集并检查索引编制情况

您可以列出所有商品集,并使用 indexTime 字段验证是否已将商品集成功编入索引:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    https://vision.googleapis.com/v1/projects/$PROJECT_ID/locations/$LOCATION_ID/productSets

如果响应成功,系统会列出您的所有商品集,包括商品集 ID(例如 product_set0)和指示索引编制完成时间的 indexTime 字段:

{
  "productSets": [
    {
      "name": "projects/project-id/locations/location-id/productSets/product_set0",
      "displayName": " ",
      "indexTime": "2019-11-30T18:33:40.093508652Z",
      "indexError": {}
    }
  ]
}

列出商品

您可以使用从商品集列表返回的 product-set-id 列出商品集中的所有商品:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
https://vision.googleapis.com/v1/projects/$PROJECT_ID/locations/$LOCATION_ID/productSets/product-set-id/products?pageSize=15

成功的响应会列出商品详细信息。

在该请求中,您使用可选查询参数 pageSize 将结果列表设置为 15 件商品。响应中的 nextPageToken 也表明还可以列出更多商品。您可以使用列出的令牌来检索更多结果。如需详细了解如何使用 pageToken,请参阅获取和列出资源

{
  "products": [
    {
      "name": "projects/project-id/locations/location-id/products/product_id0",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "women"
        },
        {
          "key": "category",
          "value": "shoe"
        }
      ]
    },
    {
      "name": "projects/project-id/locations/location-id/products/product_id1",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "men"
        },
        {
          "key": "category",
          "value": "shoe"
        }
      ]
    },
    ...
    {
      "name": "projects/project-id/locations/location-id/products/product_id21",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "women"
        },
        {
          "key": "category",
          "value": "dress"
        }
      ]
    }
  ],
  "nextPageToken": "1LqhSgZfM_uWKOxvog"
}

使用 Vision API Product Search 搜索匹配的商品

索引编制完成后,您可以搜索与示例图片匹配的商品。在本快速入门中,您将使用存储在 Google Cloud Storage 存储分区中的图片,如下面的图片。

Cloud Storage 存储分区中的连衣裙图片
gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg

使用远程图片进行搜索

通过以下请求,使用存储在公共 Cloud Storage 存储分区中的图片进行搜索。

首先,创建一个名为 search_request.json 的请求 JSON 文件,并将其保存到您当前的工作目录中:更改请求 JSON 中的以下值,以与您的项目信息相匹配:

  • my-project-id
  • my-location-id
  • my-product-set-id

search_request.json

{
  "requests": [
    {
      "image": {
        "source": {
          "gcsImageUri": "gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg"
        }
      },
      "features": [
        {
          "type": "PRODUCT_SEARCH"
        }
      ],
      "imageContext": {
        "productSearchParams": {
          "productSet": "projects/project-id/locations/location-id/productSets/product-set-id",
          "productCategories": [
               "apparel-v2"
             ],
        "filter": "style=womens OR style=women"
        }
      }
    }
  ]
}

创建请求 JSON 文件后,发送以下请求:

curl -X POST \
    -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @search_request.json \
    https://vision.googleapis.com/v1/images:annotate

如果请求成功,将返回用商品 ID 表示的匹配商品的列表。如果一张图片包含多件商品,那么显示的结果会按由边界框标识的各件商品进一步细分。

如需查看有关检测单件商品以及检测图片中多件商品的示例,请参阅了解搜索响应和多对象检测主题。

此外,还会返回 score 字段。此字段表示该服务确定商品与所提供图片相匹配的置信度,其范围介于 0(零置信度)到 1(最高置信度)之间。

indexTime 字段显示正在搜索的索引版本。在此之后对图片进行的更改不会反映在这些结果中。

恭喜!您已向 Vision API Product Search 服务发送了第一个 images.annotate 请求。

清理

为避免产生不必要的 Google Cloud Platform 费用,请使用 Cloud Console 删除您不需要的项目。

后续步骤