Filtrare i consigli

Questa pagina descrive il filtraggio dei risultati per i consigli utilizzando gli attributi prodotto.

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

Esistono due versioni del filtro per i consigli:

• È consigliata 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 del filtro, che filtra i consigli utilizzando gli attributi di prodotto.

Filtro dei consigli, versione 2

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

Quando utilizzi gli attributi per filtrare i prodotti, la risposta di 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 tutti i prodotti rossi o blu impostati come "Nuovi arrivi" 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 del filtro per i consigli, segui queste procedure. Ogni procedura viene descritta più avanti in questa pagina.

1. Attiva il filtro dei suggerimenti per un modello che mostrerà i suggerimenti filtrati.
2. Attiva il filtro dei suggerimenti per gli attributi dei prodotti su cui prevedi di filtrare.
3. Utilizza gli attributi di prodotto 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 sui tag di filtro, che devi aggiungere manualmente a tutti i prodotti del tuo catalogo che prevedi di filtrare.

Il seguente esempio di espressione di filtro utilizza i tag di filtro per specificare i prodotti contrassegnati come "Rosso" o "Blu", nonché il tag "Nuovo arrivo", e non sono contrassegnati come "promozionali":

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 anche essere preceduti immediatamente da un trattino (-), che equivale 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. Il flag filterOutOfStockItems filtra tutti i prodotti con un stockState di OUT_OF_STOCK.

Puoi combinare i filtri dei tag e i filtri per esaurimento scorte in modo che vengano restituiti solo gli articoli che soddisfano tutte le espressioni di filtro specificate.

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 non hanno il tag items-to-exclude.

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

Compatibilità tra filtri degli attributi e filtri dei tag

Se un modello ha tag creati manualmente e attributi di prodotto filtrabili, può pubblicare richieste di previsione utilizzando una delle due versioni del filtro. Tuttavia, non è possibile includere espressioni di filtro v1 e v2 nella stessa richiesta di previsione.

Limiti di filtraggio dei consigli

Aggiungi manualmente i criteri di filtro per limitare l'insieme di consigli restituiti agli utenti finali. Utilizza Vertex AI Search for Commerce per applicare regole aziendali per ottimizzare ciò che vedono i clienti, incluse le opzioni per filtrare per disponibilità del prodotto, tag personalizzati e altri criteri.

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

• Nel catalogo è possibile impostare fino a 10 attributi personalizzati come filtrabili.

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

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

Se superi i limiti, non puoi impostare altri attributi come filtrabili. Se hai bisogno di 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 riesce. Se durante l'addestramento del modello vengono trovati più di 10 attributi personalizzati filtrabili, ne vengono utilizzati solo 10.

Sintassi dell'espressione di filtro dei consigli

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

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;

Limitazioni della sintassi del filtro

Si applicano le seguenti limitazioni:

• La profondità degli operatori AND e OR tra parentesi è limitata. Le espressioni logiche nel filtro devono essere in forma normale congiuntiva (CNF). L'espressione logica più complessa supportata può essere un elenco di clausole connesse tramite 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 -. Questa operazione funziona solo con le espressioni ANY() con un solo argomento che non includono attributi correlati all'inventario.
• Le limitazioni basate su availability devono essere di primo livello. Non possono essere utilizzati come parte di una clausola OR o di una negazione (NOT).
• Poiché il filtro dei suggerimenti standard supporta solo i campi di testo, le operazioni di confronto minore di, maggiore di e controllo dell'intervallo non sono supportate per il filtro dei suggerimenti standard. Le operazioni di minore e maggiore possono essere utilizzate solo con le condizioni di controllo di aumento o riduzione dei suggerimenti, che supportano alcuni campi numerici (vedi Campi supportati per l'aumento/la riduzione).
• 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 ha 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 motivi per cui non sono validi.

Filtro degli attributi correlati all'inventario

