创建商品集并搜索商品
本快速入门演示如何创建和使用三种 Vision API Product Search 资源:一个包含一组商品的商品集以及与这些商品关联的参考图片。
在本快速入门中,您将通过批量导入的方式一步创建商品集、商品及其参考图片。
在将商品集编入索引后,您可以使用 Vision API Product Search 查询该商品集。
本快速入门将引导您逐步完成以下过程:
- 使用 CSV 和批量导入功能来创建商品集、商品和参考图片。
- 使用存储在 Cloud Storage 存储桶中的图片向 Vision API Product Search 发出请求。
准备工作
请按照以下说明设置您的项目(如果尚未设置)。
设置项目
- 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手,请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Create or select a Google Cloud 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.
-
-
Enable the Vision API:
gcloud services enable vision.googleapis.com
-
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:myemail@example.com
. - Replace
ROLE
with each individual role.
- Replace
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Create or select a Google Cloud 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.
-
-
Enable the Vision API:
gcloud services enable vision.googleapis.com
-
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:myemail@example.com
. - Replace
ROLE
with each individual role.
- Replace
设置环境变量
为了更方便地运行本快速入门中的 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 存储桶中:
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 存储桶中的图片进行搜索。
首先,创建一个名为 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
请求。
清理
-
Optional: Revoke credentials from the gcloud CLI.
gcloud auth revoke
-
Delete a Google Cloud project:
gcloud projects delete PROJECT_ID
后续步骤
- 借助 Vision API Product Search 客户端库,以您偏好的语言开始使用 Vision API Product Search。
- 浏览方法指南。
- 浏览教程。