Creare un set di prodotti e cercare prodotti

Questa guida rapida illustra come creare e utilizzare i tre tipi di risorse Product Search dell'API Vision: un set di prodotti contenente un gruppo di prodotti e le immagini di riferimento associate ai prodotti.

In questa guida rapida, creerai un set di prodotti, i prodotti e le relative immagini di riferimento in un unico passaggio tramite importazione in batch.

Dopo che il set di prodotti è stato indicizzato, puoi eseguire una query sul set di prodotti utilizzando Product Search dell'API Vision.

Questa guida rapida illustra i seguenti passaggi:

  • Utilizzo di un file CSV e di un'importazione collettiva per creare un set di prodotti, prodotti e immagini di riferimento.
  • Richiesta a Product Search dell'API Vision con un'immagine archiviata in un bucket Cloud Storage.

Prima di iniziare

Se non lo hai già fatto, configura il progetto come spiegato di seguito.

Configura il progetto

  1. Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.
  2. Installa Google Cloud CLI.

  3. Per initialize gcloud CLI, esegui questo comando: 

    gcloud init

  4. Crea o seleziona un progetto Google Cloud.

    • Crea un progetto Google Cloud:

      gcloud projects create PROJECT_ID

      Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

    • Seleziona il progetto Google Cloud che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del tuo progetto Google Cloud.

  5. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

  6. Attiva Vision API. 

    gcloud services enable vision.googleapis.com

  7. Concedi i ruoli al tuo Account Google. Esegui questo comando una volta per ciascuno dei seguenti ruoli IAM: roles/storage.objectViewer 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS" --role=ROLE
    • Sostituisci PROJECT_ID con l'ID progetto.
    • Sostituisci EMAIL_ADDRESS con il tuo indirizzo email.
    • Sostituisci ROLE con ogni singolo ruolo.
    8.
  8. Installa Google Cloud CLI.

  9. Per initialize gcloud CLI, esegui questo comando: 

    gcloud init

  10. Crea o seleziona un progetto Google Cloud.

    • Crea un progetto Google Cloud:

      gcloud projects create PROJECT_ID

      Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

    • Seleziona il progetto Google Cloud che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del tuo progetto Google Cloud.

  11. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

  12. Attiva Vision API. 

    gcloud services enable vision.googleapis.com

  13. Concedi i ruoli al tuo Account Google. Esegui questo comando una volta per ciascuno dei seguenti ruoli IAM: roles/storage.objectViewer 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS" --role=ROLE
    • Sostituisci PROJECT_ID con l'ID progetto.
    • Sostituisci EMAIL_ADDRESS con il tuo indirizzo email.
    • Sostituisci ROLE con ogni singolo ruolo.
    14.

Imposta le variabili di ambiente

Per semplificare l'esecuzione degli esempi curl in questa guida rapida, imposta le seguenti variabili di ambiente dove:

  • PROJECT_ID è l'ID del tuo progetto Google Cloud.
  • LOCATION_ID è la località Google Cloud in cui verrà eseguito il tutorial, ad esempio us-east1. Gli identificatori di località validi sono: us-west1, us-east1, europe-west1 e asia-east1.

Utilizzo di un set di dati

In questa guida rapida utilizzerai un set di dati di circa 100 voci relative alle categorie di prodotto apparel-v2. Questo set di dati disponibile pubblicamente si trova in un bucket Cloud Storage pubblico all'indirizzo:

Il formato CSV è il seguente:

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

Utilizza l'importazione collettiva per creare un set di prodotti, i prodotti e le immagini di riferimento

Utilizza il comando curl seguente per creare un nuovo set di prodotti con prodotti e immagini di riferimento. Questo set è denominato product_set0, un valore dichiarato nel file CSV di importazione.

Innanzitutto, crea un file JSON di richiesta denominato import_request.json e salvalo nella directory di lavoro attuale:

import_request.json

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

Dopo aver creato il file JSON della richiesta, invia la richiesta:

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

