本頁面由 Cloud Translation API 翻譯而成。

篩選建議

如果您有建議應用程式，可以使用文件欄位篩選建議結果。本頁說明如何使用文件欄位，將建議篩選為特定文件集。雖然本頁面的範例是媒體推薦內容，但顯示的原則與自訂推薦內容相同。如要進一步瞭解媒體推薦功能，請參閱「媒體專用 Vertex AI Search 簡介」。

篩選建議和資料儲存庫更新

資料儲存空間更新後，模型需要重新訓練，最多可能需要 8 小時。這是因為模型需要瞭解文件的中繼資料目前的值，以及哪些欄位已設為可篩選。您必須等待文件變更和結構定義變更傳播。建議 (與搜尋不同) 不會即時篩選。

篩選器和多元化設定 (僅限媒體推薦內容)

除了篩選器，應用程式的多樣性設定也會影響媒體建議回應中傳回的結果。篩選器和多元化效果會合併。系統會先執行多元化，再執行篩選。

結合高規則式多樣性和以類別為準的屬性篩選條件，通常會導致輸出內容為空白。這是因為高多樣性會限制應用程式，只能為每個類別傳回一個結果。

舉例來說，您想根據《玩具總動員》推薦電影。您將規則式多樣化程度設為高。由於多樣性程度較高，雖然許多電影可能只會推薦一部電影 (例如《瓦力》)，但會傳回兒童電影類別。接著套用兒童電影的篩選條件，系統就只會推薦《瓦力》。

如要瞭解多樣性的一般資訊，請參閱「讓媒體推薦內容多樣化」。

事前準備

請確認您已建立建議應用程式和資料儲存庫。詳情請參閱「建立媒體應用程式」或「建立自訂建議資料存放區」。

文件範例

請參閱這些媒體文件範例。閱讀本頁內容時，可以參考這些範例文件。

{"id":"1","schemaId":"default_schema","structData":{"title":"Toy Story (1995)","categories":["Adventure","Animation","Children","Comedy","Fantasy"],"uri":"http://mytestdomain.movie/content/1","available_time":"2023-01-01T00:00:00Z","media_type":"movie"}}
{"id":"88125","schemaId":"default_schema","structData":{"title":"Harry Potter and the Deathly Hallows: Part 2 (2011)","categories":["Action","Adventure","Drama","Fantasy","Mystery","IMAX"],"uri":"http://mytestdomain.movie/content/88125","available_time":"2023-01-01T00:00:00Z","media_type":"movie"}}
{"id":"2857","schemaId":"default_schema","structData":{"title":"Yellow Submarine (1968)","categories":["Adventure","Animation","Comedy","Fantasy","Musical"],"uri":"http://mytestdomain.movie/content/2857","available_time":"2023-01-01T00:00:00Z","media_type":"movie"}}
{"id":"60069","schemaId":"default_schema","structData":{"title":"WALL·E (2008)","categories":["Adventure","Animation","Children","Romance","Sci-Fi"],"uri":"http://mytestdomain.movie/content/60069","available_time":"2023-01-01T00:00:00Z","media_type":"movie"}}

篩選運算式

使用篩選運算式定義建議篩選器。

篩選運算式語法

下列擴充 Backus-Naur 形式會總結可用於定義建議篩選器的篩選器運算式語法。

  # 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 }, ")"
    # OR filter by "available"
    available, ":", "true",
  # 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)。支援的最複雜邏輯運算式可以是 AND 連接的子句清單，其中只包含 OR 運算子，例如：(... OR ... OR ...) AND (... OR ...) AND (... OR ...)
您可以使用 NOT 關鍵字或 - 否定運算式。這項功能僅適用於具有單一引數的 ANY() 運算式。
available 限制必須位於頂層。不能做為 OR 子句或否定 (NOT) 的一部分，只能使用 available: true。如果省略這個篩選條件，系統可能會傳回過期文件和尚未可用的文件做為建議。

available 欄位會對應至下列邏輯：

datetime.now >= available_time AND datetime.now <= expire_time

如果未設定 expire_time，datetime.now <= expire_time 會解析為 true。
頂層 AND 子句最多只能有 20 個字詞。
OR 子句最多可有 100 個引數，這些引數會納入 ANY() 運算式。如果 OR 子句有多個 ANY() 運算式，所有引數都會計入這個上限。舉例來說，categories: ANY("drama", "comedy") OR categories: ANY("adventure") 有三個引數。

篩選運算式範例

下表列出有效和無效的篩選器運算式範例。並說明無效範例無效的原因。

運算式	有效	附註
`language_code: ANY("en", "fr")`	是
`NOT language_code: ANY("en")`	是
`NOT language_code: ANY("en", "fr")`	否	否定具有多個引數的 `ANY()`。
`language_code: ANY("en", "fr") OR categories: ANY("drama")`	是
`(language_code: ANY("en") OR language_code: ANY("fr")) AND categories: ANY("drama")`	是
`(language_code: ANY("en") AND language_code: ANY("fr")) OR categories: ANY("drama")`	否	不在合取範式中。
`(language_code: ANY("en")) AND (available: true)`	是
`(language_code: ANY("en")) OR (available: true)`	否	在 `OR` 運算式中，將 `available` 與其他條件合併。

下列篩選運算式會篩選出戲劇或動作類別的文件，且這些文件不是英文，但可供使用：

categories: ANY("drama", "action") AND NOT language_code: ANY("en") AND available: true

篩選限制

