Configuration de la recherche dans le datastore

Vous pouvez influencer les résultats de recherche récupérés à partir des outils de data store des agents conversationnels (Dialogflow CX) en configurant des spécifications de boost et de filtre. Cela permet des interactions plus personnalisées et contextuelles lorsque votre agent utilise un data store pour trouver des informations.

Vous pouvez également inclure des expressions dynamiques pour affiner vos résultats en fonction du contexte de la conversation. Par exemple, votre agent a capturé des informations indiquant que l'utilisateur final possède un "téléphone mobile". Vous pouvez configurer l'outil de data store pour mettre en avant les documents liés aux téléphones mobiles lorsque vous répondez à une requête générale plus tard dans la conversation, comme "Comment consulter ma messagerie vocale ?".

Vous pouvez configurer les résultats de recherche du data store à l'aide de la console, de l'API ou de l'intégration de Dialogflow CX Messenger.

Saisie des conditions de recherche

Les résultats de recherche sont configurés à l'aide des champs spécification d'amplification (BoostSpec) et spécification de filtre (FilterSpec) dans un objet SearchConfig. Ces configurations sont appliquées par data store dans l'outil, ce qui vous permet de contrôler précisément le comportement de chaque data store connecté.

Vous pouvez configurer des conditions de recherche de deux manières : à l'aide de la console ou en envoyant un appel d'API direct. Il existe des différences importantes entre les deux.

  • Appel d'API : BoostSpec et FilterSpec sont envoyés dans un SearchConfig à l'aide d'un appel d'API DetectIntent. Un objet SearchConfig complet doit être fourni dans la requête. Un SearchConfig envoyé par un appel d'API direct remplace toujours un SearchConfig envoyé à l'aide de la console. Les expressions dynamiques et les références de paramètres ne sont pas acceptées.

  • Console : vos configurations BoostSpec et FilterSpec sont utilisées pour construire un objet SearchConfig qui est envoyé avec la requête de recherche. Vous pouvez éventuellement inclure des références de paramètres et des expressions dynamiques pour adapter les résultats aux données contextuelles enregistrées lors de la conversation. Vous n'avez qu'à fournir des objets ConditionBoostSpec et une liste de chaînes de filtre pour construire FilterSpecs plutôt qu'un objet SearchConfig complet.

Les informations sur l'utilisateur final sont fournies au format JSON. Aucun schéma n'est attendu. Vous êtes donc libre de définir les propriétés de l'objet.

Spécifications de boost

Les spécifications de boost vous permettent de modifier le classement des résultats de recherche en appliquant une valeur de boost à des documents spécifiques. Vous pouvez ajouter plusieurs spécifications d'amplification à un même data store.

Chaque spécification de boost est saisie sous forme de chaîne JSON. Cette chaîne JSON doit représenter un seul objet ConditionBoostSpec.

Champs clés :

  • condition : (chaîne) expression qui spécifie quand le boost doit s'appliquer. Il utilise la syntaxe d'expression de filtre standard. Vous pouvez utiliser des expressions Dialogflow pour rendre les résultats dynamiques, comme $session.params.YOUR_PARAM_NAME ou $request.end-user-metadata.YOUR_KEY.
  • boost : (nombre) valeur comprise entre -1,0 et 1,0 qui détermine l'intensité du boost.
    • Une valeur positive favorise les documents correspondants. Une valeur de 1.0 correspond à une promotion importante.
    • Une valeur négative rétrograde les documents correspondants. Une valeur de -1.0 entraîne une forte rétrogradation.
    • La valeur 0.0 n'applique aucune amélioration et n'est pas autorisée.
  • boostControlSpec : fournit plus de contrôles pour un classement personnalisé que la combinaison de base de la condition et de l'amplification. Pour en savoir plus sur la configuration de ce champ, consultez la documentation de référence.

Exemple d'entrée de la console :

Si vous configurez votre agent dans la console, vous devez fournir une liste de ConditionBoostSpecs au format suivant.

Dans cet exemple, les documents dont l'URI correspond à la valeur du paramètre de session $session.params.doc_id seront boostés avec une intensité de 0,5. JSON de ce format

{
  "condition": "uri: ANY(\"http://www.example.com/docs/$session.params.doc_id\")",
  "boost": 0.5
}

