Filtra suggerimenti

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

Puoi filtrare i risultati della previsione specificando un'espressione di filtro nella previsione richieste. L'espressione di filtro è un'espressione logica che viene valutata ogni prodotto. L'elenco dei prodotti nella risposta è limitato ai prodotti in cui l'espressione restituisce true.

Nota: la disponibilità degli aggiornamenti delle espressioni di tag può richiedere fino a otto ore da utilizzare per filtrare le previsioni con le versioni v1 e v2, incluse le configurazioni degli attributi per l'applicazione di filtri e le modifiche ai metadati a livello di prodotto. Solo il campo Availability ha aggiornamenti in tempo reale.

Esistono due versioni di filtri per i suggerimenti:

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

Le sezioni di questa guida illustrativa 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 suggerimenti possono quindi utilizzarli automaticamente tag per l'applicazione di filtri ai suggerimenti, invece di dover richiedere manualmente aggiungere 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 ulteriori informazioni 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. Utilizzare gli attributi dei prodotti filtrabili nelle richieste di previsione.

Filtro dei consigli, versione 1 (ritirata)

La versione 1 utilizza 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 di filtro per specificare i prodotti contrassegnato come "Rosso" o "Blu", così come il tag "New-Arrival" e non sono con la dicitura "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 tag possono contenere gli operatori booleani OR o NOT, che devono dai valori del 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 per filterOutOfStockItems. L'indicatore filterOutOfStockItems esclude tutti i prodotti con un valore stockState OUT_OF_STOCK.

Puoi combinare filtri dei tag e filtri non disponibili in modo che solo gli elementi che per soddisfare 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 con il tag spring-sale o exclusive (o entrambi) e non presenta i 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ò gestire richieste di previsione utilizzando entrambe le versioni del filtro. Tuttavia, è possibile includere espressioni di filtro v1 e v2 nello stesso di previsione.

Limiti per i filtri dei consigli

Ogni attributo filtrabile consuma memoria in ciascuno dei tuoi modelli. La I seguenti limiti consentono di evitare effetti negativi sulle prestazioni della pubblicazione:

• È possibile impostare fino a 10 attributi personalizzati come filtrabili nel catalogo.

• Nel 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 filtrabile, il numero totale di valori degli attributi può essere stimato come 3*1000=3000.

  Se utilizzi l'applicazione di filtri ai suggerimenti della versione 1 insieme alla versione 2, di tag filtro concorrono alla tua 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 più impostando attributi aggiuntivi come filtrabili. Se devi superare questi limiti, richiedere 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 riesce. Se più di 10 elementi personalizzati filtrabili vengono trovati durante l'addestramento del modello, ma 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 di sintassi dei filtri

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 suggerimenti standard supportano solo campi di testo, le operazioni di minore, maggiore di e controllo intervallo non sono supportate per dei suggerimenti standard. Le operazioni di minore di e di maggiore di possono essere usata solo con condizioni di controllo boost/bury di suggerimenti, che supportano alcuni campi numerici (vedi Campi supportati per Boost/bury).
• 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 seguente tabella mostra esempi di espressioni di filtro valide e non valide esempi e i motivi per cui non sono validi.

