Questa pagina è stata tradotta dall'API Cloud Translation.

Filtrare i consigli

Se hai un'app di consigli che utilizza i dati strutturati, puoi utilizzare campi documento per filtrare i risultati dei suggerimenti. Questa pagina spiega come utilizzare i campi dei documenti per filtrare un consiglio in base a un insieme specifico di documenti. Sebbene gli esempi in questa pagina siano riferiti a consigli sui contenuti multimediali, i principi mostrati qui sono gli stessi per i suggerimenti generici. Per ulteriori informazioni consulta Introduzione a Vertex AI Search per contenuti multimediali.

Filtrare i suggerimenti e gli aggiornamenti del datastore

Dopo qualsiasi aggiornamento del datastore, dovrai attendere fino a 8 ore mentre il modello riaddestra. Questo perché il modello deve conoscere i valori attuali in i metadati del documento, nonché i campi configurati come filtrabili. Devi attendere che le modifiche al documento e allo schema vengano propagate. Per i consigli (a differenza della ricerca), il filtro non viene eseguito in tempo reale.

Impostazioni di filtri e diversificazione (solo consigli sui contenuti multimediali)

Oltre ai filtri, l'impostazione di diversificazione di un'app influisce anche sui risultati restituiti in una risposta ai consigli sui contenuti multimediali. Gli effetti dei filtri e della diversificazione vengono combinati. La diversificazione viene eseguita prima e il filtro dopo.

La combinazione di una diversità elevata basata su regole e il filtro degli attributi in base alla categoria spesso genera un output vuoto. Questo perché una diversità elevata limita l'app a che restituisce un risultato per ogni categoria.

Ad esempio, vuoi consigliare film basati su Toy Story. Hai impostato livello di diversità basato su regole ad alto. Poiché il livello di diversità è elevato, anche se molti film potrebbero essere consigliati, viene restituito un solo film (ad esempio WALL·E) nella categoria dei film per bambini. Quando viene applicato il filtro per i film per bambini, viene restituito solo WALL·E come consiglio.

Per informazioni generali sulla diversità, consulta Diversificare i media personalizzati.

Prima di iniziare

Assicurati di aver creato un datastore e un'app per suggerimenti. Per maggiori informazioni informazioni, vedi Creare app multimediali oppure Crea un datastore di suggerimenti generici.

Documenti di esempio

Esamina questi documenti multimediali di esempio. Puoi fare riferimento a questi documenti di esempio mentre leggi questa pagina.

{"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"}}

Espressioni di filtro

Utilizza le espressioni di filtro per definire i filtri dei consigli.

Sintassi delle espressioni di filtro

La seguente forma Backus-Naur estesa riassume la sintassi dell'espressione di filtro che puoi utilizzare per definire i filtri dei consigli.

  # 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;

Limitazioni delle espressioni di filtro

Le seguenti limitazioni si applicano alle espressioni di filtro per i consigli:

La profondità di incorporamento degli operatori AND e OR tra parentesi è limitata. Le espressioni logiche nel filtro devono essere in forma normale congiuntiva (CNF). L'espressione logica supportata più complessa può essere un elenco di clausole collegate da AND che contengono solo operatori OR, ad esempio: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
Le espressioni possono essere negate con la parola chiave NOT o con -. Solo questo funziona con le espressioni ANY() con un singolo argomento.
Le limitazioni per available devono essere di livello superiore. Non possono essere utilizzati come parte di una clausola OR o di una negazione (NOT). Puoi utilizzare solo available: true.
Il numero massimo di termini nella clausola AND di primo livello è 20.
Una clausola OR può avere fino a 100 argomenti inclusi in ANY() le espressioni regolari. Se una clausola OR ha più espressioni ANY(), la relativa clausola tutti gli argomenti vengono conteggiati per questo limite. Ad esempio, categories: ANY("drama", "comedy") OR categories: ANY("adventure") ha tre argomenti.

Esempi di espressioni di filtro

La tabella seguente mostra esempi di espressioni di filtro valide e non valide. Inoltre, indica i motivi per cui gli esempi non validi non sono validi.

Espressione	Valido	Note
`language_code: ANY("en", "fr")`	Sì
`NOT language_code: ANY("en")`	Sì
`NOT language_code: ANY("en", "fr")`	No	Nega un `ANY()` con più di un argomento.
`language_code: ANY("en", "fr") OR categories: ANY("drama")`	Sì
`(language_code: ANY("en") OR language_code: ANY("fr")) AND categories: ANY("drama")`	Sì
`(language_code: ANY("en") AND language_code: ANY("fr")) OR categories: ANY("drama")`	No	Non in forma normale congiuntiva.
`(language_code: ANY("en")) AND (available: true)`	Sì
`(language_code: ANY("en")) OR (available: true)`	No	Combina `available` in un'espressione `OR` con altre condizioni.