Exemple d'entrée de l'API :

Si vous appelez l'API directement, vous devez fournir ConditionBoostSpecs dans un objet SearchConfig complet.La configuration de recherche suivante décrit une spécification d'amplification :

"searchConfig": {
  "boostSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "spec": [
        {
          "conditionBoostSpecs": {
            "condition": "CONDITION",
            "boost": "1.0"
          }
        }
      ]
    }
  ]
}

Spécifications de filtre

Les spécifications de filtre limitent les résultats de recherche aux documents qui correspondent aux critères définis. Vous pouvez ajouter plusieurs spécifications de filtre à un même data store.

Chaque spécification de filtre doit être saisie sous forme d'expression de chaîne. La chaîne doit respecter la syntaxe standard des expressions de filtre. Vous pouvez utiliser des expressions Dialogflow dans cette chaîne pour rendre les résultats dynamiques, comme $session.params.YOUR_PARAM_NAME ou $request.end-user-metadata.YOUR_KEY.

Exemple de chaîne de spécification de filtre de console :

Si vous configurez votre agent à l'aide de la console, vous devez fournir une liste de chaînes filter pour former un objet FilterSpec.

Dans cet exemple, le filtre ne renvoie que les documents dont la valeur numeric_field est supérieure ou égale à la valeur $session.params.min_value ET dont la valeur stock_availability est "IN_STOCK".

"numeric_field >= $session.params.min_value AND stock_availability: ANY(\"IN_STOCK\")"

Exemple de configuration de filtre d'API :

Si vous appelez l'API directement, vous devez fournir des chaînes filter dans un objet SearchConfig complet :

"searchConfig": {
  "filterSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "filter": "CONDITION"
    }
  ]
}

Expressions dynamiques Dialogflow

Les conditions BoostSpec et les chaînes FilterSpec peuvent intégrer des expressions Dialogflow pour les rendre dynamiques. Cela vous permet d'adapter le comportement de recherche en fonction des données contextuelles extraites d'une conversation en cours. Les expressions dynamiques ne sont pas compatibles avec les appels d'API directs et ne peuvent être utilisées que si vous effectuez la configuration à l'aide de la console.

Vous pouvez accéder aux données de contexte de conversation de deux manières :

  • Paramètres de session : valeurs collectées pendant la conversation à l'aide de $session.params.YOUR_PARAMETER_ID.
  • Métadonnées de l'utilisateur final : métadonnées sur l'utilisateur final transmises dans DetectIntentRequest à l'aide de $request.end-user-metadata.YOUR_KEY. Pour que cette option soit disponible, vérifiez que end_user_metadata est inclus dans le QueryParameters de vos appels DetectIntent. Pour en savoir plus, consultez endUserMetadata.

Pour en savoir plus sur les fonctions système et la syntaxe des expressions disponibles, consultez la documentation de référence sur les conditions et les fonctions système.

Conditions de recherche appliquées au moment de l'exécution

Lorsque votre outil de data store exécute une recherche :

  1. Les chaînes JSON que vous avez fournies pour les spécifications Boost sont évaluées. Chaque chaîne JSON valide est convertie en objet ConditionBoostSpec. Elles sont ensuite regroupées dans un objet BoostSpecs pour la connexion spécifique à l'data store, qui est ajouté à l'objet SearchConfig global.
  2. Les chaînes que vous avez fournies pour les spécifications de filtre sont évaluées en tant qu'expressions Dialogflow. Chaque chaîne de filtre résultante est utilisée pour créer un objet FilterSpecs pour le data store, qui est également ajouté à SearchConfig.
  3. Ce SearchConfig construit de manière dynamique est ensuite inclus dans le QueryParameters de la requête de recherche envoyée au data store.

Configurer les conditions de recherche

Avant de configurer des conditions de recherche, vérifiez que vous disposez des éléments suivants :

  • Un agent d'agents de conversation (Dialogflow CX) existant.
  • Un outil de datastore configuré pour votre agent avec un ou plusieurs datastores activés.

