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 vous permet d'avoir des interactions plus personnalisées et contextuelles lorsque votre agent utilise un data store pour trouver des informations.

Vous pouvez éventuellement 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, de l'API ou de l'intégration de Dialogflow CX Messenger.

Entrées de condition de recherche

Vous configurez les résultats de recherche à l'aide des champs spécification de boost (BoostSpec) et spécification de filtre (FilterSpec) dans un objet SearchConfig. Ces configurations s'appliquent par data store dans l'outil, ce qui vous permet de contrôler le comportement de chaque data store connecté.

Vous pouvez configurer les conditions de recherche de deux manières : en utilisant la console ou en envoyant un appel d'API direct.

Il existe des différences importantes entre les deux :

  • Appel d'API : vous envoyez BoostSpec et FilterSpec dans un SearchConfig à l'aide d'un appel d'API DetectIntent. Vous devez fournir un objet SearchConfig complet dans la requête. Un SearchConfig envoyé par 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 : la console utilise vos configurations BoostSpec et FilterSpec pour construire un objet SearchConfig qu'elle envoie 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 à partir de la conversation. Il vous suffit de 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 dans detectIntentRequest. Il n'y a pas de schéma attendu. Vous pouvez donc définir les propriétés de l'objet.

Spécifications de boost (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 même data store.

Vous saisissez chaque spécification de boost sous la forme d'une chaîne JSON représentant un seul objet ConditionBoostSpec.

Champs clés :

  • condition : (chaîne) expression qui spécifie quand la boost doit s'appliquer. Cette option 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 l'intensité du boosting.
    • Une valeur positive favorise les documents correspondants. Une valeur de 1.0 donne une forte promotion.
    • Une valeur négative rétrograde les documents correspondants. Une valeur de -1.0 entraîne une forte rétrogradation.
    • Une valeur de 0.0 n'applique aucune amélioration et n'est pas autorisée.
  • boostControlSpec : fournit plus de commandes pour un classement personnalisé que la combinaison de base de condition et de boost. Pour en savoir plus sur la configuration de ce champ, consultez la documentation de référence.

Exemple d'entrée de console :

Si vous configurez votre agent dans la console, fournissez une liste de ConditionBoostSpecs au format suivant :

{
  "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 pour n'inclure que les documents correspondant 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 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 de $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 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 contextuelles récupérées d'une conversation en cours. Les expressions dynamiques ne sont pas acceptées 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 contextuelles 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 de 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. Évaluez les chaînes JSON que vous avez fournies pour les spécifications de boost. Chaque chaîne JSON valide est convertie en objet ConditionBoostSpec. Ils sont ensuite regroupés dans un objet BoostSpecs pour la connexion au data store spécifique, qui est ajouté à l'objet SearchConfig global.
  2. Évaluez les chaînes que vous avez fournies pour les spécifications de filtre 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é à SearchConfig.
  3. Incluez ce SearchConfig construit de manière dynamique dans le QueryParameters de la requête de recherche envoyée au data store.

Configurer les conditions de recherche

Pour configurer des conditions de recherche, assurez-vous d'avoir rempli les conditions préalables suivantes :

  • 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 projetGoogle Cloud .
  2. Sélectionnez un agent dans le menu déroulant.
  3. Accédez au menu de gauche, puis 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. Ici, vous pouvez ajouter des spécifications de boosting et de filtrage 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 filtrage. 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 recherche à Dialogflow CX lorsque vous envoyez des requêtes de détection d'intent. Vous devez fournir ces informations dans chaque requête de détection d'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 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, vous devez ajouter l'extrait de code suivant au code Dialogflow CX Messenger lorsque vous l'intégrez à un site Web :

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

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

Dépannage

Les solutions suivantes permettent de résoudre certains problèmes courants rencontrés lors de la configuration. Testez minutieusement vos configurations 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 é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 Conversational Agents effectue une validation de la chaîne JSON ConditionBoostSpec lors de son enregistrement pour vérifier qu'il s'agit d'un JSON valide et que sa structure peut être mappée à un objet ConditionBoostSpec. Si le code 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ètre), le service de recherche renvoie une erreur.

Erreurs de substitution d'exécution

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

Étapes suivantes