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 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 datastore pour booster les documents liés aux téléphones mobiles lorsque vous répondez à une requête générale plus tard dans la conversation, par exemple "Comment consulter ma messagerie vocale ?".

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

Entrées de condition de recherche

Les résultats de recherche sont configurés à l'aide des champs spécification de boost (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 les 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 prises en charge.

  • 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 également inclure des références de paramètres et des expressions dynamiques pour adapter les résultats aux données de contexte enregistrées à partir de la conversation. Vous n'avez qu'à fournir des objets ConditionBoostSpec et une liste de chaînes de filtre pour construire des 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 de boost à un seul 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. Elle utilise la syntaxe d'expression de filtre standard . Vous pouvez utiliser des expressions Dialogflow CX pour rendre les résultats dynamiques, par exemple $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 la force du boost.
    • Une valeur positive promeut les documents correspondants. Une valeur de 1.0 offre une forte promotion.
    • Une valeur négative rétrograde les documents correspondants. Une valeur de -1.0 offre une forte rétrogradation.
    • Une valeur de 0.0 n'applique aucun boost et n'est pas autorisée.
  • boostControlSpec: fournit plus de commandes pour un classement personnalisé que la combinaison de base de la condition et du boost. 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 force 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 d'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 de boost :

"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 seul data store.

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

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

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

Dans cet exemple, le filtre ne renvoie que les documents dont le numeric_field est supérieur ou égal à la valeur de $session.params.min_value ET où 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 CX

Les conditions BoostSpec et les chaînes FilterSpec peuvent intégrer des expressions Dialogflow CX pour les rendre dynamiques. Cela vous permet d'adapter le comportement de recherche en fonction des données de contexte récupérées à partir d'une conversation en cours. Les expressions dynamiques ne sont pas prises en charge dans 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 la 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 le 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 les QueryParameters de vos appels DetectIntent. Pour en savoir plus, consultez endUserMetadata.

Pour en savoir plus sur les fonctions système disponibles et la syntaxe des expressions, 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 de 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 de data store spécifique, qui est ajouté au SearchConfig global.
  2. Les chaînes que vous avez fournies pour les spécifications de filtre sont évaluées en tant qu'expressions Dialogflow CX. Chaque chaîne de filtre obtenue est utilisée pour créer un objet FilterSpecs pour le data store, qui est également ajouté au SearchConfig.
  3. Ce SearchConfig construit dynamiquement est ensuite inclus dans les QueryParameters de la requête de recherche envoyée au data store.

Configurer les conditions de recherche

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

  • Un agent 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 choisissez un Google Cloud projet.
  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 y ajouter des spécifications de boost et de filtre pour modifier vos résultats de recherche.
    • Pour une spécification de boost, fournissez un objet JSON qui définit un ConditionBoostSpec. Pour en savoir plus, consultez 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 de filtre.
  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 recherche à Dialogflow CX lorsque vous envoyez des requêtes de détection d'intention. Ces informations doivent être fournies dans chaque requête de détection d'intention, 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 recherche à l'intégration Dialogflow CX Messenger. Pour en savoir plus, consultez la setContext.

Pour appliquer une spécification de recherche ou une configuration de recherche, l'extrait de code suivant doit être ajouté au code Dialogflow CX Messenger lors de son 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 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 Dialogflow CX non valide (par exemple, une syntaxe incorrecte ou une référence à un paramètre inexistant), la compilation de l'expression échoue. Les erreurs liées à la compilation d'expressions sont généralement renvoyées dans le DetectIntentResponse dans le champ diagnostic_info sous la forme SystemFunctionResults.

JSON ConditionBoostSpec non valide

La console Conversational Agents effectue une validation sur la chaîne JSON ConditionBoostSpec lors de son enregistrement. Il s'agit de vérifier qu'il s'agit d'un JSON valide et que sa structure peut être mappée à un objet ConditionBoostSpec. Si le 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 au moment de l'exécution

Si une ConditionBoostSpec chaîne JSON est valide et analysable, mais qu'une erreur se produit lors de la substitution au moment de l'exécution des expressions Dialogflow CX dans ses champs (tels que la chaîne de condition), ces erreurs sont 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. L'examen du SearchConfig peut fournir des informations sur d'autres problèmes non décrits ici.

Étape suivante

Précédent
Agents hybrides du data store
Suivant
Principes de base des agents basés sur un flux