La seguente espressione di filtro filtra per i documenti che si trovano nella serie dell'azione, che non siano in inglese e che siano disponibili:

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

Limiti di filtraggio

Ogni campo del documento filtrabile consuma una certa quantità di memoria in ciascuno dei tuoi modelli. I seguenti limiti consentono di evitare effetti negativi sulle prestazioni della pubblicazione:

Nello schema puoi impostare fino a 10 campi personalizzati come filtrabili.

Se durante l'addestramento dell'app vengono trovati più di 10 campi personalizzati, solo 10 vengono in uso.
Nel schema possono essere presenti fino a 100.000.000 di valori di campo filtrabili.

Puoi stimare il numero totale di valori dei campi filtrabili nel tuo schema moltiplicando il numero di documenti nel tuo schema per il numero di campi filtrabili. Se superi questi limiti, si verifica quanto segue:
- Non puoi impostare altri campi come filtrabili.
- L'addestramento dell'app non riesce.

Filtrare i consigli

Per filtrare i consigli sui contenuti multimediali:

Individua l'ID datastore. Se hai già un datastore ID, vai al passaggio successivo.
1. Nella console Google Cloud, vai alla pagina Agent Builder e nel menu di navigazione fai clic su Data Store.
  
  Vai alla pagina Datastore
2. Fai clic sul nome del tuo datastore.
3. Individua l'ID datastore nella pagina Dati del datastore.
Determina il campo o i campi del documento in base ai quali vuoi filtrare. Ad esempio, per i documenti in Prima di iniziare, puoi utilizzare il campo categories come filtro.
Per rendere filtrabile il campo categories:
1. Nella console Google Cloud, vai alla pagina Agent Builder.
  
  Agent Builder
2. Fai clic sull'app per consigli.
3. Fai clic sulla scheda Schema. Questa scheda mostra le impostazioni correnti dei campi.
4. Fai clic su Modifica.
5. Se non è già selezionata, seleziona la casella di controllo Filtrabile nella riga categories e fai clic su Salva.
6. Attendi sei ore per consentire la propagazione delle modifiche dello schema. Dopo le sei ore, puoi procedere con il passaggio successivo.
Per ricevere un consiglio e filtrare in base al campo categories, esegui il seguente codice nella riga di comando:
```
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: l'ID del progetto.
- DATA_STORE_ID: l'ID del tuo datastore.
- DOCUMENT_ID: l'ID del documento di cui vuoi visualizzare l'anteprima consigli personalizzati. Utilizza il documento d'identità utilizzato per all'ora in cui hai importato i dati.
- EVENT_TYPE: il tipo di evento utente. Per i valori eventType, consulta UserEvent.
- USER_PSEUDO_ID: un identificatore dell'utente a cui sono stati assegnati pseudonimi. Puoi utilizzare un cookie HTTP per questo campo, che identifica in modo univoco un visitatore su un singolo dispositivo. Non impostare questo campo sullo stesso identificatore per più utenti. In questo modo le loro cronologie degli eventi vengono combinate e la qualità del modello peggiora. Non includere l'identificazione personale informazioni (PII) in questo campo.
- SERVING_CONFIG_ID: l'ID della configurazione di pubblicazione. L'ID configurazione della pubblicazione è uguale all'ID motore, quindi utilizza l'ID motore qui.
- FILTER: un campo di testo che consente di filtrare in base a un insieme specificato di campi utilizzando la sintassi dell'espressione di filtro. Il valore predefinito è una stringa vuota, il che significa che non viene applicato alcun filtro.
Ad esempio, supponiamo che tu voglia un consiglio per un evento specifico di riproduzione di contenuti multimediali e che tu voglia filtrare i risultati del consiglio in modo che contengano solo i documenti che si trovano (1) nella categoria Bambini e (2) sono attualmente disponibili. Per farlo, includi le seguenti dichiarazioni nella tua chiamata:
- "eventType": "media-play"
- "filter": "categories: ANY(\"Children\") AND available: true"
Per ulteriori informazioni, consulta il metodo recommend.
Fai clic per una risposta di esempio.

Se invii una richiesta di consigli come quella precedente, puoi aspettarti di ricevere una risposta simile alla seguente. Tieni presente che la risposta include i due documenti con un valore categories di Children e un valore availability_start_time successivo alla data corrente.
```
{
"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",
"debugInfo": {
  "fallbackModelInvoked": false
}
}
```