Filtrare i consigli

Questa pagina descrive il filtro dei risultati per i consigli utilizzando gli attributi dei prodotti.

Puoi filtrare i risultati di previsione specificando un'espressione di filtro nelle richieste di previsione. L'espressione di filtro è un'espressione logica che viene valutata per ciascun prodotto. L'elenco di prodotti nella risposta viene limitato ai prodotti per i quali l'espressione restituisce true.

Esistono due versioni di filtri per i consigli:

• Si consiglia la versione 2.
• La versione 1 è deprecata, ma potrebbe essere ancora in uso.

Le sezioni di questa guida pratica si applicano solo alla versione 2 dei filtri, che filtra i consigli utilizzando gli attributi dei prodotti.

Filtro dei consigli, versione 2

La versione 2 utilizza gli attributi dei prodotti. Le espressioni di filtro si basano sugli attributi del prodotto. Possono essere attributi di sistema predefiniti, come categories e colors, o attributi personalizzati che definisci, come attributes.styles. Quando imposti un attributo del prodotto come filtrabile, i consigli possono utilizzare automaticamente questi attributi come tag per il filtro dei consigli, anziché richiedere l'aggiunta manuale dei tag di filtro.

Quando utilizzi gli attributi per filtrare i prodotti, la risposta della previsione restituisce i prodotti principali che contengono almeno un prodotto principale o una variante con un valore dell'attributo corrispondente all'espressione del filtro. Per saperne di più sui prodotti principali e sulle varianti, consulta Livelli di prodotto.

Il seguente esempio di espressione di filtro filtra anche per i prodotti rossi o blu impostati come "Novità" e non come promozionali:

colors: ANY("red", "blue") AND attributes.status: ANY("New-Arrival") AND NOT attributes.is_promotional: ANY("true")

Per utilizzare la versione 2 dei filtri per i consigli, segui queste procedure. Ogni procedura è descritta più avanti in questa pagina.

1. Attivare il filtro dei consigli per un modello che li mostrerà.
2. Attiva i filtri dei consigli per gli attributi dei prodotti su cui vuoi applicare il filtro.
3. Utilizza gli attributi dei prodotti filtrabili nelle richieste di previsione.

Filtro dei consigli, versione 1 (ritirata)

La versione 1 utilizza i tag di filtro creati manualmente. Le espressioni di filtro si basano su tag di filtro, che devi aggiungere manualmente a tutti i prodotti del tuo catalogo che vuoi filtrare.

Il seguente esempio di espressione di filtro utilizza i tag filtro per specificare i prodotti помечены come "Rosso" o "Blu", nonché il tag "Novità" e non sono помечены come "Promozionale":

tag=("Red" OR "Blue") tag="New-Arrival" tag=(NOT "promotional")

Consulta la documentazione di riferimento dell'API per il campo Product.tags[].

Le espressioni dei tag possono contenere gli operatori booleani OR o NOT, che devono essere separati dai valori dei tag da uno o più spazi. I valori dei tag possono essere anche preceduti immediatamente da un trattino (-), che è equivalente all'operatore NOT. Le espressioni dei tag che utilizzano gli operatori booleani devono essere racchiuse tra parentesi.

Oltre ai tag, puoi filtrare in base a filterOutOfStockItems. L'indicatore filterOutOfStockItems esclude tutti i prodotti con un valore stockState OUT_OF_STOCK.

Puoi combinare i filtri dei tag e quelli di disponibilità in modo da restituire solo gli elementi chesoddisfano tutte le espressioni di filtro specificate.

Ecco alcune stringhe di filtro di esempio:

"filter": "tag=\"spring-sale\""

"filter": "filterOutOfStockItems"

"filter": "tag=\"spring-sale\" tag=\"exclusive\" filterOutOfStockItems"

L'esempio seguente restituisce solo gli articoli disponibili che hanno il tag spring-sale o exclusive (o entrambi) e che non hanno il tag items-to-exclude.

"filter": "tag=(\"spring-sale\" OR \"exclusive\") tag=(-\"items-to-exclude\") filterOutOfStockItems"

Compatibilità del filtro degli attributi e del filtro dei tag

Se un modello contiene sia tag creati manualmente sia attributi di prodotto filtrabili, può elaborare le richieste di previsione utilizzando entrambe le versioni di filtro. Tuttavia, non è possibile includere sia le espressioni di filtro v1 sia quelle di filtro v2 nella stessa richiesta di previsione.

Limiti per i filtri dei consigli

