增加或減少媒體推薦內容

本頁說明如何使用提升放送控制項 (也稱為控制項)，變更模型傳回的媒體建議排名位置。

模型傳回建議後，升級控制項會變更建議的順序。您可以對結果套用篩選運算式，找出要提升或隱藏的建議，然後套用介於 -1 和 +1 之間的提升值。如果升幅值為 +1，系統會將建議升級至最高等級，並顯示在建議結果最上方。值為 -1 會將建議埋藏在傳回的建議清單底部。

提高排名是放送時間控制項。首先，建議模型會傳回建議清單。接著，系統會使用供應設定將升幅控制項套用至該清單，以調整建議的排名。升級控制項不會新增或刪除建議，但會控管向使用者顯示建議的順序。

提高與篩選建議

「升級」是柔和的濾鏡，而「篩選最佳化建議」一節所述的建議一般篩選器，則是嚴格篩選器。

如果對建議內容套用嚴格篩選器，系統就不會顯示遭篩除的文件。不過，使用軟性篩選條件時，系統不會從建議清單中移除文件。而是用來決定在傳回的建議清單中，哪些文件應排在較高或較低的位置。

避免讓建議模型過於複雜

套用提高或隱藏篩選條件時，建議使用接近零的小值。如果值接近 +1 或 -1，可能會導致推薦內容模型過度運算，因此模型套用的推薦內容排名不會反映在使用者看到的推薦內容順序中。

舉例來說，如果將動畫片設為 +1，使用者只會在建議清單頂端看到動畫片；這樣一來，模型高度推薦的非動畫片就會被擠到清單底部，使用者可能看不到。

降級與隱藏

降級和隱藏都會將建議移至建議清單的較低位置，否則建議會顯示在清單中。

不過，降級是根據內容的發布時間，或使用者是否已觀看部分內容而定。如要進一步瞭解如何降低媒體推薦內容的排名，請參閱「降低媒體推薦內容的排名」。

隱藏功能適用於篩選器識別的內容。篩選器可以是結構定義中標示為可篩選的任何資料欄位。如要瞭解建議篩選器的一般資訊，包括如何將欄位標示為可篩選，請參閱「篩選建議」。

關於提高曝光度控制項和放送設定

每個提升放送控制選項都包含篩選條件和提升值。舉例來說，其中一個升幅控制項會將片名含有「聖誕節」的電影升幅設為 0.1，另一個則會將恐怖片升幅設為 -0.2。

建立一或多個升幅控制項後，請將控制項附加至供應設定。建立 Vertex AI Search 應用程式時，系統也會自動建立預設的服務設定。供應設定會在供應時參照，以決定應用程式產生的結果。除了提升控制選項，放送設定還可包含其他類型的控制選項，例如多樣化和降級控制選項。

呼叫 recommend 方法時，可以套用供應設定。然後，放送設定中的所有控制項都會套用至方法呼叫傳回的建議。

此外，您可以為應用程式建立多項供應設定，在不同情況下套用不同的控制項組合。舉例來說，如果推薦要求來自孩子的帳戶，請提高適合兒童的電影類別，並隱藏不適合的電影。同樣地，如果要求來自標示為成人的帳戶，請提升成人喜愛的影片標題或類別。或者，您也可以選擇為不同地理位置設定不同的放送設定，並根據區域熱門內容來宣傳內容。如要進一步瞭解放送設定，請參閱「建立及管理媒體放送設定」。

增幅值會累加

如果已將多個供應控管機制附加至供應設定，則升級和降級會變成加法。

舉例來說，如果將兒童動畫片和動畫冒險片分別調高 0.3 和 0.4，則歸類為兒童動畫冒險片的電影會調高 0.7。

同樣地，如果某部恐怖片在同一個放送設定中，因某項控制項而獲得 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 陣列中的第一個項目包含「beachball」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\")。

• 您有一個自訂布林值欄位 audio_desc，如果媒體包含為視障觀眾提供的口述影像內容，這個欄位就會設為 true。如要篩選出含有口述影像的媒體內容，請按照下列步驟操作：
  "filter": "attributes.audio_desc: ANY(true)"

可篩選欄位的限制

放送量提升控制選項有以下限制：

• 只有字串和布林值類型的屬性欄位，才能用於提升的篩選運算式。

• 您無法篩選巢狀層級超過一級的欄位。舉例來說，您可以篩選 persons.name，但無法篩選 persons.name.stage 欄位 (即使有這類欄位)。

• 篩選條件必須完全相符。也就是說，在範例中，系統不會宣傳名為「Christmas Story」或「CHRISTMAS」的電影。

事前準備

• 請確認您已建立媒體推薦應用程式和資料儲存庫。 詳情請參閱「建立媒體推薦應用程式和資料儲存庫」。

