Empfehlungen filtern

Auf dieser Seite wird beschrieben, wie Sie Ergebnisse für Empfehlungen mithilfe von Produktattributen filtern.

Sie können Vorhersageergebnisse filtern, indem Sie in predict-Anfragen einen Filterausdruck angeben. Der Filterausdruck ist ein logischer Ausdruck, der für jedes Produkt ausgewertet wird. Die Liste der Produkte in der Antwort wird auf Produkte beschränkt, für die der Ausdruck „true“ ergibt.

Es gibt zwei Versionen des Filterprozesses für Empfehlungen:

Die Abschnitte in dieser Anleitung beziehen sich nur auf Version 2 der Filterung, bei der Empfehlungen anhand von Produktattributen gefiltert werden.

Empfehlungsfilterung, Version 2

In Version 2 werden Produktattribute verwendet. Filterausdrücke basieren auf Produktattributen. Das können vordefinierte Systemattribute wie categories und colors oder benutzerdefinierte Attribute wie attributes.styles sein. Wenn Sie ein Produktattribut als filterbar festlegen, können Empfehlungen diese Attribute automatisch als Tags zum Filtern von Empfehlungen verwenden. Sie müssen dann nicht manuell Filter-Tags hinzufügen.

Wenn Sie Attribute zum Filtern von Produkten verwenden, werden in der Vorhersageantwort primäre Produkte zurückgegeben, die mindestens ein primäres Produkt oder ein Variantenprodukt mit einem Attributwert enthalten, der dem Filterausdruck entspricht. Weitere Informationen zu primären Produkten und Produktvarianten finden Sie unter Produktebenen.

Das folgende Beispiel für einen Filterausdruck filtert auch nach allen roten oder blauen Produkten, die als „Neuheit“ festgelegt und nicht als Werbeartikel gekennzeichnet sind:

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

So verwenden Sie Version 2 der Filterung für Empfehlungen: Die einzelnen Verfahren werden weiter unten auf dieser Seite beschrieben.

  1. Aktivieren Sie die Empfehlungsfilterung für ein Modell, um gefilterte Empfehlungen zu erhalten.
  2. Aktivieren Sie die Filterung von Empfehlungen für Produktattribute, nach denen Sie filtern möchten.
  3. Filterbare Produktattribute in Vorhersageanfragen verwenden:

Empfehlungsfilterung, Version 1 (eingestellt)

In Version 1 werden manuell erstellte Filter-Tags verwendet. Filterausdrücke basieren auf Filtertags, die Sie manuell allen Produkten in Ihrem Katalog hinzufügen müssen, die Sie filtern möchten.

Im folgenden Beispiel für einen Filterausdruck werden Filter-Tags verwendet, um Produkte anzugeben, die mit „Rot“ oder „Blau“ sowie mit dem Tag „Neuheit“ gekennzeichnet sind und nicht mit „Werbeangebot“ gekennzeichnet sind:

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

Weitere Informationen finden Sie in der API-Referenzdokumentation zum Feld Product.tags[].

Tag-Ausdrücke können die booleschen Operatoren OR oder NOT enthalten. Diese müssen von den Tag-Werten durch ein oder mehrere Leerzeichen getrennt sein. Den Tag-Werten können auch Bindestriche (-) vorangestellt werden. Dies entspricht dem Operator NOT. Tag-Ausdrücke, die boolesche Operatoren verwenden, müssen in Klammern stehen.

Zusätzlich zu Tags können Sie auch nach filterOutOfStockItems filtern. Das Flag filterOutOfStockItems filtert alle Produkte heraus, für die für stockState der Wert OUT_OF_STOCK gilt.

Sie können Tag-Filter und „Nicht auf Lager“-Filter kombinieren, sodass nur Artikel zurückgegeben werden, die allen angegebenen Filterausdrücken entsprechen.

Beispiele für Filterstrings:

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

Im folgenden Beispiel werden nur Artikel zurückgegeben, die auf Lager sind und entweder das Tag spring-sale oder das Tag exclusive (oder beides) und nicht das Tag items-to-exclude enthalten.

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

Kompatibilität von Attribut- und Tag-Filtern

