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 qui contient 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 en effectuant une importation par lot.

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

Ce guide de démarrage rapide va vous aider 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 sans frais pour exécuter, tester et déployer des charges de travail.

  2. Installez la Google Cloud CLI.

  3. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  4. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

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

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
    • Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

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

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

  7. Activez l'API Vision :

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles. 

    gcloud services enable vision.googleapis.com

  8. Attribuez des rôles à votre compte utilisateur. 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:USER_IDENTIFIER" --role=ROLE

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet
    • USER_IDENTIFIER : identifiant de votre compte d'utilisateur. Par exemple, myemail@example.com.
    • ROLE : rôle IAM que vous accordez à votre compte utilisateur.

  9. Installez la Google Cloud CLI.

  10. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  11. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

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

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
    • Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

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

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

  14. Activez l'API Vision :

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles. 

    gcloud services enable vision.googleapis.com

  15. Attribuez des rôles à votre compte utilisateur. 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:USER_IDENTIFIER" --role=ROLE

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet
    • USER_IDENTIFIER : identifiant de votre compte d'utilisateur. Par exemple, myemail@example.com.
    • ROLE : rôle IAM que vous accordez à votre compte utilisateur.
    16.

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

Remplacez les éléments suivants :

  • LOCATION_ID : emplacement où exécuter votre tutoriel (par exemple, us-east1). Les indicateurs d'emplacement valides sont : us-west1, us-east1, europe-west1 et asia-east1.

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 environ une fois par jour. 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.

Recenser les ensembles de produits et vérifier l'indexation

Vous pouvez recenser 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 recense 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": {}
    }
  ]
}

Recenser les produits

Vous pouvez utiliser l'identifiant PRODUCT_SET_ID renvoyé avec la liste des ensembles de produits pour recenser 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 liste 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 Obtenir et répertorier 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 allez utiliser 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 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. Supprimer un projet Google Cloud  :

    gcloud projects delete PROJECT_ID

Étapes suivantes