Filtrer les recommandations

Si vous disposez d'une application de recommandations, vous pouvez utiliser des champs de document pour filtrer les résultats de vos recommandations. Cette page explique comment utiliser des champs de document pour filtrer une recommandation sur un ensemble spécifique de documents. Bien que les exemples de cette page concernent les recommandations de médias, les principes présentés ici sont les mêmes pour les recommandations personnalisées. Pour en savoir plus sur les recommandations de médias, consultez la page Présentation de la recherche d'agent pour les médias.

Filtrer les recommandations et les mises à jour des 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 aux documents et au schéma soient propagées. Pour les recommandations (contrairement à la recherche), le filtrage n'est pas effectué en temps réel.

Paramètres de filtres et 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 de média. Les effets des filtres et de la diversification sont combinés. La diversification est effectuée en premier, puis le filtrage.

La combinaison d'une diversité élevée basée sur des règles et d'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 basés sur 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é, bien que de nombreux films puissent être recommandés, un seul film (par exemple, WALL-E) de la catégorie des films pour enfants est renvoyé. Lorsque le filtre pour les films pour enfants est ensuite appliqué, seul WALL-E est renvoyé en tant que recommandation.

Pour obtenir des informations générales sur la diversité, consultez la page 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 de médias ou Créer un datastore de recommandations personnalisé.

Exemples de documents

Consultez ces exemples de documents multimédias. Vous pouvez vous référer à ces exemples de documents tout au long de 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 des expressions 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 sous forme normale conjonctive (CNF). L'expression logique la plus complexe acceptée peut être une liste de clauses connectées par AND-qui ne contiennent que des OR opérateurs, par exemple : (... OR ... OR ...) AND (... OR ...) AND (... OR ...)

  • Les expressions peuvent être niées avec le mot clé NOT ou avec -. Cela ne fonctionne qu'avec les expressions ANY() avec un seul argument.

  • Les restrictions available doivent se trouver au niveau supérieur. Elles ne peuvent pas être utilisées dans une clause OR ni dans une négation (NOT). Vous ne pouvez utiliser que available: true. Si vous omettez ce filtre, les documents expirés et les documents non encore disponibles peuvent être renvoyés en tant que recommandations.

    Le champ available correspond à la logique suivante :

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

    Si le expire_time n'est pas défini, datetime.now <= expire_time est résolu en true.

  • Le nombre maximal de termes dans la clause AND de niveau supérieur est de 20.

  • Une clause OR peut comporter jusqu'à 100 arguments inclus dans les expressions ANY(). Si une clause OR comporte plusieurs expressions ANY(), tous leurs arguments sont pris en compte 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.

Expression Valide Remarques
language_code: ANY("en", "fr") Oui
NOT language_code: ANY("en") Oui
NOT language_code: ANY("en", "fr") Non Nie une expression ANY() avec plusieurs arguments.
language_code: ANY("en", "fr") OR categories: ANY("drama") Oui
(language_code: ANY("en") OR language_code: ANY("fr")) AND categories: ANY("drama") Oui
(language_code: ANY("en") AND language_code: ANY("fr")) OR categories: ANY("drama") Non N'est pas sous forme normale conjonctive.
(language_code: ANY("en")) AND (available: true) Oui
(language_code: ANY("en")) OR (available: true) Non Combine available dans une expression OR avec d'autres conditions.

L'expression de filtre suivante filtre les documents qui appartiennent à 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 trouvés lors de l'entraînement de l'application, seuls 10 sont utilisés.

  • Votre schéma peut contenir jusqu'à 100 000 000 de 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 dans votre schéma par le nombre de champs filtrables. Si vous dépassez ces limites, les conséquences suivantes se produisent :

    • Vous ne pouvez pas définir de champs supplémentaires comme filtrables.
    • L'entraînement de l'application échoue.

Filtrer les recommandations

Pour filtrer les recommandations de mé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 Google Cloud console, accédez à la page AI Applications (Applications d'IA), puis cliquez sur Data Stores (Datastores) dans le menu de navigation.

      Accéder à la page "Datastores"

    2. Cliquez sur le nom de votre data store.

    3. Sur la page Data (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 effectuer un filtrage. 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 Google Cloud console, accédez à la page AI Applications (Applications d'IA).

      AI Applications

    2. Cliquez sur votre application de recommandations.

    3. Cliquez sur l'onglet Schema (Schéma). Cet onglet affiche les paramètres de champ actuels.

    4. Cliquez sur Edit (Modifier).

    5. Si elle n'est pas déjà sélectionnée, cochez la case Filterable (Filtrable) dans la ligne categories (catégories), puis cliquez sur Save (Enregistrer).

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

  4. Pour obtenir une recommandation et filtrer 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"

    Remplacez les éléments suivants :

    • 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 UserEvent.
    • USER_PSEUDO_ID: chaîne encodée au format UTF-8, qui sert d'identifiant pseudonymisé unique permettant de suivre les utilisateurs. Elle peut comporter jusqu'à 128 caractères. Google vous recommande vivement d'utiliser ce champ, car il améliore les performances du modèle et la qualité de la personnalisation. Vous pouvez utiliser un cookie HTTP pour ce champ, qui identifie de manière unique un visiteur sur un seul appareil. Voici quelques points importants à prendre en compte :

      • Cet identifiant ne change pas lorsque le visiteur se connecte à un site Web ou s'en déconnecte.
      • Ce champ ne doit pas être défini sur le même identifiant pour plusieurs utilisateurs. Sinon, le même ID utilisateur peut combiner les historiques d'événements de différents utilisateurs et dégrader la qualité du modèle.
      • Ce champ ne doit pas inclure d'informations permettant d'identifier personnellement l'utilisateur.

      Pour en savoir plus, consultez userPseudoId.

    • SERVING_CONFIG_ID : ID de votre configuration de diffusion. L'ID de votre configuration de diffusion est le même que l'ID de votre moteur. Utilisez donc l'ID de votre moteur ici.
    • FILTER: champ de texte qui vous permet de filtrer un ensemble de champs spécifié à l'aide de la syntaxe des expressions 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 une recommandation pour un événement utilisateur de lecture de média spécifique et que vous souhaitiez filtrer les résultats de la recommandation pour ne contenir que les documents qui : (1) appartiennent à la catégorie "Enfants" et (2) sont actuellement disponibles. Pour ce faire, incluez les instructions suivantes dans votre appel :

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

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

    Cliquez pour obtenir un exemple de réponse.

    Si vous effectuez une demande de recommandation comme la précédente, vous pouvez vous attendre à obtenir une réponse semblable à la suivante. Notez que la réponse inclut les deux documents dont la valeur categories est Children et dont 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"
}