Il filtro sugli attributi correlati all'inventario si basa sullo stato in tempo reale dei tuoi prodotti. Per il filtro availability: ANY("IN_STOCK"), la risposta di 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 il filtro Primary only o Variant only.

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

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

Campi supportati

I campi di testo supportati sono riepilogati nella tabella seguente.

Il potenziamento o l'esclusione per i consigli supporta campi aggiuntivi che non sono supportati dal filtro standard dei consigli. Per un elenco di questi campi, consulta Campi supportati per l'aumento/la riduzione della visibilità.

Campi supportati per il boost/bury

Boost/bury supporta alcuni campi aggiuntivi non supportati dal filtro standard dei consigli, inclusi i campi numerici.

Oltre ai campi elencati in Campi supportati, il boost/seppellimento per i consigli supporta i seguenti campi:

Campi testuali

Campi numerici

Impostare il filtro dei consigli per un modello

Puoi attivare il filtro per i consigli utilizzando la console Search for commerce o la risorsa 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 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 le previsioni ha attivato la corrispondenza delle categorie, il filtro non funziona con l'attributo "categories" perché la risposta restituisce solo i risultati dei prodotti che condividono una categoria con il prodotto contestuale.

Impostare il filtro per un modello utilizzando la console

Utilizzando la console Search for commerce, seleziona l'opzione Genera automaticamente 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 il filtraggio avviene per ultimo.

• Ad esempio, la combinazione di diversity-level e category attribute filtering basati su regole spesso genera un output vuoto.
  • diversity-level=high-diversity impone al modello di limitare i risultati massimi per le stesse stringhe di categorie. 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 scarti gli elementi che non corrispondono.
  • L'output finale contiene meno di tre risultati.
• Per il modello similar-items, è già presente 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 filtraggio personalizzate.

Consulta Creare modelli di suggerimento per istruzioni sulla creazione di un modello di suggerimento 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.

Imposta il filtro 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 filtraggio, imposta il campo filteringOption per il modello. I valori consentiti per questo campo sono:

• RECOMMENDATIONS_FILTERING_DISABLED (valore predefinito): il filtro è disattivato per il modello.
• RECOMMENDATIONS_FILTERING_ENABLED: Il filtro è attivo per i prodotti principali.

Il seguente esempio di curl crea un nuovo modello con l'attivazione del filtro dei suggerimenti.

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"

L'esempio di curl seguente 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 di prodotto che utilizzerai nelle espressioni di filtro. Puoi aggiornare questa impostazione utilizzando la console Search for commerce 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 Search for Commerce.

1. Vai alla pagina Controlli nella console Search for commerce.
   
   Vai alla pagina Controlli

2. Vai alla scheda Controlli degli attributi.

   Questa scheda mostra una tabella di tutti gli attributi di prodotto per i quali puoi impostare controlli a livello di sito.

3. Fai clic su editModifica controlli.

4. Imposta Filtro su Vero per l'attributo prodotto.

5. Fai clic su Salva controlli.

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

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 di prodotto 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"

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

Quando aggiorni un attributo esistente, mantieni i valori originali dell'attributo per indexableOption, dynamicFacetableOption e searchableOption come visualizzati 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 filtraggio al termine del ciclo di addestramento del modello successivo. In genere, questa operazione richiede almeno otto ore.

Utilizzare gli attributi filtrabili in una richiesta di previsione

Dopo aver eseguito il retraining del modello, puoi utilizzare gli attributi di prodotto 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 ha sia tag creati manualmente sia attributi di prodotto filtrabili, può pubblicare richieste di previsione utilizzando una delle due versioni del filtro. Tuttavia, non è possibile includere espressioni di filtro v1 e v2 nella stessa richiesta di previsione.

Il seguente esempio parziale di curl mostra filterSyntaxV2 impostato su true e un'espressione di filtro che utilizza gli attributi 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, anche l'impostazione di diversificazione della configurazione di pubblicazione può influire sul numero di risultati restituiti dalla risposta.