Ogni attributo filtrabile consuma una certa quantità di memoria in ciascuno dei tuoi modelli. I seguenti limiti contribuiscono a evitare effetti negativi sul rendimento della pubblicazione:

• Nel tuo catalogo puoi impostare fino a 10 attributi personalizzati come filtrabili.

• Nel tuo catalogo possono essere presenti fino a 100.000.000 di valori degli attributi filtrabili.

  Il numero totale di valori degli attributi nel tuo catalogo può essere stimato moltiplicando il numero di prodotti nel catalogo per il numero di attributi filtrabili.

  Ad esempio, se hai un catalogo con 1000 prodotti e 3 attributi impostati come filtrabili, il numero totale di valori dell'attributo può essere stimato come 3*1000=3000.

  Se utilizzi i filtri dei consigli della versione 1 insieme alla versione 2, il numero di tag filtro viene conteggiato ai fini della quota. Assicurati che il numero di tag filtro aggiunti al numero totale di valori dell'attributo sia inferiore a 100.000.000.

Se superi i limiti, non potrai impostare altri attributi come filtrabili. Se devi superare questi limiti, richiedi un aumento della quota.

Il numero totale di tag viene calcolato durante l'addestramento del modello. Se il numero totale supera il limite, l'addestramento del modello non va a buon fine. Se durante l'addestramento del modello vengono trovati più di 10 attributi personalizzati filtrabili, ne vengono utilizzati solo 10.

Sintassi dell'espressione del filtro dei consigli

Le sintassi delle espressioni di filtro per la ricerca e i consigli sono simili. Tuttavia, i consigli presentano diversi limiti.

