Importare i dati del completamento automatico per la ricerca

Il completamento automatico è una funzionalità per prevedere il resto di una parola che l'utente sta digitando, che possono migliorare l'esperienza di ricerca degli utenti. Può fornire typeahead suggerimento basato sul set di dati fornito o sugli eventi utente che hai fornito.

Valuta la possibilità di importare i dati del completamento automatico solo se vuoi avere ulteriori (Non rimuovere, Elenco valori non consentiti) o se devi utilizzare i tuoi dati di completamento automatico. L'attivazione dell'apprendimento automatico è sufficiente nella maggior parte dei casi in cui è necessario il completamento automatico. L'apprendimento automatico offre una macchina set di dati di suggerimenti basato sull'apprendimento basato sugli eventi di ricerca dell'utente. Consulta: Completamento automatico per scoprire come attivare l'apprendimento 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 del completamento automatico al momento della query, consulta su 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 nella sezione Prima di iniziare, nello specifico configurare il progetto, creando un account di servizio e aggiungendo l'account di servizio all'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 di seguito sezioni e documentazione dell'API.

• Non utilizzare valori segnaposto.

• Includi il maggior numero possibile di campi.

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

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

Importa dati di completamento automatico

Importa i dati di completamento automatico da BigQuery

Vertex AI Search for Retail supporta l'importazione dati BigQuery per l'opzione Rifiuta Elenco, Non rimuovere l'elenco e 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 ulteriori informazioni 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 verificare se la formattazione JSON abbiano nomi e tipi di campo corretti (come STRING, INTEGER e RECORD), ma non può eseguire convalide come determinare:

• Se un campo 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.

   Aperto 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 fornire il ruolo Visualizzatore dati all'intero puoi aggiungere questo ruolo 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 per il 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 oppure seleziona Sfoglia per selezionare la località.

   Il percorso BigQuery deve trovarsi nello stesso progetto e il relativo schema deve essere corretto. Per verificarlo, fai clic su Sfoglia e seleziona 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. Il tuo i valori dei parametri di input dipendono dal fatto che tu stia importando dati 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 (mostrato 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. A per richiedere lo stato di questo oggetto, sostituisci il campo name con 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 di completamento automatico

Il file JSON deve avere l'aspetto dei seguenti esempi. I ritorni a capo sono per la leggibilità; devi fornire un intero suggerimento su una singola riga. Ogni suggerimento deve essere su riga separata.

Campi obbligatori minimi suggeriti:

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

Oppure:

{
  "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 è contrassegnato come true. Dopodiché potrebbero essere necessari altri 1-2 giorni per l'indicizzazione e l'utilizzo dei dati nella pubblicazione in produzione.

Mantieni aggiornato il set di dati di completamento automatico

Se prevedi di utilizzare il tuo set di dati caricato, ti consigliamo di mantenere i set di dati caricati con cadenza regolare.

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.

Monitora l'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 for Retail

Quando importi il set di dati di completamento automatico da BigQuery, utilizza lo schema di ricerca di Vertex AI 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 bloccata per impedire il suggerimento di frasi.

JSON dello schema della lista bloccata di completamento automatico di Vertex AI Search for 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"
  }
]