This is the documentation for Recommendations AI, Retail Search, and the new Retail console.

Cataloghi e informazioni di catalogo

Questa pagina fornisce le best practice per creare le informazioni del catalogo e inserire i dati.

Panoramica

I dati di catalogo che importi in Retail hanno un effetto diretto sulla qualità del modello risultante, e quindi sulla qualità dei risultati forniti dall'API Retail. In generale, più le informazioni del catalogo sono più precise e specifiche che puoi fornire, maggiore è la qualità del modello.

Il catalogo deve essere aggiornato. Puoi caricare le modifiche al catalogo tutte le volte che è necessario; idealmente, ogni giorno per i cataloghi con un tasso di modifica elevato. Puoi caricare (patch) articoli di prodotto esistenti; verranno aggiornati solo i campi modificati. Non è previsto alcun costo per il caricamento delle informazioni del catalogo. Per scoprire di più, consulta Mantenere aggiornato il catalogo.

Filiali di catalogo

Se utilizzi Ricerca Google per la vendita al dettaglio, puoi utilizzare i rami di catalogo per testare i nuovi dati che hai caricato offline prima di pubblicarli sul tuo sito.

Con l'API Retail, puoi utilizzare fino a tre rami, identificati come 0, 1 e 2. Il sito pubblicato rimanda a default_branch per i dati di catalogo. Specifica quale ramo è attualmente il tuo default_branch attivo (per impostazione predefinita è impostato su ramo 0) utilizzando setDefaultBranch o la scheda Dati in Google Cloud Console. Il tuo sito utilizza quindi i dati di catalogo forniti dal ramo a cui default_branch indirizza.

Ad esempio, supponiamo che default_branch sia attualmente impostato sul ramo ID 0, quindi il tuo sito utilizzi i dati di catalogo che hai caricato nel ramo. Puoi caricare nuovi dati di catalogo per il ramo 1 e visualizzarli in anteprima. Dopo aver confermato che il catalogo è stato caricato correttamente, puoi passare al ramo 1 come pubblicato default_branch.

L'aggiornamento della cache del catalogo può richiedere fino a 30 minuti dopo il passaggio al ramo.

Se utilizzi Recommendations AI, ti consigliamo di utilizzare solo il ramo predefinito a causa del ritardo di aggiornamento durante il passaggio del ramo. Se la differenza tra i rami dei dati è maggiore, il ritardo dell'aggiornamento può influire negativamente sui risultati della previsione.

Prodotti

Il catalogo è una raccolta di oggetti prodotto.

Informazioni obbligatorie sul prodotto

I seguenti campi sono obbligatori: devi fornire i valori quando crei gli articoli del prodotto nel catalogo. Devono inoltre corrispondere ai valori utilizzati nel tuo database interno dei prodotti e rispecchiare accuratamente il prodotto rappresentato, perché sono inclusi nell'addestramento dei modelli.

In alcuni casi, sono necessari anche altri campi. Consulta l'elenco completo di tutti i campi del prodotto nella pagina di riferimento di Product.

Tutte le informazioni sui prodotti che fornisci possono essere utilizzate per migliorare la qualità dei consigli e dei risultati di ricerca. Assicurati di fornire il maggior numero possibile di campi.

Campo Note
name Il nome completo e univoco della risorsa del prodotto. Obbligatorio per tutti i metodi "Product" tranne import. Durante l'importazione, il nome viene generato automaticamente e non è necessario fornirlo manualmente.
id L'ID prodotto utilizzato dal database di prodotti. Il campo ID deve essere univoco in tutto il catalogo. Lo stesso valore viene utilizzato quando registri un evento utente e viene restituito anche dai metodi predict e search.
title Titolo del prodotto ricavato dal database dei prodotti. Una stringa con codifica UTF-8. Può contenere un massimo di 1250 caratteri.

Attributi prodotto

È vivamente consigliato fornire valori per gli attributi di sistema predefiniti in Product, ad esempio marca, colore e taglia. Puoi anche includere attributi personalizzati definiti da te con Product.attributes.

