Créer un ensemble de produits et rechercher des produits

Créer un ensemble de produits et rechercher des produits

Ce guide de démarrage rapide explique comment créer et utiliser les trois types de ressources associées à la recherche de produits de l'API Vision : un ensemble de produits contenant un groupe de produits, et des images de référence associées à ces produits.

Dans ce guide de démarrage rapide, vous allez créer un ensemble de produits, des produits et leurs images de référence en une seule étape via une importation par lot.

Une fois l'ensemble de produits indexé, il peut être interrogé grâce à la fonctionnalité de recherche de produits de l'API Vision.

Ce guide de démarrage rapide vous guide tout au long des processus suivants :

• Utiliser un fichier CSV et effectuer une importation par lot pour créer un ensemble de produits, des produits et des images de référence
• Envoyer une requête à la fonctionnalité de recherche de produits de l'API Vision avec une image stockée dans un bucket Cloud Storage

Avant de commencer

Si vous ne l'avez pas déjà fait, configurez votre projet comme expliqué ci-dessous.

Configurer votre projet

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: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: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.

Définir des variables d'environnement

Pour faciliter l'exécution des exemples curl dans ce guide de démarrage rapide, définissez les variables d'environnement suivantes où :

• PROJECT_ID est l'ID du projet Google Cloud.
• LOCATION_ID est l'emplacement Google Cloud qui exécutera votre tutoriel, par exemple, us-east1. Les indicateurs d'emplacement valides sont : us-west1, us-east1, europe-west1 et asia-east1.

Utiliser un ensemble de données

Dans ce guide de démarrage rapide, vous allez utiliser un ensemble de données constitué d'une centaine de produits de type apparel-v2. Cet ensemble de données accessible au public est situé dans un bucket Cloud Storage public :

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

Le format du fichier CSV est le suivant :

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

Remarque : Cet exemple de fichier CSV omet les colonnes facultatives product-display et bounding-poly. Pour en savoir plus sur les exigences du format CSV, consultez la section Mettre en forme un fichier CSV d'importation par lot.

Utiliser l'importation par lot pour créer un ensemble de produits, des produits et des images de référence

Exécutez la commande curl suivante pour créer un ensemble de produits avec des produits et des images de référence. Cet ensemble est nommé product_set0, une valeur déclarée dans le fichier CSV d'importation.

Créez d'abord un fichier JSON de requête appelé import_request.json et enregistrez-le dans votre répertoire de travail actuel :

import_request.json

{
  "inputConfig": {
    "gcsSource": {
      "csvFileUri": "gs://cloud-samples-data/vision/product_search/product_catalog.csv"
    }
  }
}

Après avoir créé le fichier JSON, envoyez la requête suivante :

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

Une réponse positive contient un objet "opération de longue durée", comme illustré ci-dessous :

{
  "name": "locations/LOCATION_ID/operations/0a0aec86192599fa"
}

La réponse contient également un ID d'opération relative (par exemple, 0a0aec86192599fa) que vous pouvez utiliser pour obtenir l'état de l'opération.

Obtenir l'état de l'opération d'importation

Vous pouvez utiliser l'identifiant operation-id renvoyé par l'opération d'importation pour vérifier l'état de l'opération d'importation groupée :

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

Voici un exemple de réponse réussie :

{
  "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": [
      {},
      {},
      [...]
      {},
      {}
    ]
  }
}

Indexation

L'index de recherche de produits est mis à jour toutes les 30 minutes environ. Lorsque des images sont ajoutées ou supprimées, la modification ne sera pas reflétée dans les réponses des recherches de produits avant la prochaine mise à jour de l'index.

Pour vous assurer que l'indexation s'est déroulée correctement, consultez le champ indexTime de l'ensemble de produits.

Répertorier les ensembles de produits et vérifier l'indexation

Vous pouvez répertorier tous vos ensembles de produits et utiliser le champ indexTime pour vérifier que l'indexation s'est déroulée correctement :

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

Une réponse réussie répertorie tous vos ensembles de produits, y compris les ID (par exemple, product_set0), ainsi que le champ indexTime indiquant la fin de l'indexation :

{
  "productSets": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/productSets/product_set0",
      "displayName": " ",
      "indexTime": "2019-11-30T18:33:40.093508652Z",
      "indexError": {}
    }
  ]
}

Répertorier les produits

Vous pouvez utiliser l'identifiant PRODUCT_SET_ID renvoyé avec la liste des ensembles de produits pour répertorier tous les produits de votre ensemble de produits :

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

Une réponse réussie répertorie les détails de chaque produit.

Dans cette requête, vous utilisez le paramètre de requête facultatif pageSize pour définir le nombre de résultats à afficher sur 15 produits. L'élément nextPageToken qui figure dans la réponse indique également qu'il y a davantage de produits à répertorier. Vous pouvez utiliser le jeton associé pour extraire d'autres résultats. Pour en savoir plus sur l'utilisation d'un pageToken, consultez la page Obtenir et lister des ressources.

{
  "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"
}

Rechercher des produits correspondants avec la recherche de produits de l'API Vision

Une fois l'indexation terminée, vous pouvez rechercher des produits qui correspondent à un exemple d'image. Dans ce guide de démarrage rapide, vous utilisez une image stockée dans un bucket Google Cloud Storage, telle que l'image suivante.

Remarque : Vous pouvez également effectuer une recherche à l'aide d'une image locale encodée en base64. Pour les exemples de code utilisant une image locale, consultez la page Rechercher des produits.

gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg

Rechercher sur la base d'une image distante

Utilisez la requête suivante pour effectuer une recherche à l'aide d'une image stockée dans un bucket Cloud Storage public.

Créez d'abord un fichier JSON de requête appelé search_request.json et enregistrez-le dans votre répertoire de travail actuel. Modifiez les valeurs suivantes dans la requête JSON pour qu'elles correspondent aux informations de votre projet :

• 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"
        }
      }
    }
  ]
}

Après avoir créé le fichier JSON, envoyez la requête suivante :

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

Une requête qui réussit renvoie une liste de produits correspondants, identifiés par leur ID de produit. S'il existe plusieurs produits dans une même image, ces résultats sont ensuite affinés produit par produit, chacun étant identifié par un cadre de délimitation.

Pour obtenir des exemples de détection d'un seul produit et de détection de plusieurs produits dans une image, consultez la section Comprendre les réponses des recherches et la multidétection.

Un champ score est également renvoyé. Il indique le niveau de confiance selon lequel le service estime que le produit correspond à l'image fournie, sur une échelle de 0 (faible probabilité de correspondance) à 1 (très forte probabilité de correspondance).

Le champ indexTime indique la version de l'index en cours de recherche. Les modifications apportées aux images après ce point ne sont pas reflétées dans les résultats.

Réponse

{
  "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
              }
            ]
          }
        ]
      }
    }
  ]
}

Félicitations ! Vous avez effectué votre première requête images.annotate auprès du service de recherche de produits de l'API Vision.

Effectuer un nettoyage

1. Optional: Revoke credentials from the gcloud CLI.

   gcloud auth revoke

2. Attention : La suppression d'un projet entraîne les effets décrits ci-dessous :

   • Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
   • Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

   Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

   Delete a Google Cloud project:

   gcloud projects delete PROJECT_ID

Étapes suivantes

• Débutez avec la recherche de produits de l'API Vision dans le langage de votre choix en utilisant une bibliothèque cliente pour la recherche de produits avec l'API Vision.
• Suivez les guides pratiques.
• Parcourez le tutoriel.