Una risposta corretta contiene un oggetto operazione a lunga esecuzione:

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

La risposta contiene anche un ID operazione relativo (ad esempio 0a0aec86192599fa) che può essere utilizzato per ottenere lo stato dell'operazione.

Verifica lo stato dell'importazione

Puoi utilizzare il operation-id restituito dall'operazione di importazione per controllare lo stato dell'operazione di importazione collettiva:

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

Una risposta positiva ha il seguente aspetto:

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

Indicizzazione

L'indice dei prodotti di Shopping viene aggiornato ogni 30 minuti circa. Quando vengono aggiunte o eliminate immagini, la modifica non viene riportata nelle risposte di Product Search fino al successivo aggiornamento dell'indice.

Per assicurarti che l'indicizzazione sia stata completata correttamente, controlla il campo indexTime di un set di prodotti.

Elenca i set di prodotti e controlla l'indicizzazione

Puoi elencare tutti i set di prodotti e utilizzare il campo indexTime per verificare che l'indicizzazione sia stata completata correttamente:

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

Una risposta corretta elenca tutti i set di prodotti, inclusi un ID set di prodotti (ad esempio, product_set0) e il campo indexTime che indica quando l'indicizzazione è stata completata:

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

Elenca prodotti

Puoi utilizzare il PRODUCT_SET_ID restituito dall'elenco dei set di prodotti per elencare tutti i prodotti del set:

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

Una risposta riuscita elenca i dettagli del prodotto.

In questa richiesta, utilizzerai il parametro di query facoltativo pageSize per impostare l'elenco dei risultati su 15 prodotti. Il nextPageToken nella risposta indica anche che ci sono altri prodotti da elencare. Puoi utilizzare il token elencato per recuperare ulteriori risultati. Per ulteriori informazioni sull'utilizzo di un pageToken, consulta Creazione e elenco delle risorse.

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

Cerca prodotti corrispondenti con Product Search dell'API Vision

Una volta completata l'indicizzazione, puoi cercare i prodotti corrispondenti a un'immagine di esempio. In questa guida rapida utilizzerai un'immagine archiviata in un bucket Google Cloud Storage come nell'immagine seguente.

Un'immagine dress in un bucket Cloud Storage.
gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg

Cerca utilizzando un'immagine remota

Utilizza la seguente richiesta per eseguire una ricerca utilizzando l'immagine archiviata in un bucket Cloud Storage pubblico.

Innanzitutto crea un file JSON di richiesta denominato search_request.json e salvalo nella directory di lavoro attuale. Modifica i seguenti valori nel JSON della richiesta in modo che corrispondano alle informazioni del progetto:

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

Dopo aver creato il file JSON della richiesta, invia la richiesta:

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

Una richiesta corretta restituisce un elenco di prodotti corrispondenti, con il relativo ID prodotto. Questi risultati sono ulteriormente suddivisi in base ai singoli prodotti identificati da riquadri di delimitazione, se in una singola immagine sono presenti più prodotti.

Per un esempio di rilevamento di un singolo prodotto e di rilevamento multiplo dei prodotti in un'immagine, consulta Informazioni sulle risposte alla ricerca e sul rilevamento multiplo.

Viene restituito anche un campo score. Questo campo indica l'affidabilità con cui il servizio ritiene che il prodotto corrisponda all'immagine fornita, su una scala da 0 (nessuna confidenza) a 1 (affidabilità totale).

Il campo indexTime mostra in quale versione dell'indice viene eseguita la ricerca. Le modifiche apportate alle immagini dopo questa data non si riflettono nei risultati.

Complimenti! Hai inviato la tua prima richiesta images.annotate al servizio Product Search dell'API Vision.

Esegui la pulizia

  1. Facoltativo: revoca le credenziali dallgcloud CLI. 

    gcloud auth revoke

  2. Elimina un progetto Google Cloud:

    gcloud projects delete PROJECT_ID

Passaggi successivi