Vertex AI Search per il retail verrà rinominato in Vertex AI Search per il commercio. Stiamo aggiornando i contenuti in base al nuovo branding.

Questa pagina è stata tradotta dall'API Cloud Translation.

Importare i dati del completamento automatico per la ricerca

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

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

Queste istruzioni riguardano solo il caricamento dei tuoi dati di completamento automatico. Mantienilo aggiornato se prevedi di utilizzare sempre il set di dati del completamento automatico. Per ottenere 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 la configurazione del progetto, la creazione di un service account e l'aggiunta del account di servizio all'ambiente locale.

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

Best practice per l'importazione del 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 set di dati caricato.
L'importazione dei dati da un altro progetto non è consentita.

Importare i dati di completamento automatico

Importare i dati del completamento automatico da BigQuery

Vertex AI Search for commerce supporta l'importazione dei dati BigQuery per l'elenco di negazione, l'elenco da non rimuovere e l'elenco dei termini suggeriti. Per maggiori dettagli, vedi 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 il commercio 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 for Commerce.

Per ulteriore assistenza con le 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 di completamento automatico, assicurati che la località del set di dati sia impostata sulla località multiregionale "US". Se non lo imposti correttamente, la tua 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.

Inserimento dei dati in BigQuery

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

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

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

Per garantire la qualità dei tuoi 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 for commerce e completa i seguenti passaggi.

Apri la pagina IAM nella console Google Cloud .

Apri la pagina IAM
Seleziona il progetto Vertex AI Search for Commerce.
Nella pagina IAM e amministrazione, fai clic su Concedi l'accesso.
Per Nuovi principal, inserisci cloud-retail-customer-data-access@system.gserviceaccount.com 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ù.
Fai clic su Salva.

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

Console

Vai alla pagina Controlli
Vai alla scheda Controlli del completamento automatico.
Nella sezione Elenchi di termini, individua il tipo di elenco che intendi importare (Elenco di termini vietati, Elenco di termini da non rimuovere o Elenco di termini suggeriti) e fai clic su Importa o Sostituisci.

Si apre il riquadro Importa.
Inserisci il percorso BigQuery della posizione dei dati o seleziona Sfoglia per selezionare la posizione.

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

L'importazione inizia. Puoi uscire dalla pagina senza interrompere l'importazione.

cURL

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 indirizzare il tuo set di dati BigQuery.
- dataset-id: l'ID del set di dati BigQuery.
- table-id: l'ID della tabella BigQuery che contiene 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 Commerce.
```
{
  "inputConfig":{
    "bigQuerySource": {
      "datasetId":"dataset-id",
      "tableId":"table-id",
      "dataSchema":"data-schema"
    }
  }
}
```

Importa le informazioni sul completamento automatico in Vertex AI Search per il commercio effettuando 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 nome è 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 Stato 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 dovrebbe essere simile agli esempi seguenti. Le interruzioni di riga servono per la leggibilità; devi fornire un intero suggerimento su una singola riga. Ogni suggerimento deve essere su una riga separata.

Campi minimi obbligatori per il suggerimento:

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

Oppure:

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

Durata dell'importazione dei dati di completamento automatico

In genere, l'importazione da BigQuery richiede da pochi minuti a un'ora.

Al termine dell'importazione del set di dati, il campo done nell'oggetto 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.

Mantenere aggiornato il set di dati di 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 batch il completamento automatico. Per farlo, segui la stessa procedura dell'importazione iniziale; segui i passaggi descritti in Importazione dei dati di completamento automatico. Verrà sostituito l'intero set di dati importato.

Monitorare l'integrità dell'importazione

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

Schema di completamento automatico di Vertex AI Search per il commercio

Quando importi il set di dati di completamento automatico da BigQuery, utilizza lo schema di Vertex AI Search per il commercio 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 l'e-commerce

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 che le frasi vengano suggerite.

Schema JSON della denylist del completamento automatico di Vertex AI Search per l'e-commerce

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 ignorare le post-elaborazioni (come il controllo ortografico e il filtro dei risultati zero) per tutte le frasi in questa lista consentita.

Schema JSON della lista consentita del completamento automatico di Vertex AI Search per l'e-commerce

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

Importare i dati del completamento automatico per la ricerca Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Best practice per l'importazione del completamento automatico

Importare i dati di completamento automatico

Importare i dati del completamento automatico da BigQuery

Posizione del set di dati BigQuery

Inserimento dei dati in BigQuery

Configurare l'accesso al set di dati BigQuery

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

Console

cURL

Formato dei dati di completamento automatico

Durata dell'importazione dei dati di completamento automatico

Mantenere aggiornato il set di dati di completamento automatico

Aggiornamento batch

Monitorare l'integrità dell'importazione

Schema di completamento automatico di Vertex AI Search per il commercio

Schema per i suggerimenti

Schema JSON dei suggerimenti di completamento automatico di Vertex AI Search per l'e-commerce

JSON

Schema per la lista bloccata

Schema JSON della denylist del completamento automatico di Vertex AI Search per l'e-commerce

JSON

Schema per la lista consentita

Schema JSON della lista consentita del completamento automatico di Vertex AI Search per l'e-commerce

JSON

Importare i dati del completamento automatico per la ricerca