每個可篩選的文件欄位都會耗用每個模型中的部分記憶體。下列限制有助於避免放送成效受到負面影響：

您最多可以在架構中將 10 個自訂欄位設為可篩選。

如果在應用程式訓練期間找到超過 10 個自訂欄位，系統只會使用 10 個。
您的結構定義最多可包含 100,000,000 個可篩選的欄位值。

如要估算結構定義中可篩選的欄位值總數，請將結構定義中的文件數乘以可篩選的欄位數。如果超出這些限制，會發生下列情況：
- 您無法將其他欄位設為可篩選。
- 應用程式訓練失敗。

篩選建議

如要篩選媒體建議，請按照下列步驟操作：

找出資料儲存庫 ID。如果已有資料商店 ID，請跳到下一個步驟。
1. 前往 Google Cloud 控制台的「AI Applications」頁面，然後點按導覽選單中的「Data Stores」(資料儲存庫)。
  
  前往「資料儲存庫」頁面
2. 點按資料儲存庫的名稱。
3. 在資料儲存庫的「資料」頁面中，取得資料儲存庫 ID。
找出要篩選的文件欄位。舉例來說，您可以將「開始前」中的文件使用 categories 欄位做為篩選條件。
如要讓 categories 欄位可供篩選，請按照下列步驟操作：
1. 前往 Google Cloud 控制台的「AI Applications」頁面。
  
  AI 應用程式
2. 按一下推薦應用程式。
3. 按一下 [Schema] (結構定義) 分頁標籤。這個分頁會顯示目前的欄位設定。
4. 按一下 [編輯]。
5. 如果尚未選取，請勾選「類別」列中的「可篩選」核取方塊，然後按一下「儲存」。
6. 請等待六小時，讓結構定義編輯作業生效。六小時後，即可繼續進行下一個步驟。
如要取得建議並依 categories 欄位篩選，請在指令列執行下列程式碼：
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
     "userEvent": {
       "eventType": "EVENT_TYPE",
       "userPseudoId": "USER_PSEUDO_ID",
       "documents": {
         "id": "DOCUMENT_ID"
       }
     },
     "params": {
       "returnDocument": true,
       "attributeFilteringSyntax": true,
       "strictFiltering": true
     },
     "filter": "FILTER"
   }' \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/SERVING_CONFIG_ID:recommend"
```
更改下列內容：
- PROJECT_ID：專案 ID。
- DATA_STORE_ID：資料儲存庫的 ID。
- DOCUMENT_ID：要預覽建議的文件 ID。請使用您在擷取資料時為這份文件使用的 ID。
- EVENT_TYPE：使用者事件類型。如需 eventType 值，請參閱「UserEvent」。
- USER_PSEUDO_ID：以 UTF-8 編碼的字串，可做為追蹤使用者的專屬匿名 ID。長度上限為 128 個半形字元。 Google 強烈建議使用這個欄位，因為這有助於提升模型效能和個人化品質。您可以使用 HTTP Cookie 做為這個欄位的值，明確識別單一裝置上的訪客。以下是幾個重要考量：
  - 訪客登入或登出網站時，這個 ID 不會變更。
  - 這個欄位不得為多位使用者設定相同的 ID。否則，相同的使用者 ID 可能會合併不同使用者的事件記錄，導致模型品質下降。
  - 這個欄位不得包含個人識別資訊 (PII)。
  詳情請參閱 userPseudoId。
- SERVING_CONFIG_ID：供應設定的 ID。服務設定 ID 與引擎 ID 相同，因此請在此處使用引擎 ID。
- FILTER：文字欄位，可讓您使用篩選運算式語法，篩選特定欄位組合。預設值為空字串，表示未套用任何篩選器。
舉例來說，假設您想取得特定媒體播放使用者事件的建議，並篩選建議結果，只顯示 (1) 屬於「兒童」類別，且 (2) 目前可用的文件。方法是在呼叫中加入下列陳述式：
- "eventType": "media-play"
- "filter": "categories: ANY(\"Children\") AND available: true"
詳情請參閱 recommend 方法。
按一下即可查看範例回覆。

如果您提出類似上述的建議要求，預期會收到類似以下的回應。請注意，回應包含兩個 categories 值為 Children 的文件，以及 availability_start_time 值晚於目前日期的文件。
```
{
"results": [
  {
    "id":"1",
    "schemaId":"default_schema",
    "structData":{"title":"Toy Story (1995)","categories":["Adventure","Animation","Children","Comedy","Fantasy"],"uri":"http://mytestdomain.movie/content/1",
    "availability_start_time":"2023-01-01T00:00:00Z",
    "media_type":"movie"
    }
  },
  {
    "id":"60069",
    "schemaId":"default_schema",
    "structData":{"title":"WALL·E (2008)","categories":["Adventure","Animation","Children","Romance","Sci-Fi"],"uri":"http://mytestdomain.movie/content/60069",
    "availability_start_time":"2023-01-01T00:00:00Z",
    "media_type":"movie"
    }
  }
],
"attributionToken": "ChMzMDk3NTQ4MzQxOTcxOTE0ODM1GglhZi10ZXN0LTEiDmFmLXRlc3QtMTE0NTE0KAAwBg"
}
```

篩選建議 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

篩選建議和資料儲存庫更新

篩選器和多元化設定 (僅限媒體推薦內容)

事前準備

文件範例

篩選運算式

篩選運算式語法

篩選運算式限制

篩選運算式範例

篩選限制

篩選建議

篩選建議