Filtrer les recommandations

Si vous disposez d'une application de recommandations qui utilise des données structurées, vous pouvez utiliser les champs de document pour filtrer les résultats de vos recommandations. Cette page explique comment utiliser les champs de document pour filtrer une recommandation sur un ensemble spécifique de documents. Bien que les exemples de cette page concernent des recommandations multimédias, les principes présentés ici sont les mêmes pour les recommandations génériques. Pour en savoir plus sur les recommandations multimédias, consultez la Présentation de Vertex AI Search for Media.

Filtrer les recommandations et les mises à jour du data store

Après toute mise à jour du data store, vous devrez attendre jusqu'à huit heures pendant que le modèle est réentraîné. En effet, le modèle doit connaître les valeurs actuelles des métadonnées du document, ainsi que les champs configurés comme filtrables. Vous devez attendre que les modifications apportées au document et au schéma se propagent. Pour les recommandations (contrairement à la recherche), le filtrage n'est pas effectué en temps réel.

Filtres et paramètres de diversification (recommandations de médias uniquement)

En plus des filtres, le paramètre de diversification d'une application affecte également les résultats renvoyés dans une réponse de recommandation multimédia. Les effets des filtres et de la diversification sont combinés. La diversification est effectuée en premier, puis le filtrage.

Combiner une diversité élevée basée sur des règles et un filtrage des attributs basé sur des catégories entraîne souvent une sortie vide. En effet, une diversité élevée limite l'application à renvoyer un seul résultat pour chaque catégorie.

Par exemple, vous souhaitez recommander des films en fonction de Toy Story. Vous définissez le niveau de diversité basé sur des règles sur "Élevé". Étant donné que le niveau de diversité est élevé, même si de nombreux films peuvent être recommandés, un seul (par exemple, WALL·E) est renvoyé dans la catégorie des films pour enfants. Lorsque le filtre pour les films pour enfants est appliqué, seul WALL·E est renvoyé en tant que recommandation.

Pour en savoir plus sur la diversité, consultez Diversifier les recommandations de médias.

Avant de commencer

Assurez-vous d'avoir créé une application de recommandations et data store. Pour en savoir plus, consultez Créer des applications multimédias ou Créer un entrepôt de données de recommandations génériques.

Exemples de documents

Consultez ces exemples de documents multimédias. Vous pouvez vous reporter à ces exemples de documents lorsque vous lisez cette page.

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

Expressions de filtre

Utilisez des expressions de filtre pour définir vos filtres de recommandations.

Syntaxe des expressions de filtre

La forme Backus-Naur étendue suivante résume la syntaxe de l'expression de filtre que vous pouvez utiliser pour définir vos filtres de recommandations.

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

Restrictions concernant les expressions de filtre

Les restrictions suivantes s'appliquent aux expressions de filtre pour les recommandations:

• La profondeur d'intégration des opérateurs AND et OR entre parenthèses est limitée. Les expressions logiques du filtre doivent être au format forme normale conjonctive (CNF). L'expression logique la plus complexe acceptée peut être une liste de clauses connectées par AND qui ne contient que des opérateurs OR, par exemple: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
• Les expressions peuvent être annulées à l'aide du mot clé NOT ou de -. Cette option n'est disponible que pour les expressions ANY() avec un seul argument.
• Les restrictions available doivent être au niveau supérieur. Ils ne peuvent pas être utilisés dans une clause OR ni dans une négation (NOT). Vous ne pouvez utiliser que available: true.
• Le nombre maximal de termes dans la clause AND de premier niveau est de 20.
• Une clause OR peut comporter jusqu'à 100 arguments inclus dans des expressions ANY(). Si une clause OR comporte plusieurs expressions ANY(), leurs arguments sont tous comptabilisés dans cette limite. Par exemple, categories: ANY("drama", "comedy") OR categories: ANY("adventure") comporte trois arguments.

Exemples d'expressions de filtre

Le tableau suivant présente des exemples d'expressions de filtre valides et non valides. Il indique également les raisons pour lesquelles les exemples non valides ne le sont pas.

L'expression de filtre suivante permet de filtrer les documents appartenant à la catégorie "Drame" ou "Action", qui ne sont pas en anglais et qui sont disponibles:

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

Limites de filtrage

