Importare i dati del completamento automatico per la ricerca

Il completamento automatico è una funzionalità che consente di prevedere la parte rimanente di una parola che l'utente sta digitando, in modo da migliorare la sua esperienza di ricerca. Può fornire suggerimenti di tipo avanzato in base al tuo set di dati fornito o in base agli eventi utente che hai fornito.

Valuta la possibilità di importare i dati di completamento automatico solo se vuoi avere controlli aggiuntivi (elenco Non rimuovere, elenco Contenuti bloccati) o se devi utilizzare i tuoi dati di completamento automatico. L'attivazione dell'apprendimento automatico è sufficiente per la maggior parte dei casi in cui è necessario il completamento automatico. L'apprendimento automatico fornisce un set di dati di suggerimenti basato sul machine learning in base agli eventi di ricerca degli utenti. Per scoprire come attivare l'apprendimento automatico, consulta Completamento automatico.

Nota: da settembre 2022, puoi utilizzare l'interfaccia utente Console Cloud > Controlli > Controlli di completamento automatico per attivare l'importazione dei dati.

Queste istruzioni riguardano solo il caricamento dei tuoi dati di completamento automatico. Mantieni aggiornato il set di dati per il completamento automatico se prevedi di utilizzarlo sempre. Per ottenere i risultati di completamento automatico al momento della query, consulta CompletionService.CompleteQuery. I dati del completamento automatico vengono utilizzati solo per la ricerca. Questi dati non vengono utilizzati dai consigli.

Prima di iniziare

Prima di poter importare le informazioni di completamento automatico, devi aver completato le istruzioni riportate in Prima di iniziare, in particolare configurare il progetto, creare un account di servizio e aggiungere l'account di servizio al tuo ambiente locale.

Per eseguire l'importazione, devi disporre del ruolo IAM Editor Retail.

Best practice per l'importazione con il completamento automatico

Quando importi i dati di completamento automatico, assicurati di implementare le seguenti best practice:

• Leggi lo schema BigQuery elencato nelle seguenti sezioni e nella documentazione dell'API.

• Non utilizzare valori segnaposto.

• Includi quanti più campi possibile.

• Mantieni aggiornato il tuo set di dati di completamento automatico se prevedi di utilizzare il tuo set di dati caricato.

• L'importazione dei dati da un altro progetto non è consentita.

Importare i dati di compilazione automatica

Importa i dati di completamento automatico da BigQuery

Vertex AI Search per la vendita al dettaglio supporta l'importazione dei dati di BigQuery per l'elenco di esclusione, l'elenco di esenzione dalla rimozione e l'elenco di termini di suggerimento. Scopri di più in Completamento automatico.

Per importare i dati di completamento automatico nel formato corretto da BigQuery, utilizza lo schema di completamento automatico di Vertex AI Search per la vendita al dettaglio per creare una tabella BigQuery con il formato corretto e caricare la tabella con i dati di completamento automatico. Poi, carica i tuoi dati in Vertex AI Search per il retail.

Per ulteriore assistenza sulle tabelle BigQuery, consulta Introduzione alle tabelle. Per assistenza con le query BigQuery, consulta Panoramica sull'esecuzione di query sui dati di BigQuery.

Posizione del set di dati BigQuery

Quando crei per la prima volta il set di dati BigQuery per le tabelle BigQuery con completamento automatico, assicurati che la località del set di dati sia impostata sulla località multiregione "US". Se non lo imposti correttamente, la richiesta di importazione non andrà a buon fine in un secondo momento. Per scoprire di più sulle località dei set di dati BigQuery, consulta Località dei set di dati nella documentazione di BigQuery.

Inserire i dati in BigQuery

Utilizza lo schema di completamento automatico di Vertex AI Search per la vendita al dettaglio per caricare i dati di completamento automatico in BigQuery.

BigQuery può utilizzare lo schema per convalidare se i dati in formato JSON hanno nomi e tipi di campo corretti (ad esempio STRING, INTEGER e RECORD), ma non può eseguire convalide come determinare:

• Se un campo di stringa è mappato in un valore enum riconoscibile.
• Se un campo di stringhe utilizza il formato corretto.
• Se un campo intero o con virgola mobile ha un valore in un intervallo valido.
• Se un campo mancante è obbligatorio.

Per garantire la qualità dei dati e l'esperienza di ricerca dell'utente finale, consulta lo schema e la documentazione di riferimento per informazioni dettagliate su valori e formato.

Configurare l'accesso al set di dati BigQuery

Per configurare l'accesso, assicurati che il set di dati BigQuery si trovi nello stesso progetto del servizio Vertex AI Search per la vendita al dettaglio e completa i seguenti passaggi.

