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
etFilterSpec
sont envoyés dans unSearchConfig
à l'aide d'un appel d'APIDetectIntent
. Un objetSearchConfig
complet doit être fourni dans la requête. UnSearchConfig
envoyé par un appel d'API direct remplace toujours unSearchConfig
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
etFilterSpec
sont utilisées pour construire un objetSearchConfig
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 objetsConditionBoostSpec
et une liste de chaînes de filtre pour construireFilterSpecs
plutôt qu'un objetSearchConfig
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.
- Une valeur positive favorise les documents correspondants. Une valeur de
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 queend_user_metadata
est inclus dans leQueryParameters
de vos appelsDetectIntent
. 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 :
- 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 objetBoostSpecs
pour la connexion spécifique à l'data store, qui est ajouté à l'objetSearchConfig
global. - 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
. - Ce
SearchConfig
construit de manière dynamique est ensuite inclus dans leQueryParameters
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
- Ouvrez la console Conversational Agents et sélectionnez un projet Google Cloud.
- Sélectionnez un agent dans le menu déroulant.
- Accédez au menu de gauche et cliquez sur Outils. Sélectionnez l'outil de data store que vous souhaitez configurer.
- 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.
- 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.
- Pour une spécification d'amplification, fournissez un objet JSON qui définit un
- Après avoir ajouté et configuré vos spécifications, cliquez sur Confirmer en bas du panneau latéral.
- 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
- Pour en savoir plus sur la structure de
SearchConfig
et de ses composants, consultez la documentationsearch_config
. - Pour en savoir plus sur la syntaxe des expressions, consultez la documentation de référence sur les conditions et les fonctions système de Dialogflow.
- Pour en savoir plus sur la syntaxe des expressions de filtre pour la recherche, consultez Filtrer et trier les résultats.