Se utilizzi la vendita al dettaglio, gli attributi vengono inclusi con un prodotto nella risposta di ricerca se li contrassegni come recuperabili in Product.retrievableFields. Possono quindi essere utilizzate per altre funzionalità della Ricerca al dettaglio, come filtri e facet.

Livelli di prodotto

Se importi il catalogo collegando il tuo account Merchant Center, puoi importare prodotti di ogni tipo. Se importi il catalogo per la prima volta da BigQuery o Cloud Storage, puoi specificare uno dei seguenti livelli di prodotto:

  • Gli elementi principali vengono restituiti nei risultati di ricerca o di previsione dall'API Retail. Possono essere singoli elementi (a livello di SKU) o gruppi di elementi simili (gruppi di SKU). Per impostazione predefinita, se il livello prodotto non è definito, l'API Retail utilizza il livello prodotto principale e importa prodotti di tutti i tipi.

  • Gli articoli varianti sono versioni di un prodotto principale. Le varianti possono essere soltanto singoli articoli (a livello di SKU). Ad esempio, se il prodotto principale è "Camicia con scollo a V", le varianti potrebbero essere "Camicia con scollo a V marrone, taglia XL" e "Camicia con scollo a V bianco", taglia S". I colori primari e le varianti a volte sono descritti come articoli "genitore" e "bambino".

Durante l'importazione del catalogo, imposta i livelli di prodotto utilizzando il metodo Catalog.patch. Ad esempio:

curl -X PATCH 
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)"
-H "Content-Type: application/json; charset=utf-8"
--data '{ "productLevelConfig": { "ingestionProductType": "PRODUCT-TYPE", "merchantCenterProductIdField": "PRODUCT-ID-FIELD" } }'
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

Per determinare le migliori scelte a livello di prodotto per l'implementazione, devi esaminare i dati del catalogo e la logica del sito web. Quali ID prodotto sono disponibili quando acquisisci i dati degli eventi utente? Quali ID prodotto potrebbero essere più efficaci da restituire con previsioni o risultati di ricerca? Qual è la relazione tra questi ID e i loro rapporti?

Utilizza i passaggi appropriati a seconda che tu stia importando da Merchant Center o meno:

Definire i livelli di prodotto per l'importazione da Merchant Center

Quando importi dati del catalogo da Merchant Center, l'API Retail utilizza ingestionProductType per identificare se caricarli come principali o varianti, nonché il campo merchantCenterProductIdField per specificare se utilizzare Merchant Center offer_id o item_group_id come ID prodotto.

Controlla i dati del tuo catalogo e la logica del tuo sito web per rispondere alle seguenti domande:

  • Nel mio catalogo sono disponibili sia varianti primarie che varianti?
  • In tal caso, a quale livello avrò a disposizione quando acquisire i dati degli eventi utente?
  • Che tipo di articoli devo restituire con i miei risultati?

Determina se:

  1. Il tuo catalogo ha un solo livello di articoli. Ciò può significare che:

    • Tutti i prodotti e gli eventi sono a livello di SKU e vuoi previsioni a livello di SKU.
    • Tutti i prodotti e gli eventi sono a livello di gruppo e vuoi delle previsioni a livello di gruppo.

    In questo caso, importa solo gli elementi principali. Questa è l'impostazione di importazione predefinita.

  2. Vuoi previsioni a livello di gruppo (principale), ma i tuoi prodotti Merchant Center sono a livello di SKU. In questo caso, la decisione di importazione dipende da come vengono acquisiti i tuoi eventi.

    1. I tuoi eventi vengono acquisiti a livello di gruppo. In questo caso, utilizza le seguenti impostazioni durante l'importazione:

      Se più prodotti Merchant Center hanno lo stesso Merchant Center item_group_id, Retail ne importa solo uno come prodotto principale e utilizza item_group_id come ID prodotto. In questo caso, non è possibile importare i prodotti che non dispongono di un elemento item_group_id. Gli eventi registrati devono fare riferimento all'ID prodotto principale (a livello di gruppo).

    2. I tuoi eventi vengono acquisiti a livello di SKU. In questo caso, utilizza le seguenti impostazioni durante l'importazione:

      Il negozio di vendita importa i tuoi prodotti come varianti e utilizza il Merchant Center offer_id come ID prodotto. Gli eventi registrati devono fare riferimento all'ID prodotto della variante (a livello di SKU).

