このページでは、ブースト サービス提供コントロール(コントロールとも呼ばれます)を使用して、モデルから返されるメディアの推奨事項のランキング位置を変更する方法について説明します。
ブースト制御は、モデルから推奨事項が返された後に、推奨事項の順序を変更します。フィルタ式を結果に適用して、ブーストまたはベリーするレコメンデーションを特定し、-1 ~+1 のブースト値を適用します。ブースト値 +1 は、推奨事項に最大のブーストを与え、返される推奨事項の最上位に配置します。値 -1 は、返された推奨事項のリストの下部に推奨事項を埋め込みます。
ブーストはサービス提供時のコントロールです。まず、レコメンデーション モデルがレコメンデーションのリストを返します。サービス構成を使用して、ブースト コントロールがそのリストに適用され、おすすめのランキングが調整されます。ブースト コントロールは、おすすめの追加や削除は行いませんが、おすすめがユーザーに表示される順序を制御します。
レコメンデーションのブーストとフィルタリング
ブーストはソフト フィルタです。一方、レコメンデーションのフィルタで説明されているレコメンデーションの通常のフィルタは、ハードフィルタです。
レコメンデーションにハードフィルタを適用すると、フィルタで除外されたドキュメントは表示されなくなります。ただし、ソフトフィルタでは、おすすめのリストからドキュメントは削除されません。代わりに、フィルタは、返されるレコメンデーションのリストでどのドキュメントを上位または下位にすべきかを判断するために使用されます。
レコメンデーション モデルの過負荷を回避する
ブーストまたは埋め込みフィルタを適用する場合は、ゼロに近い小さな値をおすすめします。値が +1 または -1 に近いと、レコメンデーション モデルが過剰に反応し、モデルによって適用されるレコメンデーション ランキングが、ユーザーに表示されるレコメンデーションの順序に反映されない可能性があります。
たとえば、アニメーション映画を +1 でブーストすると、ユーザーにはアニメーション映画のみがおすすめリストの上部に表示されます。これにより、モデルによって強く推奨されたアニメーション以外の映画がリストの下部に押し下げられ、ユーザーに表示されない可能性があります。
降格と非表示
降格と埋め込みの両方で、推奨事項が返されるリスト内の位置が、通常よりも下になります。
ただし、降格は、コンテンツの古さや、ユーザーがすでにコンテンツの一部を視聴しているかどうかに基づいて行われます。降格の詳細については、メディア レコメンデーションの降格をご覧ください。
非表示は、フィルタで特定されたコンテンツに適用されます。フィルタには、スキーマでフィルタ可能としてマークされた任意のデータ フィールドを指定できます。フィールドをフィルタ可能としてマークする方法など、レコメンデーション フィルタに関する一般的な情報については、レコメンデーションをフィルタリングするをご覧ください。
ブースト コントロールとサービス構成について
各ブーストサービング コントロールは、フィルタとブースト値で構成されています。たとえば、1 つのブースト制御で、タイトルに「クリスマス」が含まれる映画を 0.1
の値でブーストし、別のブースト制御で、ホラー映画を -0.2
の値で非表示にします。
1 つ以上のブースト コントロールを作成したら、そのコントロールをサービス構成に関連付けます。Vertex AI Search アプリを作成すると、デフォルトのサービス構成も自動的に作成されます。サービス構成は、サービス時に参照され、アプリが生成する結果を決定します。サービス提供構成には、ブースト コントロールに加えて、多様化コントロールや降格コントロールなど、他のタイプのコントロールを含めることができます。
サービス構成は、recommend メソッドを呼び出すときに適用できます。サービス構成内のすべてのコントロールが、メソッド呼び出しによって返されたレコメンデーションに適用されます。
さらに、アプリに関連付けることができるサービス構成は複数あります。これにより、状況に応じて異なるコントロールのセットを適用できます。たとえば、おすすめのリクエストがお子様のアカウントから送信された場合は、お子様向けのカテゴリの映画を上位に表示し、不適切な映画を非表示にします。同様に、リクエストが成人向けとマークされたアカウントから送信された場合は、成人に人気のタイトルやカテゴリをブーストします。また、地域ごとに異なるサービング構成を設定し、地域で人気のあるコンテンツをブーストすることもできます。サービス提供構成の詳細については、メディア サービス提供構成の作成と管理をご覧ください。
ブースト値は加算される
複数のサービス提供コントロールをサービス構成にアタッチした場合、ブーストと埋め込みは加算されます。
たとえば、子供向けアニメ映画のブースト値を 0.3、アニメ アドベンチャー映画のブースト値を 0.4 に設定した場合、子供向けアニメ アドベンチャーに分類される映画のブースト値は 0.7 になります。
同様に、ホラー映画が同じサービス構成で 1 つのコントロールによって 0.2 増加し、別のコントロールによって -0.3 減少した場合、最終的な結果は映画が -0.1 減少することになります。
ブーストの合計は +1 を超えることがあります。たとえば、子供向けアニメ映画のブーストが 0.6、アニメ アドベンチャー映画のブーストが 0.5 の場合、子供向けアニメ アドベンチャー映画のブーストは +1.1 になります。
フィルタの例
メディア レコメンデーションのフィルタの例を次に示します。
一般的なキー プロパティのフィルタ
一般的なキー文字列プロパティ(category
、image_name
、image_uri
、language
、title
、uri
)のフィルタの例。
子供向けアニメーション:
"filter": "categories: ANY(\"animation\") AND categories: ANY(\"children\")"
怖いメディア:
"filter": "categories: ANY(\"horror\", \"thriller\", \"crime\")
タイトルが「クリスマス」のメディア:
"filter": "title: ANY(\"Christmas\")"
images
配列の最初のアイテムのname
が「ビーチボール」であるメディア:
"filter": "images[0].name: ANY(\"beach ball\")"
メディアキーのプロパティでフィルタ
メディアキーのプロパティのフィルタの例。メディアキーのプロパティは media_
で始まり、フィルタ構文では、フィールド名の前に media_key_properties.
が付きます。メディアキー プロパティの一覧については、Google の事前定義済みスキーマとカスタム スキーマをご覧ください。
タイプが
audio
のメディア:
"filter": "media_key_properties.media_type: ANY(\"audio\")"
hash_tags 配列に文字列
#winter
が含まれているメディア:
"filter": "media_key_properties.hash_tags: ANY(\"#winter\")"
hash_tags 配列の最初の要素が文字列
#winter
のメディア:
"filter": "media_key_properties.hash_tags[0]: ANY(\"#winter\")"
カスタム フィールド
カスタム フィールドのフィルタの例。カスタム属性の場合は、フィールド名の前に attributes.
を付けます。
スキーマに、映画がプレミア上映された映画祭を表すカスタム文字列フィールド
festival
があります。カンヌでプレミア上映された映画のみをフィルタするには:
"filter": "attributes.festival: ANY(\"Cannes\")
視覚障がいのある視聴者向けの音声解説がメディアに含まれている場合に true になるカスタム ブール値フィールド
audio_desc
があります。音声による説明付きのメディアをフィルタするには:
"filter": "attributes.audio_desc: ANY(true)"
フィルタリング可能なフィールドの制限事項
ブースト サービス管理には次の制限が適用されます。
ブーストのフィルタ式で使用できるのは、文字列型とブール型のプロパティ フィールドのみです。
2 つ以上のレベルでネストされたフィールドでフィルタすることはできません。たとえば、
persons.name
でフィルタリングできますが、フィールドpersons.name.stage
でフィルタリングすることはできません(そのようなフィールドが存在する場合でも)。フィルタは完全一致である必要があります。つまり、例では、「
Christmas Story
」または「CHRISTMAS
」という映画はブーストされません。
始める前に
メディア レコメンデーション アプリとデータストアが作成されていることを確認します。詳細については、メディア レコメンデーション アプリとデータストアを作成するをご覧ください。
省略可: デフォルトのサービング構成を使用しない場合は、サービング構成を作成するの手順 1 ~ 5 と 7 に沿って新しいサービング構成を作成します。アプリが本番環境にある場合は、ブースト制御を本番環境のサービング構成に適用する前に、ブースト制御のテスト用に別のサービング構成を作成することをおすすめします。
ブースト制御で使用するフィールドは、スキーマで Filterable としてマークされていることを確認します。詳細については、フィールド設定を構成するをご覧ください。フィルタリングの上限もご覧ください。
推奨事項をブーストまたはベリーする
この手順では、ブースト コントロールを作成して、サービス提供構成にコントロールを関連付ける方法について説明します。
コントロールがサービス構成に関連付けられたら、servingConfigs.recommend
メソッドを呼び出すときにサービス構成を指定できます。ブースト コントロールは、返されるレコメンデーションの順序に影響を与えるために使用されます。
REST
ブースト サービス提供コントロールを作成してサービス提供構成にアタッチする手順は次のとおりです。
アプリ ID を確認します。アプリ ID がすでにある場合は、次のステップに進みます。
Google Cloud コンソールで、[AI アプリケーション] ページに移動します。
[アプリ] ページで、アプリの名前を見つけ、[ID] 列からアプリの ID を取得します。
データストア ID を確認します。データストア ID がすでにある場合は、次のステップに進みます。
Google Cloud コンソールで、[AI アプリケーション] ページに移動し、ナビゲーション メニューで [データストア] をクリックします。
データストアの名前をクリックします。
データストアの [データ] ページで、データストア ID を取得します。
ブースト コントロールを作成します。
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -H "X-Goog-User-Project: PROJECT_NUMBER" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \ -d '{ "displayName": "CONTROL_DISPLAY_NAME", "solutionType": "SOLUTION_TYPE_RECOMMENDATION", "boostAction": { "dataStore": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/dataStores/DATA_STORE_ID", "boost" : BOOST_VALUE, "filter": "FILTER" } }'
次のように置き換えます。
PROJECT_NUMBER
: Google Cloud プロジェクトの番号。CONTROL_DISPLAY_NAME
: コントロールを識別するための人が読める形式の名前。最大長が 128 文字の UTF-8 文字列である必要があります。CONTROL_ID
: コントロールの固有識別子(データストア内)。ID には、小文字、数字、ハイフン、アンダースコアを使用できます。APP_ID
: Vertex AI Search アプリの ID。DATA_STORE_ID
: Vertex AI Search データストアの ID。BOOST_VALUE
: [-1,1] の範囲の浮動小数点数。値が負の場合、結果の下位に推奨事項が表示されます。値が正の場合、推奨事項は昇格されます(結果の上位に表示されます)。FILTER
: ブーストまたは非表示にするドキュメントを記述するフィルタ式。フィルタ式を作成する方法の詳細については、フィルタ式をご覧ください。
レコメンデーションに適用するブースト コントロールごとに、ステップ 3 を繰り返します。たとえば、子供向けの映画をブーストする 1 つのブースト コントロール
boost-kids
と、ホラー映画を埋め込む 2 つ目のコントロールbury-horror
が必要になる場合があります。サービス提供構成の ID を確認します。サービス提供構成 ID がすでにある場合は、次のステップに進みます。
Google Cloud コンソールで、[AI アプリケーション] ページに移動します。
[アプリ] ページで、アプリの名前をクリックします。
[構成] ページに移動し、[サービス提供] タブをクリックします。
[ID] 列からサービス提供構成 ID を取得します。
engines.servingConfigs.patch
メソッドを使用して、更新リクエストで新しいブースト サービス提供コントロールをサービス構成に関連付けます。curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/CONFIG_ID?update_mask=boost_control_ids" \ -d '{ "boostControlIds": ["CONTROL_ID"] }'
次のように置き換えます。
CONFIG_ID
: ブースト コントロールを関連付けるサービング構成の ID(例:my_app-1234567_id
)。前の手順を参照してください。CONTROL_ID
: サービス提供構成に接続する 1 つ以上のブースト サービス提供コントロールの ID が含まれます(例:"boost-kids", "bury-horror"
)。これは文字列の配列です。複数の ID がある場合は、区切り記号の引用符とカンマを使用することを忘れないでください。
結果が反映されるまで数分待ちます。
ブースト制御の効果をプレビューします。メディア レコメンデーションを取得するをご覧ください。
ブースト コントロールを更新する
この手順では、既存のブースト コントロールを更新して、ブーストまたはフィルタの値を変更する方法について説明します。
ブースト コントロールをテストした後、ブーストを強くしたり弱くしたりしたいと思うことがあります。また、フィルタ文字列を変更することもできます。
ブースト値またはフィルタを更新する場合は、engines.controls.patch
メソッドを呼び出します。
patch メソッドは、boost
と filter
の値を指定した新しい値に置き換えます。この手順では、boost
値(ステップ 3)と filter
値(ステップ 4)を個別に編集する方法を示します。両方を編集する場合は、1 つの curl コマンドで実行できます。
REST
既存のコントロールのフィルタのブースト値を変更する手順は次のとおりです。
アプリ ID を確認します。アプリ ID がすでにある場合は、次のステップに進みます。
Google Cloud コンソールで、[AI アプリケーション] ページに移動します。
[アプリ] ページで、アプリの名前を見つけ、[ID] 列からアプリの ID を取得します。
engines.servingConfigs.get
メソッドを使用して、更新するブースト コントロールの ID を見つけます。ID がすでにある場合は、次のステップに進みます。curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls"
次のように置き換えます。
PROJECT_ID
: 実際の Google Cloud プロジェクト ID。APP_ID
: Vertex AI Search アプリの ID。
コントロールのブースト値を編集します。
curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID?update_mask=boost_action.boost" \ -d '{ "name": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID", "boostAction": { "boost": BOOST_VALUE } }'
次のように置き換えます。
PROJECT_ID
: 実際の Google Cloud プロジェクト ID。APP_ID
: Vertex AI Search アプリの ID。CONTROL_ID
: 編集するブースト制御の一意の識別子。ステップ 2 でGET
コマンドによって出力されたname
フィールドの最後の部分。例:boost-kids
BOOST_VALUE
: [-1,1] の範囲の浮動小数点数。値が負の場合、結果の下位に推奨事項が表示されます。値が正の場合、推奨事項は昇格されます(結果の上位に表示されます)。
ブースト コントロールのフィルタを編集します。
curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID?update_mask=boost_action.filter" \ -d '{ "name": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID", "boostAction": { "filter": "FILTER" } }'
次のように置き換えます。
PROJECT_ID
: 実際の Google Cloud プロジェクト ID。APP_ID
: Vertex AI Search アプリの ID。CONTROL_ID
: 編集するブースト制御の一意の識別子。ステップ 2 のGET
コマンドで出力されたname
フィールドの最後の部分。FILTER
: ブーストまたは非表示にするドキュメントを記述するフィルタ式。フィルタ式を作成する方法の詳細については、フィルタ式をご覧ください。
ブースト コントロールを削除する
この手順では、ブースト制御を削除する方法について説明します。ブースト制御を使用していない場合は、許可されている制御の数の割り当てに達したり、割り当てを超えたりしないように、ブースト制御を削除することをおすすめします。
ブースト制御を削除するときは、engines.controls.delete
メソッドを呼び出します。
サービス構成に関連付けられているブースト コントロールは削除できません。ブースト制御を削除しようとすると、エラー メッセージにサービング構成の名前が表示されます。次に、そのサービス構成を削除するか、サービス構成からコントロールを切り離す必要があります。
REST
ブースト制御を削除する手順は次のとおりです。
アプリ ID を確認します。アプリ ID がすでにある場合は、次のステップに進みます。
Google Cloud コンソールで、[AI アプリケーション] ページに移動します。
[アプリ] ページで、アプリの名前を見つけ、[ID] 列からアプリの ID を取得します。
engines.servingConfigs.get
メソッドを使用して、削除するブースト制御の ID を見つけます。ID がすでにある場合は、次のステップに進みます。curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls"
次のように置き換えます。
PROJECT_ID
: 実際の Google Cloud プロジェクト ID。APP_ID
: Vertex AI Search アプリの ID。
出力を確認します。サービス構成にブースト コントロールが関連付けられている場合は、サービス構成を更新して、削除するコントロールを削除します。サービス構成を更新してブースト コントロールを削除するをご覧ください。
次の curl コマンドを実行して、ブースト制御を削除します。
curl -X DELETE \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID"
次のように置き換えます。
PROJECT_ID
: 実際の Google Cloud プロジェクト ID。APP_ID
: Vertex AI Search アプリの ID。CONTROL_ID
: 削除するブースト制御の一意の識別子。ステップ 2 のGET
コマンドで出力されたname
フィールドの最後の部分。
コントロールが 1 つ以上のサービング構成でアクティブに参照されていることを示すエラー メッセージが表示された場合は、サービング構成を更新してブースト コントロールを削除するをご覧ください。
サービス構成を更新してブースト コントロールを削除する
ブースト コントロールを削除する前に、すべてのサービング コントロールからブースト コントロールを切り離す必要があります。これを行うには、サービス提供コントロールにパッチを適用して、ブースト コントロールの ID を削除します。
ブースト コントロールをサービス構成から切り離すには、次の操作を行います。
engines.servingConfigs.get
リクエストを行い、レスポンスのboostControlIds
フィールドを確認して、サービス提供構成に適用されているブースト コントロールを特定します。curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/CONFIG_ID"
次のように置き換えます。
PROJECT_ID
: 実際の Google Cloud プロジェクト ID。APP_ID
: Vertex AI Search アプリの ID。CONFIG_ID
: 詳細を確認するサービス提供構成の ID。
サービス構成を更新してブースト コントロールを 1 つ削除するには、
engines.servingConfigs.patch
メソッドを使用します。curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/CONFIG_ID?update_mask=boost_control_ids" \ -d '{ "boostControlIds": ["CONTROL_ID"] }'
次のように置き換えます。
CONFIG_ID
: ブースト コントロールを関連付けるサービング構成の ID(例:my_app-1234567_id
)。前の手順を参照してください。CONTROL_ID
: サービス提供構成に含めるブースト制御の ID を 1 つ以上含む。削除するブースト コントロールは省略してください。これは文字列の配列です。複数の ID がある場合は、区切り記号として引用符とカンマを使用してください(例:boost-1", "boost-2
)。