Wenn ein Modell sowohl manuell erstellte Tags als auch filterbare Produktattribute hat, können Vorhersageanfragen mit beiden Versionen der Filterung verarbeitet werden. Es ist jedoch nicht möglich, sowohl v1- als auch v2-Filterausdrücke in dieselbe Vorhersageanfrage aufzunehmen.

Einschränkungen bei der Filterung von Empfehlungen

Fügen Sie manuell Filterkriterien hinzu, um die Menge der Empfehlungen einzugrenzen, die Endnutzern angezeigt werden. Mit Vertex AI Search for Commerce können Sie Geschäftsregeln anwenden, um Kunden relevante Produktangebote zu präsentieren. Dazu haben Sie unter anderem die Möglichkeit, nach Produktverfügbarkeit, benutzerdefinierten Tags und anderen Kriterien zu filtern.

Jedes filterbare Attribut belegt in jedem Ihrer Modelle etwas Arbeitsspeicher. Die folgenden Grenzwerte sollen negative Auswirkungen auf die Anzeigenbereitstellung verhindern:

  • In Ihrem Katalog können Sie bis zu 10 benutzerdefinierte Attribute als filterbar festlegen.
  • Ihr Katalog kann bis zu 100.000.000 filterbare Attributwerte enthalten.

    Die Gesamtzahl der Attributwerte in Ihrem Katalog lässt sich schätzen, indem Sie die Anzahl der Produkte in Ihrem Katalog mit der Anzahl der filterbaren Attribute multiplizieren.

    Wenn Sie beispielsweise einen Katalog mit 1.000 Produkten und 3 Attributen haben, die als filterbar festgelegt sind, kann die Gesamtzahl der Attributwerte auf 3 × 1.000=3.000 geschätzt werden.

    Wenn Sie die Filterung von Empfehlungen der Version 1 zusammen mit Version 2 verwenden, wird die Anzahl der Filter-Tags auf Ihr Kontingent angerechnet. Achten Sie darauf, dass die Anzahl der Filtertags, die zur Gesamtzahl der Attributwerte hinzugefügt werden, unter 100.000.000 liegt.

Wenn Sie die Grenzwerte überschreiten, können Sie keine weiteren Attribute als filterbar festlegen. Wenn Sie diese Limits überschreiten müssen, fordern Sie eine Kontingenterhöhung an.

Die Gesamtzahl der Tags wird während des Modelltrainings berechnet. Wenn die Gesamtzahl das Limit überschreitet, schlägt das Modelltraining fehl. Wenn beim Modelltraining mehr als 10 benutzerdefinierte Attribute gefunden werden, die gefiltert werden können, werden nur 10 verwendet.

Syntax für Filterausdrücke für Empfehlungen

Die Syntaxen für Filterausdrücke für die Suche und Empfehlungen sind ähnlich. Empfehlungen haben jedoch einige Einschränkungen.

Die Syntax des Filterausdrucks für Empfehlungen kann mit dem folgenden EBNF zusammengefasst werden:

  # 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;

Einschränkungen der Filtersyntax

Folgende Einschränkungen gelten:

  • Die Tiefe der Einbettung von AND- und OR-Operatoren in Klammern ist begrenzt. Die logischen Ausdrücke im Filter müssen in konjunktiver Normalform (CNF) sein. Der komplexeste unterstützte logische Ausdruck kann eine mit AND verbundene Liste von Klauseln sein, die nur OR-Operatoren enthalten, z. B.: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
  • Ausdrücke können mit dem Schlüsselwort NOT oder mit - negiert werden. Das funktioniert nur mit ANY()-Ausdrücken mit einem einzelnen Argument, die keine inventarbezogenen Attribute enthalten.
  • availability-basierte Einschränkungen müssen auf der obersten Ebene liegen. Sie können nicht als Teil einer OR-Klausel oder einer Negation (NOT) verwendet werden.
  • Da die Filterung von Standardempfehlungen nur Textfelder unterstützt, werden die Vorgänge „kleiner als“, „größer als“ und „Bereichsprüfung“ für die Filterung von Standardempfehlungen nicht unterstützt. Die Operationen „kleiner als“ und „größer als“ können nur mit Kontrollbedingungen für das Hochstufen oder Verbergen von Empfehlungen verwendet werden, die einige numerische Felder unterstützen (siehe Unterstützte Felder für das Hochstufen/Verbergen).
  • Die maximale Anzahl von Begriffen in der AND-Klausel der obersten Ebene beträgt 20.
  • Eine OR-Klausel kann bis zu 100 Argumente enthalten, die in ANY()-Ausdrücken enthalten sind. Wenn eine OR-Klausel mehrere ANY()-Ausdrücke enthält, werden alle ihre Argumente auf dieses Limit angerechnet. colors: ANY("red", "green") OR colors: ANY("blue") hat beispielsweise drei Argumente. Im Anwendungsfall von Vertex AI Search for Commerce entspricht ein Argument einem Attributwert.