La sintassi dell'espressione di filtro dei consigli può essere riassunta come segue: EBNF:

  # A single expression or multiple expressions that are joined by "AND" or "OR".
  filter = expression, { " AND " | "OR", expression };

  # An expression can be prefixed with "-" or "NOT" to express a negation.
  expression = [ "-" | "NOT " ],
                    # A parenthesized expression
                    | "(", expression, ")"
                    # A simple expression applying to a textual field.
                    # Function "ANY" returns true if the field contains any of the literals.
                    ( textual_field, ":", "ANY", "(", literal, { ",", literal }, ")"

  # A literal is any double-quoted case sensitive string. You must escape backslash (\) and
  # quote (") characters. We do not support textual values containing `/` characters, or partial string matches.

  # The literal must be an exact match for products in the catalog. The Predict
  # API returns empty results when no possible matches exist.

  literal = double-quoted string;

  textual_field = see the tables below;

Restrizioni alla sintassi del filtro

Si applicano le seguenti limitazioni:

• La profondità di incorporamento degli operatori AND e OR tra parentesi è limitata. Le espressioni logiche nel filtro devono essere in forma normale congiuntiva (CNF). L'espressione logica supportata più complessa può essere un elenco di clausole collegate da AND che contengono solo operatori OR, ad esempio: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
• Le espressioni possono essere negate con la parola chiave NOT o con -. Questo funziona solo con le espressioni ANY() con un singolo argomento che non includono attributi correlati all'inventario.
• Le limitazioni basate su availability devono essere al primo livello. Non possono essere utilizzati all'interno di una clausola OR o di una negazione (NOT).
• Poiché i filtri dei consigli standard supportano solo i campi di testo, le operazioni di controllo maggiore, minore e di intervallo non sono supportate per i filtri dei consigli standard. Le operazioni di confronto maggiore e minore possono essere utilizzate solo con le condizioni di controllo di promozione/seppellimento dei consigli, che supportano alcuni campi numerici (vedi Campi supportati per la promozione/seppellimento).
• Il numero massimo di termini nella clausola AND di primo livello è 20.
• Una clausola OR può avere fino a 100 argomenti inclusi nelle espressioni ANY(). Se una clausola OR contiene più espressioni ANY(), tutti i relativi argomenti vengono conteggiati ai fini di questo limite. Ad esempio, colors: ANY("red", "green") OR colors: ANY("blue") ha tre argomenti.

La tabella seguente mostra esempi di espressioni di filtro valide, nonché esempi non validi e i relativi motivi.

Filtro degli attributi correlati all'inventario

I filtri per gli attributi correlati all'inventario si basano sullo stato in tempo reale dei prodotti. Per il filtro availability: ANY("IN_STOCK"), la risposta della previsione restituisce i prodotti principali in cui il prodotto principale o una variante ha il valore corrispondente di IN_STOCK. Per saperne di più sui prodotti principali e sulle varianti, consulta Livelli di prodotto. Non supportiamo i filtri Primary only o Variant only.

IN_STOCK è l'unico valore dell'attributo availability supportato dalla versione 2 del filtro dei consigli.

Gli attributi relativi all'inventario possono essere utilizzati nelle clausole AND, ma non nelle clausole OR.

Campi supportati

I campi di testo supportati sono riportati nella tabella seguente.

La funzionalità Metti in evidenza/Nascondi per i consigli supporta campi aggiuntivi che non sono supportati dal filtro dei consigli standard. Per un elenco di campi aggiuntivi supportati da boost/bury per i consigli, consulta Campi supportati da boost/bury.

Campi supportati per boost/bury

La funzionalità Potenzia/Nascondi supporta alcuni campi aggiuntivi non supportati dal filtro dei consigli standard, inclusi i campi numerici.

Oltre ai campi elencati in Campi supportati, l'opzione boost/bury per i consigli supporta i seguenti campi:

Campi di testo

Campi numerici

Impostare il filtro dei consigli per un modello

Puoi attivare il filtro per i consigli utilizzando la console Ricerca per la vendita al dettaglio o la risorsa dell'API Models.

Dalla console, puoi creare un nuovo modello con il filtro dei consigli attivato. Puoi anche aggiornare questa opzione per i modelli esistenti.

Utilizzando la risorsa dell'API Models, puoi creare un nuovo modello con il filtro dei consigli attivato o aggiornare questa impostazione per un modello esistente utilizzando models.Patch.

Tieni presente che se nella configurazione di pubblicazione che restituisce le previsioni è attivata la corrispondenza delle categorie, il filtro non funziona per l'attributo "categories" perché la risposta restituisce solo i risultati dei prodotti che condividono una categoria con il prodotto del contesto.

Impostare i filtri per un modello utilizzando la console

Utilizzando la console Ricerca per la vendita al dettaglio, seleziona l'opzione Genera automaticamente i tag durante la creazione del modello per consentire il filtro dei consigli per quel modello.

Verifica la compatibilità con altre impostazioni, come diversity-level e category-match-level e così via, perché gli effetti totali si combinano e l'applicazione del filtro avviene per ultima.

• Ad esempio, la combinazione di diversity-level e category attribute filtering basati su regole spesso genera un output vuoto.
  • diversity-level=high-diversity forza il modello a limitare i risultati massimi per le stesse stringhe di categoria. Ad esempio, 1 risultato per la categoria 1, 1 risultato per la categoria 2 e così via.
  • Il filtro degli attributi che utilizza i metadati della categoria (Product.categories = ANY ("category2")) fa sì che il modello elimini gli elementi che non corrispondono.
  • L'output finale contiene meno di tre risultati.
• Per il modello similar-items, contiene già un aumento della pertinenza della categoria con il valore predefinito category-match-level = relaxed-category-match. Passa a category-match-level=no-category-match per disattivare il comportamento e utilizzare regole di filtro personalizzate.

Consulta Creare modelli di suggerimenti per istruzioni su come creare un modello di suggerimenti utilizzando la console.

Questa impostazione non può essere aggiornata nella console per i modelli esistenti. Per aggiornare questa impostazione per un modello, utilizza il metodo API models.Patch.

Impostare i filtri per un modello utilizzando l'API

Puoi attivare il filtro dei consigli per un modello utilizzando models.Create quando crei un nuovo modello o models.Patch quando aggiorni un modello esistente.

Per consentire il filtro, imposta il campo filteringOption per il modello. I valori consentiti di questo campo sono:

• RECOMMENDATIONS_FILTERING_DISABLED (valore predefinito): il filtro è disattivato per il modello.
• RECOMMENDATIONS_FILTERING_ENABLED: i filtri sono attivi per i prodotti principali.

Il seguente esempio di curl crea un nuovo modello in cui è attivato il filtro dei consigli.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
       'name': 'MODEL_NAME',
       'displayName': 'MODEL_DISPLAY_NAME',
       'type': 'home-page',
       'filteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED',
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/models"

Il seguente esempio di curl aggiorna l'impostazione dell'opzione di filtro per un modello esistente.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
       'filteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED',
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/models/MODEL_ID?updateMask=filteringOption"

Impostare gli attributi come filtrabili

Per filtrare i prodotti consigliati, attiva il filtro per gli attributi del prodotto che utilizzerai nelle espressioni di filtro. Puoi aggiornare questa impostazione utilizzando la console di ricerca per la vendita al dettaglio o la risorsa API Attributes.

Non rendere filtrabili più attributi del necessario. Esiste un limite al numero di attributi filtrabili.

Impostare gli attributi come filtrabili utilizzando la console

Puoi impostare un attributo come filtrabile nella pagina Controlli della console di Search for Retail.

1. Vai alla pagina Controlli nella console Ricerca per la vendita al dettaglio.
   
   Vai alla pagina Controlli

2. Vai alla scheda Controlli attributi.

   Questa scheda mostra una tabella di tutti gli attributi dei prodotti per i quali puoi impostare controlli su tutto il sito.

3. Fai clic su editModifica controlli.

4. Imposta Filtrabile su True per l'attributo del prodotto.

5. Fai clic su Salva controlli.

Puoi iniziare a utilizzare l'attributo per il filtro al termine del successivo ciclo di addestramento del modello.

Impostare gli attributi come filtrabili utilizzando l'API

AttributesConfig rappresenta un elenco di attributi per un catalogo.

Imposta il campo AttributesConfig.filteringOption per CatalogAttribute. I valori consentiti di questo campo sono:

• RECOMMENDATIONS_FILTERING_DISABLED (valore predefinito): il filtro è disattivato per l'attributo.
• RECOMMENDATIONS_FILTERING_ENABLED: il filtro è attivo per l'attributo.

Il seguente esempio di curl esegue query sugli attributi dei prodotti esistenti.

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \ "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/attributesConfig"

Il seguente esempio di curl imposta l'attributo prodotto categories come filtrabile.

Quando aggiorni un attributo esistente, mantieni i valori originali dell'attributo per indexableOption, dynamicFacetableOption e searchableOption come appaiono nel passaggio precedente. Se l'attributo scelto non è visualizzato quando visualizzi attributesConfig come nell'esempio precedente, utilizza le impostazioni predefinite come mostrato nell'esempio seguente.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
        'name': 'projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/attributesConfig',
        'catalogAttributes': {
          'categories': {
            'key': 'categories',
            'indexableOption': 'INDEXABLE_ENABLED',
            'dynamicFacetableOption': 'DYNAMIC_FACETABLE_DISABLED',
            'searchableOption': 'SEARCHABLE_DISABLED',
            'recommendationsFilteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED'
          }
        },
        'attributeConfigLevel': 'CATALOG_LEVEL_ATTRIBUTE_CONFIG'
     }" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/attributesConfig"