Espressione	Valido	Note
colors: ANY("red", "green")	Sì
NOT colors: ANY("red")	Sì
NOT colors: ANY("red", green")	No	Nega una funzione "ANY()" con più di un argomento.
colors: ANY("red", "green") OR categories: ANY(\"Phone > Android > Pixel\")	Sì
(colors: ANY("red") OR colors: ANY("green")) AND categories: ANY(\"Phone > Android > Pixel\")	Sì
(colors: ANY("red") AND colors: ANY("green")) OR categories: ANY(\"Phone > Android > Pixel\")	No	Non in forma normale congiuntiva.
(colors: ANY("red")) AND (availability: ANY("IN_STOCK")	Sì
(colors: ANY("red")) OR (availability: ANY("IN_STOCK"))	No	Combina availability in un'espressione OR con altre condizioni.

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 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 riepilogati nella seguente tabella.

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.

campo	description
"productId"	L'ID prodotto (l'ultimo segmento di Product.name).
"brands"	I Product.brands.
"categorie"	Le categorie Product.categories.
"genders"	Il parametro Audience.genders.
"ageGroups"	Audience.age_groups.
"colorFamilies"	ColorInfo.color_families.
"colors"	Il parametro ColorInfo.colors.
"dimensioni"	Product.sizes.
"materiali"	I materiali Product.materials.
"pattern"	I pattern Product.
"condizioni"	Le condizioni Product.conditions.
"attributes.key"	L'attributo personalizzato di testo nell'oggetto Product. La chiave può essere qualsiasi chiave la mappa Product.attributes, se i valori degli attributi sono testuali.

Campi supportati per boost/bury

Boost/bury supporta alcuni campi aggiuntivi non supportati dallo standard e l'applicazione di filtri a suggerimenti, inclusi i campi numerici.

Oltre ai campi elencati in Campi supportati, boost/bury per suggerimenti supporta i seguenti campi:

Campi di testo

campo	description
"tag"	Product.tags[]. Tag personalizzati associati al prodotto.

Campi numerici

campo	description
"price"	PriceInfo.price. Il prezzo del prodotto.
"sconto"	Lo sconto sul prodotto. Questo campo viene calcolato utilizzando il prezzo originale e i valori del campo del prezzo di PriceInfo.
"rating"	Product.rating. Il numero totale di valutazioni per prodotto.
"ratingCount"	rating.ratingCount. Il numero totale di valutazioni per il prodotto.

Impostare il filtro dei consigli per un modello

Puoi attivare i filtri 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 la configurazione di pubblicazione che restituisce previsioni ha corrispondenza delle categorie abilitata, il filtro non funziona le "categorie" perché la risposta restituisce solo risultati relativi ai prodotti che condividono una categoria con il prodotto di 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, ad esempio diversity-level, category-match-level e così via, perché gli effetti totali si combinano e il filtro viene applicato per ultimo.

• Ad esempio, se combini diversity-level e category attribute filtering basati su regole spesso, l'output è vuoto.
  • diversity-level=high-diversity obbliga il modello a limitare i risultati massimi per le stesse stringhe di categoria. Ad esempio, 1 risultato per categoria1, 1 risultato per categoria2, ecc.
  • 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.
• Il modello similar-items contiene già un aumento della pertinenza della categoria extra 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 dell'API models.Patch.

Impostare i filtri per un modello utilizzando l'API

Puoi attivare l'applicazione di filtri dei suggerimenti 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. Il valore di questo campo Sono consentiti i seguenti valori:

• RECOMMENDATIONS_FILTERING_DISABLED (predefinito): il filtro è disattivato per del modello.
• RECOMMENDATIONS_FILTERING_ENABLED: il filtro è attivato per l'account principale prodotti di big data e machine learning.

Il seguente esempio di curl crea un nuovo modello con suggerimenti dei filtri attivati.

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"

Imposta 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.

Imposta 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 di Search for Retail.
   
   Vai alla pagina Controlli

2. Vai alla scheda Controlli degli 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 Modifica controlli.

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

5. Fai clic su Save Controls (Salva controlli).

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

Imposta 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 del prodotto categories come filtrabile.

Quando aggiorni un attributo esistente, mantieni i valori originali dell'attributo per indexableOption, dynamicFacetableOption e searchableOption mentre stanno nel passaggio precedente. Se l'attributo scelto non è stato visualizzato quando visualizzazione di attributesConfig come nell'esempio precedente, quindi utilizza il valore predefinito 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 l'applicazione di filtri dopo il successivo addestramento del modello ciclo completo. 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 la versione 2 il filtro dei suggerimenti. Se il parametro non è impostato, il filtro della versione 1 rimane attivo. Se un modello include sia tag creati manualmente sia prodotto filtrabile può gestire richieste di previsione utilizzando entrambe le versioni del filtro. Tuttavia, non è possibile includere entrambi i filtri v1 e v2 nella stessa richiesta di previsione.

Il seguente esempio di curl parziale mostra il valore filterSyntaxV2 impostato su true e un valore espressione di filtro utilizzando gli attributi di prodotto 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.