Retail è stato rinominato Vertex AI Search for Retail. Stiamo aggiornando i contenuti per riflettere il nuovo branding.

Questa pagina è stata tradotta dall'API Cloud Translation.

Filtra suggerimenti

In questa pagina viene spiegato come filtrare i risultati per i suggerimenti utilizzando gli attributi del prodotto.

Puoi filtrare i risultati della 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 dei prodotti nella risposta viene ristretto ai prodotti in cui l'espressione restituisce true.

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 dell'applicazione di filtri, che filtra i suggerimenti utilizzando gli attributi del prodotto.

Filtro dei suggerimenti, versione 2

La versione 2 utilizza gli attributi del prodotto. Le espressioni di filtro si basano sugli attributi dei prodotti. Possono essere attributi di sistema predefiniti, come categories e colors, o attributi personalizzati da te definiti, come attributes.styles. Quando imposti un attributo del prodotto come filtrabile, i suggerimenti possono utilizzare automaticamente questi attributi come tag per l'applicazione di filtri dei suggerimenti, invece di dover aggiungere manualmente i 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 eventuali prodotti rossi o blu impostati come "Nuovo-arrivo" e non impostati 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 suggerimenti, segui queste procedure. Ogni procedura viene descritta più avanti in questa pagina.

Attiva i filtri dei suggerimenti per un modello che pubblicherà suggerimenti filtrati.
Attiva i filtri dei suggerimenti per gli attributi dei prodotti per i quali prevedi di applicare filtri.
Utilizzare gli attributi dei prodotti filtrabili nelle richieste di previsione.

Filtro dei suggerimenti, versione 1 (deprecata)

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 nel catalogo che intendi filtrare.

Il seguente esempio di espressione di filtro utilizza i tag di filtro per specificare i prodotti taggati come "Rosso" o "Blu", nonché il tag "Nuovo-arrivo", e che 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 tag possono contenere gli operatori booleani OR o NOT, che devono essere separati dai valori del tag da uno o più spazi. I valori dei tag possono anche essere immediatamente anteposti a un trattino (-), che equivale all'operatore NOT. Le espressioni tag che utilizzano gli operatori booleani devono essere racchiuse tra parentesi.

Oltre ai tag, puoi filtrare per filterOutOfStockItems. Il flag filterOutOfStockItems esclude tutti i prodotti con un valore stockState di OUT_OF_STOCK.

Puoi combinare filtri dei tag e filtri non disponibili in modo che vengano restituiti solo gli elementi che soddisfano tutte le espressioni di filtro specificate.

Ecco alcuni esempi di stringhe di filtro:

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

"filter": "filterOutOfStockItems"

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

L'esempio seguente restituisce solo gli elementi disponibili con il tag spring-sale e exclusive (o entrambi) e senza il tag items-to-exclude.

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

Compatibilità di filtro degli attributi e filtro dei tag

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

Limiti di filtro dei suggerimenti

Ogni attributo filtrabile consuma memoria in ciascuno dei tuoi modelli. I seguenti limiti aiutano a prevenire 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 dei valori degli attributi nel 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 i suggerimenti della versione 1 oltre 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 potrai impostare attributi aggiuntivi 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 riesce. Se durante l'addestramento del modello vengono trovati più di 10 attributi personalizzati filtrabili, solo 10 vengono utilizzati.

Sintassi delle espressioni di filtro dei suggerimenti

La sintassi delle espressioni di filtro per la ricerca e i suggerimenti è simile. Tuttavia, i suggerimenti presentano diverse limitazioni.

La sintassi delle espressioni di filtro dei suggerimenti può essere riassunta dal seguente 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 a 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 metodo funziona solo con le espressioni ANY() con un singolo argomento che non include attributi relativi 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é i filtri dei suggerimenti standard supportano solo campi di testo, le operazioni di tipo minore di, maggiore di e controllo intervallo non sono supportate per l'applicazione di filtri dei suggerimenti standard. Le operazioni di valore minore di e maggiore di possono essere utilizzate 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 ha più espressioni ANY(), i relativi argomenti vengono conteggiati per questo limite. Ad esempio, colors: ANY("red", "green") OR colors: ANY("blue") ha tre argomenti.

La seguente tabella mostra esempi di espressioni di filtro validi, nonché esempi non validi e i motivi della loro validità.

Espressione	Valida	Note
`colors: ANY("red", "green")`	Sì
`NOT colors: ANY("red")`	Sì
`NOT colors: ANY("red", green")`	No	Nega "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

