创建商品集并搜索商品

创建商品集并搜索商品

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

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

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

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

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

准备工作

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

设置项目

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Vision API:

   gcloud services enable vision.googleapis.com

7. Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/storage.objectViewer

   gcloud projects add-iam-policy-binding PROJECT_ID --member="USER_IDENTIFIER" --role=ROLE

   • Replace PROJECT_ID with your project ID.

   • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:[e-mail].

   • Replace ROLE with each individual role.
8. Install the Google Cloud CLI.

9. To initialize the gcloud CLI, run the following command:

   gcloud init

10. Create or select a Google Cloud project.

    Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

11. Make sure that billing is enabled for your Google Cloud project.

12. Enable the Vision API:

    gcloud services enable vision.googleapis.com

13. Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/storage.objectViewer

    gcloud projects add-iam-policy-binding PROJECT_ID --member="USER_IDENTIFIER" --role=ROLE

    • Replace PROJECT_ID with your project ID.

    • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:[e-mail].

    • Replace ROLE with each individual role.

设置环境变量

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

• PROJECT_ID 是您的 Google Cloud 项目的 ID。
• LOCATION_ID 是将运行您的教程的 Google Cloud 位置，例如 us-east1。有效的位置标识符包括 us-west1、us-east1、europe-west1 和 asia-east1。

使用数据集

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

• gs://cloud-samples-data/vision/product_search/product_catalog.csv

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

注意：此示例 CSV 省略了可选列 product-display 和 bounding-poly。如需详细了解 CSV 要求，请参阅设置批量导入 CSV 的格式方法主题。

使用批量导入操作创建商品集、商品和参考图片

使用以下 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 存储桶中的图片，如下图所示。

注意：您还可以使用 base64 编码的本地图片进行搜索。如需查看使用本地图片的代码示例，请参阅搜索商品。

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 字段显示正在搜索的索引版本。在此之后对图片进行的更改不会反映在这些结果中。

响应

{
  "responses": [
    {
      "productSearchResults": {
        "indexTime": "2020-01-07T18:33:45.300851144Z",
        "results": [
          {
            "product": {
              "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16",
              "displayName": " ",
              "productCategory": "apparel-v2",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                }
              ]
            },
            "score": 1,
            "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16/referenceImages/image16"
          },
          {
            "product": {
              "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id29",
              "displayName": " ",
              "productCategory": "apparel-v2",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                }
              ]
            },
            "score": 0.27578148,
            "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id29/referenceImages/image29"
          },
          ...
          {
            "product": {
              "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id22",
              "displayName": " ",
              "productCategory": "apparel-v2",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                },
                {
                  "key": "kids",
                  "value": "true"
                }
              ]
            },
            "score": 0.20356013,
            "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id22/referenceImages/image22"
          }
        ],
        "productGroupedResults": [
          {
            "boundingPoly": {
              "normalizedVertices": [
                {
                  "x": 0.25542393,
                  "y": 0.15517132
                },
                {
                  "x": 0.8196448,
                  "y": 0.15517132
                },
                {
                  "x": 0.8196448,
                  "y": 0.92001766
                },
                {
                  "x": 0.25542393,
                  "y": 0.92001766
                }
              ]
            },
            "results": [
              {
                "product": {
                  "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16",
                  "displayName": " ",
                  "productCategory": "apparel-v2",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 1,
                "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16/referenceImages/image16"
              },
              {
                "product": {
                  "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id57",
                  "displayName": " ",
                  "productCategory": "apparel-v2",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 0.27369013,
                "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id57/referenceImages/image57"
              },
              ...
              {
                "product": {
                  "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id18",
                  "displayName": " ",
                  "productCategory": "apparel-v2",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 0.21221256,
                "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id18/referenceImages/image18"
              }
            ],
            "objectAnnotations": [
              {
                "mid": "/m/01d40f",
                "name": "Dress",
                "score": 0.968603
              }
            ]
          }
        ]
      }
    }
  ]
}

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

清理

1. Optional: Revoke credentials from the gcloud CLI.

   gcloud auth revoke

2. 注意：删除项目会产生以下影响：

   • 项目中的所有内容都会被删除。如果您将现有项目用于本文档中的任务，则删除该项目后，还将删除您已在该项目中完成的任何其他工作。
   • 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。

   如果您打算探索多个架构、教程或快速入门，则重复使用项目可以帮助您避免超出项目配额限制。

   Delete a Google Cloud project:

   gcloud projects delete PROJECT_ID

后续步骤

• 借助 Vision API Product Search 客户端库，以您偏好的语言开始使用 Vision API Product Search。
• 浏览方法指南。
• 浏览教程。