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 Vorhersageanfragen 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 eingegrenzt, bei denen der Ausdruck zu „wahr“ ausgewertet wird.

Es gibt zwei Versionen des Filters für Empfehlungen:

• Version 2 wird empfohlen.
• Version 1 wird nicht mehr unterstützt, wird aber möglicherweise noch verwendet.

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

Empfehlungsfilterung, Version 2

Bei Version 2 werden Produktattribute verwendet. Filterausdrücke basieren auf Produktattributen. Das können vordefinierte Systemattribute wie categories und colors oder von Ihnen definierte benutzerdefinierte Attribute wie attributes.styles sein. Wenn Sie ein Produktattribut als filterbar festlegen, können diese Attribute automatisch als Tags für den Filter von Empfehlungen verwendet werden, anstatt dass Sie Filter-Tags manuell hinzufügen müssen.

Wenn Sie Produkte mithilfe von Attributen filtern, werden in der Prognoseantwort Hauptprodukte zurückgegeben, die mindestens ein Haupt- oder Variantenprodukt mit einem Attributwert enthalten, der dem Filterausdruck entspricht. Weitere Informationen zu Haupt- und Variantenprodukten finden Sie unter Produktebenen.

Im folgenden Beispiel für einen Filterausdruck wird außerdem nach roten oder blauen Produkten gefiltert, die als „Neuerscheinung“ und nicht als Angebot 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, für das gefilterte Empfehlungen ausgeliefert werden sollen.
2. Aktivieren Sie die Filterung von Empfehlungen für Produktattribute, nach denen Sie filtern möchten.
3. Verwenden Sie filterbare Produktattribute in Anfragen für Vorhersagen.

Empfehlungsfilter, Version 1 (eingestellt)

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

Im folgenden Beispiel für einen Filterausdruck werden Filtertags verwendet, um Produkte anzugeben, die mit „Rot“ oder „Blau“ getaggt sind, sowie das Tag „Neuer-Artikel“ und nicht das Tag „Werbeartikel“:

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 Filter für nicht auf Lager befindliche Artikel 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 enthält, können Vorhersageanfragen mit beiden Filterversionen ausgeführt 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 Anzahl der Empfehlungen einzuschränken, die an Endnutzer zurückgegeben werden. Mit Vertex AI Search for Commerce können Sie Geschäftsregeln anwenden, um Kunden relevante Produktangebote zu präsentieren. Außerdem haben Sie die Möglichkeit, nach Produktverfügbarkeit, benutzerdefinierten Tags und anderen Kriterien zu filtern.

Jedes filterbare Attribut belegt in jedem Ihrer Modelle etwas Arbeitsspeicher. Mit den folgenden Limits lassen sich negative Auswirkungen auf die Anzeigenbereitstellung vermeiden:

• Bis zu 10 benutzerdefinierte Attribute können in Ihrem Katalog als filterbar festgelegt werden.

• In Ihrem Katalog können bis zu 100.000.000 filterbare Attributwerte vorhanden sein.

  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 Empfehlungen der Version 1 zusammen mit der Version 2 verwenden, wird die Anzahl der Filter-Tags auf Ihr Kontingent angerechnet. Die Anzahl der Filter-Tags darf zusammen mit der Gesamtzahl der Attributwerte nicht mehr als 100.000.000 betragen.

Wenn Sie die Limits ü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 zehn filterbare benutzerdefinierte Attribute gefunden werden, werden nur zehn verwendet.

Syntax für Empfehlungen

Die Syntax der Filterausdrücke für die Suche und Empfehlungen ist ä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 Einbettung von AND- und OR-Operatoren in Klammern ist auf eine bestimmte Tiefe beschränkt. Die logischen Ausdrücke im Filter müssen in konjunktiver Normalform (CNF) sein. Der komplexeste unterstützte logische Ausdruck kann eine 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 sich auf der obersten Ebene befinden. Sie können nicht als Teil einer OR-Klausel oder einer Negation (NOT) verwendet werden.
• Da für die Standardfilterung von Empfehlungen nur Textfelder unterstützt werden, werden die Vorgänge „kleiner als“, „größer als“ und „Bereichsprüfung“ nicht unterstützt. Vergleichsoperatoren können nur mit Bedingungen für die Empfehlungen „Bewerben“ oder „Begraben“ verwendet werden, die einige numerische Felder unterstützen (siehe Unterstützte Felder für „Bewerben“/„Begraben“).
• 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 Argumente auf dieses Limit angerechnet. colors: ANY("red", "green") OR colors: ANY("blue") hat beispielsweise drei Argumente.

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

Filterung nach Inventarattributen

Die Filterung nach inventarbezogenen Attributen basiert auf dem Echtzeitstatus Ihrer Produkte. Bei der availability: ANY("IN_STOCK")-Filterung werden in der Vorhersageantwort primäre Produkte zurückgegeben, bei denen das primäre Produkt oder ein Variantenprodukt den übereinstimmenden Wert IN_STOCK hat. Weitere Informationen zu Haupt- und Variantenprodukten finden Sie unter Produktebenen. Die Filterung 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 sind in der folgenden Tabelle zusammengefasst.

