Importa i dati di completamento automatico per la ricerca

Il completamento automatico è una funzionalità per prevedere il resto di una parola che un utente sta digitando, che può migliorare l'esperienza di ricerca dell'utente. Può fornire suggerimenti typeahead in base al set di dati fornito o agli eventi utente che hai fornito.

Valuta la possibilità di importare i dati del completamento automatico solo se vuoi avere controlli aggiuntivi (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. L'apprendimento automatico fornisce un set di suggerimenti basato sul machine learning e sugli eventi di ricerca dell'utente. Per informazioni su come attivare l'apprendimento automatico, vedi Completamento automatico.

Nota: da settembre 2022, puoi utilizzare Cloud Console > Controlli > la UI Controlli per il completamento automatico per attivare l'importazione dati.

Queste istruzioni servono solo per caricare i tuoi dati di completamento automatico. Mantienilo aggiornato se prevedi di utilizzare sempre il set di dati di completamento automatico. Per ottenere i risultati del 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 in Prima di iniziare, in particolare configurazione del progetto, creazione di un account di servizio e aggiunta dell'account di servizio all'ambiente locale.

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

Best practice per l'importazione con completamento automatico

Quando importi 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 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 di BigQuery per le liste bloccate, non rimuovere l'elenco e l'elenco dei termini dei suggerimenti. Per maggiori dettagli, consulta la sezione Completamento automatico.

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

Per ulteriori informazioni sulle tabelle BigQuery, consulta Introduzione alle tabelle. Per assistenza con le query di BigQuery, consulta Panoramica dell'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à multiregionale "US". Se non viene configurato correttamente, la richiesta di importazione non andrà a buon fine in un secondo momento. Per scoprire di più sulle posizioni dei set di dati BigQuery, consulta Località dei set di dati nella documentazione di BigQuery.

Inserisci i dati in BigQuery

Utilizza lo schema di completamento automatico di Vertex AI Search for Retail per caricare i dati di completamento automatico su BigQuery.

BigQuery può utilizzare lo schema per verificare 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 stringa mappato in un valore enum riconoscibile.
• Se un campo stringa utilizza il formato corretto.
• Se un campo intero o in virgola mobile contiene un valore in un intervallo valido.
• Se un campo mancante è un campo obbligatorio.

Per garantire la qualità dei tuoi dati e l'esperienza di ricerca dell'utente finale, assicurati di fare riferimento allo schema e alla 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 for Retail e completa i passaggi seguenti.

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 Nuove entità, inserisci [e-mail] e seleziona il ruolo BigQuery > Visualizzatore dati BigQuery.

   Se non vuoi fornire il ruolo Visualizzatore dati all'intero progetto, puoi aggiungerlo direttamente al set di dati. Ulteriori informazioni

5. Fai clic su Salva.

Attiva l'importazione dati in Vertex AI Search for 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 termini non consentiti, Elenco di 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 località dei dati oppure seleziona Sfoglia per selezionare la località.

   Il percorso BigQuery deve trovarsi nello stesso progetto e il suo schema deve essere corretto. Per verificarlo, fai clic su Sfoglia e poi sul nome della tabella per visualizzarne il contenuto 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 dall'importazione da Cloud Storage o BigQuery.

   Utilizza l'oggetto BigQuerySource per puntare al tuo set di dati BigQuery.

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

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

2. Importa le informazioni di completamento automatico in Vertex AI Search for Retail effettuando una richiesta POST al metodo REST CompletionData:import, fornendo il nome del file di dati (indicato come input.json nell'esempio di seguito).

   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 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 name con il valore restituito dal metodo di importazione. Al termine dell'importazione, il campo done restituisce 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 avrà un valore done pari a true e include un oggetto Status simile all'esempio seguente:

   {
     "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 tuo file JSON dovrebbe avere l'aspetto degli esempi riportati di seguito. Le interruzioni di riga consentono la leggibilità; devi fornire un suggerimento completo su un'unica riga. Ogni suggerimento deve essere su una riga separata.

Campi minimi obbligatori del suggerimento:

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

Oppure:

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

Durata importazione dati con completamento automatico

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

Al termine dell'importazione del set di dati, il campo done nell'oggetto dell'operazione viene contrassegnato come true. Dopodiché, potrebbero essere necessari altri 1-2 giorni prima che i dati vengano indicizzati e utilizzati 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 regolarmente aggiornato il set di dati caricato.

Aggiornamento batch

Puoi utilizzare il metodo di importazione per aggiornare in batch il completamento automatico. A tale scopo, procedi come con l'importazione iniziale; segui i passaggi descritti in Importare i dati di completamento automatico. L'intero set di dati importato verrà sostituito.

Monitora l'integrità dell'importazione

Mantenere aggiornato il tuo set di dati è importante per ottenere risultati di suggerimenti di alta qualità quando lo utilizzi. Monitora i tassi di errore dell'importazione e intervieni 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 Vertex AI Search for Retail 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 suggerimenti di completamento automatico con i tuoi punteggi.

Schema JSON dei suggerimenti di completamento automatico di Vertex AI Search for 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 a 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 lista consentita

Questo set di dati viene utilizzato per saltare i processi di post (come la correzione ortografica e il filtro con risultati pari a zero) per tutte le frasi in questa lista consentita.

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