Nota:Vertex AI Search verrà rinominato Agent Search. Stiamo aggiornando i contenuti per riflettere il nuovo brand.

Filtrare i consigli

Se hai un'app di suggerimenti, puoi utilizzare i campi dei documenti per filtrare i risultati dei suggerimenti. Questa pagina spiega come utilizzare i campi dei documenti per filtrare un suggerimento in base a un insieme specifico di documenti. Sebbene gli esempi in questa pagina riguardino i suggerimenti per i contenuti multimediali, i principi illustrati qui sono gli stessi per i suggerimenti personalizzati. Per saperne di più sui suggerimenti per i contenuti multimediali, vedi Introduzione alla ricerca di agenti per i contenuti multimediali.

Filtrare i suggerimenti e gli aggiornamenti del datastore

Dopo qualsiasi aggiornamento del datastore, dovrai attendere fino a 8 ore per il riaddestramento del modello. Questo perché il modello deve conoscere i valori attuali nei metadati dei documenti, nonché i campi configurati come filtrabili. Devi attendere la propagazione delle modifiche ai documenti e allo schema. Per i suggerimenti (a differenza della ricerca), il filtro non viene eseguito in tempo reale.

Impostazioni di filtri e diversificazione (solo suggerimenti per i contenuti multimediali)

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

La combinazione di una diversità elevata basata su regole e del filtro degli attributi basato su categorie spesso genera un output vuoto. Questo perché la diversità elevata limita l'app alla restituzione di un solo risultato per ogni categoria.

Ad esempio, vuoi consigliare film basati su Toy Story. Imposta il livello di diversità basato su regole su alto. Poiché il livello di diversità è elevato, anche se potrebbero essere consigliati molti film, 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 suggerimento.

Per informazioni generali sulla diversità, vedi Diversificare i suggerimenti per i contenuti multimediali.

Prima di iniziare

Assicurati di aver creato un'app di suggerimenti e un datastore. Per saperne di più, vedi Creare app per contenuti multimediali o Creare un datastore di suggerimenti personalizzati.

Documenti di esempio

Esamina questi documenti di esempio sui contenuti multimediali. 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 suggerimenti.

Sintassi delle espressioni di filtro

Il seguente modulo di Backus-Naur esteso riassume la sintassi delle espressioni di filtro che puoi utilizzare per definire i filtri dei suggerimenti.

  # 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

Si applicano le seguenti limitazioni alle espressioni di filtro per i suggerimenti:

La profondità degli operatori AND e OR di incorporamento 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 connesse da AND-che contengono solo operatoriOR, ad esempio: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
Le espressioni possono essere negate con la parola chiave NOT o con -. Questa opzione funziona solo con le espressioni ANY() con un singolo argomento.
Le limitazioni available devono essere di primo livello. Non possono essere utilizzate come parte di una clausola OR o di una negazione (NOT). Puoi utilizzare solo available: true. Se ometti questo filtro, i documenti scaduti e i documenti non ancora disponibili potrebbero essere restituiti come suggerimenti.

Il campo available esegue il mapping alla seguente logica:

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

Se il expire_time non è impostato, datetime.now <= expire_time viene risolto in true.
Il numero massimo di termini nella clausola AND di primo livello è 20.
Una clausola OR può avere fino a 100 argomenti inclusi nelle espressioni ANY(). Se una clausola OR ha più espressioni ANY(), tutti i relativi argomenti vengono conteggiati ai fini di questo limite. Ad esempio, categories: ANY("drama", "comedy") OR categories: ANY("adventure") ha tre argomenti.

Esempi di espressioni di filtro

La seguente tabella mostra esempi di espressioni di filtro valide e non valide. Fornisce anche i motivi per cui gli esempi non validi non sono validi.

Espressione	Valido	Note
`language_code: ANY("en", "fr")`	Yes
`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")`	Yes
`(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)`	Yes
`(language_code: ANY("en")) OR (available: true)`	No	Combina `available` in un'espressione `OR` con altre condizioni.