1. Apri la pagina IAM nella console Google Cloud.

   Apri la pagina IAM

2. Seleziona il tuo progetto Vertex AI Search for Retail.

3. Nella pagina IAM e amministrazione, fai clic su  Concedi l'accesso.

4. Per Nuovi principali, inserisci [e-mail] e seleziona il ruolo BigQuery > Visualizzatore dati BigQuery.

   Se non vuoi assegnare il ruolo Visualizzatore dati all'intero progetto, puoi aggiungerlo direttamente al set di dati. Scopri di più.

5. Fai clic su Salva.

Attivare l'importazione dei dati in Vertex AI Search per il retail

Console

1. Vai alla pagina Controlli

2. Vai alla scheda Controlli completamento automatico.

3. Nella sezione Elenchi di termini, individua il tipo di elenco che intendi importare (Elenco di esclusione, Elenco di elementi da non rimuovere o Elenco di termini suggeriti) e fai clic su Importa o Sostituisci.

   Viene visualizzato il riquadro Importa.

4. Inserisci il percorso BigQuery della posizione dei dati o seleziona Sfoglia per selezionarla.

   Il percorso BigQuery deve trovarsi nello stesso progetto e il relativo schema deve essere corretto. Per verificare, fai clic su Sfoglia e poi sul nome della tabella per visualizzarne i contenuti nella console BigQuery.

5. Nel riquadro Importa, fai clic su Importa.

   Inizia l'importazione. Puoi uscire dalla pagina senza interrompere l'importazione.

cURL

1. Crea un file di dati per i parametri di input per l'importazione. I valori dei parametri di input dipendono dal fatto che l'importazione venga eseguita da Cloud Storage o BigQuery.

   Utilizza l'oggetto BigQuerySource per fare riferimento al set di dati BigQuery.

   • dataset-id: l'ID del set di dati BigQuery.
   • table-id: l'ID della tabella BigQuery che contiene i dati.
   • data-schema: per la proprietà dataSchema, utilizza il valore suggestions (predefinito), allowlist, denylist. Utilizza lo schema di completamento automatico di Vertex AI Search per il retail.

   {
     "inputConfig":{
       "bigQuerySource": {
         "datasetId":"dataset-id",
         "tableId":"table-id",
         "dataSchema":"data-schema"
       }
     }
   }

2. Importa le informazioni di completamento automatico in Vertex AI Search per il retail inviando una richiesta POST al metodo REST CompletionData:import, fornendo il nome del file di dati (visualizzato come input.json nell'esempio seguente).

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" -d @./input.json
   "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/completionData:import"

   Puoi controllare lo stato in modo programmatico utilizzando l'API. Dovresti ricevere un oggetto di risposta simile al seguente:

   {
     "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456",
     "done": false
   }

   Il campo name è l'ID dell'oggetto operazione. Per richiedere lo stato di questo oggetto, sostituisci il campo del nome con il valore restituito dal metodo di importazione. Al termine dell'importazione, il campo done viene restituito come true:

   curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456"

   Al termine dell'operazione, l'oggetto restituito ha un valore done di true e include un oggetto Status simile al seguente esempio:

   {
     "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportMetadata",
       "createTime": "2020-01-01T03:33:33.000001Z",
       "updateTime": "2020-01-01T03:34:33.000001Z",
       "successCount": "2",
       "failureCount": "1"
     },
     "done": true
     "response": {
       "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportCompletionDataResponse",
     }
   }

Formato dei dati del completamento automatico

Il file JSON deve avere il seguente aspetto. I ritorni a capo sono per la leggibilità; devi fornire un intero suggerimento su una singola riga. Ogni suggerimento deve essere inserito in una riga separata.

Suggerimento per i campi obbligatori minimi:

{
  "suggestion": "ABC",
  "globalScore": "0.5"
}

In alternativa:

{
  "suggestion": "ABC",
  "frequency": "100"
}

Durata dell'importazione dei dati di completamento automatico

In genere, il completamento di un'importazione da BigQuery richiede da alcuni minuti a un'ora.

Al termine dell'importazione del set di dati, il campo done nell'oggetto operation viene contrassegnato come true. Dopodiché potrebbero essere necessari altri 1-2 giorni per l'indicizzazione e l'utilizzo dei dati nella pubblicazione in produzione.

Mantenere aggiornato il set di dati del completamento automatico

Se prevedi di utilizzare il tuo set di dati caricato, è consigliabile mantenerlo aggiornato regolarmente.

Aggiornamento batch