Für die Funktion „Empfehlungen hervorheben oder begraben“ werden zusätzliche Felder unterstützt, die von der standardmäßigen Filterung für Empfehlungen nicht unterstützt werden. Eine Liste dieser Felder finden Sie unter Unterstützte Felder für die Funktion „Hervorheben/Begraben“.

Unterstützte Felder hervorheben/verbergen

Für die Funktion „Bewerben“/„Begraben“ werden einige zusätzliche Felder unterstützt, die vom standardmäßigen Filtern von Empfehlungen nicht unterstützt werden, z. B. numerische Felder.

Zusätzlich zu den unter Unterstützte Felder aufgeführten Feldern werden für Empfehlungen mit „Boost“/„Bury“ die folgenden Felder unterstützt:

Textfelder

Numerische Felder

Empfehlungsfilter für ein Modell festlegen

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

In der Console können Sie ein neues Modell erstellen, für das 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 mit aktivierter Empfehlungsfilterung erstellen oder diese Einstellung für ein vorhandenes Modell mit models.Patch aktualisieren.

Wenn in der Auslieferungskonfiguration, die Vorhersagen zurückgibt, die Kategorieübereinstimmung aktiviert ist, funktioniert das Filtern nach dem Attribut „categories“ nicht, da in der Antwort nur Produktergebnisse zurückgegeben werden, die dieselbe Kategorie wie das Kontextprodukt haben.

Filter 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 die Empfehlungsfilterung für dieses Modell zu aktivieren.

Prüfe die Kompatibilität mit anderen Einstellungen wie diversity-level und category-match-level, da sich die Gesamteffekte kombinieren und die Filterung zuletzt erfolgt.

• Die Kombination von regelbasierten diversity-level und category attribute filtering führt beispielsweise häufig zu einer leeren Ausgabe.
  • diversity-level=high-diversity erzwingt, dass das Modell die maximale Anzahl von Ergebnissen für dieselben Kategoriestrings begrenzt. Das bedeutet, dass ein Ergebnis für Kategorie 1, ein Ergebnis für Kategorie 2 usw. angezeigt werden muss.
  • Bei der Attributfilterung mithilfe von Kategoriemetadaten (Product.categories = ANY ("category2")) werden im Modell Elemente verworfen, die nicht übereinstimmen.
  • Die endgültige Ausgabe enthält weniger als drei Ergebnisse.
• Das similar-items-Modell enthält bereits eine zusätzliche Steigerung der Kategorierelevanz mit dem Standard-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. Verwenden Sie die API-Methode models.Patch, um diese Einstellung für ein Modell zu aktualisieren.

Filter für ein Modell mithilfe der API festlegen

Sie können die Empfehlungsfilterung für ein Modell mit models.Create aktivieren, wenn Sie ein neues Modell erstellen, oder mit models.Patch, wenn Sie ein vorhandenes Modell aktualisieren.

Wenn Sie das Filtern zulassen möchten, müssen Sie das Feld filteringOption für Ihr Modell festlegen. Zulässige Werte für dieses Feld:

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

Im folgenden curl-Beispiel wird ein neues Modell erstellt, für das der Empfehlungsfilter aktiviert ist.

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 der 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 über die Search for Commerce Console oder über die Attributes API-Ressource aktualisieren.

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

Attribute über die Console als filterbar festlegen

Sie können ein Attribut in der Search for Commerce Console auf der Seite „Einstellungen“ als filterbar festlegen.

1. Rufen Sie in der Search for Commerce Console die Seite Einstellungen auf.
   
   Zur Seite „Steuerelemente“

2. Rufen Sie den Tab Attributeinstellungen auf.

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

3. Klicken Sie auf editSteuerelemente ändern.

4. Legen Sie für das Produktattribut Filterbar auf True fest.

5. Klicken Sie auf Steuerelemente speichern.

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

Attribute mithilfe der API als filterbar festlegen

AttributesConfig ist 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 für das Attribut ist 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, belassen Sie die ursprünglichen Werte des Attributs für indexableOption, dynamicFacetableOption und searchableOption so, wie sie im vorherigen Schritt angezeigt werden. Wenn das ausgewählte Attribut bei der Anzeige 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, sobald 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.

Legen Sie den Wert des Anfrageparameters filterSyntaxV2 auf „wahr“ fest, um die Filterung von Empfehlungen für Version 2 zu aktivieren. Wenn der Parameter nicht festgelegt ist, bleibt die Version 1-Filterung aktiv. Wenn ein Modell sowohl manuell erstellte Tags als auch filterbare Produktattribute hat, können Vorhersageanfragen mit beiden Filterversionen verarbeitet werden. Es ist jedoch nicht möglich, in derselben Vorhersageanfrage sowohl V1- als auch V2-Filterausdrücke anzugeben.

Im folgenden teilweisen curl-Beispiel ist filterSyntaxV2 auf „wahr“ 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 den Filtern kann sich auch die Diversifizierungseinstellung der Bereitstellungskonfiguration auf die Anzahl der Ergebnisse auswirken, die in der Antwort zurückgegeben werden.