创建商品集并搜索商品

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

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

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

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

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

准备工作

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

设置项目

  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 Vision API:

    gcloud services enable vision.googleapis.com
  7. 向您的 Google 账号授予角色。对以下每个 IAM 角色运行以下命令一次: roles/storage.objectViewer

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS" --role=ROLE
    • PROJECT_ID 替换为您的项目 ID。
    • EMAIL_ADDRESS 替换为您的电子邮件地址。
    • ROLE 替换为每个角色。
  8. 安装 Google Cloud CLI。
  9. 如需初始化 gcloud CLI,请运行以下命令:

    gcloud init
  10. 创建或选择 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 项目 名称。

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

  12. Enable the Vision API:

    gcloud services enable vision.googleapis.com
  13. 向您的 Google 账号授予角色。对以下每个 IAM 角色运行以下命令一次: roles/storage.objectViewer

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS" --role=ROLE
    • PROJECT_ID 替换为您的项目 ID。
    • EMAIL_ADDRESS 替换为您的电子邮件地址。
    • ROLE 替换为每个角色。

设置环境变量

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

  • PROJECT_ID 是您的 Google Cloud 项目的 ID。
  • LOCATION_ID 是将运行您的教程的 Google Cloud 位置,例如 us-east1。有效的位置标识符包括 us-west1us-east1europe-west1asia-east1

使用数据集

在本快速入门中,您将使用一个包含 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 print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -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 print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -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 print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -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 print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -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 中的以下值,以与您的项目信息相匹配:

  • PROJECT_ID
  • LOCATION_ID
  • 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 print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -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 请求。

清理

  1. 可选:从 gcloud CLI 撤消凭据。

    gcloud auth revoke
  2. 删除 Google Cloud 项目:

    gcloud projects delete PROJECT_ID

后续步骤