Configuration de console

  1. Ouvrez la console Conversational Agents et sélectionnez un projet Google Cloud.
  2. Sélectionnez un agent dans le menu déroulant.
  3. Accédez au menu de gauche et cliquez sur Outils. Sélectionnez l'outil de data store que vous souhaitez configurer.
  4. Sur la page de modification de l'outil, accédez à la section Datastores. Cliquez sur l'icône Paramètres (⚙️) à côté du data store que vous souhaitez modifier.
  5. Le menu Configurer le datastore s'affiche. Vous pouvez ajouter des spécifications de boost et de filtre pour modifier vos résultats de recherche.
    • Pour une spécification d'amplification, fournissez un objet JSON qui définit un ConditionBoostSpec. Pour en savoir plus, consultez les spécifications de Boost.
    • Pour une spécification de filtre, fournissez une chaîne qui définit les critères de filtre. Pour en savoir plus, consultez Spécifications des filtres.
  6. Après avoir ajouté et configuré vos spécifications, cliquez sur Confirmer en bas du panneau latéral.
  7. Cliquez sur Enregistrer sur la page de modification de l'outil de data store pour enregistrer les modifications.

Configuration d'API

Vous pouvez fournir des données de configuration de la recherche aux agents conversationnels (Dialogflow CX) lorsque vous envoyez des requêtes de détection d'intention. Ces informations doivent être fournies dans chaque requête "detect intent", car elles ne sont pas conservées dans la session.

Fournissez ces informations dans le champ queryParams.searchConfig de la méthode Sessions.detectIntent.

Sélectionnez un protocole et une version pour la référence de session :

Protocole V3 V3beta1
REST Ressource de session Ressource de session
RPC Interface de session Interface de session
C++ SessionsClient Non disponible
C# SessionsClient Non disponible
Go SessionsClient Non disponible
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP Non disponible Non disponible
Python SessionsClient SessionsClient
Ruby Non disponible Non disponible

Configuration de Dialogflow CX Messenger

Vous pouvez fournir des données de configuration de la recherche à l'intégration Dialogflow CX Messenger. Pour en savoir plus, consultez la méthode setContext.

Pour appliquer une spécification ou une configuration de recherche, l'extrait suivant doit être ajouté au code Dialogflow CX Messenger lors de l'intégration dans un site Web :

<script>
  document.addEventListener('df-messenger-loaded', () => {
    const dfMessenger = document.querySelector('df-messenger');
    const searchConfig = { ... }
    dfMessenger.setQueryParameters(searchConfig);
  });
</script>

Consultez la méthode setQueryParameters.

Dépannage

Cette section décrit les solutions à certains problèmes courants rencontrés lors de la configuration. Testez toujours vos configurations de manière approfondie en simulant des conversations qui déclenchent différents paramètres de session et valeurs de métadonnées de l'utilisateur final.

Expressions non valides

Si une condition de spécification de boost ou une chaîne de spécification de filtre contient une expression d'agents conversationnels (Dialogflow CX) non valide (par exemple, une syntaxe incorrecte ou une référence à un paramètre inexistant), la compilation de l'expression échouera. Les erreurs liées à la compilation d'expressions sont généralement renvoyées dans DetectIntentResponse dans le champ diagnostic_info sous la forme SystemFunctionResults.

JSON ConditionBoostSpec non valide

La console Agents conversationnels effectue une validation de la chaîne JSON ConditionBoostSpec lors de son enregistrement. Cela permet de vérifier qu'il s'agit d'un fichier JSON valide et que sa structure peut être mappée à un objet ConditionBoostSpec. Si le fichier JSON est valide, mais qu'il génère un SearchConfig non valide selon le service de recherche sous-jacent (par exemple, une chaîne de condition non valide après la substitution de paramètres), le service de recherche renvoie une erreur.

Erreurs de substitution lors de l'exécution

Si une chaîne JSON ConditionBoostSpec est valide et analysable, mais qu'une erreur se produit lors de la substitution d'expressions Dialogflow dans ses champs (tels que la chaîne de condition), ces erreurs seront signalées dans diagnostic_info sous la forme SystemFunctionResults.

Examiner le SearchConfig compilé

Le SearchConfig appliqué lors de l'exécution de la requête est disponible dans search_signals dans la réponse. Consulter le SearchConfig peut vous aider à identifier d'autres problèmes qui ne sont pas mentionnés ici.

Étapes suivantes