In der folgenden Tabelle finden Sie Beispiele für gültige Filterausdrücke sowie ungültige Beispiele und die Gründe für ihre Ungültigkeit.

Ausdruck Gültig Hinweise
colors: ANY("red", "green") Ja
NOT colors: ANY("red") Ja
NOT colors: ANY("red", green") Nein Negiert eine `ANY()`-Funktion mit mehr als einem Argument.
colors: ANY("red", "green") OR
categories: ANY(\"Phone > Android > Pixel\")
Ja
(colors: ANY("red") OR colors: ANY("green")) AND
categories: ANY(\"Phone > Android > Pixel\")
Ja
(colors: ANY("red") AND colors: ANY("green")) OR
categories: ANY(\"Phone > Android > Pixel\")
Nein Nicht in konjunktiver Normalform.
(colors: ANY("red")) AND (availability: ANY("IN_STOCK") Ja
(colors: ANY("red")) OR (availability: ANY("IN_STOCK")) Nein Kombiniert availability in einem OR-Ausdruck mit anderen Bedingungen.

Filterung nach inventarbezogenen Attributen

Die Filterung nach inventarbezogenen Attributen basiert auf dem Echtzeitstatus Ihrer Produkte. Beim Filtern nach availability: ANY("IN_STOCK") werden in der Vorhersageantwort primäre Produkte zurückgegeben, bei denen das primäre Produkt oder eine Variante den entsprechenden Wert von IN_STOCK hat. Weitere Informationen zu primären Produkten und Produktvarianten finden Sie unter Produktebenen. Das Filtern nach Primary only oder Variant only wird nicht unterstützt.

IN_STOCK ist der einzige availability-Attributwert, der von Version 2 der Empfehlungsfilterung unterstützt wird.

Inventarbezogene Attribute können in AND-Klauseln, aber nicht in OR-Klauseln verwendet werden.

Unterstützte Felder

Die unterstützten Textfelder werden in der folgenden Tabelle zusammengefasst.

Für das Hervorheben oder Ausblenden von Empfehlungen werden zusätzliche Felder unterstützt, die nicht für das Filtern von Standardempfehlungen verwendet werden können. Eine Liste solcher Felder finden Sie unter Unterstützte Felder für die Steigerung/Unterdrückung.

Feld Beschreibung
„productId“ Die Produkt-ID (das letzte Segment von Product.name).
"brands" Die Product.brands.
„categories“ Die Product.categories.
„genders“ Die Audience.genders.
„ageGroups“ Die Audience.age_groups.
"colorFamilies" Die ColorInfo.color_families.
„colors“ Die ColorInfo.colors.
„sizes“ Die Product.sizes.
„materials“ Die Product.materials.
„patterns“ Die Product.patterns.
„conditions“ Die Product.conditions.
"attributes.key" Das benutzerdefinierte Textattribut im Produktobjekt. Ein Schlüssel kann ein beliebiger Schlüssel in der Zuordnung Product.attributes sein, wenn die Attributwerte in Textform vorliegen.

Unterstützte Felder hoch-/herabstufen

Boost/bury unterstützt einige zusätzliche Felder, die nicht vom Standardfilter für Empfehlungen unterstützt werden, einschließlich numerischer Felder.

Zusätzlich zu den in Unterstützte Felder aufgeführten Feldern werden für das Hochstufen/Ausblenden von Empfehlungen die folgenden Felder unterstützt:

Textfelder

Feld description
„tags“ Product.tags[]. Benutzerdefinierte Tags, die dem Produkt zugeordnet sind.

Numerische Felder

Feld Beschreibung
„price“ PriceInfo.price. Der Preis des Produkts.
„discount“ Der Produktrabatt. Dieses Feld wird anhand des ursprünglichen Preises und der Werte des Preisfelds aus PriceInfo berechnet.
„rating“ Product.rating. Die Gesamtzahl der Bewertungen für das Produkt.
„ratingCount“ rating.ratingCount. Die Gesamtzahl der Bewertungen für das Produkt.

Empfehlungsfilterung für ein Modell festlegen

Sie können das Filtern von Empfehlungen über die Search for Commerce Console oder die Models API-Ressource aktivieren.

In der Console können Sie ein neues Modell erstellen, bei dem die Empfehlungsfilterung aktiviert ist. Sie können diese Option auch für vorhandene Modelle aktualisieren.

Mit der API-Ressource Models können Sie ein neues Modell erstellen, bei dem die Filterung von Empfehlungen aktiviert ist. Sie können diese Einstellung auch für ein vorhandenes Modell mit models.Patch aktualisieren.

Wenn in der Serving-Konfiguration, mit der Vorhersagen zurückgegeben werden, Kategorieabgleich aktiviert ist, funktioniert das Filtern nach dem Attribut „categories“ nicht, da in der Antwort nur Produktergebnisse zurückgegeben werden, die eine Kategorie mit dem Kontextprodukt gemeinsam haben.

Filterung für ein Modell mit der Console festlegen

Wählen Sie in der Search for Commerce Console beim Erstellen des Modells die Option Tags automatisch generieren aus, um Empfehlungen für dieses Modell filtern zu können.

Prüfen Sie die Kompatibilität mit anderen Einstellungen wie diversity-level und category-match-level usw., da die Gesamteffekte kombiniert werden und die Filterung zuletzt erfolgt.

  • Wenn Sie beispielsweise regelbasierte diversity-level und category attribute filtering kombinieren, erhalten Sie häufig eine leere Ausgabe.
    • Mit diversity-level=high-diversity wird das Modell gezwungen, die maximalen Ergebnisse für dieselben Kategorienstrings zu begrenzen. Das heißt, ein Ergebnis für Kategorie 1, ein Ergebnis für Kategorie 2 usw.
    • Bei der Attributfilterung mit Kategorienmetadaten (Product.categories = ANY ("category2")) werden Elemente, die nicht übereinstimmen, vom Modell verworfen.
    • Die endgültige Ausgabe enthält weniger als drei Ergebnisse.
  • Das similar-items-Modell enthält bereits eine zusätzliche Steigerung der Relevanz von Kategorien mit dem Standardwert category-match-level = relaxed-category-match. Wechseln Sie zu category-match-level=no-category-match, um das Verhalten zu deaktivieren und benutzerdefinierte Filterregeln zu verwenden.

Eine Anleitung zum Erstellen eines Empfehlungsmodells mit der Console finden Sie unter Empfehlungsmodelle erstellen.

Diese Einstellung kann für vorhandene Modelle nicht in der Console aktualisiert werden. Wenn Sie diese Einstellung für ein Modell aktualisieren möchten, verwenden Sie die API-Methode models.Patch.

Filterung für ein Modell mithilfe der API festlegen

Sie können die Empfehlungsfilterung für ein Modell aktivieren, indem Sie beim Erstellen eines neuen Modells models.Create oder beim Aktualisieren eines vorhandenen Modells models.Patch verwenden.

Legen Sie das Feld filteringOption für Ihr Modell fest, um das Filtern zu ermöglichen. Die zulässigen Werte für dieses Feld sind:

  • RECOMMENDATIONS_FILTERING_DISABLED (Standard): Die Filterung ist für das Modell deaktiviert.
  • RECOMMENDATIONS_FILTERING_ENABLED: Die Filterung ist für primäre Produkte aktiviert.

Im folgenden curl-Beispiel wird ein neues Modell mit aktivierter Filterung von Empfehlungen erstellt.

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"

Im folgenden curl-Beispiel wird die Einstellung für die Filteroption für ein vorhandenes Modell aktualisiert.

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"

Attribute als filterbar festlegen

Wenn Sie empfohlene Produkte filtern möchten, aktivieren Sie die Filterung für die Produktattribute, die Sie in Filterausdrücken verwenden. Sie können diese Einstellung in der Search for Commerce Console oder mit der Attributes API-Ressource aktualisieren.

Machen Sie nicht mehr Attribute filterbar als nötig. Die Anzahl der filterbaren Attribute ist begrenzt.

Attribute mit der Console als filterbar festlegen

Sie können ein Attribut auf der Seite „Steuerelemente“ in der Search for Commerce-Konsole als filterbar festlegen.

  1. Rufen Sie in der Search for Commerce Console die Seite Steuerelemente auf.

    Zur Seite „Steuerelemente“

  2. Rufen Sie den Tab Attribut-Einstellungen auf.

    Auf diesem Tab wird eine Tabelle mit allen Produktattributen angezeigt, für die Sie websiteweite Steuerungen festlegen können.

  3. Klicken Sie auf Steuerelemente ändern.

  4. Setzen Sie Filterable für das Produktattribut auf True.

  5. Klicken Sie auf Steuerelemente speichern.

Sie können das Attribut zum Filtern verwenden, nachdem der nächste Modelltrainingszyklus abgeschlossen ist.

Attribute mithilfe der API als filterbar festlegen

AttributesConfig steht für eine Liste von Attributen für einen Katalog.

Legen Sie das Feld AttributesConfig.filteringOption für CatalogAttribute fest. Zulässige Werte für dieses Feld:

  • RECOMMENDATIONS_FILTERING_DISABLED (Standard): Die Filterung ist für das Attribut deaktiviert.
  • RECOMMENDATIONS_FILTERING_ENABLED: Die Filterung ist für das Attribut aktiviert.

Im folgenden curl-Beispiel werden Ihre vorhandenen Produktattribute abgefragt.

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"

Im folgenden curl-Beispiel wird das Produktattribut categories als filterbar festgelegt.

Wenn Sie ein vorhandenes Attribut aktualisieren, behalten Sie die ursprünglichen Werte des Attributs für indexableOption, dynamicFacetableOption und searchableOption bei, wie sie im vorherigen Schritt angezeigt werden. Wenn das ausgewählte Attribut beim Aufrufen von attributesConfig wie im vorherigen Beispiel nicht angezeigt wurde, verwenden Sie die Standardeinstellungen, wie im folgenden Beispiel gezeigt.

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"

Sie können das Attribut zum Filtern verwenden, nachdem der nächste Modelltrainingszyklus abgeschlossen ist. Das dauert in der Regel mindestens acht Stunden.

Filterbare Attribute in einer Vorhersageanfrage verwenden

Nachdem Ihr Modell neu trainiert wurde, können Sie filterbare Produktattribute in Ihren Vorhersageanfragen verwenden.

Setzen Sie den Wert des Anfrageparameters filterSyntaxV2 auf „true“, um die Filterung von Empfehlungen der Version 2 zu aktivieren. Wenn der Parameter nicht festgelegt ist, bleibt die Filterung der Version 1 aktiv. Wenn ein Modell sowohl manuell erstellte Tags als auch filterbare Produktattribute hat, können Vorhersageanfragen mit beiden Versionen der Filterung verarbeitet werden. Es ist jedoch nicht möglich, sowohl v1- als auch v2-Filterausdrücke in dieselbe Vorhersageanfrage aufzunehmen.

Im folgenden teilweisen curl-Beispiel ist filterSyntaxV2 auf „true“ gesetzt und es wird ein Filterausdruck mit den Produktattributen colors und categories verwendet. In diesem Beispiel wird davon ausgegangen, dass colors und categories als filterbar festgelegt sind.

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

Das folgende curl-Beispiel zeigt eine vollständige Vorhersageanfrage.

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"

Neben Filtern kann auch die Einstellung für die Diversifizierung der Bereitstellungskonfiguration die Anzahl der in der Antwort zurückgegebenen Ergebnisse beeinflussen.