本教程介绍如何创建包含一组商品及其参考图片的商品集,本教程向用户介绍如何通过在线(逐一)导入的方式创建商品集。在将商品集编入索引后,您可以使用 Vision API Product Search 查询该商品集。
在本教程中,您将学习如何完成以下操作:
- 通过在线(逐一)导入的方式创建商品集
- 创建单件商品
- 将商品添加到商品集
- 更新商品
- 创建参考图片
- 搜索类似商品
准备工作
在开始本教程之前,请确保您已安装了相应的客户端库,已为项目启用结算和 API,并且已正确设置身份验证。
导入库
如要使用 Vision API Product Search,请在下载并安装客户端库后导入以下模块:
Go
Java
Node.js
Python
其他语言
C#: 请按照客户端库页面上的 C# 设置说明操作,然后访问 .NET 版 Vision API Product Search 参考文档。
PHP: 请按照客户端库页面上的 PHP 设置说明操作,然后访问 PHP 版 Vision API Product Search 参考文档。
Ruby 版: 请按照客户端库页面上的 Ruby 设置说明操作,然后访问 Ruby 版 Vision API Product Search 参考文档。
运行应用
第 1 步:创建商品目录
用户可以通过两种方式创建商品目录:即使用 CSV 文件执行批量导入或使用在线导入;前一种方法可以在一次 API 调用中导入整个商品目录,后一种方法可让您控制商品集并允许一次管理一种资源或关系。这主要意味着,您可以逐一创建商品集、商品和参考图片。利用在线导入功能,您还可以逐步更新已通过批量导入创建的商品目录。
在本教程中,您将使用在线导入功能。如需获取有关使用 CSV 进行批量导入的示例,请参阅快速入门。
在线(逐一)导入
1.创建商品集
创建一个空商品集(用于容纳一组商品的简单容器)。
请求
使用 create_product_set()
方法执行以下请求,以创建一个空商品集并将其命名为“PS_CLOTH-SHOE_070318”。以参数形式传递商品集 ID 和显示名。
REST
在使用任何请求数据之前,请先进行以下替换:
- PROJECT_ID:您的 Google Cloud 项目 ID。
- LOCATION_ID:有效的位置标识符。有效的位置标识符包括
us-west1
、us-east1
、europe-west1
和asia-east1
。 - DISPLAY_NAME:您选择的字符串显示名。
HTTP 方法和网址:
POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets
请求 JSON 正文:
{ "displayName": "display-name" }
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.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 @request.json \
"https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets"
PowerShell
将请求正文保存在名为 request.json
的文件中,然后执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets" | Select-Object -Expand Content
如果请求成功,服务器将返回一个 200 OK
HTTP 状态代码以及 JSON 格式的响应。
您应该会看到类似如下所示的输出。可以使用商品集 ID(本例中为 b6d809615b6dd675
)对商品集执行其他操作。
{ "name": "projects/project-id/locations/location-id/productSets/b6d809615b6dd675", "displayName": "new-product-set" }
Go
Java
Node.js
Python
其他语言
C#: 请按照客户端库页面上的 C# 设置说明操作,然后访问 .NET 版 Vision API Product Search 参考文档。
PHP: 请按照客户端库页面上的 PHP 设置说明操作,然后访问 PHP 版 Vision API Product Search 参考文档。
Ruby 版: 请按照客户端库页面上的 Ruby 设置说明操作,然后访问 Ruby 版 Vision API Product Search 参考文档。
响应
Product set name: projects/prj-prod-search-tutorials/locations/us-east1/productSets/PS_CLOTH-SHOE_070318 Product set id: PS_CLOTH-SHOE_070318 Product set display name: CLOTH-SHOE
2. 创建商品
创建商品集后,接下来需要创建商品。 执行以下请求来创建商品。
REST
在使用任何请求数据之前,请先进行以下替换:
- PROJECT_ID:您的 Google Cloud 项目 ID。
- LOCATION_ID:有效的位置标识符。有效的位置标识符包括
us-west1
、us-east1
、europe-west1
和asia-east1
。 - DISPLAY_NAME:您选择的字符串显示名。
- PRODUCT_DESCRIPTION:您选择的字符串说明。
- product-category:有效的商品类别。目前提供了以下商品类别:
homegoods-v2
、apparel-v2
、toys-v2
、packagedgoods-v1
和general-v1
。 productLabels
:与商品关联的一个或多个键值对。每个 KEY_STRING 必须具有一个关联的 VALUE_STRING。
HTTP 方法和网址:
POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products
请求 JSON 正文:
{ "displayName": "display-name", "description": "product-description", "productCategory": "product-category", "productLabels": [ { "key": "key-string", "value": "value-string" } ] }
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.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 @request.json \
"https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products"
PowerShell
将请求正文保存在名为 request.json
的文件中,然后执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products" | Select-Object -Expand Content
请求正文示例:
{ "displayName": "sample-product-1234", "description": "Athletic shorts", "productCategory": "apparel-v2", "productLabels": [ { "key": "style", "value": "womens" }, { "key": "color", "value": "blue" } ] }
如果请求成功,服务器将返回一个 200 OK
HTTP 状态代码以及 JSON 格式的响应。
您应该会看到类似如下所示的输出。可以使用商品 ID(本例中为 37b9811d308c4e42
)对商品执行其他操作。
{ "name": "projects/project-id/locations/location-id/products/37b9811d308c4e42", "displayName": "sample-product-456", "description": "Athletic shorts", "productCategory": "apparel-v2", "productLabels": [ { "key": "style", "value": "womens" }, { "key": "color", "value": "blue" } ] }
Go
Java
Node.js
Python
其他语言
C#: 请按照客户端库页面上的 C# 设置说明操作,然后访问 .NET 版 Vision API Product Search 参考文档。
PHP: 请按照客户端库页面上的 PHP 设置说明操作,然后访问 PHP 版 Vision API Product Search 参考文档。
Ruby 版: 请按照客户端库页面上的 Ruby 设置说明操作,然后访问 Ruby 版 Vision API Product Search 参考文档。
响应
Product name: projects/prj-prod-search-tutorials/locations/us-east1/products/P_CLOTH-SHOE_46903668_070318 Product id: P_CLOTH-SHOE_46903668_070318 Product display name: Blue Dress Product category: apparel Product description: Short sleeved and 1950s style satin dress Product labels: Product label 1: key: style value: women Product label 2: key: category value: dress Product label 3: key: color value: dark-blue
3. 将商品添加到商品集
创建商品集和商品后,您可以将商品添加到商品集中。
REST
在使用任何请求数据之前,请先进行以下替换:
- PROJECT_ID:您的 Google Cloud 项目 ID。
- LOCATION_ID:有效的位置标识符。有效的位置标识符包括
us-west1
、us-east1
、europe-west1
和asia-east1
。 - PRODUCT_SET_ID:您要对其执行操作的商品集的 ID。
- PRODUCT_NAME:商品的完整资源名称。
格式如下:
projects/PROJECT_ID/locations/LOCATION_ID/products/PRODUCT_ID
HTTP 方法和网址:
POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets/product-set-id:addProduct
请求 JSON 正文:
{ "product": "product-name" }
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.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 @request.json \
"https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets/product-set-id:addProduct"
PowerShell
将请求正文保存在名为 request.json
的文件中,然后执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets/product-set-id:addProduct" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
{}
Go
Java
Node.js
Python
其他语言
C#: 请按照客户端库页面上的 C# 设置说明操作,然后访问 .NET 版 Vision API Product Search 参考文档。
PHP: 请按照客户端库页面上的 PHP 设置说明操作,然后访问 PHP 版 Vision API Product Search 参考文档。
Ruby 版: 请按照客户端库页面上的 Ruby 设置说明操作,然后访问 Ruby 版 Vision API Product Search 参考文档。
响应
Product added to product set.
4.更新商品
如果您需要在创建商品或商品集后对其进行更新,则可以使用我们的更新方法。此示例展示了商品更新,其中标签有所更改:
命令行
发送 PATCH
请求时,所有先前的字段及其值都将被清空,但 productCategory
字段除外,它是不可变的。发出 PATCH
更新请求后,发送您所需的包含值的所有字段。
在使用任何请求数据之前,请先进行以下替换:
- PROJECT_ID:您的 Google Cloud 项目 ID。
- LOCATION_ID:有效的位置标识符。有效的位置标识符包括
us-west1
、us-east1
、europe-west1
和asia-east1
。 - PRODUCT_ID:与参考图片关联的商品的 ID。此 ID 由用户在创建商品时随机设置或指定。
- display-name:您选择的字符串显示名。 它可以与之前的显示名或更新后的值相同。
- description:您选择的字符串说明。 它可以与之前的显示名或更新后的值相同。如果您不需要
description
字段和值,请忽略。 productLabels
:与商品关联的一个或多个键值对。每个 KEY_STRING 必须具有一个关联的 VALUE_STRING。
HTTP 方法和网址:
PATCH https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id
请求 JSON 正文:
{ "displayName": "display-name", "description": "description", "productLabels": [ { "key": "key-string", "value": "value-string" }, { "key": "key-string", "value": "value-string" } ] }
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.json
的文件中,然后执行以下命令:
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: project-id" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id"
PowerShell
将请求正文保存在名为 request.json
的文件中,然后执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }
Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应:
{ "name": "projects/project-id/locations/location-id/products/product-id", "displayName": "display-name", "description": "description", "productCategory": "apparel-v2", "productLabels": [ { "key": "style", "value": "womens" }, { "key": "onSale", "value": "true" } ] }
Go
Java
Node.js
Python
其他语言
C#: 请按照客户端库页面上的 C# 设置说明操作,然后访问 .NET 版 Vision API Product Search 参考文档。
PHP: 请按照客户端库页面上的 PHP 设置说明操作,然后访问 PHP 版 Vision API Product Search 参考文档。
Ruby 版: 请按照客户端库页面上的 Ruby 设置说明操作,然后访问 Ruby 版 Vision API Product Search 参考文档。
响应
Product name: projects/prj-prod-search-tutorials/locations/us-east1/products/P_CLOTH-SHOE_46903668_070318 Product id: P_CLOTH-SHOE_46903668_070318 Product display name: Blue Dress Updated product labels: Product label 1: key: style value: women Product label 2: key: category value: dress Product label 3: key: color value: blue Product description: Short sleeved and 1950s style satin dress
5. 创建商品的参考图片
为单件商品创建参考图片后,如果该商品已编入索引,Vision API Product Search 便可按图片搜索商品。您可以为一件商品创建多个参考图片,尤其是在希望获得更精确的匹配项时。
您可以随时为商品添加新的参考图片。
创建参考图片时,您可以选择添加边界多边形坐标。边界多边形用于标识感兴趣的参考图片区域。例如,如果为夹克商品创建了参考图片,那么您可以在边界多边形参数中提供夹克的坐标,这样,系统在查找商品匹配项时便只会考虑夹克商品。注意:您可以在索引时提供多个边界多边形,但在查询时,该 API 仅支持一个边界多边形。
获取图片的边界多边形坐标的快捷方式是使用 Vision API 对象本地化功能。如需详细了解对象本地化,请参阅检测多个对象。
REST
在使用任何请求数据之前,请先进行以下替换:
- PROJECT_ID:您的 Google Cloud 项目 ID。
- LOCATION_ID:有效的位置标识符。有效的位置标识符包括
us-west1
、us-east1
、europe-west1
和asia-east1
。 - PRODUCT_ID:与参考图片关联的商品的 ID。此 ID 由用户在创建商品时随机设置或指定。
- CLOUD_STORAGE_IMAGE_URI:Cloud Storage 存储分区中有效图片文件的路径。您必须至少拥有该文件的读取权限。
示例:
gs://storage-bucket/filename.jpg
HTTP 方法和网址:
POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id/referenceImages
请求 JSON 正文:
{ "uri": "cloud-storage-image-uri", "boundingPolys": [ { "vertices": [ { "x": X_MIN, "y": Y_MIN }, { "x": X_MAX, "y": Y_MIN }, { "x": X_MAX, "y": Y_MAX }, { "x": X_MIN, "y": Y_MAX } ] } ] }
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.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 @request.json \
"https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id/referenceImages"
PowerShell
将请求正文保存在名为 request.json
的文件中,然后执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id/referenceImages" | Select-Object -Expand Content
如果请求成功,服务器将返回一个 200 OK
HTTP 状态代码以及 JSON 格式的响应。
您应该会看到类似如下所示的输出。示例请求在图片中指定了单个 boundingPoly
。边界框的顶点未归一化;顶点值是实际像素值,与原始图片无关,且范围为 0 - 1。这些顶点具有以下值:[(33,22),(282,22),(282,278),(33,278)]。
{ "name": "projects/project-id/locations/location-id/products/product-id/referenceImages/image-id", "uri": "gs://storage-bucket/filename.jpg", "boundingPolys": [ { "vertices": [ { "x": 33, "y": 22 }, { "x": 282, "y": 22 }, { "x": 282, "y": 278 }, { "x": 33, "y": 278 } ] } ] }
Go
Java
Node.js
Python
其他语言
C#: 请按照客户端库页面上的 C# 设置说明操作,然后访问 .NET 版 Vision API Product Search 参考文档。
PHP: 请按照客户端库页面上的 PHP 设置说明操作,然后访问 PHP 版 Vision API Product Search 参考文档。
Ruby 版: 请按照客户端库页面上的 Ruby 设置说明操作,然后访问 Ruby 版 Vision API Product Search 参考文档。
响应
Reference image name: projects/prj-prod-search-tutorials/locations/us-east1/products/P_CLOTH-SHOE_46903668_070318/referenceImages/I_469a896b70ba11e8be97d20059124800_070418 Reference image id: I_469a896b70ba11e8be97d20059124800_070418 Reference image uri: gs://product-search-tutorial/dress-shoe-dataset/469a896b70ba11e8be97d20059124800.jpg Reference image bounding polygons: vertices { x: 80 y: 50 } vertices { x: 80 y: 660 } vertices { x: 300 y: 50 } vertices { x: 430 y: 660 }
第 2 步:搜索匹配商品
在此界面中,您可以通过将新图片作为输入并搜索最匹配的商品来查询所创建的商品目录。
与创建参考图片类似,在搜索匹配图片时,您可以选择添加边界多边形坐标。边界多边形用于标识要查找其匹配项的来源图片中的感兴趣区域。例如,如果您的来源图片同时包含服装和钱包,而您只想查找服装匹配项,那么您可以标识仅包含服装的图片区域的边界多边形坐标。默认情况下,如果未指定边界多边形,则该 API 会确定最大的边界多边形并自动进行查询。
获取图片的边界多边形坐标的快捷方式是使用 Vision API 对象本地化功能。如需详细了解对象本地化,请参阅检测多个对象。例如,若要明确查询完整图片,指定整个图片框的边界多边形即可:[(0, 0), (0, 1), (1, 1), (1, 0)]。
该请求会返回 API 响应,其中包含与图片最匹配的商品以及得分和匹配图片。该图片是以最高置信度值返回的。
REST
在使用任何请求数据之前,请先进行以下替换:
- BASE64_ENCODED_IMAGE:二进制图片数据的 base64 表示(ASCII 字符串)。此字符串应类似于以下字符串:
/9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==
- PROJECT_ID:您的 Google Cloud 项目 ID。
- LOCATION_ID:有效的位置标识符。有效的位置标识符包括
us-west1
、us-east1
、europe-west1
和asia-east1
。 - PRODUCT_SET_ID:您要对其执行操作的商品集的 ID。
特定于字段的注意事项:
features.maxResults
- 要返回的结果数的上限。imageContext.productCategories
- 要搜索的商品类别。目前,您只能指定一种商品类别(家庭用品、服装、玩具、包装商品和一般商品)。imageContext.filter
-(可选)用于商品标签的一个(或多个)键值对过滤表达式。格式:“key
=value
”。过滤键值对可以与 AND 或 OR 表达式搭配使用:“color
=blue
ANDstyle
=mens
”或“color
=blue
ORcolor
=black
”。如果使用 OR 表达式,则表达式中的所有键必须相同。
HTTP 方法和网址:
POST https://vision.googleapis.com/v1/images:annotate
请求 JSON 正文:
{ "requests": [ { "image": { "content": base64-encoded-image }, "features": [ { "type": "PRODUCT_SEARCH", "maxResults": 5 } ], "imageContext": { "productSearchParams": { "productSet": "projects/project-id/locations/location-id/productSets/product-set-id", "productCategories": [ "apparel" ], "filter": "style = womens" } } } ] }
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.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 @request.json \
"https://vision.googleapis.com/v1/images:annotate"
PowerShell
将请求正文保存在名为 request.json
的文件中,然后执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/images:annotate" | Select-Object -Expand Content
如果请求成功,服务器将返回一个 200 OK
HTTP 状态代码以及 JSON 格式的响应。
响应 JSON 包含以下两种结果类型:
productSearchResults
- 包含整个图片的匹配商品列表。在示例响应中,匹配商品为 product_id65、product_id35、product_id34、product_id62 和 product_id32。productGroupedResults
- 包含图片中识别的每个商品的边界框坐标和匹配项。在以下响应中,仅识别了一个商品,后跟示例商品集中的匹配商品:product_id65、product_id35、product_id34、product_id93 和 product_id62。
请注意,虽然这两种结果类型存在重叠,但也可能存在差异(例如,响应中的 product_id32 和 product_id93)。
Go
Java
Node.js
Python
其他语言
C#: 请按照客户端库页面上的 C# 设置说明操作,然后访问 .NET 版 Vision API Product Search 参考文档。
PHP: 请按照客户端库页面上的 PHP 设置说明操作,然后访问 PHP 版 Vision API Product Search 参考文档。
Ruby 版: 请按照客户端库页面上的 Ruby 设置说明操作,然后访问 Ruby 版 Vision API Product Search 参考文档。
服装响应示例
Search Image: D:/product/final/images-20180618T073733Z-01/images/469355b570ba11e88ff2d20059124800.jpg
Similar product information: Product id: 46930b6b Product display name: Evening gown Product description: Blue evening gown in 1940s style Product category: apparel style: women category: dress color: blue
使用标签进行搜索
以下搜索示例包括一个基于颜色的过滤条件。
请求
使用方法 get_similar_products_file()
或 get_similar_products_uri()
执行以下请求,以发出搜索请求。商品集 ID、本地图片文件路径和过滤条件作为参数传入。该输入图片也存在于“resources/input/”中。
Python
python product_search.py get_similar_products_file "12000002" "D:/product/final/images-20180618T073733Z-001/images/469355b570ba11e88ff2d20059124800.jpg" "color=white"
响应
Search Image: D:/product/final/images-20180618T073733Z-001/images/469355b570ba11e88ff2d20059124800.jpg
Similar product information: Product id: p569d4e7a1 Product display name: Wedding Dress Product description: Elegant Wedding Dress for women Product category: apparel style: women category: dress color: white