「Retail」は「小売業向け Vertex AI Search」に名称変更されます。現在、新しいブランディングを反映するようにコンテンツの更新を進めています。

レコメンデーションをフィルタリングする

このページでは、商品属性を使用したレコメンデーションの結果のフィルタリングについて説明します。

予測リクエストでフィルタ式を指定すると、予測結果をフィルタリングできます。フィルタ式は、各商品に対して評価される論理式です。レスポンス内の商品のリストは、式が true と評価された商品に絞られます。

レコメンデーションのフィルタリングには次の 2 つのバージョンがあります。

バージョン 2 をおすすめします。
バージョン 1 は非推奨ですが、まだ使用されている可能性があります。

この入門ガイドのセクションは、商品属性を使用してレコメンデーションをフィルタリングする、バージョン 2 のフィルタリングにのみ適用されます。

レコメンデーションフィルタリング、バージョン 2

バージョン 2: 商品属性を使用します。フィルタ式は、商品属性に基づいています。これは、categories や colors などの事前定義されたシステム属性や、attributes.styles などの定義したカスタム属性です。商品の属性をフィルタ可能に設定すると、レコメンデーションが属性を自動的にレコメンデーションフィルタリングのタグとして使用するようになります（手動でフィルタタグを追加する必要はありません）。

属性を使用して商品をフィルタリングする場合、予測レスポンスは、少なくとも 1 つのプライマリ商品またはフィルタ式に一致する属性値を持つバリエーション商品を含むプライマリ商品を返します。プライマリ商品とバリエーション商品の詳細については、商品レベルをご覧ください。

次のフィルタ式の例では、「New-Arrival」として設定された赤または青の商品で、プロモーションとして設定されていない商品をフィルタします。

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

レコメンデーションのバージョン 2 のフィルタリングを使用するには、次の手順を行います。各手順は、このページの後半で説明します。

フィルタリングされたレコメンデーションを提供するモデルのレコメンデーションフィルタを有効にします。
フィルタの対象とする商品属性のレコメンデーションフィルタを有効にします。
予測リクエストでフィルタ可能な商品属性を使用します。

レコメンデーションフィルタリング、バージョン 1（非推奨）

バージョン 1: 手動で作成したフィルタタグを使用します。フィルタ式はフィルタタグに基づいており、フィルタするカタログ内の商品に手動で追加する必要があります。

次のフィルタ式の例では、フィルタタグを使用して「赤」または「青」のタグと「新着」タグが付き、「プロモーション」のタグが付いていない商品を指定します。

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

Product.tags[] フィールドの API リファレンスドキュメントをご覧ください。

Tag 式には、ブール演算子 OR または NOT を含めることができます。これらの演算子は、Tag 値から 1 つ以上のスペースで区切られている必要があります。Tag 値の直前にダッシュ（-）を付けることもできます。これは NOT 演算子と同等です。ブール演算子を使用する Tag 式は、かっこで囲む必要があります。

タグに加えて、filterOutOfStockItems でフィルタできます。filterOutOfStockItems フラグは、stockState が OUT_OF_STOCK の商品をすべて除外します。

タグフィルタと在庫切れフィルタを組み合わせると、指定されたすべてのフィルタ式を満たすアイテムのみが返されるようになります。

フィルタ文字列の例:

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

"filter": "filterOutOfStockItems"

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

次の例では、spring-sale タグまたは exclusive タグ（あるいはその両方）があり、items-to-exclude タグがない在庫のあるアイテムのみを返します。

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

属性フィルタとタグフィルタの互換性

モデルに手動で作成されたタグとフィルタ可能な商品属性の両方がある場合は、どちらのバージョンのフィルタリングでも予測リクエストを処理できます。ただし、同じ予測リクエストに v1 と v2 の両方のフィルタリング式を含めることはできません。

レコメンデーションのフィルタリングの上限

フィルタリング可能な属性ごと、モデルごとにメモリが消費されます。次の上限は、サービスのパフォーマンスに対する悪影響を防ぐのに役立ちます。

