快速入门

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

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

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

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

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

准备工作

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

设置项目

  1. 登录您的 Google Cloud 帐号。如果您是 Google Cloud 新手,请创建一个帐号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
  2. 在 Google Cloud Console 的项目选择器页面上,选择或创建一个 Google Cloud 项目。

    转到“项目选择器”

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

  4. 启用 Vision API。

    启用 API

  5. 创建服务帐号:

    1. 在 Cloud Console 中,转到创建服务帐号页面。

      转到“创建服务帐号”
    2. 选择一个项目。
    3. 服务帐号名称字段中,输入一个名称。 Cloud Console 会根据此名称填充服务帐号 ID 字段。

      服务帐号说明字段中,输入说明。例如,Service account for quickstart

    4. 点击创建
    5. 点击选择角色字段。

      快速访问下,点击基本,然后点击所有者

    6. 点击继续
    7. 点击完成以完成服务帐号的创建过程。

      不要关闭浏览器窗口。您将在下一步骤中用到它。

  6. 创建服务帐号密钥:

    1. 在 Cloud Console 中,点击您创建的服务帐号的电子邮件地址。
    2. 点击密钥
    3. 依次点击添加密钥创建新密钥
    4. 点击创建。JSON 密钥文件将下载到您的计算机上。
    5. 点击关闭
  7. 将环境变量 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

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

该响应还包含相关操作 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

成功的响应如下所示:

编制索引

商品的 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 字段:

列出商品

您可以使用从商品集列表返回的 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,请参阅获取和列出资源

使用 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

创建请求 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 删除您不需要的项目。

后续步骤