Puoi utilizzare il metodo di importazione per aggiornare in blocco il completamento automatico. Procedi come per l'importazione iniziale; segui la procedura descritta in Importazione dei dati di completamento automatico. Verrà sostituito l'intero set di dati importato.

Monitorare lo stato di integrità dell'importazione

Mantenere aggiornato il tuo set di dati è importante per ottenere risultati di suggerimenti di alta qualità quando lo utilizzi. Devi monitorare le percentuali di errore di importazione e intervenire se necessario.

Schema di completamento automatico di Vertex AI Search per il retail

Quando importi il set di dati di completamento automatico da BigQuery, utilizza lo schema di Vertex AI Search per la vendita al dettaglio riportato di seguito per creare tabelle BigQuery con il formato corretto e caricarle con i dati di completamento automatico.

Schema per i suggerimenti

Questo set di dati viene utilizzato per fornire le tue frasi di suggerimento di completamento automatico con i tuoi punteggi.

Schema JSON dei suggerimenti di completamento automatico di Vertex AI Search per il retail

JSON

[
  {
    "description": "The suggestion text",
    "mode": "NULLABLE",
    "name": "suggestion",
    "type": "STRING"
  },
  {
    "description": "Global score of this suggestion. Control how this suggestion would be scored / ranked. Only one of this and frequency should be set.",
    "mode": "NULLABLE",
    "name": "globalScore",
    "type": "FLOAT"
  },
  {
    "description": "Frequency of this suggestion. Will be used to rank suggestions when score is not available.",
    "mode": "NULLABLE",
    "name": "frequency",
    "type": "INTEGER"
  },
  {
    "description": "BCP-47 language code of this suggestion.",
    "mode": "NULLABLE",
    "name": "languageCode",
    "type": "STRING"
  },
  {
    "description": "If two suggestions have the same groupID, they will not be returned together. Instead the one ranked higher will be returned. This can be used to deduplicate semantically identical suggestions.",
    "mode": "NULLABLE",
    "name": "groupID",
    "type": "STRING"
  },
  {
    "description": "The score of this suggestion within its group",
    "mode": "NULLABLE",
    "name": "groupScore",
    "type": "FLOAT"
  },
  {
    "description": "Device type for this suggestion.",
    "mode": "NULLABLE",
    "name": "deviceType",
    "type": "STRING"
  },
  {
    "description": "Alternative matching phrases for this suggestion.",
    "mode": "REPEATED",
    "name": "alternativePhrases",
    "type": "STRING"
  },
  {
    "fields": [
      {
        "description": "The name of the custom attribute.",
        "mode": "NULLABLE",
        "name": "key",
        "type": "STRING"
      },
      {
        "fields": [
          {
            "description": "The textual values of this custom attribute.",
            "mode": "REPEATED",
            "name": "text",
            "type": "STRING"
          },
          {
            "description": "The numerical values of this custom attribute.",
            "mode": "REPEATED",
            "name": "numbers",
            "type": "FLOAT"
          }
        ],
        "mode": "NULLABLE",
        "name": "value",
        "type": "RECORD"
      }
    ],
    "description": "A custom attribute that is not explicitly modeled, which can be retrieved together with the suggestion at serving time.",
    "mode": "REPEATED",
    "name": "customAttributes",
    "type": "RECORD"
  }
]

Schema per la lista bloccata

Questo set di dati viene utilizzato come lista vietata per impedire che le frasi vengano suggerite.

Schema JSON della lista di esclusione per l'autocompletamento di Vertex AI Search per il retail

JSON

[
  {
    "description": "The phrase to block from autocomplete suggestions.",
    "mode": "REQUIRED",
    "name": "phrase",
    "type": "STRING"
  },
  {
    "description": "The operator to apply for this phrase. Choose whether to block the exact phrase, or block any suggestions containing this phrase. Supported value \"EXACT_MATCH\", \"CONTAINS\"",
    "mode": "REQUIRED",
    "name": "operator",
    "type": "STRING"
  }
]

Schema per la lista consentita

Questo set di dati viene utilizzato per saltare le post-elaborazioni (ad es. la correzione ortografica e il filtro con zero risultati) per tutte le frasi in questa lista consentita.

Schema JSON della lista consentita per il completamento automatico di Vertex AI Search per il retail

JSON

[
  {
    "description": "The phrase to be exempted from autocomplete post processing, e.g. spell correction, filtering",
    "mode": "REQUIRED",
    "name": "phrase",
    "type": "STRING"
  },
  {
    "description": "The operator to apply for this phrase. Whether to match the exact phrase, or any suggestions contain this phrase. Supported values are \"EXACT_MATCH\", \"CONTAINS\".",
    "mode": "REQUIRED",
    "name": "operator",
    "type": "STRING"
  }
]