Il filtro in base agli attributi relativi all'inventario si basa sullo stato in tempo reale dei tuoi 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 ulteriori informazioni 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 suggerimenti.

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.

Boost/bury per suggerimenti supporta campi aggiuntivi non supportati dal filtro dei suggerimenti standard. Per un elenco dei campi aggiuntivi supportati da boost/bury per i suggerimenti, consulta Campi supportati da Boost/bury.

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

Campi supportati per Boost/bury

Boost/bury supporta alcuni campi aggiuntivi non supportati dai filtri dei suggerimenti standard, 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.
"discount"	Lo sconto sul prodotto. Questo campo viene calcolato utilizzando i valori originali del campo del prezzo e del prezzo da `PriceInfo`.
"valutazione"	`Product.rating`. Il numero totale di valutazioni del prodotto.
"ratingCount"	`rating.ratingCount`. Il numero totale di valutazioni del prodotto.

Imposta i filtri dei suggerimenti per un modello

Puoi attivare i filtri per i suggerimenti utilizzando la console Search for Retail o la risorsa API Models.

Dalla console puoi creare un nuovo modello in cui sono abilitati i filtri dei suggerimenti. Puoi aggiornare questa opzione anche per i modelli esistenti.

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

Tieni presente che se la configurazione di pubblicazione che restituisce previsioni ha attivato la corrispondenza delle categorie, l'applicazione di filtri non funziona per l'attributo "categorie" perché la risposta restituisce solo i risultati dei prodotti che condividono una categoria con il prodotto di contesto.

Impostare i filtri per un modello utilizzando la console

Nella console di Search for Retail, seleziona l'opzione Genera automaticamente tag durante la creazione del modello per consentire l'applicazione di filtri ai suggerimenti per il modello in questione.

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 utilizzando i metadati della categoria (Product.categories = ANY ("category2")) fa sì che il modello scarti gli elementi che non corrispondono.
- L'output finale ha 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 le 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.

Impostare i filtri per un modello utilizzando l'API

Puoi attivare i filtri dei suggerimenti per un modello utilizzando models.Create quando crei un nuovo modello o models.Patch quando aggiorni un modello esistente.

Per consentire l'applicazione di filtri, imposta il campo filteringOption per il tuo modello. I valori consentiti per questo campo sono:

RECOMMENDATIONS_FILTERING_DISABLED (predefinito): il filtro è disattivato per il modello.
RECOMMENDATIONS_FILTERING_ENABLED: i filtri sono attivati per i prodotti primari.

Il seguente esempio di curl crea un nuovo modello con filtri per i suggerimenti attivato.

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 delle opzioni 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 i filtri in base agli attributi dei prodotti che utilizzerai nelle espressioni di filtro. Puoi aggiornare questa impostazione utilizzando la console Search for Retail o la risorsa API Attributes.

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

Impostare gli attributi come filtrabili utilizzando la console

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

Vai alla pagina Controlli nella console di Search for Retail.

Vai alla pagina Controlli
Vai alla scheda Controlli degli attributi.

Questa scheda mostra una tabella di tutti gli attributi del prodotto per i quali puoi impostare i controlli in tutto il sito.
Fai clic su Modifica controlli.
Imposta Filterable (Filtrabile) su True per l'attributo del prodotto.
Fai clic su Save Controls (Salva controlli).

Puoi iniziare a utilizzare l'attributo per l'applicazione di filtri una volta completato il 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 per questo campo sono:

RECOMMENDATIONS_FILTERING_DISABLED (predefinito): il filtro è disattivato per l'attributo.
RECOMMENDATIONS_FILTERING_ENABLED: il filtro è attivato per l'attributo.

Il seguente esempio di curl interroga gli 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 così come vengono visualizzati nel passaggio precedente. Se l'attributo scelto non compariva durante la visualizzazione di 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 l'applicazione di filtri una volta completato il successivo ciclo di addestramento del modello. Questa operazione richiede in genere almeno otto ore.

Usare attributi filtrabili in una richiesta di previsione

Dopo aver riaddestrato 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 suggerimenti della versione 2. Se il parametro non viene impostato, il filtro della versione 1 rimane attivo. Se un modello dispone sia di tag creati manualmente sia di attributi di prodotto filtrabili, può pubblicare richieste di previsione utilizzando entrambe le versioni dei filtri. Tuttavia, non è possibile includere espressioni di filtro v1 e v2 nella stessa richiesta di previsione.

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