カタログ内で最大 10 個のカスタム属性をフィルタ可能に設定できます。
カタログには、最大 100,000,000 個のフィルタ可能な属性値を含めることができます。

カタログ内の属性値の合計数は、カタログ内の商品数にフィルタ可能な属性の数を掛けることで見積もることができます。

たとえば、1,000 個の商品を含むカタログと 3 つの属性がフィルタ可能に設定されている場合、属性値の合計数は 3×1,000=3, 000 と推定できます。

バージョン 1 のレコメンデーションフィルタリングをバージョン 2 と併用する場合は、フィルタタグの数が割り当てに加算されます。属性値の合計に加算されるフィルタタグの数が 100,000,000 未満であることを確認してください。

上限を超えると、追加の属性をフィルタ可能に設定できなくなります。これらの上限を超える必要がある場合は、割り当ての増加をリクエストしてください。

タグの総数はモデルのトレーニング中に計算されます。合計数が上限を超えると、モデルのトレーニングが失敗します。モデルのトレーニング中にフィルタ可能なカスタム属性が 10 個より多く見つかった場合は、10 個のみが使用されます。

レコメンデーションのフィルタ式の構文

検索とレコメンデーションのフィルタ式構文は類似しています。ただし、レコメンデーションにはいくつかの制限があります。

レコメンデーションのフィルタ式の構文は、次の 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 string. You must escape backslash (\) and
  # quote (") characters.
  literal = double-quoted string;

  textual_field = see the tables below;

フィルタ構文の制限

次の制限が適用されます。

AND 演算子と OR 演算子をかっこに埋め込む深さには制限があります。フィルタの論理式は連言標準形（CNF）にする必要があります。サポートされる論理式で最も複雑なものは、OR 演算子のみを含む AND 句の連結リストです（例: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)）。
式は NOT キーワードまたは - で否定できます。これは、在庫に関連する属性を含まない 1 つの引数を持つ ANY() 式でのみ機能します。
availability ベースの制限は最上位に存在する必要があります。OR 句または否定（NOT）の一部として使用することはできません。
標準レコメンデーションフィルタリングはテキストフィールドのみをサポートするため、標準レコメンデーションフィルタリングでは、次より小さい、次より大きい、または範囲チェックのオペレーションはサポートされません。次より小さい、および、次より大きいのオペレーションは、一部の数値フィールドをサポートするレコメンデーションブースト/ベリー制御条件でのみ使用できます（ブースト/ベリー対応のフィールドをご覧ください）。
最上位の AND 句の用語の最大数は 20 です。
OR 句には、ANY() 式に含める引数を最大 100 個まで指定できます。OR 句に複数の ANY() 式がある場合、それらの引数はすべてこの上限にカウントされます。たとえば、colors: ANY("red", "green") OR colors: ANY("blue") には 3 つの引数があります。

次の表に、有効なフィルタ式の例、無効な例、無効な理由を示します。

Expression	有効	メモ
`colors: ANY("red", "green")`	○
`NOT colors: ANY("red")`	○
`NOT colors: ANY("red", green")`	No	複数の引数を使用して「ANY()」を否定します。
`colors: ANY("red", "green") OR categories: ANY(\"Phone > Android > Pixel\")`	○
`(colors: ANY("red") OR colors: ANY("green")) AND categories: ANY(\"Phone > Android > Pixel\")`	○
`(colors: ANY("red") AND colors: ANY("green")) OR categories: ANY(\"Phone > Android > Pixel\")`	No	連言標準形ではありません。
`(colors: ANY("red")) AND (availability: ANY("IN_STOCK")`	○
`(colors: ANY("red")) OR (availability: ANY("IN_STOCK"))`	No	`OR` 式の `availability` を他の条件と結合します。

在庫に関連する属性のフィルタリング

在庫に関連する属性のフィルタリングは、商品のリアルタイムの状態に基づきます。

