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. Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.
  2. Installez Google Cloud CLI.

  3. Pour initialiser gcloudCLI, exécutez la commande suivante : 

    gcloud init

  4. Créez ou sélectionnez un projet Google Cloud.

    • Créez un projet Google Cloud :

      gcloud projects create PROJECT_ID

      Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.

    • Sélectionnez le projet Google Cloud que vous avez créé :

      gcloud config set project PROJECT_ID

      Remplacez PROJECT_ID par le nom de votre projet Google Cloud.

  5. Vérifiez que la facturation est activée pour votre projet Google Cloud.

  6. Activer Vision API : 

    gcloud services enable vision.googleapis.com

  7. Attribuez des rôles à votre compte Google. Exécutez la commande suivante une fois pour chacun des rôles IAM suivants : roles/storage.objectViewer 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS" --role=ROLE
    • en remplaçant PROJECT_ID par l'ID de votre projet :
    • Remplacez EMAIL_ADDRESS par votre adresse e-mail.
    • Remplacez ROLE par chaque rôle individuel.
    8.
  8. Installez Google Cloud CLI.

  9. Pour initialiser gcloudCLI, exécutez la commande suivante : 

    gcloud init

  10. Créez ou sélectionnez un projet Google Cloud.

    • Créez un projet Google Cloud :

      gcloud projects create PROJECT_ID

      Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.

    • Sélectionnez le projet Google Cloud que vous avez créé :

      gcloud config set project PROJECT_ID

      Remplacez PROJECT_ID par le nom de votre projet Google Cloud.

  11. Vérifiez que la facturation est activée pour votre projet Google Cloud.

  12. Activer Vision API : 

    gcloud services enable vision.googleapis.com

  13. Attribuez des rôles à votre compte Google. Exécutez la commande suivante une fois pour chacun des rôles IAM suivants : roles/storage.objectViewer 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS" --role=ROLE
    • en remplaçant PROJECT_ID par l'ID de votre projet :
    • Remplacez EMAIL_ADDRESS par votre adresse e-mail.
    • Remplacez ROLE par chaque rôle individuel.
    14.

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 :

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

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

Indexer des images

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.

Image d'une robe dans un bucket Cloud Storage
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.

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. Facultatif : Révoquez les identifiants de la CLI gcloud. 

    gcloud auth revoke

  2. Supprimez un projet Google Cloud :

    gcloud projects delete PROJECT_ID

Étapes suivantes