Chaque champ de document filtrable consomme de la mémoire dans chacun de vos modèles. Les limites suivantes permettent d'éviter les effets négatifs sur les performances de diffusion:

• Vous pouvez définir jusqu'à 10 champs personnalisés comme filtrables dans votre schéma.

  Si plus de 10 champs personnalisés sont détectés lors de l'entraînement de l'application, seuls 10 d'entre eux sont utilisés.

• Votre schéma peut contenir jusqu'à 100 000 000 valeurs de champ filtrables.

  Vous pouvez estimer le nombre total de valeurs de champ filtrables dans votre schéma en multipliant le nombre de documents de votre schéma par le nombre de champs filtrables. Si vous dépassez ces limites, voici ce qui se produit:

  • Vous ne pouvez pas définir d'autres champs comme filtrables.
  • Échec de l'entraînement de l'application.

Filtrer les recommandations

Pour filtrer les recommandations multimédias, procédez comme suit:

1. Recherchez l'ID de votre data store. Si vous disposez déjà de l'ID de votre data store, passez à l'étape suivante.

   1. Dans la console Google Cloud, accédez à la page Agent Builder et cliquez sur Data Stores dans le menu de navigation.

      Accéder à la page "Datastores"

   2. Cliquez sur le nom de votre data store.

   3. Sur la page Données de votre data store, obtenez l'ID du data store.

2. Déterminez le ou les champs de document sur lesquels vous souhaitez appliquer des filtres. Par exemple, pour les documents de la section Avant de commencer, vous pouvez utiliser le champ categories comme filtre.

3. Pour rendre le champ categories filtrable, procédez comme suit:

   1. Dans la console Google Cloud, accédez à la page Agent Builder.

      Agent Builder

   2. Cliquez sur votre application de recommandations.

   3. Cliquez sur l'onglet Schéma. Cet onglet affiche les paramètres actuels des champs.

   4. Cliquez sur Modifier.

   5. Si ce n'est pas déjà le cas, cochez la case Filtrable dans la ligne catégories, puis cliquez sur Enregistrer.

   6. Attendez six heures pour que la modification de votre schéma soit prise en compte. Au bout de six heures, vous pouvez passer à l'étape suivante.

4. Pour obtenir une recommandation et filtrer sur le champ categories, exécutez le code suivant dans la ligne de commande:

   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 de votre projet.
   • DATA_STORE_ID: ID de votre data store.
   • DOCUMENT_ID: ID du document pour lequel vous souhaitez prévisualiser les recommandations. Utilisez l'ID que vous avez utilisé pour ce document au moment de l'ingestion de vos données.
   • EVENT_TYPE: type d'événement utilisateur. Pour connaître les valeurs eventType, consultez la section UserEvent.
   • USER_PSEUDO_ID: identifiant pseudonymisé de l'utilisateur. Vous pouvez utiliser un cookie HTTP pour ce champ, qui identifie de manière unique un visiteur sur un seul appareil. Ne définissez pas ce champ sur le même identifiant pour plusieurs utilisateurs. Cela combinerait leurs historiques d'événements et dégraderait la qualité du modèle. N'ajoutez pas d'informations permettant d'identifier personnellement l'utilisateur dans ce champ.
   • SERVING_CONFIG_ID: ID de votre configuration de diffusion. Votre ID de configuration de diffusion est identique à votre ID de moteur. Utilisez donc votre ID de moteur ici.
   • FILTER: champ de texte qui vous permet de filtrer sur un ensemble de champs spécifié à l'aide de la syntaxe d'expression de filtre. La valeur par défaut est une chaîne vide, ce qui signifie qu'aucun filtre n'est appliqué.

   Par exemple, supposons que vous souhaitiez obtenir une recommandation pour un événement utilisateur de lecture multimédia spécifique et que vous souhaitiez filtrer les résultats de la recommandation pour n'inclure que les documents qui: (1) appartiennent à la catégorie "Enfants" et (2) sont actuellement disponibles. Pour ce faire, incluez les instructions suivantes avec votre appel:

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

   Pour en savoir plus, consultez la section sur la méthode recommend.

   Cliquez pour voir un exemple de réponse.

   Si vous envoyez une requête de recommandation comme celle-ci, vous devriez obtenir une réponse semblable à la suivante. Notez que la réponse inclut les deux documents dont la valeur categories est Children et la valeur availability_start_time est postérieure à la date actuelle.

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