• 選用：如不想使用預設供應設定，請按照「建立供應設定」一文中的步驟 1 到 5 和步驟 7，建立新的供應設定。如果應用程式已發布，建議您先建立獨立的放送設定來測試提升控制項，再將控制項套用至正式放送設定。

• 請確認要在升幅控制項中使用的所有欄位，都在結構定義中標示為「可篩選」。詳情請參閱「設定欄位設定」。另請參閱篩選限制。

增加或減少建議

這項程序說明如何建立升幅控制項，並將控制項附加至放送設定。

將控制項附加至放送設定後，您可以在呼叫 servingConfigs.recommend 方法時指定放送設定，系統就會使用升幅控制項影響傳回建議的順序。

更新增幅控制項

這個程序說明如何更新現有的提升控制項，以變更提升或篩選條件的值。

測試升幅控制項後，您可能會發現需要調高或調低升幅。或者，您也可以變更篩選器字串。

更新升幅值或篩選器時，請呼叫 engines.controls.patch 方法。

修補程式方法會將 boost 和 filter 的值替換為您提供的新值。這個程序會說明如何分別編輯 boost 值 (步驟 3) 和 filter 值 (步驟 4)。不過，如果您想同時編輯兩者，可以使用單一 curl 指令完成。

刪除升壓控制項

本程序說明如何刪除升壓控制。 如果您未使用升幅控制項，建議刪除該控制項，以免達到或超過允許的控制項數量配額。

刪除升級控制項時，請呼叫 engines.controls.delete 方法。

如果提升控制項已附加至供應設定，就無法刪除。如果您嘗試刪除增幅控制項，系統會顯示錯誤訊息，並提供放送設定的名稱。接著，您需要刪除該供應設定，或從供應設定取消連結該控制項。

更新供應設定，移除升幅控制項

如要刪除升幅控制項，必須先從所有放送控制項中取消連結。方法是修補放送控制項，移除升幅控制項的 ID。

如要從放送設定中分離升幅控制項，請按照下列步驟操作：

1. 發出 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。

   指令和結果範例

   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: my-project-123" \
   "https://discoveryengine.googleapis.com/v1beta/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/my_app-1234567_id"
   

   {
     "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/servingConfigs/my_app-1234567_id",
     "displayName": "jane-day-test-serving-config-for-boost-bury",
     "solutionType": "SOLUTION_TYPE_RECOMMENDATION",
     "modelId": "my-app",
     "diversityLevel": "no-diversity",
     "diversityType": "RULE_BASED_DIVERSITY",
     "mediaConfig": {},
     "createTime": "2024-11-22T23:54:45.613178Z",
     "updateTime": "2024-11-26T20:28:11.967439Z",
     "boostControlIds": [
       "boost-kids",
       "bury-horror"
     ]
   }
   

   這項指令會列出供應設定 my_app-1234567_id 的相關資訊，特別是顯示供應設定已附加兩個提升控制項：boost-kids 和 bury-horror。

2. 如要更新放送設定以移除一項加成控制項，請使用 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。請務必省略要刪除的任何升級控制項。這是字串陣列。如果您有多個 ID，請務必使用分隔引號和半形逗號，例如 boost-1", "boost-2。

   指令和結果範例：只保留一個控制項

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: my-project-123" \
   "https://discoveryengine.googleapis.com/v1beta/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/my_app-1234567_id?update_mask=boost_control_ids" \
   -d '{
     "boostControlIds": ["bury-horror"]
   }'
   

   {
     "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/servingConfigs/my_app-1234567_id",
     "displayName": "jane-day-test-serving-config-for-boost-bury",
     "solutionType": "SOLUTION_TYPE_RECOMMENDATION",
     "modelId": "my-app",
     "diversityLevel": "no-diversity",
     "diversityType": "RULE_BASED_DIVERSITY",
     "mediaConfig": {},
     "boostControlIds": [
       "bury-horror"
     ]
   }
   

   這項指令會保留附加至供應設定的 bury-horror 提升控制項，並移除 boost-kids 控制項。假設 boost-kids 未附加至任何其他供應設定，現在即可刪除。請參閱刪除加速控制項。

   指令和結果範例：移除所有控制項

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: my-project-123" \
   "https://discoveryengine.googleapis.com/v1beta/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/my_app-1234567_id?update_mask=boost_control_ids" \
   -d '{
   "boostControlIds": []
   }'
   

   {
   "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/servingConfigs/my_app-1234567_id",
   "displayName": "jane-day-test-serving-config-for-boost-bury",
   "solutionType": "SOLUTION_TYPE_RECOMMENDATION",
   "modelId": "my-app",
   "diversityLevel": "no-diversity",
   "diversityType": "RULE_BASED_DIVERSITY",
   "mediaConfig": {}
   }
   

   這項指令會從供應設定中移除所有升幅控制項， my_app-1234567_id