Filtrare i consigli

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

Filtrare i consigli e gli aggiornamenti del datastore

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

Filtri e impostazioni di 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 accade perché un'elevata diversità limita l'app a restituire un risultato per ogni categoria.

Ad esempio, vuoi consigliare film basati su Toy Story. Imposti il livello di diversità basato su regole su 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 suggerimenti per i contenuti multimediali.

Prima di iniziare

Assicurati di aver creato un'app di suggerimenti e un datastore. Per ulteriori informazioni, consulta Creare app multimediali o Creare un datastore di suggerimenti generici.

Documenti di esempio

Esamina questi documenti di esempio per i 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 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 contenenti solo operatori OR, ad esempio: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
• Le espressioni possono essere negate con la parola chiave NOT o con -. Questo funziona solo con le espressioni ANY() con un singolo argomento.
• Le limitazioni available devono trovarsi al 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 nelle espressioni ANY(). Se una clausola OR contiene 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 tabella seguente mostra esempi di espressioni di filtro valide e non valide. Fornisce inoltre i motivi per cui gli esempi non validi non sono validi.

La seguente espressione di filtro restituisce i documenti disponibili appartenenti alla categoria Dramma o Azione e non in inglese:

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 evitare effetti negativi sul rendimento della pubblicazione:

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

  Se durante l'addestramento dell'app vengono trovati più di 10 campi personalizzati, ne vengono utilizzati solo 10.

• Nel schema possono essere presenti fino a 100.000.000 di valori di campo filtrabili.

  Puoi stimare il numero totale di valori di campo 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 consigli

Per filtrare i consigli sui contenuti multimediali:

1. Trova l'ID del tuo datastore. Se hai già l'ID del tuo datastore, 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. Nella pagina Dati del tuo datastore, ottieni l'ID datastore.

2. 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.

3. Per rendere filtrabile il campo categories:

   1. Nella console Google Cloud, vai alla pagina Agent Builder.

      Agent Builder

   2. Fai clic sull'app di 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 Categorie e poi fai clic su Salva.

   6. Attendi sei ore per consentire la propagazione della modifica dello schema. Dopo sei ore, puoi procedere al passaggio successivo.

4. 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 per cui vuoi visualizzare l'anteprima dei consigli. 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 eventType, consulta UserEvent.
   • USER_PSEUDO_ID: un identificatore pseudonimo dell'utente. 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. Ciò combinerebbe le relative cronologie degli eventi e degraderebbe la qualità del modello. Non includere informazioni che consentono l'identificazione personale (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. A tal fine, includi le seguenti istruzioni nella chiamata:

   • "eventType": "media-play"
   • "filter": "categories: ANY(\"Children\") AND available: true"

   Per ulteriori informazioni, consulta il metodo recommend.

   Fai clic per visualizzare un esempio di risposta.

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