En este instructivo, se explica cómo crear un conjunto de productos que contenga un grupo de productos con imágenes de referencia. Aquí se muestra a los usuarios cómo crear un conjunto de productos mediante la importación en línea (individual). Después de indexar el conjunto de productos, puedes consultarlo con la API de Cloud Vision Product Search.
En este instructivo aprenderás a realizar las siguientes tareas:
- Crear un conjunto de productos a través de la importación en línea (individual)
- Crear un producto individual
- Agregar un producto a un conjunto de productos
- Actualiza un producto
- Crear una imagen de referencia
- Buscar productos similares
Antes de comenzar
Antes de comenzar este instructivo, asegúrate de que tienes instaladas las bibliotecas cliente correspondientes, de que habilitaste la facturación y la API para tu proyecto y de que configuraste la autenticación de forma adecuada.
Importa las bibliotecas
Para usar Product Search de la API de Vision, importa los siguientes módulos después de descargar y, luego, instala la biblioteca cliente:
Comienza a usarlo
Java
Node.js
Python
Ejecuta la aplicación
Paso 1: Crea un catálogo de productos
Los usuarios tienen dos formas de crear un catálogo de productos, ya sea mediante una importación por lotes con un archivo CSV, el cual permite que se importe un catálogo en una sola llamada a la API, o a través de una importación en línea, que te ofrece control sobre tus conjuntos de productos y te permite administrar un recurso o relación a la vez. Esto significa, principalmente, la creación individual de conjuntos de productos, imágenes de referencia y productos en sí. La importación en línea también te permite actualizar de manera gradual un catálogo de productos que ya hayas creado a través de la importación en lotes.
En este instructivo usarás la importación en línea. Consulta la Guía de inicio rápido para ver un ejemplo de cómo importar por lotes con un CSV.
Importación en línea (individual)
1. Crea un conjunto de productos
Crea un conjunto de productos vacío que sea un contenedor simple para un grupo de productos.
Solicitud
Crea un conjunto de productos vacío y llámalo “PS_CLOTH-SHOE_070318”. Para ello, ejecuta la siguiente solicitud con el método create_product_set()
.
Pasa el nombre visible y el ID del conjunto de productos como argumentos.
LÍNEA DE CMD Y REST
Antes de usar cualquiera de los siguientes datos de solicitud, realiza estos reemplazos:
- project-id: El ID de tu proyecto de GCP
- location-id: Un identificador de ubicación válido. Los identificadores de ubicación válidos son:
us-west1
,us-east1
,europe-west1
yasia-east1
- display-name: El nombre visible de la string que elijas
Método HTTP y URL:
POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets
Cuerpo JSON de la solicitud:
{ "displayName": "display-name" }
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets
PowerShell
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
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
Si la solicitud se realiza de forma correcta, el servidor muestra un código de estado HTTP 200 OK
y la respuesta en formato JSON.
Deberías ver un resultado similar al siguiente. Puede usar el ID del conjunto de productos (b6d809615b6dd675
, en este caso) para realizar otras operaciones en el conjunto.
{ "name": "projects/project-id/locations/location-id/productSets/b6d809615b6dd675", "displayName": "new-product-set" }
Comienza a usarlo
Java
Node.js
Python
Respuesta
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. Crea un producto
Una vez que se creó un conjunto de productos, el paso siguiente es crear un producto. Ejecuta la siguiente solicitud para crear un producto.
LÍNEA DE CMD Y REST
Antes de usar cualquiera de los siguientes datos de solicitud, realiza estos reemplazos:
- project-id: El ID de tu proyecto de GCP
- location-id: Un identificador de ubicación válido. Los identificadores de ubicación válidos son:
us-west1
,us-east1
,europe-west1
yasia-east1
- display-name: El nombre visible de la string que elijas
- product-description: Una descripción de string que elijas
- product-category: Una categoría de producto válida. Por el momento, están disponibles las siguientes categorías de producto:
homegoods-v2
,apparel-v2
,toys-v2
,packagedgoods-v1
ygeneral-v1
productLabels
: Uno o más pares clave-valor asociados con un producto. Cada key-string debe tener un value-string asociado
Método HTTP y URL:
POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products
Cuerpo JSON de la solicitud:
{ "displayName": "display-name", "description": "product-description", "productCategory": "product-category", "productLabels": [ { "key": "key-string", "value": "value-string" } ] }
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products
PowerShell
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
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
Ejemplo de cuerpo de la solicitud:
{ "displayName": "sample-product-1234", "description": "Athletic shorts", "productCategory": "apparel-v2", "productLabels": [ { "key": "style", "value": "womens" }, { "key": "color", "value": "blue" } ] }
Si la solicitud se realiza de forma correcta, el servidor muestra un código de estado HTTP 200 OK
y la respuesta en formato JSON.
Deberías ver un resultado similar al siguiente. Puedes usar el ID del producto (37b9811d308c4e42
, en este caso) para realizar otras operaciones en el producto.
{ "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" } ] }
Comienza a usarlo
Java
Node.js
Python
Respuesta
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. Agrega un producto a un conjunto de productos
Después de crear un producto y un conjunto de productos, puedes agregar el producto al conjunto.
LÍNEA DE CMD Y REST
Antes de usar cualquiera de los siguientes datos de solicitud, realiza estos reemplazos:
- project-id: El ID de tu proyecto de GCP
- location-id: Un identificador de ubicación válido. Los identificadores de ubicación válidos son:
us-west1
,us-east1
,europe-west1
yasia-east1
. - product-set-id: Es el ID del conjunto de productos en el que deseas ejecutar la operación.
- product-name: Es el nombre completo del recurso del producto.
Formato:
projects/project-id/locations/location-id/products/product-id
Método HTTP y URL:
POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets/product-set-id:addProduct
Cuerpo JSON de la solicitud:
{ "product": "product-name" }
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-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
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
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
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
{}
Comienza a usarlo
Java
Node.js
Python
Respuesta
Product added to product set.
4. Actualiza un producto
Si necesitas actualizar un producto o un conjunto de ellos después de haberlo creado, puedes usar nuestros métodos de actualización. En este ejemplo se muestra una actualización del producto donde se cambian las etiquetas:
Línea de comandos
Para actualizar un producto, envía una solicitudPATCH
al siguiente URI.- Reemplaza project-id por el ID del proyecto de Google Cloud.
- Reemplaza location-id por un identificador de ubicación válido. Los identificadores de ubicación válidos son:
us-west1
,us-east1
,europe-west1
yasia-east1
. - Reemplaza product-id por el ID del producto que deseas actualizar.
curl -X PATCH \ -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/products/product-id -d "{ 'updateMask': { 'paths': ['display_name'] }, 'product': { 'display_name': 'new-display-name' } }"
Comienza a usarlo
Java
Node.js
Python
Respuesta
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. Crea una imagen de referencia de un producto
Crear una imagen de referencia para un producto individual le permite a la API de Vision Product Search buscar el producto a partir de esta imagen una vez que se haya indexado. Puedes tener varias imágenes de referencia en un producto, en especial si deseas una mejor calidad de coincidencia.
Puedes agregar imágenes de referencia nuevas a un producto en cualquier momento.
Cuando creas una imagen de referencia tienes la opción de incluir coordenadas límite poligonales. Un polígono de límite identifica un área de interés en la imagen de referencia. Por ejemplo, si creas una imagen de referencia de un producto que es una chaqueta, puedes proporcionar las coordenadas para la chaqueta en un argumento de polígono de límite y el sistema solo considerará la chaqueta cuando busque coincidencias de producto. Nota: En el momento de la indexación puedes proporcionar varios polígonos de límite, sin embargo, en el momento de la consulta la API admite solo uno.
Una forma conveniente de obtener las coordenadas límite poligonales para una imagen es usar la localización de objetos de la API de Vision. Para obtener más información sobre la localización de objetos, consulta Detecta varios objetos.
LÍNEA DE CMD Y REST
Antes de usar cualquiera de los siguientes datos de solicitud, realiza estos reemplazos:
- project-id: El ID de tu proyecto de GCP
- location-id: Un identificador de ubicación válido. Los identificadores de ubicación válidos son los siguientes:
us-west1
,us-east1
,europe-west1
yasia-east1
- product-id: El ID del producto asociado con una imagen de referencia. Este ID se establece de forma aleatoria, o el usuario lo especifica cuando crea el producto
- cloud-storage-image-uri: La ruta a un archivo de imagen válido en un depósito de Cloud Storage. Como mínimo, debes tener privilegios de lectura en el archivo.
Ejemplo:
gs://storage-bucket/filename.jpg
Método HTTP y URL:
POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id/referenceImages
Cuerpo JSON de la solicitud:
{ "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 } ] } ] }
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-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
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
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
Si la solicitud se realiza de forma correcta, el servidor muestra un código de estado HTTP 200 OK
y la respuesta en formato JSON.
Deberías ver un resultado similar al siguiente. La solicitud de ejemplo especificó un solo boundingPoly
en la imagen. Los vértices del cuadro de límite no se normalizan. Los valores de los vértices son los valores reales de los píxeles y no son relativos a la imagen original ni van del 0 al 1. Estos vértices tienen los siguientes valores: [(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 } ] } ] }
Comienza a usarlo
Java
Node.js
Python
Respuesta
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 }
Paso 2: Busca productos que coincidan
Esta interfaz te permite consultar el catálogo de productos que creaste cuando tomas una imagen nueva como entrada y buscas el mejor producto que coincide.
Como en la creación de imágenes de referencia, cuando buscas imágenes que coinciden tienes la opción de incluir coordenadas límite poligonales. Un polígono de límite identifica un área de interés en la imagen de origen para la que deseas encontrar coincidencias. Por ejemplo, si tu imagen de origen contiene un vestido y un bolso y solo quieres encontrar coincidencias del vestido, puedes identificar las coordenadas límite poligonales para la región de la imagen que contiene el vestido. De forma predeterminada, si no se especifica ningún polígono de límite, la API determina el polígono de límite más grande y lo consulta de manera automática.
Una forma conveniente de obtener las coordenadas límite poligonales para una imagen es usar la localización de objetos de la API de Vision. Para obtener más información sobre la localización de objetos, consulta Detecta varios objetos. Por ejemplo, puedes hacer una consulta explícita a una imagen completa si especificas un polígono de límite del cuadro de la imagen: [(0, 0), (0, 1), (1, 1), (1, 0)].
La solicitud muestra una respuesta de API que incluye el mejor producto que coincide para una imagen con la puntuación y la imagen. Esta imagen se muestra con el valor de confianza más alto.
LÍNEA DE CMD Y REST
Antes de usar cualquiera de los siguientes datos de solicitud, realiza estos reemplazos:
- base64-encoded-image: Es la representación en base64 (string ASCII) de los datos de la imagen binaria. Esta string debería ser similar a la siguiente:
/9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==
- project-id: Es el ID de tu proyecto de GCP.
- location-id: Un identificador de ubicación válido. Los identificadores de ubicación válidos son:
us-west1
,us-east1
,europe-west1
yasia-east1
. - product-set-id: Es el ID del conjunto de productos en el que deseas ejecutar la operación.
Consideraciones específicas del campo:
features.maxResults
: Es la cantidad máxima de resultados que se mostrarán.imageContext.productCategories
: Es la categoría de producto en la que se debe buscar. Por el momento, solo puedes especificar una categoría de producto (artículos para el hogar, indumentaria, juguetes, productos envasados y artículos en general).imageContext.filter
: Es una expresión de filtrado de clave-valor (o varias expresiones) para la etiqueta del producto. Formato: “key
=value
”. Los pares clave-valor de filtrado se pueden vincular con expresiones OR o AND: “color
=blue
ANDstyle
=mens
” o “color
=blue
ORcolor
=black
”. Si se usa la expresión OR, todas las claves de la expresión deben ser iguales.
Método HTTP y URL:
POST https://vision.googleapis.com/v1/images:annotate
Cuerpo JSON de la solicitud:
{ "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" } } } ] }
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://vision.googleapis.com/v1/images:annotate
PowerShell
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
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
Si la solicitud se completa de forma correcta, el servidor muestra un código de estado HTTP 200 OK
y la respuesta en formato JSON.
El JSON de respuesta incluye los siguientes dos tipos de resultados:
productSearchResults
: Contiene una lista de productos coincidentes para toda la imagen. En la respuesta de muestra, los productos que coinciden son estos: product_id65, product_id35, product_id34, product_id62 y product_id32.productGroupedResults
: Contiene coordenadas de cuadro de límite y elementos coincidentes para cada producto identificado en la imagen. En la siguiente respuesta, solo se identificó un producto, seguido de productos coincidentes en el conjunto de productos de muestra: product_id65, product_id35, product_id34, product_id93 y product_id62.
Ten en cuenta que, si bien hay una superposición en los dos tipos de resultados, también puede haber diferencias (por ejemplo, product_id32 y product_id93 en la respuesta).
Comienza a usarlo
Java
Node.js
Python
Ejemplo de respuesta de vestimenta
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
Busca con etiquetas
El siguiente ejemplo de búsqueda incluye un filtro por color.
Solicitud
Realiza una solicitud de búsqueda mediante la ejecución de la siguiente solicitud con el método get_similar_products_file()
o get_similar_products_uri()
. El ID del conjunto de productos, la ruta de acceso del archivo de imagen local y el filtro se pasan como argumentos. Esta imagen de entrada también se encuentra en “resources/input/”.
Python
python product_search.py get_similar_products_file "12000002" "D:/product/final/images-20180618T073733Z-001/images/469355b570ba11e88ff2d20059124800.jpg" "color=white"
Respuesta
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