La seguente espressione di filtro filtra i documenti che appartengono alla categoria drammatica o azione, che non sono in inglese e che sono disponibili:

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

Limiti di filtro

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

Nello schema è possibile impostare come filtrabili fino a 10 campi personalizzati.

Se durante l'addestramento dell'app vengono trovati più di 10 campi personalizzati, ne vengono utilizzati solo 10.
Nello schema possono essere presenti fino a 100.000.000 di valori di campi filtrabili.

Puoi stimare il numero totale di valori di campi filtrabili nello schema moltiplicando il numero di documenti nello schema per il numero di campi filtrabili. Se superi questi limiti, si verificano le seguenti situazioni:
- Non puoi impostare altri campi come filtrabili.
- L'addestramento dell'app non riesce.

Filtrare i suggerimenti

Per filtrare i suggerimenti per i contenuti multimediali:

Trova l'ID del datastore. Se hai già l'ID del datastore, vai al passaggio successivo.
1. Nella Google Cloud console, vai alla pagina AI Applications e nel menu di navigazione, fai clic su Datastore.
  
  Vai alla pagina Datastore
2. Fai clic sul nome del tuo datastore.
3. Nella pagina Dati del datastore, recupera l'ID 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 categories campo come filtro.
Per rendere filtrabile il campo categories:
1. Nella Google Cloud console, vai alla pagina AI Applications.
  
  AI Applications
2. Fai clic sull'app di suggerimenti.
3. Fai clic sulla scheda Schema. Questa scheda mostra le impostazioni dei campi correnti.
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 della modifica dello schema. Dopo sei ore, puoi procedere al passaggio successivo.
Per ottenere un suggerimento 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"
```
Sostituisci quanto segue:
- PROJECT_ID: l'ID progetto.
- DATA_STORE_ID: l'ID del datastore.
- DOCUMENT_ID: l'ID del documento per il quale vuoi visualizzare l'anteprima dei suggerimenti. Utilizza l'ID che hai utilizzato per questo documento al momento dell'importazione dei dati.
- EVENT_TYPE: il tipo di evento utente. Per i valori di eventType, vedi UserEvent.
- USER_PSEUDO_ID: una stringa con codifica UTF-8 che funge da identificatore pseudonimizzato univoco che tiene traccia degli utenti. Può avere una lunghezza massima di 128 caratteri. Google consiglia vivamente di utilizzare questo campo perché migliora le prestazioni del modello e la qualità della personalizzazione. Puoi utilizzare un cookie HTTP per questo campo, che identifica in modo univoco un visitatore su un singolo dispositivo. Di seguito sono riportate alcune considerazioni importanti:
  - Questo identificatore non cambia quando il visitatore esegue l'accesso o la disconnessione da un sito web.
  - Questo campo non deve essere impostato sullo stesso identificatore per più utenti. In caso contrario, lo stesso ID utente può combinare le cronologie degli eventi di utenti diversi e ridurre la qualità del modello.
  - Questo campo non deve includere informazioni che consentono l'identificazione personale (PII).
  Per saperne di più, vedi userPseudoId.
- SERVING_CONFIG_ID: l'ID della configurazione di pubblicazione. L'ID della configurazione di pubblicazione è lo stesso dell'ID motore, quindi utilizza l'ID motore qui.
- FILTER: un campo di testo che ti consente di filtrare in base a un insieme specificato di campi, utilizzando la sintassi delle espressioni di filtro. Il valore predefinito è una stringa vuota, il che significa che non viene applicato alcun filtro.
Ad esempio, supponiamo che tu voglia un suggerimento per un evento utente di riproduzione di contenuti multimediali specifico e che tu voglia filtrare i risultati dei suggerimenti in modo che contengano solo i documenti che: (1) appartengono alla categoria Bambini e (2) sono attualmente disponibili. Per farlo, includi le seguenti istruzioni nella chiamata:
- "eventType": "media-play"
- "filter": "categories: ANY(\"Children\") AND available: true"
Per saperne di più, vedi il recommend metodo.
Fai clic per visualizzare una risposta di esempio.

Se effettui una richiesta di suggerimento 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"
}
```