IN_STOCK は、レコメンデーションフィルタリングのバージョン 2 でサポートされる唯一の availability 属性値です。

在庫に関連する属性は AND 句で使用できますが、OR 句では使用できません。

サポートされるフィールド

サポートされているテキスト項目を次の表にまとめます。

レコメンデーションのブースト/ベリーは、標準レコメンデーションフィルタリングではサポートされていない追加のフィールドをサポートしています。レコメンデーションのブースト/ベリーでサポートされているその他のフィールドのリストについては、ブースト/ベリーのサポートされているフィールドをご覧ください。

フィールド	説明
「productId」	商品 ID（Product.name の最後のセグメント）。
「brands」	Product.brands。
「categories」	Product.categories。
「genders」	Audience.genders。
「ageGroups」	Audience.age_groups。
"colorFamilies"	ColorInfo.color_families。
「colors」	ColorInfo.colors。
「sizes」	Product.sizes。
「materials」	Product.materials。
「patterns」	Product.patterns。
「conditions」	Product.conditions。
「attributes.key」	商品オブジェクトのテキストカスタム属性。属性値がテキストの場合、キーは、Product.attributes マップ内の任意のキーです。

ブースト/ベリー対応フィールド

ブースト/ベリーは、数値フィールドなど、標準レコメンデーションフィルタリングではサポートされていない追加のフィールドをサポートしています。

サポートされているフィールドにリストされているフィールドに加えて、レコメンデーションのブースト/ベリーは次のフィールドをサポートしています。

テキストフィールド

フィールド	説明
「tags」	`Product.tags[]`。商品に関連付けられたカスタムタグ。

数値フィールド

フィールド	説明
「price」	`PriceInfo.price`。商品の価格。
「discount」	商品の割引。このフィールドは、`PriceInfo` の元の価格と price フィールド値を使用して計算されます。
「rating」	`Product.rating`。商品に対する評価の合計数。
「ratingCount」	`rating.ratingCount`。商品に対する評価の合計数。

モデルのレコメンデーションのフィルタリングを設定する

レコメンデーションのフィルタリングを有効にするには、Retail コンソールまたは Models API リソースを使用します。

コンソールから、レコメンデーションフィルタリングが有効な新しいモデルを作成できます。このオプションは既存のモデルで更新することもできます。

Models API リソースを使用して、レコメンデーションフィルタリングが有効な新しいモデルを作成するか、models.Patch を使用して既存のモデルに対してこの設定を更新します。

予測を返すサービス提供構成でカテゴリマッチングが有効になっている場合、レスポンスではコンテキスト商品とカテゴリを共有する商品の結果のみが返されるため、「カテゴリ」属性は機能しません。

コンソールを使用してモデルのフィルタリングを設定する

モデルの作成中に Search for Retail コンソールを使用して [タグを自動生成] を選択し、そのモデルのレコメンデーションフィルタリングを有効にします。

コンソールを使用してレコメンデーションモデルを作成する手順については、レコメンデーションモデルの作成をご覧ください。

この設定は、既存モデルのコンソールでは更新できません。モデルのこの設定を更新するには、models.Patch API メソッドを使用します。

API を使用してモデルのフィルタリングを設定する

モデルのレコメンデーションフィルタを有効にするには、新しいモデルを作成するときに models.Create を使用するか、既存のモデルを更新するときに models.Patch を使用します。

フィルタリングを許可するには、モデルの filteringOption フィールドを設定します。このフィールドに指定できる値は次のとおりです。

RECOMMENDATIONS_FILTERING_DISABLED（デフォルト）: モデルのフィルタリングがオフです。
RECOMMENDATIONS_FILTERING_ENABLED: プライマリプロダクトのフィルタリングがオンです。

次の curl の例では、レコメンデーションフィルタリングが有効な新しいモデルを作成します。

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"

次の curl の例では、既存のモデルのフィルタリングオプション設定を更新します。

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"

属性をフィルタ可能に設定する