Puoi iniziare a utilizzare l'attributo per il filtro al termine del successivo ciclo di addestramento del modello. In genere, questa operazione richiede almeno otto ore.

Utilizzare gli attributi filtrabili in una richiesta di previsione

Dopo aver addestrato nuovamente il modello, puoi utilizzare gli attributi dei prodotti filtrabili nelle richieste di previsione.

Imposta il valore parametro di richiesta filterSyntaxV2 su true per attivare il filtro dei consigli della versione 2. Se il parametro non è impostato, il filtro della versione 1 rimane attivo. Se un modello contiene sia tag creati manualmente sia attributi dei prodotti filtrabili, può soddisfare le richieste di previsione utilizzando entrambe le versioni di filtro. Tuttavia, non è possibile includere sia le espressioni di filtro v1 sia quelle di filtro v2 nella stessa richiesta di previsione.

Il seguente esempio di curl parziale mostra filterSyntaxV2 impostato su true e un'espressione di filtro che utilizza gli attributi dei prodotti colors e categories. Questo esempio presuppone che colors e categories siano impostati come filtrabili.

"params": {
  "filterSyntaxV2": true
},
"filter": "(categories: ANY(\"Phone > Android > Pixel\") OR colors: ANY(\"red\", \"green\")) AND (availability: ANY(\"IN_STOCK\"))"

Il seguente esempio di curl mostra una richiesta di previsione completa.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
        'userEvent': {
          'eventType': 'detail-page-view',
          'visitorId': 'VISITOR_ID',
          'productDetails': {
            'product': {
              'id': 'PRODUCT_ID'
            }
          }
        },
        'params': {
          'returnProduct': true,
          'filterSyntaxV2': true,
          'strictFiltering': true,
        },
        'filter': 'categories: ANY(\"xyz\")'
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/placements/SERVING_CONFIG:predict"

Oltre ai filtri, l'impostazione di diversificazione della configurazione di pubblicazione può influire anche sul numero di risultati restituiti dalla risposta.