Definire i livelli di prodotto per l'importazione senza Merchant Center

Tutti i tuoi prodotti devono avere un valore per primaryProductId oppure nessuno di essi può esserlo. Non puoi importare i dati di catalogo con primaryProductId impostato per alcuni articoli, ma non per altri.

  1. Se il catalogo ha un solo livello di articoli, ciò può significare che:

    • Tutti i prodotti e gli eventi sono a livello di SKU e vuoi risultati a livello di SKU.
    • Tutti i prodotti e gli eventi sono a livello di gruppo e vuoi risultati a livello di gruppo.

    In questo caso, importa solo gli elementi principali. Questa è l'impostazione di importazione predefinita, consigliata.

  2. Se gli eventi e i prodotti sono a livello di SKU, puoi ottenere risultati a livello di gruppo. Imposta ingestionProductType su variant durante l'importazione.

La previsione e la ricerca a livello di SKU non sono supportate se hai solo eventi e prodotti a livello di gruppo.

Se hai intenzione di importare i dati del catalogo da Merchant Center in futuro, rivedi i tuoi dati come descritto per le importazioni di Merchant Center per assicurarti di fare la scelta corretta. La modifica di questa configurazione può essere eseguita solo eliminando il catalogo e caricandolo nuovamente (vedi Modificare la configurazione a livello di prodotto).

Metriche relative alla qualità dei dati del catalogo

Per aiutarti a monitorare la qualità della ricerca dei tuoi dati di catalogo, Retail valuta i dati di prodotto in base a un insieme di regole di qualità. Puoi visualizzare la percentuale di prodotti che soddisfano ogni regola di qualità nella pagina Dati di vendita al dettaglio.

La tabella seguente descrive le metriche sulla qualità utilizzate da Retail per valutare i dati di prodotto:

Metrica qualità catalogo Regola qualità Note
URI presente e accessibile Il prodotto ha un elemento Product.uri valido. L'URI deve essere accessibile e corrispondere al dominio. Cloud Retail Search utilizza indicatori web sottoposti a scansione tramite questo URI per migliorare la qualità della ricerca.
Conforme alla conformità temporale Product.availableTime è precedente all'ora attuale e Product.expireTime è successiva all'ora attuale. Solo i prodotti che soddisfano gli standard di conformità temporali sono disponibili per la ricerca.
Presente un attributo disponibile per la ricerca Il prodotto ha almeno un elemento attribute impostato per la ricerca. Gli attributi personalizzati contrassegnati come disponibili per la ricerca possono essere cercati nelle query di testo.
La descrizione è presente Il prodotto non è vuoto Product.description. Una descrizione completa contribuisce a migliorare la qualità della ricerca.
Il titolo è costituito da almeno due parole Product.title è costituito da almeno due parole. Un titolo completo contribuisce a migliorare la qualità della ricerca.
Ha una variante con immagine Il prodotto variant abbia almeno un Product.image. Puoi ignorare questa metrica se tutti i tuoi prodotti sono a livello di primary. Questa metrica è solo a scopo informativo e non influisce sulla qualità della ricerca.
Ha una variante con informazioni sul prezzo Per il prodotto variant è stato impostato Product.priceInfo. Puoi ignorare questa metrica se tutti i tuoi prodotti sono a livello di primary. Questa metrica è solo a scopo informativo e non influisce sulla qualità della ricerca.

Schema di vendita al dettaglio

Quando importi un catalogo da BigQuery, utilizza lo schema Vendita al dettaglio riportato di seguito per creare una tabella BigQuery con il formato corretto e caricalo con i dati del catalogo. Poi, importa il catalogo.