おすすめの商品をフィルタリングするには、フィルタ式で使用する商品属性のフィルタリングを有効にします。この設定は、Search for Retail コンソールまたは Attributes API リソースを使用して更新できます。

必要以上にフィルタ可能な属性を設定しないでください。フィルタリング可能な属性の数には制限があります。

コンソールを使用して属性をフィルタ可能に設定する

属性は、Search for Retail コンソールのフィルタ可能な [コントロール] ページとして設定できます。

Search for Retail コンソールの [コントロール] ページに移動します。

[コントロール] ページに移動
[属性コントロール] タブに移動します。

このタブには、サイト全体のコントロールを設定できるすべての商品属性の表が表示されます。
[Control Controls] をクリックします。
商品属性の [フィルタ可能] を [True] に設定します。
[コントロールを保存] をクリックします。

この属性は、次のモデルトレーニングサイクルが完了した後にフィルタリングに使用できます。

API を使用して属性をフィルタ可能に設定する

AttributesConfig は、カタログの属性のリストを表します。

CatalogAttribute の AttributesConfig.filteringOption フィールドを設定します。このフィールドに指定できる値は次のとおりです。

RECOMMENDATIONS_FILTERING_DISABLED（デフォルト）: 属性のフィルタリングがオフです。
RECOMMENDATIONS_FILTERING_ENABLED: 属性のフィルタリングがオンです。

次の curl の例では、既存の商品属性をクエリします。

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"

次の curl の例では、商品属性 categories がフィルタ可能に設定されています。

既存の属性を更新する場合は、前の手順の indexableOption、dynamicFacetableOption、searchableOption の属性を元の値のままにします。前の例のように attributesConfig を表示したときに、選択した属性が表示されない場合は、次の例に示すようにデフォルト設定を使用します。

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"

この属性は、次のモデルトレーニングサイクルが完了した後にフィルタリングに使用できます。

予測リクエストでフィルタ可能な属性を使用する

モデルを再トレーニングしたら、予測リクエストでフィルタ可能な商品属性を使用できます。

リクエストパラメータ値 filterSyntaxV2 を true に設定して、バージョン 2 のレコメンデーションフィルタリングを有効にします。このパラメータを設定しない場合、バージョン 1 のフィルタリングはアクティブのままになります。モデルに手動で作成されたタグとフィルタ可能な商品属性の両方がある場合は、どちらのバージョンのフィルタリングでも予測リクエストを処理できます。ただし、同じ予測リクエストに v1 と v2 の両方のフィルタリング式を含めることはできません。

次の curl の一部の例は、filterSyntaxV2 が true に設定され、商品属性 colors と categories を使用したフィルタ式を示しています。この例では、colors と categories がフィルタ可能に設定されていることを前提としています。

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

次の curl の例は、完全な予測リクエストを示しています。

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\")',
        useMostRecentServingConfig: true
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/placements/SERVING_CONFIG:predict"

フィルタに加えて、サービス提供構成の多様化設定は、レスポンスによって返される結果の数に影響する可能性もあります。

レコメンデーションをフィルタリングする

レコメンデーション フィルタリング、バージョン 2

レコメンデーション フィルタリング、バージョン 1（非推奨）

属性フィルタとタグフィルタの互換性

レコメンデーションのフィルタリングの上限

レコメンデーションのフィルタ式の構文

フィルタ構文の制限

在庫に関連する属性のフィルタリング

サポートされるフィールド

ブースト/ベリー対応フィールド

テキスト フィールド

数値フィールド

モデルのレコメンデーションのフィルタリングを設定する

コンソールを使用してモデルのフィルタリングを設定する

API を使用してモデルのフィルタリングを設定する

属性をフィルタ可能に設定する

コンソールを使用して属性をフィルタ可能に設定する

API を使用して属性をフィルタ可能に設定する

予測リクエストでフィルタ可能な属性を使用する

レコメンデーションフィルタリング、バージョン 2

レコメンデーションフィルタリング、バージョン 1（非推奨）

テキストフィールド